chore: update agent docs, add commit conventions, and exclude .goat-flow from git" -m "- Add .github/git-commit-instructions.md with conventional commit rules

  - Add .goat-flow/ to .gitignore (internal tooling workspace, not for VCS)
  - Overhaul AGENTS.md and CLAUDE.md with accurate component list, MCP tool
    guidance, and goat-flow router table
  - Align match arm default cases in TokenType, FHIRPathSpecificationTest,
    FHIRIGGeneratorCommand, and FHIRPrimitiveTypeNormalizer

Author: Ardenexal

.github/git-commit-instructions.md

@@ -0,0 +1,43 @@
+# Commit Conventions
+
+## Format
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer]
+```
+
+## Types
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New feature or user-visible capability |
+| `fix` | Bug fix |
+| `chore` | Build scripts, dependencies, tooling, CI |
+| `test` | Adding or updating tests |
+| `docs` | Documentation only |
+| `refactor` | Code restructure with no behaviour change |
+
+## Rules
+
+- **Subject line:** ≤ 72 characters, imperative mood ("add support for X", not "added"), no trailing period
+- **Scope:** optional, names the component affected (e.g. `serialization`, `codegen`, `fhirpath`)
+- **Body:** explain *why*, not *what*; wrap at 72 characters
+- **No AI mentions:** do not reference AI tools, Claude, or AI assistance in commit messages or PR descriptions
+- **GPG-sign** commits when possible (`git commit -S`)
+- **No `--no-verify`** — pre-commit hooks must pass; fix the underlying issue instead
+
+## Examples
+
+```
+feat(serialization): add strict validation mode to JSON deserializer
+
+fix(fhirpath): handle empty collection in where() function
+
+chore: upgrade phpstan to 2.x
+
+test(codegen): add coverage for profile inheritance resolution
+```

.gitignore

@@ -9,6 +9,7 @@ Thumbs.db
 # Internal tool configs
 .kiro/
 .claude/
+.goat-flow/
 
 ###> symfony/framework-bundle ###
 /config/secrets/prod/prod.decrypt.private.php

AGENTS.md

@@ -32,9 +32,14 @@
 
 ### Components
 
-- **FHIRBundle** (`ardenexal/fhir-bundle`): Symfony Bundle for seamless integration
-- **CodeGeneration** (`ardenexal/fhir-code-generation`): Standalone FHIR class generator
-- **Serialization** (`ardenexal/fhir-serialization`): Standalone FHIR JSON serialization
+All components are distributed as a single package (`ardenexal/fhir-tools`):
+
+- **Metadata**: Shared PHP 8 attributes and contracts used by all other components
+- **CodeGeneration**: FHIR class generator from Structure Definitions
+- **Models**: Generated FHIR model classes (R4, R4B, R5) — do not hand-edit
+- **Serialization**: FHIR JSON/XML serialization and validation
+- **FHIRPath**: FHIRPath expression parser and evaluator
+- **FHIRBundle**: Symfony Bundle wiring all components together
 
 ---
 
@@ -72,23 +77,33 @@ $serializer = new FHIRSerializationService();
 
 ## Essential Commands
 ### Testing
+Prefer the `phpunit-run` MCP tool over CLI. It returns compact structured output and
+accepts `file`, `class`, `method`, and `filter` parameters.
+
 ```bash
-composer run test
-composer run generate-models-all
+# Fallback CLI only — use phpunit-run MCP tool instead when available
+composer test-ai        # all tests, compact output
+composer test-ai-unit   # unit suite only
+
+composer run generate-models-all   # regenerate all FHIR models (no MCP equivalent)
 ```
 
 ### Code Quality
+Prefer the `phpstan-analyse` MCP tool over CLI. Use the `path` parameter to target a
+single file or directory.
+
 ```bash
-composer run lint      # Fix code style
-composer run phpstan   # Static analysis
+# Fallback CLI only — use phpstan-analyse MCP tool instead when available
+composer phpstan-ai  # static analysis, compact output
+
+composer lint        # fix code style with Pint (no MCP equivalent)
 ```
 
 ### Component Testing
 ```bash
-# Test specific components
-composer run test -- tests/Unit/Bundle/FHIRBundle/
-composer run test -- tests/Unit/Component/CodeGeneration/
-composer run test -- tests/Unit/Component/Serialization/
+# Via MCP: phpunit-run with filter="CodeGeneration" (or Serialization / FHIRPath)
+# Via CLI fallback (tests live under src/Component/<Name>/tests/):
+composer test-ai -- --filter CodeGeneration
 ```
 
 ---
@@ -105,12 +120,16 @@ composer run test -- tests/Unit/Component/Serialization/
 src/
 ├── Bundle/FHIRBundle/           # Symfony Bundle
 ├── Component/
+│   ├── Metadata/                # Shared attributes and contracts
 │   ├── CodeGeneration/          # FHIR class generation
-│   └── Serialization/           # FHIR JSON serialization
+│   ├── Models/                  # Generated FHIR models (do not hand-edit)
+│   ├── Serialization/           # FHIR JSON/XML serialization
+│   └── FHIRPath/                # FHIRPath expression evaluator
 docs/
-├── architecture.md              # Multi-project architecture
-├── migration-guide.md           # Migration instructions
 └── component-guides/            # Component-specific guides
+    ├── fhir-bundle.md
+    ├── fhir-path.md
+    └── serialization.md
 ```
 
 ---
@@ -158,7 +177,9 @@ docs/
 Before submitting changes, confirm:
 - [ ] Symfony compliance (DI, Console helpers).
 - [ ] `declare(strict_types=1);` in all files.
-- [ ] Code passes `composer run lint` and `composer run phpstan`.
+- [ ] `phpstan-analyse` MCP tool (or `composer phpstan-ai`) reports no errors.
+- [ ] `phpunit-run` MCP tool (or `composer test-ai`) passes.
+- [ ] `composer lint` passes (no MCP equivalent).
 - [ ] All PHPUnit tests pass.
 - [ ] Component isolation maintained.
 - [ ] Backward compatibility preserved.
@@ -172,12 +193,47 @@ Before submitting changes, confirm:
 ---
 
 ### Documentation Resources
-- **Architecture Guide**: `/docs/architecture.md` - Multi-project structure overview
-- **Migration Guide**: `/docs/migration-guide.md` - Step-by-step migration instructions  
-- **Component Guides**: `/docs/component-guides/` - Detailed component documentation
-- **FHIRBundle Guide**: `/docs/component-guides/fhir-bundle.md` - Symfony integration
-- **CodeGeneration Guide**: `/docs/component-guides/code-generation.md` - Standalone generation
-- **Serialization Guide**: `/docs/component-guides/serialization.md` - JSON serialization
+- **Architecture Guide**: `.goat-flow/architecture.md` - System architecture and component overview
+- **Code Map**: `.goat-flow/code-map.md` - File layout and hot paths
+- **FHIRBundle Guide**: `docs/component-guides/fhir-bundle.md` - Symfony integration
+- **FHIRPath Guide**: `docs/component-guides/fhir-path.md` - FHIRPath evaluator
+- **Serialization Guide**: `docs/component-guides/serialization.md` - JSON/XML serialization
+
+## Execution Loop
+
+### READ
+
+Before starting any task, orient with these sources:
+
+- Read `.goat-flow/architecture.md` for system context.
+- Read `.goat-flow/code-map.md` for file layout.
+- Before declaring any tool or capability unavailable, read the matching playbook in `.goat-flow/skill-reference/` (e.g. `browser-use.md`, `page-capture.md`) and run that doc's "Availability Check" section verbatim — project-local CLI tools at `~/.local/bin/` are valid; do not conflate "no harness/MCP tool" with "no tool".
+
+### SCOPE
+
+Identify files to touch, tests to run, and a binary exit criterion. Confirm with user if scope extends beyond `src/` or `tests/` into config, CI, or infra files.
+
+### ACT
+
+Edit minimal files. Run `phpunit-run` (MCP) after each logical unit; fall back to `composer test-ai` if MCP is unavailable. Never hand-edit `src/Component/Models/src/`; run `php demo/bin/console fhir:generate` instead.
+
+### VERIFY
+
+`phpstan-analyse` (MCP) clean · `phpunit-run` (MCP) passes · `composer lint` passes. No hand-edits to generated model files. All exit criteria met with proof, not recollection.
+
+## Router Table
+
+| What you need | Where to look |
+|---|---|
+| Architecture overview | `.goat-flow/architecture.md` |
+| Repository layout | `.goat-flow/code-map.md` |
+| Domain terminology | `.goat-flow/glossary.md` |
+| Known traps and footguns | `.goat-flow/footguns/` |
+| Lessons from past incidents | `.goat-flow/lessons/` |
+| Architecture decisions | `.goat-flow/decisions/` |
+| Tool playbooks (CLI/MCP availability checks: browser-use, page-capture, skill-* references) | `.goat-flow/skill-reference/` — read BEFORE declaring a tool unavailable |
+
+---
 
 <!-- BEGIN AI_MATE_INSTRUCTIONS -->
 AI Mate Summary: