Initial commit

2025-11-30 08:43:17 +08:00
commit 8967d326a7
30 changed files with 5154 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,12 @@
+{
+  "name": "agents",
+  "description": "Generate and maintain AGENTS.md files following the public agents.md convention. Creates thin root files with precedence rules, scoped files for subsystems, auto-extracts commands from build tools, and supports Go, PHP, TypeScript, and Python projects with language-specific templates.",
+  "version": "1.1.0-20251125",
+  "author": {
+    "name": "Netresearch DTT GmbH",
+    "email": "info@netresearch.de"
+  },
+  "skills": [
+    "./"
+  ]
+}
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,19 @@
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary
+*.tmp
+*.bak
+.cache/
+
+# Test output
+test-output/
+*.test.md
--- a/18
+++ b/18
@@ -0,0 +1,18 @@
+GNU GENERAL PUBLIC LICENSE
+Version 2, June 1991
+
+Copyright (C) 2025 Netresearch DTT GmbH
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
+# agents
+
+Generate and maintain AGENTS.md files following the public agents.md convention. Creates thin root files with precedence rules, scoped files for subsystems, auto-extracts commands from build tools, and supports Go, PHP, TypeScript, and Python projects with language-specific templates.
--- a/SKILL.md
+++ b/SKILL.md
@@ -0,0 +1,390 @@
+---
+name: agents
+version: 1.1.0
+description: Generate and maintain AGENTS.md files following the public agents.md convention. Use when creating documentation for AI agent workflows, onboarding guides, or when standardizing agent interaction patterns across projects.
+license: Complete terms in LICENSE.txt
+---
+
+# AGENTS.md Generator Skill
+
+Generate and maintain AGENTS.md files following the public agents.md convention.
+
+## What This Skill Does
+
+Creates hierarchical AGENTS.md documentation for software projects:
+
+- **Thin root files** (~30 lines) with precedence rules and global defaults
+- **Scoped files** for subsystems (backend/, frontend/, internal/, cmd/, etc.)
+- **Auto-extracted commands** from Makefile, package.json, composer.json, go.mod
+- **Managed headers** marking files as agent-maintained with timestamps
+- **Language-specific templates** for Go, PHP, TypeScript, Python, and hybrid projects
+- **Idempotent updates** that preserve existing structure
+
+Based on analysis of 21 real AGENTS.md files across Netresearch projects.
+
+## When to Use This Skill
+
+- **New projects**: Establish baseline AGENTS.md structure
+- **Existing projects**: Standardize agent documentation
+- **Team onboarding**: Provide AI assistants with project context
+- **Multi-repo consistency**: Apply same standards across repositories
+- **Documentation updates**: Refresh after major changes
+
+## Usage
+
+### Generate for Current Project
+
+```bash
+# Basic generation (thin root + auto-detected scopes)
+/tmp/agents-skill/scripts/generate-agents.sh .
+
+# Dry-run to preview what will be created
+/tmp/agents-skill/scripts/generate-agents.sh . --dry-run
+
+# Verbose output with detection details
+/tmp/agents-skill/scripts/generate-agents.sh . --verbose
+```
+
+### Template Styles
+
+```bash
+# Thin root (default, ~30 lines, simple-ldap-go style)
+/tmp/agents-skill/scripts/generate-agents.sh . --style=thin
+
+# Verbose root (~100-200 lines, ldap-selfservice style)
+/tmp/agents-skill/scripts/generate-agents.sh . --style=verbose
+```
+
+### Update Existing Files
+
+```bash
+# Update timestamps and refresh auto-extracted content
+/tmp/agents-skill/scripts/generate-agents.sh . --update
+
+# Force regeneration (overwrites existing, keeps structure)
+/tmp/agents-skill/scripts/generate-agents.sh . --force
+```
+
+### Validation
+
+```bash
+# Validate existing AGENTS.md structure
+/tmp/agents-skill/scripts/validate-structure.sh .
+
+# Check for missing scoped files
+/tmp/agents-skill/scripts/detect-scopes.sh .
+```
+
+## Supported Project Types
+
+### Languages & Frameworks
+
+- **Go**: Libraries, web apps (Fiber/Echo/Gin), CLI tools (Cobra/urfave/cli)
+- **PHP**: Composer packages, TYPO3 extensions, Laravel/Symfony apps
+- **TypeScript/JavaScript**: React, Next.js, Vue, Node.js, Express
+- **Python**: pip, poetry, pipenv, Django, Flask, FastAPI
+- **Hybrid**: Multi-language projects (auto-creates scoped files per stack)
+
+### Detection Signals
+
+| Signal | Detection |
+|--------|-----------|
+| `go.mod` | Go project, extracts version |
+| `composer.json` | PHP project, detects TYPO3/Laravel |
+| `package.json` | Node.js project, detects framework |
+| `pyproject.toml` | Python project, detects poetry/ruff |
+| `Makefile` | Extracts targets with `##` comments |
+| `.github/workflows/` | Extracts CI checks |
+| `docker-compose.yml` | Docker-first setup |
+
+## Output Structure
+
+### Thin Root (Default)
+
+**~30 lines** following `simple-ldap-go` pattern:
+
+```markdown
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: YYYY-MM-DD -->
+
+# AGENTS.md (root)
+
+**Precedence:** The **closest AGENTS.md** to changed files wins. Root holds global defaults only.
+
+## Global rules
+- Keep PRs small (~≤300 net LOC)
+- Conventional Commits: type(scope): subject
+- Ask before: heavy deps, full e2e, repo rewrites
+- Never commit secrets or PII
+
+## Minimal pre-commit checks
+- Typecheck: [auto-detected from build tools]
+- Lint: [auto-detected from linters]
+- Format: [auto-detected from formatters]
+- Tests: [auto-detected from test runners]
+
+## Index of scoped AGENTS.md
+- `./backend/AGENTS.md` — Backend services
+- `./frontend/AGENTS.md` — Frontend application
+
+## When instructions conflict
+Nearest AGENTS.md wins. User prompts override files.
+```
+
+### Scoped Files (9-Section Schema)
+
+Each scoped file follows this structure:
+
+1. **Overview**: Purpose of this subsystem
+2. **Setup & environment**: Prerequisites, installation
+3. **Build & tests**: File-scoped commands (preferred)
+4. **Code style & conventions**: Language-specific standards
+5. **Security & safety**: Security practices
+6. **PR/commit checklist**: Pre-commit requirements
+7. **Good vs. bad examples**: Concrete code samples
+8. **When stuck**: Where to find help
+9. **House Rules** (optional): Overrides of global rules
+
+### Managed Header
+
+All generated files include:
+
+```html
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-18 -->
+```
+
+This marks files as agent-maintained and provides update tracking.
+
+## Auto-Detection Features
+
+### Project Type Detection
+
+```bash
+$ /tmp/agents-skill/scripts/detect-project.sh .
+{
+  "type": "go-web-app",
+  "language": "go",
+  "version": "1.24",
+  "build_tool": "make",
+  "has_docker": true,
+  "quality_tools": ["golangci-lint", "gofmt"],
+  "test_framework": "testing",
+  "ci": "github-actions"
+}
+```
+
+### Scope Detection
+
+Automatically creates scoped AGENTS.md for directories with ≥5 source files:
+
+```bash
+$ /tmp/agents-skill/scripts/detect-scopes.sh .
+{
+  "scopes": [
+    {"path": "internal", "type": "backend-go", "files": 15},
+    {"path": "cmd", "type": "cli", "files": 3},
+    {"path": "examples", "type": "examples", "files": 8}
+  ]
+}
+```
+
+### Command Extraction
+
+Extracts actual commands from build tools:
+
+```bash
+$ /tmp/agents-skill/scripts/extract-commands.sh .
+{
+  "typecheck": "go build -v ./...",
+  "lint": "golangci-lint run ./...",
+  "format": "gofmt -w .",
+  "test": "go test -v -race -short ./...",
+  "build": "go build -o bin/app ./cmd/app"
+}
+```
+
+## Examples
+
+Real-world examples from Netresearch projects in `references/examples/`:
+
+### Go Library (simple-ldap-go)
+
+**Perfect thin root** (26 lines):
+- Minimal global rules
+- File-scoped commands
+- Clear scope index
+- No duplication
+
+### Hybrid App (ldap-selfservice-password-changer)
+
+**Go backend + TypeScript frontend**:
+- Root with quick navigation
+- Scoped: `internal/AGENTS.md` (Go)
+- Scoped: `internal/web/AGENTS.md` (TypeScript + Tailwind)
+
+### PHP TYPO3 Extension (t3x-rte_ckeditor_image)
+
+**Composer-based with Make targets**:
+- Root with emoji headers
+- Scoped: `Classes/AGENTS.md` (PHP backend)
+- Scoped: `Documentation/AGENTS.md` (RST docs)
+- Scoped: `Tests/AGENTS.md` (PHPUnit tests)
+
+### Python CLI (coding_agent_cli_toolset)
+
+**Script-heavy toolset**:
+- Root with precedence focus
+- Scoped: `scripts/AGENTS.md`
+
+## Customization
+
+### Override Templates
+
+Copy templates to project and modify:
+
+```bash
+cp /tmp/agents-skill/templates/root-thin.md ./.agents-templates/root.md
+# Edit ./.agents-templates/root.md
+/tmp/agents-skill/scripts/generate-agents.sh . --template-dir=./.agents-templates
+```
+
+### Add Custom Sections
+
+Templates support placeholders:
+- `{{PROJECT_NAME}}` - From package.json/composer.json/go.mod
+- `{{PROJECT_TYPE}}` - Auto-detected type
+- `{{LANGUAGE}}` - Primary language
+- `{{BUILD_COMMANDS}}` - Extracted commands
+- `{{QUALITY_TOOLS}}` - Detected linters/formatters
+- `{{TIMESTAMP}}` - Current date (YYYY-MM-DD)
+
+## Idempotent Updates
+
+Safe to run multiple times:
+
+1. Checks existing files
+2. Preserves custom content in sections
+3. Updates only auto-extracted parts (commands, versions)
+4. Refreshes timestamps
+5. Adds missing sections
+6. No changes if nothing updated
+
+## Validation
+
+```bash
+# Check structure compliance
+/tmp/agents-skill/scripts/validate-structure.sh .
+
+# Validates:
+# ✅ Root is thin (≤50 lines or has index)
+# ✅ All scoped files have 9 sections
+# ✅ Managed headers present
+# ✅ Precedence statement in root
+# ✅ Links from root to scoped files work
+# ✅ No duplicate content between root and scoped
+```
+
+## Integration with Claude Code
+
+### As Marketplace Skill
+
+Add to `claude-code-marketplace`:
+
+```json
+{
+  "name": "agents",
+  "description": "Generate AGENTS.md files following public convention",
+  "version": "1.0.0",
+  "source": "./skills/agents"
+}
+```
+
+### Direct Usage
+
+```bash
+# Clone skill
+git clone https://github.com/netresearch/agents-skill.git /tmp/agents-skill
+
+# Generate for current project
+/tmp/agents-skill/scripts/generate-agents.sh .
+```
+
+## Structure Standards Application
+
+**When creating root AGENTS.md files**, keep them thin (~30 lines):
+- Include clear precedence statement at top
+- Define minimal global rules only (PR size, commit format, safety)
+- List pre-commit checks (typecheck, lint, format, test)
+- Provide scope index linking to scoped files
+- Move detailed setup to scoped files (not in root)
+- Move language-specific patterns to scoped files (not in root)
+- Move extensive examples to scoped files (not in root)
+
+**When determining scope boundaries**, create scoped files for:
+- Different technology stacks: `backend/`, `frontend/`, `api/`
+- Package visibility: `internal/`, `pkg/` (Go projects)
+- CLI tools: `cmd/`, `cli/`
+- Utility scripts: `scripts/`
+- Documentation and examples: `docs/`, `examples/`
+- Testing infrastructure: `tests/`, `testutil/`
+
+**When extracting commands**, automate extraction from:
+- Makefile targets with `##` comments
+- package.json scripts section
+- composer.json scripts section
+- CI workflow files (.github/workflows/, .gitlab-ci.yml)
+- Never manually duplicate commands that exist in build tools
+
+## Troubleshooting
+
+### No Commands Detected
+
+```bash
+# Check what was detected
+/tmp/agents-skill/scripts/extract-commands.sh . --verbose
+
+# Fallback: Specify commands manually
+/tmp/agents-skill/scripts/generate-agents.sh . --commands='{"lint":"make lint","test":"make test"}'
+```
+
+### Wrong Project Type
+
+```bash
+# Override auto-detection
+/tmp/agents-skill/scripts/generate-agents.sh . --type=go-library
+
+# Supported types:
+# go-library, go-web-app, go-cli
+# php-library, php-typo3, php-laravel
+# typescript-react, typescript-node
+# python-library, python-cli
+# hybrid
+```
+
+### Scoped File Not Created
+
+```bash
+# Check scope detection
+/tmp/agents-skill/scripts/detect-scopes.sh .
+
+# Manually specify scopes
+/tmp/agents-skill/scripts/generate-agents.sh . --scopes=internal,cmd,examples
+```
+
+## Contributing
+
+Improvements welcome! Common additions:
+- New language templates
+- Better command extraction
+- Additional validation rules
+- More real-world examples
+
+## License
+
+GPL-2.0-or-later (matching other Netresearch skills)
+
+## References
+
+- **Analysis**: `references/analysis.md` - Analysis of 21 real AGENTS.md files
+- **Prompt**: `references/prompt.md` - Original generation prompt/rule
+- **Examples**: `references/examples/` - Real-world AGENTS.md files
+- **Best Practices**: `references/best-practices.md` - Writing guide
--- a/STATUS.md
+++ b/STATUS.md
@@ -0,0 +1,104 @@
+# agents-skill Creation Status
+
+**Created**: 2025-10-18
+**Status**: ✅ COMPLETE - Fully functional skill ready for use
+
+## ✅ Completed
+
+1. **Directory Structure**: Created all necessary directories
+2. **SKILL.md**: Complete skill metadata and documentation
+3. **`.gitignore**`: Standard ignores
+4. **Analysis**: Complete analysis of 21 real AGENTS.md files
+5. **Templates**: root-thin.md, root-verbose.md, and scoped templates (Go, PHP, TypeScript, CLI)
+6. **Scripts**: All generator and detection scripts implemented
+7. **Examples**: Real-world AGENTS.md files from 4 projects copied
+8. **README.md**: Comprehensive usage guide
+9. **LICENSE**: GPL-2.0-or-later
+10. **Git Repository**: Initialized with initial commit
+
+## 📦 Implementation Summary
+
+### Templates (✅ Complete)
+- ✅ `templates/root-thin.md` - Thin root template (simple-ldap-go style, ~30 lines)
+- ✅ `templates/root-verbose.md` - Verbose root template (~100-200 lines)
+- ✅ `templates/scoped/backend-go.md` - Go backend 9-section template
+- ✅ `templates/scoped/backend-php.md` - PHP backend 9-section template
+- ✅ `templates/scoped/frontend-typescript.md` - TypeScript frontend 9-section template
+- ✅ `templates/scoped/cli.md` - CLI tools 9-section template
+
+### Scripts (✅ Complete)
+- ✅ `scripts/generate-agents.sh` - Main orchestrator with --dry-run, --update, --force, --style
+- ✅ `scripts/detect-project.sh` - Auto-detect language, version, framework, tools
+- ✅ `scripts/detect-scopes.sh` - Find directories needing scoped AGENTS.md
+- ✅ `scripts/extract-commands.sh` - Parse Makefile, package.json, composer.json
+- ✅ `scripts/validate-structure.sh` - Validate structure compliance
+- ✅ `scripts/lib/template.sh` - Template rendering helper functions
+
+### Examples (✅ Complete)
+- ✅ `references/examples/simple-ldap-go/` - Perfect thin root (26 lines)
+- ✅ `references/examples/ldap-selfservice/` - Hybrid Go + TypeScript
+- ✅ `references/examples/t3x-rte-ckeditor-image/` - PHP TYPO3 extension
+- ✅ `references/examples/coding-agent-cli/` - Python CLI toolset
+- ✅ `references/analysis.md` - Comprehensive analysis of 21 files
+
+### Documentation (✅ Complete)
+- ✅ `README.md` - Comprehensive usage guide with examples
+- ✅ `SKILL.md` - Complete skill metadata and documentation
+- ✅ `LICENSE` - GPL-2.0-or-later
+- ✅ `.gitignore` - Standard ignores
+
+### Git Repository (✅ Complete)
+- ✅ Initialized with all files
+- ✅ Initial commit with descriptive message
+- ✅ Ready for push to GitHub
+
+## 🚀 Next Steps
+
+1. ✅ **Push to GitHub**: Create repository at `https://github.com/netresearch/agents-skill`
+2. ✅ **Add to marketplace**: Update sync configuration and workflow
+3. ✅ **Test on real projects**: Validate with simple-ldap-go, t3x-rte_ckeditor_image, etc.
+
+## 📝 Final Directory Structure
+
+```
+/tmp/agents-skill/
+├── .git/                                   ✅ Git repository initialized
+├── .gitignore                              ✅ Standard ignores
+├── LICENSE                                 ✅ GPL-2.0-or-later
+├── README.md                               ✅ Comprehensive usage guide
+├── SKILL.md                                ✅ Complete skill metadata
+├── STATUS.md                               ✅ This file
+├── templates/
+│   ├── root-thin.md                        ✅ Thin root template
+│   ├── root-verbose.md                     ✅ Verbose root template
+│   ├── scoped/
+│   │   ├── backend-go.md                   ✅ Go backend template
+│   │   ├── backend-php.md                  ✅ PHP backend template
+│   │   ├── cli.md                          ✅ CLI tools template
+│   │   └── frontend-typescript.md          ✅ TypeScript frontend template
+│   └── sections/                           (future: modular sections)
+├── scripts/
+│   ├── detect-project.sh                   ✅ Project type detection
+│   ├── detect-scopes.sh                    ✅ Scope detection
+│   ├── extract-commands.sh                 ✅ Build command extraction
+│   ├── generate-agents.sh                  ✅ Main generator
+│   ├── validate-structure.sh               ✅ Structure validation
+│   └── lib/
+│       └── template.sh                     ✅ Template rendering helpers
+└── references/
+    ├── analysis.md                         ✅ Comprehensive analysis
+    └── examples/
+        ├── simple-ldap-go/                 ✅ Perfect thin root example
+        ├── ldap-selfservice/               ✅ Hybrid Go + TypeScript
+        ├── t3x-rte-ckeditor-image/         ✅ PHP TYPO3 extension
+        └── coding-agent-cli/               ✅ Python CLI toolset
+```
+
+## ✅ Skill is Complete and Ready for Use
+
+The agents-skill is fully implemented and ready to generate AGENTS.md files for any supported project type (Go, PHP, TypeScript, Python, hybrid).
+
+**Usage**:
+```bash
+/tmp/agents-skill/scripts/generate-agents.sh /path/to/project
+```
--- a/claudedocs/refactoring-summary.md
+++ b/claudedocs/refactoring-summary.md
@@ -0,0 +1,45 @@
+# SKILL.md Refactoring Summary
+
+**Date:** 2025-11-14
+**Version Change:** 1.0.0 → 1.1.0
+**Skill:** agents
+
+## Changes Applied
+
+### Pattern 2: Converted "## Best Practices" to Imperative Form
+- **Before:** "## Best Practices" with subsections containing mixed Do's/Don'ts
+- **After:** "## Structure Standards Application" with imperative "When X" format
+
+#### Keep Root Thin
+- **Before:** "Good" and "Bloated" examples with checkmarks/X marks
+- **After:** "When creating root AGENTS.md files" with action-oriented instructions
+- Converted positive examples to directives
+- Converted negative examples to avoidance instructions
+
+#### Scope Appropriately
+- **Before:** "Create scoped files for:" with bullet list
+- **After:** "When determining scope boundaries" with action-oriented guidance
+- Same content, imperative presentation
+
+#### Auto-Extract Commands
+- **Before:** "Don't manually write commands if they exist in:"
+- **After:** "When extracting commands, automate extraction from:"
+- Positive framing with clear directive
+
+## Impact Analysis
+
+**Readability:** Improved - clearer action-oriented instructions
+**Consistency:** Aligned with skill-creator best practices
+**Usability:** Enhanced - readers know when and how to apply each pattern
+**Structure:** Maintained all examples while improving presentation
+
+## Files Modified
+
+- `/SKILL.md` (lines 1-400)
+
+## Verification
+
+- Version number updated in YAML frontmatter: ✓
+- Best Practices converted to imperative form: ✓
+- All guidance remains intact: ✓
+- No broken internal references: ✓
--- a/composer.json
+++ b/composer.json
@@ -0,0 +1,21 @@
+{
+  "name": "netresearch/agents-skill",
+  "description": "Generate and maintain AGENTS.md files following the public agents.md convention",
+  "type": "ai-agent-skill",
+  "license": "GPL-2.0-or-later",
+  "authors": [
+    {
+      "name": "Netresearch DTT GmbH",
+      "email": "plugins@netresearch.de",
+      "homepage": "https://www.netresearch.de/",
+      "role": "Manufacturer"
+    }
+  ],
+  "require": {
+    "netresearch/composer-agent-skill-plugin": "*"
+  },
+  "keywords": [
+    "ai-agent",
+    "skill"
+  ]
+}
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,153 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:netresearch/claude-code-marketplace:skills/agents",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "67fb566c43c2efc08d5c3df47b44f56d2f3e6477",
+    "treeHash": "3caa289a90b8282766f02e812cd98175c73ad5a46a126850b6214ab053cb28e6",
+    "generatedAt": "2025-11-28T10:27:20.284373Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "agents",
+    "description": "Generate and maintain AGENTS.md files following the public agents.md convention. Creates thin root files with precedence rules, scoped files for subsystems, auto-extracts commands from build tools, and supports Go, PHP, TypeScript, and Python projects with language-specific templates.",
+    "version": "1.1.0-20251125"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "LICENSE",
+        "sha256": "b4aa20b52533f8ab363e465f07d9e26ad92dac6e250b650c8947c99d6ee466e0"
+      },
+      {
+        "path": "STATUS.md",
+        "sha256": "a656b07890efb13577aa36e08becaded05e86e72e4fe09cc147d2edff921b71d"
+      },
+      {
+        "path": "README.md",
+        "sha256": "78949a278b3d0162e0665bfb5ecf5894f4052b0fabc76a62c0183782997d426a"
+      },
+      {
+        "path": ".gitignore",
+        "sha256": "03d5d046fa175e5d6ea564d562ffbd2a555e964b0a91d3ce04af8bc54f3a54ab"
+      },
+      {
+        "path": "SKILL.md",
+        "sha256": "ee7db7e9bdc267a2ae2e45fae3996af707eee3be49b9a9387e1286c449d642a2"
+      },
+      {
+        "path": "composer.json",
+        "sha256": "0c5d90b317084fbadf5b68d7c82f384ea38fb7077ad2f53a3eccd1e923c0b85d"
+      },
+      {
+        "path": "references/analysis.md",
+        "sha256": "2a24ab56d49577acfd6818a7243fd3ef1dc518d55196a379deacace140a9012c"
+      },
+      {
+        "path": "references/examples/coding-agent-cli/scripts-AGENTS.md",
+        "sha256": "fb68e9b8fdd0a38887edb23adf8a80270635b6d66c6063b5e5c9049217193aca"
+      },
+      {
+        "path": "references/examples/coding-agent-cli/AGENTS.md",
+        "sha256": "0012cbc25474d641e1f43714e4728082a2f8106323880fe91959f4b785eeb7ef"
+      },
+      {
+        "path": "references/examples/ldap-selfservice/internal-AGENTS.md",
+        "sha256": "587e67c42b0b273c3a1a7291c1cd481380aeac33693e0314c48908344efa3c5f"
+      },
+      {
+        "path": "references/examples/ldap-selfservice/internal-web-AGENTS.md",
+        "sha256": "fe8aaf9130a6f35e4a93dd91fd477088fe0e6fc8d9b046473b02c7491ef7774e"
+      },
+      {
+        "path": "references/examples/ldap-selfservice/AGENTS.md",
+        "sha256": "12e0d8102ff9a8d9afe58a6c62f5f80dfbab6a852a812d9d14ffbc2cf6167f7e"
+      },
+      {
+        "path": "references/examples/t3x-rte-ckeditor-image/Classes-AGENTS.md",
+        "sha256": "18c70510d702bdb19f0635cf56b7fd1d43f33b261195c08a076bda7cdb6e47ef"
+      },
+      {
+        "path": "references/examples/t3x-rte-ckeditor-image/AGENTS.md",
+        "sha256": "07b74ea78fa432057a660207cf0359a9fccab3823329a47a506c77f2b2e71d7a"
+      },
+      {
+        "path": "references/examples/simple-ldap-go/examples-AGENTS.md",
+        "sha256": "883911058ad0c8c48da8486897c90f029a19658986f017bf1bde5ddc54eeffc7"
+      },
+      {
+        "path": "references/examples/simple-ldap-go/AGENTS.md",
+        "sha256": "b7f17e8beca30c42f40a7285d6c0043a67807181de5703aff2bce9e9c73ab072"
+      },
+      {
+        "path": "claudedocs/refactoring-summary.md",
+        "sha256": "eddf1114e3997c29e57d31133cf5a98e5cac0eabdefb06897328851f7b67cedd"
+      },
+      {
+        "path": "scripts/validate-structure.sh",
+        "sha256": "60789bd917958d125638f94479e6501e51d2d0f5d5373a4e33970f5f7710c848"
+      },
+      {
+        "path": "scripts/detect-scopes.sh",
+        "sha256": "a02b0147487009e754b658f84d48c47b4a45e46a0345616686a2aaf72bbe7967"
+      },
+      {
+        "path": "scripts/extract-commands.sh",
+        "sha256": "0ee80d781d8b031a0c626da4206321c747084b675c70fb8cc3e1303b2c1b4fc5"
+      },
+      {
+        "path": "scripts/generate-agents.sh",
+        "sha256": "3d50161327537782bde5d322e9e5fb6c83cd059e2d487212bcee0c72dd2dfe7a"
+      },
+      {
+        "path": "scripts/detect-project.sh",
+        "sha256": "403b1324a978ec99c0c99c70314de1b97136cc3dd23eb131e2e72389d7a5980c"
+      },
+      {
+        "path": "scripts/lib/template.sh",
+        "sha256": "4b30b4d85a30eea9ff5f9a36085b34a757396fde3058c734c869c640b18d9e17"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "4d106bd89bda56ab9f230ac02e05da20e3c3d302ae78b149fa0a3aa40081499b"
+      },
+      {
+        "path": "templates/root-verbose.md",
+        "sha256": "de9d263062471fc8f1fc154729a9a521acef48fda771ffee15f8a1803fd86e2c"
+      },
+      {
+        "path": "templates/root-thin.md",
+        "sha256": "686a97e5d5dd69ecbf567059167b35dde87a0691d6c5f69eac0759039b0bf71d"
+      },
+      {
+        "path": "templates/scoped/backend-go.md",
+        "sha256": "f1aad3498ac26177fdbbe69d07196b17b129fde9538e3d600754df686f26ee9d"
+      },
+      {
+        "path": "templates/scoped/cli.md",
+        "sha256": "c54098b6a5547639c7abc2403994495b96e61072b4e94d3bcb1bec749a611201"
+      },
+      {
+        "path": "templates/scoped/frontend-typescript.md",
+        "sha256": "c8024e783a228ad367679b2f961760fd3bf79bfb3b290c9c9d70c197626867a1"
+      },
+      {
+        "path": "templates/scoped/backend-php.md",
+        "sha256": "8956f7006f8a8fc13da61e9be3abde9711c7fd94fe533dd8fdfa8b3a966a6c80"
+      }
+    ],
+    "dirSha256": "3caa289a90b8282766f02e812cd98175c73ad5a46a126850b6214ab053cb28e6"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
--- a/references/analysis.md
+++ b/references/analysis.md
@@ -0,0 +1,320 @@
+# AGENTS.md Analysis Across 6 Netresearch Projects
+
+## Executive Summary
+
+**Total AGENTS.md Files Found**: 21 files across 6 projects
+
+**Patterns Observed**:
+1. **Root files are thin** (26-348 lines) with precedence rules and global defaults
+2. **Scoped files are focused** on specific subsystems (backend, frontend, CLI, etc.)
+3. **Managed header** present in newer files: `<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: YYYY-MM-DD -->`
+4. **Consistent structure** following the 9-section schema from your prompt
+
+## File Distribution
+
+| Project | Root | Scoped Files | Total Lines (root) |
+|---------|------|--------------|-------------------|
+| t3x-rte_ckeditor_image | ✅ | Classes/, Documentation/, Resources/, Tests/ | 348 |
+| coding_agent_cli_toolset | ✅ | scripts/ | 308 |
+| ldap-selfservice-password-changer | ✅ | internal/, internal/web/ | 282 |
+| ldap-manager | ✅ | cmd/, internal/, internal/web/, scripts/ | 228 |
+| raybeam | ✅ | cmd/, internal/ | 209 |
+| simple-ldap-go | ✅ | docs/, examples/, testutil/ | 26 ⭐ **Perfect thin root** |
+
+## Key Findings
+
+### 1. **simple-ldap-go** is the Best Example ⭐
+
+**Root file** (26 lines):
+- Minimal global rules
+- Clear precedence statement
+- Index of scoped files
+- No duplication with scoped content
+
+```markdown
+## Global rules
+- Keep diffs small; add tests for new code paths
+- Ask first before: adding heavy deps, running full e2e suites, or repo-wide rewrites
+
+## Minimal pre-commit checks
+- Typecheck (all packages): `go build -v ./...`
+- Lint/format (file scope): `gofmt -w <file.go>`
+- Unit tests (fast): `go test -v -race -short -timeout=10s ./...`
+
+## Index of scoped AGENTS.md
+- `./examples/AGENTS.md` — Example applications
+- `./testutil/AGENTS.md` — Testing utilities
+- `./docs/AGENTS.md` — Documentation
+```
+
+### 2. Scoped Files Follow 9-Section Schema
+
+**Example: simple-ldap-go/examples/AGENTS.md**:
+1. ✅ Overview
+2. ✅ Setup & environment  
+3. ✅ Build & tests (file-scoped)
+4. ✅ Code style & conventions
+5. ✅ Security & safety
+6. ✅ PR/commit checklist
+7. ✅ Good vs. bad examples
+8. ✅ When stuck
+9. ⚠️  House Rules (rarely used, only when overriding)
+
+### 3. Managed Header Usage
+
+**Present in** (newer projects):
+- simple-ldap-go (all files)
+- ldap-selfservice-password-changer (all files)
+- raybeam (some files)
+
+**Missing in** (older projects):
+- t3x-rte_ckeditor_image
+- coding_agent_cli_toolset
+
+**Format**:
+```html
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
+```
+
+### 4. Precedence Rules - Consistent Pattern
+
+All root files establish precedence clearly:
+
+**Pattern 1** (verbose):
+> "This file explains repo-wide conventions and where to find scoped rules. **Precedence:** the **closest `AGENTS.md`** to the files you're changing wins. Root holds global defaults only."
+
+**Pattern 2** (concise):
+> "**Precedence**: Nearest AGENTS.md wins. This is the root file with global defaults."
+
+**Pattern 3** (index-focused):
+> "## Precedence & Scoped Files  
+> Nearest AGENTS.md wins. Use this root for defaults only."
+
+### 5. Docker-First vs Native-First
+
+**Docker-first projects** (ldap-selfservice-password-changer, ldap-manager):
+```markdown
+### Setup
+**Prerequisites**: Docker + Docker Compose (required), Go 1.25+, Node.js 24+, pnpm 10.18+ (for native dev)
+
+# Docker (recommended)
+docker compose --profile dev up
+
+# Native development
+pnpm install
+```
+
+**Native-first projects** (simple-ldap-go, t3x-rte_ckeditor_image):
+```markdown
+### Setup
+**Prerequisites**: Go 1.24, golangci-lint
+
+# Install
+go mod download
+```
+
+### 6. Language-Specific Patterns
+
+**Go Projects** (simple-ldap-go, ldap-manager, raybeam):
+- Minimal pre-commit: `go build -v ./...`, `gofmt -w`, `go test -short`
+- Go version in global rules (1.24, 1.25)
+- golangci-lint for comprehensive checks
+
+**PHP Project** (t3x-rte_ckeditor_image):
+- Composer scripts for CI pipeline
+- PHPStan + PHP-CS-Fixer + Rector
+- Make targets preferred over composer commands
+
+**Hybrid Projects** (ldap-selfservice-password-changer):
+- Separate sections for Go backend vs TypeScript frontend
+- Scoped AGENTS.md for `internal/` (Go) and `internal/web/` (TS)
+- pnpm for package management (strict version)
+
+### 7. Quick Start Patterns
+
+**Best practice** (ldap-selfservice-password-changer):
+```markdown
+## Quick Navigation
+- [internal/AGENTS.md](internal/AGENTS.md) - Go backend services
+- [internal/web/AGENTS.md](internal/web/AGENTS.md) - TypeScript frontend
+```
+
+**Alternative** (simple-ldap-go):
+```markdown
+## Index of scoped AGENTS.md
+- `./examples/AGENTS.md` — Example applications and usage patterns
+- `./testutil/AGENTS.md` — Testing utilities and container management
+```
+
+### 8. House Rules Implementation
+
+**Global defaults** typically include:
+- Commits: Conventional Commits, small PRs (~≤300 LOC)
+- Type-safety: Strict types when supported
+- SOLID, KISS, DRY, YAGNI principles
+- SemVer for versioning
+- No secrets in VCS
+- Structured logging
+- WCAG AA for UI projects
+
+**Scoped overrides** (rare):
+- Different test coverage targets per module
+- Module-specific commit conventions
+- Technology-specific style guides
+
+### 9. Common Gaps Across Projects
+
+❌ **Missing .envrc** in most projects (your prompt requires it)
+❌ **Missing .editorconfig** in some projects
+❌ **Husky + commitlint** not universally adopted
+❌ **lint-staged** not implemented in older projects
+❌ **CI parity section** often missing (should reference GitHub Actions)
+
+## Recommendations for Your Skill
+
+### Essential Features
+
+1. **Template Selection**:
+   - Thin root (simple-ldap-go style) ⭐
+   - Verbose root (ldap-selfservice-password-changer style)
+   - Auto-detect based on project size
+
+2. **Project Type Detection**:
+   - Go: Look for `go.mod`, detect version from `go.mod` directive
+   - PHP: Look for `composer.json`, detect TYPO3 from dependencies
+   - TypeScript: Look for `tsconfig.json`, detect strict mode
+   - Hybrid: Detect multiple languages, recommend scoped files
+
+3. **Scoped File Generation**:
+   - **Required scopes**: backend/, frontend/, internal/
+   - **Optional scopes**: cmd/, scripts/, examples/, docs/, testutil/
+   - **Auto-create** if directory exists and has ≥5 files
+
+4. **Content Extraction**:
+   - **Makefile**: Extract targets with `##` comments → Build & Test Commands
+   - **package.json scripts**: Extract npm/pnpm commands
+   - **go.mod**: Extract Go version → Prerequisites
+   - **composer.json scripts**: Extract PHP quality commands
+   - **GitHub Actions**: Extract CI checks → PR/commit checklist
+
+5. **Managed Header**:
+   - Always add to new files
+   - Preserve in existing files
+   - Update timestamp on regeneration
+
+6. **Precedence Rules**:
+   - Auto-add "Nearest AGENTS.md wins" statement
+   - Generate index of scoped files in root
+   - Link from root to scoped files
+
+### Skill Structure Recommendation
+
+```
+agents-skill/
+├── SKILL.md
+├── README.md
+├── templates/
+│   ├── root-thin.md          # simple-ldap-go style (recommended)
+│   ├── root-verbose.md       # ldap-selfservice style
+│   ├── scoped-backend.md     # Go/PHP backend
+│   ├── scoped-frontend.md    # TypeScript/JS frontend
+│   ├── scoped-cli.md         # CLI tools
+│   ├── scoped-docs.md        # Documentation
+│   ├── scoped-tests.md       # Testing utilities
+│   └── sections/             # Modular sections
+│       ├── header.md         # Managed header template
+│       ├── precedence.md     # Precedence statement
+│       ├── setup.md          # Setup section
+│       ├── build-commands.md # Build & test commands
+│       ├── code-style.md     # Code style guidelines
+│       ├── security.md       # Security practices
+│       ├── pr-checklist.md   # PR/commit checklist
+│       ├── examples.md       # Good vs bad examples
+│       └── when-stuck.md     # When stuck guidance
+├── scripts/
+│   ├── generate-agents.sh    # Main generator
+│   ├── detect-project.sh     # Auto-detect project type
+│   ├── extract-commands.sh   # Extract from Makefile/package.json
+│   └── validate-structure.sh # Validate generated files
+└── references/
+    ├── examples/             # Real-world examples
+    │   ├── go-library.md     # simple-ldap-go
+    │   ├── go-web-app.md     # ldap-manager
+    │   ├── php-typo3.md      # t3x-rte_ckeditor_image
+    │   └── hybrid-app.md     # ldap-selfservice-password-changer
+    └── best-practices.md     # AGENTS.md writing guide
+```
+
+### Key Differentiators
+
+✅ **Thin root by default** (not verbose like some projects)
+✅ **Auto-scope detection** (create scoped files when needed)
+✅ **Command extraction** (don't make user write commands manually)
+✅ **Managed header** (mark files as agent-maintained)
+✅ **Language-agnostic** (works with Go, PHP, TypeScript, Python, etc.)
+✅ **Idempotent** (can be re-run without breaking existing structure)
+
+## Sample Output Comparison
+
+### Your Prompt's Expected Output
+
+**Root AGENTS.md** (following simple-ldap-go pattern):
+```markdown
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-18 -->
+
+# AGENTS.md (root)
+
+**Precedence:** The **closest AGENTS.md** to changed files wins. Root holds global defaults only.
+
+## Global rules
+- Keep PRs small (~≤300 net LOC)
+- Conventional Commits: type(scope): subject
+- Ask before: heavy deps, full e2e, repo rewrites
+- Never commit secrets or PII
+
+## Minimal pre-commit checks
+- Typecheck: [auto-detected command]
+- Lint: [auto-detected command]
+- Format: [auto-detected command]
+- Tests: [auto-detected command]
+
+## Index of scoped AGENTS.md
+- `./internal/AGENTS.md` — Go backend services
+- `./internal/web/AGENTS.md` — TypeScript frontend
+
+## When instructions conflict
+Nearest AGENTS.md wins. User prompts override files.
+```
+
+**Scoped AGENTS.md** (e.g., internal/AGENTS.md):
+```markdown
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-18 -->
+
+# AGENTS.md — Backend Services
+
+## Overview
+[Auto-generated description of internal/ directory purpose]
+
+## Setup & environment
+[Auto-detected from go.mod, .env.example]
+
+## Build & tests (prefer file-scoped)
+[Auto-extracted from Makefile, go commands]
+
+## Code style & conventions
+[Auto-detected from golangci-lint config, gofmt]
+
+## Security & safety
+[Standard Go security practices + project-specific]
+
+## PR/commit checklist
+[Auto-extracted from GitHub Actions, Makefile]
+
+## Good vs. bad examples
+[Template with placeholders to fill]
+
+## When stuck
+- Check root AGENTS.md for global rules
+- Review sibling modules for patterns
+```
+
--- a/references/examples/coding-agent-cli/AGENTS.md
+++ b/references/examples/coding-agent-cli/AGENTS.md
@@ -0,0 +1,308 @@
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
+
+# AI CLI Preparation - Agent Guide (Root)
+
+**Thin root file**: See scoped AGENTS.md files for specific areas.
+
+## Precedence & Scoped Files
+
+This root AGENTS.md provides global defaults. **Nearest AGENTS.md wins** for specific rules.
+
+**Scoped files:**
+- [scripts/AGENTS.md](scripts/AGENTS.md) - Shell installation scripts
+
+## Overview
+
+AI CLI Preparation is an environment audit tool ensuring AI coding agents (like Claude Code) have access to necessary developer tools. It detects 50+ tools, reports versions, and provides installation guidance.
+
+**Architecture:**
+- **Phase 1 (Complete)**: Tool detection, version auditing, offline-first caching
+- **Phase 2 (Planned)**: Context-aware installation/upgrade management (see [docs/PRD.md](docs/PRD.md))
+
+**Tech Stack:**
+- Python 3.10+ (standard library only, no external deps for core)
+- Make for task automation
+- Shell scripts (Bash) for installation
+- JSON for caching (latest_versions.json, tools_snapshot.json)
+
+**Key Files:**
+- `cli_audit.py` (2,375 lines): Main audit engine, 50+ tool definitions
+- `smart_column.py`: ANSI/emoji-aware table formatting
+- `scripts/`: 13+ installation scripts (install/update/uninstall/reconcile)
+- `docs/`: Comprehensive technical documentation (12 files, 189KB)
+
+## Setup
+
+**Requirements:**
+- Python 3.10+ (Python 3.14.0rc2 tested)
+- Standard library only (no pip install needed for core)
+- Optional: pyflakes for linting
+
+**First-time setup:**
+```bash
+# Allow direnv (if using)
+direnv allow
+
+# Show available commands
+make help
+
+# Update snapshot (requires network)
+make update
+
+# Run audit from snapshot (fast, offline-capable)
+make audit
+```
+
+**Environment variables:**
+```bash
+# See .env.default for all options
+CLI_AUDIT_COLLECT=1      # Collect-only mode (write snapshot)
+CLI_AUDIT_RENDER=1       # Render-only mode (read snapshot)
+CLI_AUDIT_OFFLINE=1      # Offline mode (manual cache only)
+CLI_AUDIT_DEBUG=1        # Debug output
+CLI_AUDIT_JSON=1         # JSON output
+```
+
+## Build & Tests
+
+**Primary commands:**
+```bash
+make audit               # Render from snapshot (no network, <100ms)
+make update              # Collect fresh data, write snapshot (~10s)
+make audit-offline       # Offline audit with hints
+make lint                # Run pyflakes (if installed)
+make upgrade             # Interactive upgrade guide
+```
+
+**Single tool audit:**
+```bash
+make audit-ripgrep       # Audit specific tool
+make audit-offline-python-core  # Role-based preset
+```
+
+**Installation scripts:**
+```bash
+make install-python      # Install Python toolchain (uv)
+make install-node        # Install Node.js (nvm)
+make install-core        # Install core tools (fd, fzf, ripgrep, jq, etc.)
+```
+
+**Testing:**
+```bash
+# Smoke test (verifies table output and JSON format)
+./scripts/test_smoke.sh
+
+# Test single tool detection
+CLI_AUDIT_DEBUG=1 python3 cli_audit.py --only ripgrep
+
+# Validate snapshot
+jq '.__meta__' tools_snapshot.json
+```
+
+**No formal test suite yet** - README acknowledges: "currently ships without tests"
+- Smoke tests exist (test_smoke.sh)
+- Manual validation workflows documented
+
+## Code Style
+
+**Python:**
+- PEP 8 style (4-space indent, snake_case)
+- Type hints used (`from __future__ import annotations`)
+- Frozen dataclasses for immutability (`@dataclass(frozen=True)`)
+- Docstrings minimal (focus on inline comments)
+
+**Formatting:**
+- EditorConfig enforced: LF, UTF-8, 4 spaces, trim trailing whitespace
+- No auto-formatter configured (manual formatting)
+- Lint via pyflakes: `make lint`
+
+**Shell scripts:**
+- Bash with `set -euo pipefail`
+- Shellcheck-compliant (best effort)
+- Consistent error handling (see scripts/lib/)
+
+**Conventions:**
+- File paths: Absolute paths, no auto-commit
+- Functions: Snake_case, descriptive names
+- Constants: UPPER_CASE (e.g., MANUAL_LOCK, HINTS_LOCK)
+- Lock ordering: MANUAL_LOCK → HINTS_LOCK (enforced for safety)
+
+## Security
+
+**Secrets:**
+- No secrets in VCS
+- GITHUB_TOKEN optional (for GitHub API rate limit increase)
+- Set via environment: `export GITHUB_TOKEN=ghp_...`
+
+**Network:**
+- HTTPS-only for upstream queries
+- Retry logic with exponential backoff
+- Per-origin rate limits (GitHub: 5/min, PyPI: 10/min, crates.io: 5/min)
+- Timeout enforcement (default: 3s, configurable)
+
+**Input validation:**
+- Tool names validated against TOOLS registry
+- Version strings sanitized (extract_version_number)
+- Subprocess calls use lists, not shell=True (where possible)
+
+**Caching:**
+- Atomic file writes prevent corruption
+- Offline-first design (committed latest_versions.json)
+- No arbitrary code execution (package manager commands only)
+
+## PR/Commit Checklist
+
+**Before commit:**
+- [ ] Run `make lint` (pyflakes clean)
+- [ ] Run `make audit` (verify snapshot renders)
+- [ ] Test affected tool: `make audit-<tool>`
+- [ ] Update docs if behavior changed (README.md, docs/, scripts/README.md)
+- [ ] Add/update smoke test if new output format
+
+**Commit messages:**
+- Conventional Commits format: `type(scope): description`
+- Examples:
+  - `feat(audit): add snapshot-based collect/render modes`
+  - `fix(locks): enforce MANUAL_LOCK→HINTS_LOCK ordering`
+  - `docs(prd): add Phase 2 specifications and ADRs`
+  - `chore(cache): update latest_versions.json`
+
+**Pull requests:**
+- Keep PRs small (~≤300 net LOC changed)
+- Link to issue/ticket if exists
+- Update CHANGELOG section in PR description
+- Ensure CI passes (when added)
+
+## Good vs Bad Examples
+
+**Good: Atomic dataclass with type safety**
+```python
+@dataclass(frozen=True)
+class Tool:
+    name: str
+    candidates: tuple[str, ...]
+    source_kind: str  # gh|pypi|crates|npm|gnu|skip
+    source_args: tuple[str, ...]
+```
+
+**Bad: Mutable dict with unclear types**
+```python
+# Don't do this
+tool = {
+    'name': 'ripgrep',
+    'candidates': ['rg'],  # List instead of tuple
+    'source': 'github',     # Unclear allowed values
+}
+```
+
+**Good: Lock ordering enforcement**
+```python
+def update_manual_cache(tool: str, version: str) -> None:
+    with MANUAL_LOCK:  # Acquire first
+        with HINTS_LOCK:  # Then hints
+            # Safe: consistent ordering prevents deadlock
+```
+
+**Bad: Lock ordering violation**
+```python
+def update_cache(tool: str) -> None:
+    with HINTS_LOCK:    # Wrong order!
+        with MANUAL_LOCK:
+            # Deadlock risk
+```
+
+**Good: Parallel execution with isolation**
+```python
+with ThreadPoolExecutor(max_workers=16) as executor:
+    futures = [executor.submit(audit_tool, tool) for tool in TOOLS]
+    for future in as_completed(futures):
+        result = future.result()  # Failures isolated
+```
+
+**Bad: Sequential execution**
+```python
+results = []
+for tool in TOOLS:  # Slow: 50 tools * 3s = 150s
+    results.append(audit_tool(tool))
+```
+
+## When Stuck
+
+**Tool detection failing:**
+1. Check PATH: `echo $PATH | tr ':' '\n'`
+2. Debug single tool: `CLI_AUDIT_DEBUG=1 python3 cli_audit.py --only <tool>`
+3. Check version flag: `<tool> --version` or `<tool> -v`
+4. See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md#version-detection-failures)
+
+**Network issues:**
+1. Increase timeout: `CLI_AUDIT_TIMEOUT_SECONDS=10 make update`
+2. More retries: `CLI_AUDIT_HTTP_RETRIES=5 make update`
+3. Use offline mode: `make audit-offline`
+4. See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md#network-timeout-issues)
+
+**Cache corruption:**
+1. Remove caches: `rm latest_versions.json tools_snapshot.json`
+2. Regenerate: `make update`
+
+**Installation script fails:**
+1. Check permissions: `make scripts-perms`
+2. Debug script: `bash -x ./scripts/install_<tool>.sh`
+3. See [scripts/README.md](scripts/README.md) for per-script troubleshooting
+
+**Documentation:**
+- Start with [docs/QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md) for one-liners
+- See [docs/INDEX.md](docs/INDEX.md) for navigation by role/task
+- Architecture details: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- API reference: [docs/API_REFERENCE.md](docs/API_REFERENCE.md)
+
+## House Rules
+
+**Defaults** (override in scoped AGENTS.md if needed):
+
+**Commits:**
+- Atomic commits (single logical change)
+- Conventional Commits: `type(scope): description`
+- Keep PRs small (~≤300 net LOC changed)
+- Ticket IDs in commits/PRs if exists
+
+**Type-safety:**
+- Use type hints (`from __future__ import annotations`)
+- Frozen dataclasses for immutability
+- No `Any` unless truly dynamic
+
+**Design principles:**
+- SOLID, KISS, DRY, YAGNI
+- Composition > Inheritance
+- Law of Demeter (minimal coupling)
+
+**Dependencies:**
+- Standard library preferred (no external Python deps for core)
+- Latest stable versions when external deps needed
+- Document why in Decision Log (ADRs for Phase 2)
+
+**Security:**
+- No secrets in VCS
+- HTTPS-only for network calls
+- No arbitrary code execution
+- Input validation on external data
+
+**Documentation currency:**
+- Update docs in same PR as behavior changes
+- No drift between code and docs
+- Document non-obvious decisions in ADRs (see docs/adr/)
+
+**Testing:**
+- Aim for ≥80% coverage on changed code (when test suite added)
+- Bugfixes use TDD: failing test first, then fix
+- New code paths need tests (future requirement)
+
+**Current status:**
+- Phase 1: Production-ready detection/audit
+- Phase 2: Planned installation/upgrade (see [docs/PRD.md](docs/PRD.md))
+- No unit tests yet (acknowledged in README)
+
+---
+
+**Quick Start:** New to the project? Start with [README.md](README.md) → [docs/QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md) → [docs/INDEX.md](docs/INDEX.md)
+
+**Contributing:** See [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) for detailed contribution guide
--- a/references/examples/coding-agent-cli/scripts-AGENTS.md
+++ b/references/examples/coding-agent-cli/scripts-AGENTS.md
@@ -0,0 +1,389 @@
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
+
+# Installation Scripts - Agent Guide
+
+**Scope:** Shell scripts for tool installation, update, uninstall, reconcile
+
+## Overview
+
+13+ Bash scripts for installing developer tools with multiple actions:
+- **install**: Fresh installation (default action)
+- **update**: Upgrade to latest version
+- **uninstall**: Remove installation
+- **reconcile**: Switch to preferred installation method (e.g., system → user)
+
+**Key scripts:**
+- `install_core.sh`: Core tools (fd, fzf, ripgrep, jq, yq, bat, delta, just)
+- `install_python.sh`: Python toolchain via uv
+- `install_node.sh`: Node.js via nvm
+- `install_rust.sh`: Rust via rustup
+- `install_go.sh`, `install_aws.sh`, `install_kubectl.sh`, etc.
+- `guide.sh`: Interactive upgrade guide
+- `test_smoke.sh`: Smoke test for audit output
+
+**Shared utilities:** `lib/` directory (colors, logging, common functions)
+
+## Setup
+
+**Requirements:**
+- Bash 4.0+
+- `curl` or `wget` for downloads
+- Internet access for fresh installs
+- Appropriate permissions (user for `~/.local/bin`, sudo for system)
+
+**Environment variables:**
+```bash
+INSTALL_PREFIX=${INSTALL_PREFIX:-~/.local}  # Default: user-level
+FORCE_INSTALL=1                              # Skip confirmation prompts
+DEBUG=1                                      # Verbose output
+```
+
+**Permissions:**
+```bash
+make scripts-perms  # Ensure all scripts are executable
+```
+
+## Build & Tests
+
+**Run individual script:**
+```bash
+# Install action (default)
+./scripts/install_python.sh
+
+# Update action
+./scripts/install_python.sh update
+
+# Uninstall action
+./scripts/install_python.sh uninstall
+
+# Reconcile action (switch installation method)
+./scripts/install_node.sh reconcile
+```
+
+**Via Make:**
+```bash
+make install-python              # Install Python toolchain
+make update-python               # Update Python toolchain
+make uninstall-python            # Uninstall Python toolchain
+make reconcile-node              # Switch Node.js to nvm-managed
+```
+
+**Smoke test:**
+```bash
+./scripts/test_smoke.sh          # Verify audit output format
+```
+
+**Debug mode:**
+```bash
+DEBUG=1 ./scripts/install_python.sh
+bash -x ./scripts/install_python.sh  # Trace execution
+```
+
+## Code Style
+
+**Shell standards:**
+- Bash 4.0+ features allowed
+- Shebang: `#!/usr/bin/env bash` or `#!/bin/bash`
+- Set strict mode: `set -euo pipefail`
+  - `-e`: Exit on error
+  - `-u`: Error on undefined variables
+  - `-o pipefail`: Fail on pipe errors
+
+**Formatting:**
+- 4-space indentation (matches EditorConfig)
+- Function names: lowercase_with_underscores
+- Constants: UPPER_CASE
+- Local variables: lowercase
+
+**Structure:**
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Source shared utilities
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/lib/colors.sh" || true
+source "${SCRIPT_DIR}/lib/common.sh" || true
+
+# Main function per action
+install_tool() {
+    echo_info "Installing <tool>..."
+    # Implementation
+}
+
+update_tool() {
+    echo_info "Updating <tool>..."
+    # Implementation
+}
+
+uninstall_tool() {
+    echo_info "Uninstalling <tool>..."
+    # Implementation
+}
+
+reconcile_tool() {
+    echo_info "Reconciling <tool>..."
+    # Implementation
+}
+
+# Action dispatcher
+ACTION="${1:-install}"
+case "$ACTION" in
+    install) install_tool ;;
+    update) update_tool ;;
+    uninstall) uninstall_tool ;;
+    reconcile) reconcile_tool ;;
+    *) echo "Usage: $0 {install|update|uninstall|reconcile}"; exit 1 ;;
+esac
+```
+
+**Error handling:**
+```bash
+# Good: Check command exists before using
+if ! command -v curl >/dev/null 2>&1; then
+    echo_error "curl not found. Install it first."
+    exit 1
+fi
+
+# Good: Check return codes
+if ! download_file "$URL" "$DEST"; then
+    echo_error "Download failed"
+    exit 1
+fi
+
+# Good: Cleanup on error
+trap 'rm -rf "$TMPDIR"' EXIT ERR
+```
+
+**Confirmation prompts:**
+```bash
+# Good: Skip prompt if FORCE_INSTALL=1
+if [[ "${FORCE_INSTALL:-0}" != "1" ]]; then
+    read -p "Install <tool>? [y/N] " -n 1 -r
+    echo
+    [[ ! $REPLY =~ ^[Yy]$ ]] && exit 0
+fi
+```
+
+## Security
+
+**Download verification:**
+```bash
+# Always use HTTPS
+URL="https://github.com/owner/repo/releases/download/..."
+
+# Verify checksums when available
+EXPECTED_SHA256="abc123..."
+ACTUAL_SHA256=$(sha256sum "$FILE" | awk '{print $1}')
+if [[ "$ACTUAL_SHA256" != "$EXPECTED_SHA256" ]]; then
+    echo_error "Checksum mismatch!"
+    exit 1
+fi
+```
+
+**Path safety:**
+```bash
+# Good: Quote variables, use absolute paths
+INSTALL_DIR="${HOME}/.local/bin"
+mkdir -p "$INSTALL_DIR"
+mv "$TMPFILE" "$INSTALL_DIR/tool"
+
+# Bad: Unquoted, relative paths
+mkdir -p $INSTALL_DIR
+mv tool bin/
+```
+
+**Sudo usage:**
+```bash
+# Good: Prompt for sudo only when needed
+if [[ "$INSTALL_PREFIX" == "/usr/local" ]]; then
+    if ! sudo -v; then
+        echo_error "Sudo required for system installation"
+        exit 1
+    fi
+    sudo mv "$FILE" "$INSTALL_PREFIX/bin/"
+else
+    # User-level, no sudo
+    mv "$FILE" "$INSTALL_PREFIX/bin/"
+fi
+```
+
+**No secrets in scripts:**
+- No API keys, tokens, passwords in scripts
+- Use environment variables: `${GITHUB_TOKEN:-}`
+- Document required env vars in script comments
+
+## PR/Commit Checklist
+
+**Before commit:**
+- [ ] Run `shellcheck <script>` (if available)
+- [ ] Test install action: `./scripts/install_<tool>.sh`
+- [ ] Test update action: `./scripts/install_<tool>.sh update`
+- [ ] Test uninstall action: `./scripts/install_<tool>.sh uninstall`
+- [ ] Update `scripts/README.md` if new script or behavior change
+- [ ] Verify script permissions: `make scripts-perms`
+
+**Script checklist:**
+- [ ] Shebang: `#!/usr/bin/env bash`
+- [ ] Strict mode: `set -euo pipefail`
+- [ ] Source shared lib: `source "${SCRIPT_DIR}/lib/colors.sh"`
+- [ ] Action dispatcher (install/update/uninstall/reconcile)
+- [ ] Error handling (check return codes, trap on exit)
+- [ ] Confirmation prompts (respect FORCE_INSTALL)
+- [ ] PATH updates (add to ~/.bashrc or ~/.zshrc if needed)
+
+**Commit messages:**
+- `feat(scripts): add install_terraform.sh`
+- `fix(install-python): handle uv bootstrap failure`
+- `docs(scripts): update README with reconcile action`
+
+## Good vs Bad Examples
+
+**Good: Robust download with fallback**
+```bash
+download_file() {
+    local url="$1"
+    local dest="$2"
+
+    if command -v curl >/dev/null 2>&1; then
+        curl -fsSL "$url" -o "$dest"
+    elif command -v wget >/dev/null 2>&1; then
+        wget -q "$url" -O "$dest"
+    else
+        echo_error "Neither curl nor wget found"
+        return 1
+    fi
+}
+```
+
+**Bad: Assumes curl exists**
+```bash
+download_file() {
+    curl -fsSL "$1" -o "$2"  # Fails if curl not installed
+}
+```
+
+**Good: Version comparison**
+```bash
+version_gt() {
+    test "$(printf '%s\n' "$@" | sort -V | head -n 1)" != "$1"
+}
+
+CURRENT_VERSION="1.2.3"
+LATEST_VERSION="1.3.0"
+
+if version_gt "$LATEST_VERSION" "$CURRENT_VERSION"; then
+    echo "Upgrade available"
+fi
+```
+
+**Bad: String comparison for versions**
+```bash
+if [[ "$LATEST_VERSION" > "$CURRENT_VERSION" ]]; then
+    # Wrong: "1.10.0" < "1.9.0" (string comparison)
+    echo "Upgrade available"
+fi
+```
+
+**Good: Cleanup on exit**
+```bash
+TMPDIR=$(mktemp -d)
+trap 'rm -rf "$TMPDIR"' EXIT ERR
+
+# Download to temp
+download_file "$URL" "$TMPDIR/file"
+# ... process ...
+# Cleanup happens automatically via trap
+```
+
+**Bad: Manual cleanup (error-prone)**
+```bash
+TMPDIR=$(mktemp -d)
+download_file "$URL" "$TMPDIR/file"
+# ... process ...
+rm -rf "$TMPDIR"  # Skipped if earlier command fails
+```
+
+**Good: Action-specific logic**
+```bash
+install_rust() {
+    if command -v rustup >/dev/null 2>&1; then
+        echo_warn "rustup already installed"
+        return 0
+    fi
+
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+    source "$HOME/.cargo/env"
+}
+
+update_rust() {
+    if ! command -v rustup >/dev/null 2>&1; then
+        echo_error "rustup not installed. Run install first."
+        return 1
+    fi
+
+    rustup update
+}
+```
+
+## When Stuck
+
+**Script fails silently:**
+1. Add debug: `bash -x ./scripts/install_<tool>.sh`
+2. Check logs: `./scripts/install_<tool>.sh 2>&1 | tee install.log`
+3. Verify permissions: `ls -la scripts/`
+
+**Download fails:**
+1. Check network: `curl -I https://github.com`
+2. Check URL: `echo "$URL"` (verify it's correct)
+3. Try manual download: `curl -fsSL "$URL"`
+
+**Installation fails:**
+1. Check prerequisites (e.g., Python for uv, curl for rustup)
+2. Check disk space: `df -h`
+3. Check permissions: `ls -ld "$INSTALL_PREFIX"`
+
+**PATH not updated:**
+1. Source shell config: `source ~/.bashrc` or `source ~/.zshrc`
+2. Check PATH: `echo $PATH | tr ':' '\n' | grep local`
+3. Verify binary location: `ls -la ~/.local/bin/<tool>`
+
+**Reconcile fails:**
+1. Check current installation: `which <tool>`
+2. Check installation method: `cli_audit.py --only <tool>`
+3. Manually remove old version first: `apt remove <tool>` or `cargo uninstall <tool>`
+
+**Documentation:**
+- Script-specific docs: [README.md](README.md) (this directory)
+- Troubleshooting: [../docs/TROUBLESHOOTING.md](../docs/TROUBLESHOOTING.md)
+- Architecture: [../docs/DEPLOYMENT.md](../docs/DEPLOYMENT.md#installation-scripts)
+
+## House Rules
+
+**Installation preferences** (Phase 2 planning):
+- User-level preferred: `~/.local/bin` (workstations)
+- System-level for servers: `/usr/local/bin`
+- Vendor tools first: rustup, nvm, uv over system packages
+- See [../docs/adr/ADR-002-package-manager-hierarchy.md](../docs/adr/ADR-002-package-manager-hierarchy.md)
+
+**Reconciliation strategy:**
+- Parallel approach: Keep both installations, prefer user via PATH
+- No automatic removal (user chooses)
+- See [../docs/adr/ADR-003-parallel-installation-approach.md](../docs/adr/ADR-003-parallel-installation-approach.md)
+
+**Version policy:**
+- Always latest by default
+- Warn on major version upgrades
+- See [../docs/adr/ADR-004-always-latest-version-policy.md](../docs/adr/ADR-004-always-latest-version-policy.md)
+
+**Script structure:**
+- Multi-action support: install, update, uninstall, reconcile
+- Shared utilities in `lib/`
+- Consistent error handling and logging
+- Make integration via `make install-<tool>`
+
+---
+
+**Quick Start:** Run `make install-core` to install essential tools, then `make audit` to verify.
+
+**Troubleshooting:** See [README.md](README.md) for per-script troubleshooting and [../docs/TROUBLESHOOTING.md](../docs/TROUBLESHOOTING.md) for general issues.
--- a/references/examples/ldap-selfservice/AGENTS.md
+++ b/references/examples/ldap-selfservice/AGENTS.md
@@ -0,0 +1,282 @@
+# Agent Guidelines
+
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
+
+**Precedence**: Nearest AGENTS.md wins. This is the root file with global defaults.
+
+**Project**: LDAP Selfservice Password Changer — hybrid Go + TypeScript web application with WCAG 2.2 AAA accessibility compliance.
+
+## Quick Navigation
+
+- [internal/AGENTS.md](internal/AGENTS.md) - Go backend services
+- [internal/web/AGENTS.md](internal/web/AGENTS.md) - TypeScript frontend & Tailwind CSS
+
+## Global Defaults
+
+### Project Overview
+
+Self-service password change/reset web app for LDAP/ActiveDirectory with email-based password reset, rate limiting, and strict accessibility standards. Single binary deployment with embedded assets.
+
+**Stack**: Go 1.25 + Fiber, TypeScript (ultra-strict), Tailwind CSS 4, Docker multi-stage builds, pnpm 10.18
+
+**Key characteristics**:
+
+- Docker-first: All dev/CI must work via Docker
+- Accessibility: WCAG 2.2 AAA compliance (7:1 contrast, keyboard nav, screen readers)
+- Type-safe: Go with testcontainers, TypeScript with all strict flags
+- Security-focused: LDAPS, rate limiting, token-based reset, no password storage
+
+### Setup
+
+**Prerequisites**: Docker + Docker Compose (required), Go 1.25+, Node.js 24+, pnpm 10.18+ (for native dev)
+
+```bash
+# Clone and setup environment
+git clone <repo>
+cd ldap-selfservice-password-changer
+cp .env.local.example .env.local  # Edit with your LDAP config
+
+# Docker (recommended)
+docker compose --profile dev up
+
+# Native development
+pnpm install
+go mod download
+pnpm dev  # Runs concurrent TS watch, CSS watch, and Go with hot-reload
+```
+
+See [docs/development-guide.md](docs/development-guide.md) for comprehensive setup.
+
+### Build & Test Commands
+
+**Package manager**: pnpm (specified in package.json: `pnpm@10.18.1`)
+
+```bash
+# Build everything
+pnpm build                # Build frontend assets + Go binary
+
+# Frontend only
+pnpm build:assets         # TypeScript + Tailwind CSS
+pnpm js:build             # TypeScript compile + minify
+pnpm css:build            # Tailwind CSS + PostCSS
+
+# Development (watch mode)
+pnpm dev                  # Concurrent: TS watch, CSS watch, Go hot-reload
+pnpm js:dev               # TypeScript watch
+pnpm css:dev              # CSS watch
+pnpm go:dev               # Go with nodemon hot-reload
+
+# Tests
+go test -v ./...          # All Go tests with verbose output
+go test ./internal/...    # Specific package tests
+
+# Formatting
+pnpm prettier --write .   # Format TS, Go templates, config files
+pnpm prettier --check .   # Check formatting (CI)
+
+# Type checking
+pnpm js:build             # TypeScript strict compilation (no emit in dev)
+go build -v ./...         # Go compilation + type checking
+```
+
+**CI commands** (from `.github/workflows/check.yml`):
+
+- Type check: `pnpm js:build` and `go build -v ./...`
+- Format check: `pnpm prettier --check .`
+- Tests: `go test -v ./...`
+
+### Code Style
+
+**TypeScript**:
+
+- Ultra-strict tsconfig: `strict: true`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noPropertyAccessFromIndexSignature`
+- Prettier formatting: 120 char width, semicolons, double quotes, 2-space tabs
+- No `any` types - use proper type definitions
+- Follow existing patterns in `internal/web/static/`
+
+**Go**:
+
+- Standard Go formatting (`go fmt`)
+- Prettier with `prettier-plugin-go-template` for HTML templates
+- Follow Go project layout: `internal/` for private packages, `main.go` at root
+- Use testcontainers for integration tests (see `*_test.go` files)
+- Error wrapping with context
+
+**General**:
+
+- Composition over inheritance
+- SOLID, KISS, DRY, YAGNI principles
+- Law of Demeter: minimize coupling
+- No secrets in VCS (use .env.local, excluded from git)
+
+### Security
+
+- **No secrets in git**: Use `.env.local` (gitignored), never commit LDAP credentials
+- **LDAPS required**: Production must use encrypted LDAP connections
+- **Rate limiting**: 3 requests/hour per IP (configurable via `RATE_LIMIT_*` env vars)
+- **Token security**: Cryptographic random tokens with configurable expiry
+- **Input validation**: Strict validation on all user inputs (see `internal/validators/`)
+- **Dependency scanning**: Renovate enabled, review changelogs for major updates
+- **No PII logging**: Redact sensitive data in logs
+- **Run as non-root**: Dockerfile uses UID 65534 (nobody)
+
+### PR/Commit Checklist
+
+✅ **Before commit**:
+
+- [ ] Run `pnpm prettier --write .` (format all)
+- [ ] Run `pnpm js:build` (TypeScript strict check)
+- [ ] Run `go test ./...` (all tests pass)
+- [ ] Run `go build` (compilation check)
+- [ ] No secrets in changed files
+- [ ] Update docs if behavior changed
+- [ ] WCAG 2.2 AAA compliance maintained (if UI changed)
+
+✅ **Commit format**: Conventional Commits
+
+```
+type(scope): description
+
+Examples:
+feat(auth): add password reset via email
+fix(validators): correct password policy regex
+docs(api): update JSON-RPC examples
+chore(deps): update pnpm to v10.18.1
+```
+
+**No Claude attribution** in commit messages.
+
+✅ **PR requirements**:
+
+- [ ] All CI checks pass (types, formatting, tests)
+- [ ] Keep PRs small (~≤300 net LOC if possible)
+- [ ] Include ticket ID if applicable: `fix(rate-limit): ISSUE-123: fix memory leak`
+- [ ] Update relevant docs in same PR (README, AGENTS.md, docs/)
+
+### Good vs Bad Examples
+
+**✅ Good - TypeScript strict types**:
+
+```typescript
+interface PasswordPolicy {
+  minLength: number;
+  requireNumbers: boolean;
+}
+
+function validatePassword(password: string, policy: PasswordPolicy): boolean {
+  const hasNumber = /\d/.test(password);
+  return password.length >= policy.minLength && (!policy.requireNumbers || hasNumber);
+}
+```
+
+**❌ Bad - Using any or unsafe access**:
+
+```typescript
+function validatePassword(password: any, policy: any) {
+  // ❌ any types
+  return password.length >= policy.minLength; // ❌ unsafe access
+}
+```
+
+**✅ Good - Go error handling**:
+
+```go
+func connectLDAP(config LDAPConfig) (*ldap.Conn, error) {
+    conn, err := ldap.DialURL(config.URL)
+    if err != nil {
+        return nil, fmt.Errorf("failed to connect to LDAP at %s: %w", config.URL, err)
+    }
+    return conn, nil
+}
+```
+
+**❌ Bad - Ignoring errors**:
+
+```go
+func connectLDAP(config LDAPConfig) *ldap.Conn {
+    conn, _ := ldap.DialURL(config.URL)  // ❌ ignoring error
+    return conn                           // ❌ may return nil
+}
+```
+
+**✅ Good - Accessible UI**:
+
+```html
+<button type="submit" aria-label="Submit password change" class="bg-blue-600 hover:bg-blue-700 focus:ring-4">
+  Change Password
+</button>
+```
+
+**❌ Bad - Inaccessible UI**:
+
+```html
+<div onclick="submit()">Submit</div>
+❌ not keyboard accessible, wrong semantics
+```
+
+### When Stuck
+
+1. **Check existing docs**: [docs/](docs/) has comprehensive guides
+2. **Review similar code**: Look for patterns in `internal/` packages
+3. **Run tests**: `go test -v ./...` often reveals issues
+4. **Check CI logs**: GitHub Actions shows exact failure points
+5. **Verify environment**: Ensure `.env.local` is properly configured
+6. **Docker issues**: `docker compose down -v && docker compose --profile dev up --build`
+7. **Type errors**: Review `tsconfig.json` strict flags, use proper types
+8. **Accessibility**: See [docs/accessibility.md](docs/accessibility.md) for WCAG 2.2 AAA guidelines
+
+### House Rules
+
+**Docker-First Philosophy**:
+
+- All dev and CI must work via Docker Compose
+- Native setup is optional convenience, not requirement
+- Use profiles in compose.yml: `--profile dev` or `--profile test`
+
+**Documentation Currency**:
+
+- Update docs in same PR as code changes
+- No drift between code and documentation
+- Keep README, AGENTS.md, and docs/ synchronized
+
+**Testing Standards**:
+
+- Aim for ≥80% coverage on changed code
+- Use testcontainers for integration tests (see existing `*_test.go`)
+- For bugfixes: write failing test first (TDD)
+- Tests must pass before PR approval
+
+**Scope Discipline**:
+
+- Build only what's requested
+- No speculative features
+- MVP first, iterate based on feedback
+- YAGNI: You Aren't Gonna Need It
+
+**Accessibility Non-Negotiable**:
+
+- WCAG 2.2 AAA compliance required
+- 7:1 contrast ratios for text
+- Full keyboard navigation support
+- Screen reader tested (VoiceOver/NVDA)
+- See [docs/accessibility.md](docs/accessibility.md)
+
+**Commit Practices**:
+
+- Atomic commits: one logical change per commit
+- Conventional Commits format enforced
+- Never commit secrets or `.env.local`
+- Keep PRs focused and reviewable
+
+**Type Safety**:
+
+- TypeScript: No `any`, all strict flags enabled
+- Go: Leverage type system, avoid `interface{}`
+- Validate inputs at boundaries
+
+**Dependency Management**:
+
+- Renovate auto-updates enabled
+- Major version updates require changelog review
+- Use Context7 MCP or official docs for migrations
+- Keep pnpm-lock.yaml and go.sum committed
--- a/references/examples/ldap-selfservice/internal-AGENTS.md
+++ b/references/examples/ldap-selfservice/internal-AGENTS.md
@@ -0,0 +1,371 @@
+# Go Backend Services
+
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
+
+**Scope**: Go backend packages in `internal/` directory
+
+**See also**: [../AGENTS.md](../AGENTS.md) for global standards, [web/AGENTS.md](web/AGENTS.md) for frontend
+
+## Overview
+
+Backend services for LDAP selfservice password change/reset functionality. Organized as internal Go packages:
+
+- **email/**: SMTP email service for password reset tokens
+- **options/**: Configuration management from environment variables
+- **ratelimit/**: IP-based rate limiting (3 req/hour default)
+- **resettoken/**: Cryptographic token generation and validation
+- **rpc/**: JSON-RPC 2.0 API handlers (password change/reset)
+- **validators/**: Password policy validation logic
+- **web/**: HTTP server setup, static assets, routing (see [web/AGENTS.md](web/AGENTS.md))
+
+## Setup/Environment
+
+**Required environment variables** (configure in `.env.local`):
+
+```bash
+# LDAP connection
+LDAP_URL=ldaps://ldap.example.com:636
+LDAP_USER_BASE_DN=ou=users,dc=example,dc=com
+LDAP_BIND_DN=cn=admin,dc=example,dc=com
+LDAP_BIND_PASSWORD=secret
+
+# Email for password reset
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_USER=noreply@example.com
+SMTP_PASSWORD=secret
+SMTP_FROM=noreply@example.com
+APP_BASE_URL=https://passwd.example.com
+
+# Rate limiting (optional)
+RATE_LIMIT_REQUESTS=3
+RATE_LIMIT_WINDOW=1h
+
+# Token expiry (optional)
+TOKEN_EXPIRY_DURATION=1h
+```
+
+**Go toolchain**: Requires Go 1.25+ (specified in `go.mod`)
+
+**Key dependencies**:
+
+- `github.com/gofiber/fiber/v2` - HTTP server
+- `github.com/netresearch/simple-ldap-go` - LDAP client
+- `github.com/testcontainers/testcontainers-go` - Integration testing
+- `github.com/joho/godotenv` - Environment loading
+
+## Build & Tests
+
+```bash
+# Development
+go run .                      # Start server with hot-reload (via pnpm go:dev)
+go build -v ./...             # Compile all packages
+go test -v ./...              # Run all tests with verbose output
+
+# Specific package testing
+go test ./internal/validators/...    # Test password validators
+go test ./internal/ratelimit/...     # Test rate limiter
+go test ./internal/resettoken/...    # Test token generation
+go test -run TestSpecificFunction    # Run specific test
+
+# Integration tests (uses testcontainers)
+go test -v ./internal/email/...      # Requires Docker for MailHog container
+
+# Coverage
+go test -cover ./...                 # Coverage summary
+go test -coverprofile=coverage.out ./... && go tool cover -html=coverage.out
+
+# Build optimized binary
+CGO_ENABLED=0 go build -ldflags="-w -s" -o ldap-passwd
+```
+
+**CI validation** (from `.github/workflows/check.yml`):
+
+```bash
+go mod download
+go build -v ./...
+go test -v ./...
+```
+
+## Code Style
+
+**Go Standards**:
+
+- Use `go fmt` (automatic via Prettier with go-template plugin)
+- Follow [Effective Go](https://go.dev/doc/effective_go)
+- Package-level documentation comments required
+- Exported functions must have doc comments
+
+**Project Conventions**:
+
+- Internal packages only: No public API outside this project
+- Error wrapping with context: `fmt.Errorf("context: %w", err)`
+- Use structured logging (consider adding in future)
+- Prefer explicit over implicit
+- Use interfaces for testability (see `email/service.go`)
+
+**Naming**:
+
+- `internal/package/file.go` - implementation
+- `internal/package/file_test.go` - tests
+- Descriptive variable names (not `x`, `y`, `tmp`)
+- No stuttering: `email.Service`, not `email.EmailService`
+
+**Error Handling**:
+
+```go
+// ✅ Good: wrap with context
+if err != nil {
+    return fmt.Errorf("failed to connect LDAP at %s: %w", config.URL, err)
+}
+
+// ❌ Bad: lose context
+if err != nil {
+    return err
+}
+
+// ❌ Worse: ignore
+conn, _ := ldap.Dial(url)
+```
+
+**Testing**:
+
+- Table-driven tests preferred
+- Use testcontainers for external dependencies (LDAP, SMTP)
+- Test files colocated with code: `validators/validate_test.go`
+- Descriptive test names: `TestPasswordValidation_RequiresMinimumLength`
+
+## Security
+
+**LDAP Security**:
+
+- Always use LDAPS in production (`ldaps://` URLs)
+- Bind credentials in environment, never hardcoded
+- Validate user input before LDAP queries (prevent injection)
+- Use `simple-ldap-go` helpers to avoid raw LDAP filter construction
+
+**Password Security**:
+
+- Never log passwords (plain or hashed)
+- No password storage - passwords go directly to LDAP
+- Passwords only in memory during request lifetime
+- HTTPS required for transport security
+
+**Token Security**:
+
+- Cryptographic random tokens (see `resettoken/token.go`)
+- Configurable expiry (default 1h)
+- Single-use tokens (invalidated after use)
+- No token storage in logs or metrics
+
+**Rate Limiting**:
+
+- IP-based limits: 3 requests/hour default
+- Configurable via `RATE_LIMIT_*` env vars
+- In-memory store (consider Redis for multi-instance)
+- Apply to both change and reset endpoints
+
+**Input Validation**:
+
+- Strict validation on all user inputs (see `validators/`)
+- Reject malformed requests early
+- Validate email format, username format, password policies
+- No HTML/script injection vectors
+
+## PR/Commit Checklist
+
+**Before committing Go code**:
+
+- [ ] Run `go fmt ./...` (or `pnpm prettier --write .`)
+- [ ] Run `go vet ./...` (static analysis)
+- [ ] Run `go test ./...` (all tests pass)
+- [ ] Run `go build` (compilation check)
+- [ ] Update package doc comments if API changed
+- [ ] Add/update tests for new functionality
+- [ ] Check for sensitive data in logs
+- [ ] Verify error messages provide useful context
+
+**Testing requirements**:
+
+- New features must have tests
+- Bug fixes must have regression tests
+- Aim for ≥80% coverage on changed packages
+- Integration tests for external dependencies
+
+**Documentation**:
+
+- Update package doc comments (godoc)
+- Update [docs/api-reference.md](../docs/api-reference.md) for RPC changes
+- Update [docs/development-guide.md](../docs/development-guide.md) for new setup steps
+- Update environment variable examples in `.env` and docs
+
+## Good vs Bad Examples
+
+**✅ Good: Type-safe configuration**
+
+```go
+type Config struct {
+    LDAPURL      string `env:"LDAP_URL" validate:"required,url"`
+    BindDN       string `env:"LDAP_BIND_DN" validate:"required"`
+    BindPassword string `env:"LDAP_BIND_PASSWORD" validate:"required"`
+}
+
+func LoadConfig() (*Config, error) {
+    var cfg Config
+    if err := env.Parse(&cfg); err != nil {
+        return nil, fmt.Errorf("parse config: %w", err)
+    }
+    return &cfg, nil
+}
+```
+
+**❌ Bad: Unsafe configuration**
+
+```go
+func LoadConfig() *Config {
+    return &Config{
+        LDAPURL: os.Getenv("LDAP_URL"),  // ❌ no validation, may be empty
+    }
+}
+```
+
+**✅ Good: Table-driven tests**
+
+```go
+func TestPasswordValidation(t *testing.T) {
+    tests := []struct {
+        name     string
+        password string
+        policy   PasswordPolicy
+        wantErr  bool
+    }{
+        {"valid password", "Test123!", PasswordPolicy{MinLength: 8}, false},
+        {"too short", "Ab1!", PasswordPolicy{MinLength: 8}, true},
+        {"no numbers", "TestTest", PasswordPolicy{RequireNumbers: true}, true},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            err := ValidatePassword(tt.password, tt.policy)
+            if (err != nil) != tt.wantErr {
+                t.Errorf("got error %v, wantErr %v", err, tt.wantErr)
+            }
+        })
+    }
+}
+```
+
+**❌ Bad: Non-descriptive tests**
+
+```go
+func TestPassword(t *testing.T) {
+    err := ValidatePassword("test")  // ❌ what policy? what's expected?
+    if err == nil {
+        t.Fail()
+    }
+}
+```
+
+**✅ Good: Interface for testability**
+
+```go
+type EmailService interface {
+    SendResetToken(ctx context.Context, to, token string) error
+}
+
+type SMTPService struct {
+    host string
+    port int
+}
+
+func (s *SMTPService) SendResetToken(ctx context.Context, to, token string) error {
+    // real implementation
+}
+
+// In tests, use mock implementation
+type MockEmailService struct {
+    SendFunc func(ctx context.Context, to, token string) error
+}
+```
+
+**❌ Bad: Hard-to-test concrete dependency**
+
+```go
+func ResetPassword(username string) error {
+    service := NewSMTPService()  // ❌ hardcoded, can't mock
+    return service.SendEmail(...)
+}
+```
+
+## When Stuck
+
+**Go-specific issues**:
+
+1. **Module issues**: `go mod tidy` to clean dependencies
+2. **Import errors**: Check `go.mod` requires correct versions
+3. **Test failures**: `go test -v ./... -run FailingTest` for verbose output
+4. **LDAP connection**: Verify `LDAP_URL` format and network access
+5. **Email testing**: Ensure Docker running for testcontainers (MailHog)
+6. **Rate limit testing**: Tests may fail if system time incorrect
+
+**Debugging**:
+
+```bash
+# Verbose test output
+go test -v ./internal/package/...
+
+# Run specific test
+go test -run TestName ./internal/package/
+
+# Race detector (for concurrency issues)
+go test -race ./...
+
+# Build with debug info
+go build -gcflags="all=-N -l"
+```
+
+**Common pitfalls**:
+
+- **Nil pointer dereference**: Check error returns before using values
+- **Context cancellation**: Always respect `context.Context` in long operations
+- **Resource leaks**: Defer `Close()` calls immediately after acquiring resources
+- **Goroutine leaks**: Ensure all goroutines can exit
+- **Time zones**: Use `time.UTC` for consistency
+
+## Package-Specific Notes
+
+### email/
+
+- Uses testcontainers for integration tests
+- MailHog container spins up automatically in tests
+- Mock `EmailService` interface for unit tests in other packages
+
+### options/
+
+- Configuration loaded from environment via `godotenv`
+- Validation happens at startup (fail-fast)
+- See `.env.local.example` for required variables
+
+### ratelimit/
+
+- In-memory store (map with mutex)
+- Consider Redis for multi-instance deployments
+- Tests use fixed time.Now for deterministic results
+
+### resettoken/
+
+- Crypto/rand for token generation (never math/rand)
+- Base64 URL encoding (safe for URLs)
+- Store tokens server-side with expiry
+
+### rpc/
+
+- JSON-RPC 2.0 specification compliance
+- Error codes defined in [docs/api-reference.md](../docs/api-reference.md)
+- Request validation before processing
+
+### validators/
+
+- Pure functions (no side effects)
+- Configurable policies from environment
+- Clear error messages for user feedback
--- a/references/examples/ldap-selfservice/internal-web-AGENTS.md
+++ b/references/examples/ldap-selfservice/internal-web-AGENTS.md
@@ -0,0 +1,448 @@
+# Frontend - TypeScript & Tailwind CSS
+
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-09 -->
+
+**Scope**: Frontend assets in `internal/web/` directory - TypeScript, Tailwind CSS, HTML templates
+
+**See also**: [../../AGENTS.md](../../AGENTS.md) for global standards, [../AGENTS.md](../AGENTS.md) for Go backend
+
+## Overview
+
+Frontend implementation for LDAP selfservice password changer with strict accessibility compliance:
+
+- **static/**: Client-side TypeScript, compiled CSS, static assets
+  - **js/**: TypeScript source files (compiled to ES modules)
+  - **styles.css**: Tailwind CSS output
+  - Icons, logos, favicons, manifest
+- **templates/**: Go HTML templates (\*.gohtml)
+- **handlers.go**: HTTP route handlers
+- **middleware.go**: Security headers, CORS, etc.
+- **server.go**: Fiber server setup
+
+**Key characteristics**:
+
+- **WCAG 2.2 AAA**: 7:1 contrast, keyboard navigation, screen reader support, adaptive density
+- **Ultra-strict TypeScript**: All strict flags enabled, no `any` types
+- **Tailwind CSS 4**: Utility-first, dark mode, responsive, accessible patterns
+- **Progressive enhancement**: Works without JavaScript (forms submit via HTTP)
+- **Password manager friendly**: Proper autocomplete attributes
+
+## Setup/Environment
+
+**Prerequisites**: Node.js 24+, pnpm 10.18+ (from root `package.json`)
+
+```bash
+# From project root
+pnpm install          # Install dependencies
+
+# Development (watch mode)
+pnpm css:dev          # Tailwind CSS watch
+pnpm js:dev           # TypeScript watch
+# OR
+pnpm dev              # Concurrent: CSS + TS + Go hot-reload
+```
+
+**No .env needed for frontend** - all config comes from Go backend
+
+**Browser targets**: Modern browsers with ES module support (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)
+
+## Build & Tests
+
+```bash
+# Build frontend assets
+pnpm build:assets     # TypeScript + CSS (production builds)
+
+# TypeScript
+pnpm js:build         # Compile TS → ES modules + minify
+pnpm js:dev           # Watch mode with preserveWatchOutput
+tsc --noEmit          # Type check only (no output)
+
+# CSS
+pnpm css:build        # Tailwind + PostCSS → styles.css
+pnpm css:dev          # Watch mode
+
+# Formatting
+pnpm prettier --write internal/web/    # Format TS, CSS, HTML templates
+pnpm prettier --check internal/web/    # Check formatting (CI)
+```
+
+**No unit tests yet** - TypeScript strict mode catches most errors, integration via Go tests
+
+**CI validation** (from `.github/workflows/check.yml`):
+
+```bash
+pnpm install
+pnpm js:build         # TypeScript strict compilation
+pnpm prettier --check .
+```
+
+**Accessibility testing**:
+
+- Keyboard navigation: Tab through all interactive elements
+- Screen reader: Test with VoiceOver (macOS/iOS) or NVDA (Windows)
+- Contrast: Verify 7:1 ratios with browser dev tools
+- See [../../docs/accessibility.md](../../docs/accessibility.md) for comprehensive guide
+
+## Code Style
+
+**TypeScript Ultra-Strict** (from `tsconfig.json`):
+
+```json
+{
+  "strict": true,
+  "noUncheckedIndexedAccess": true,
+  "exactOptionalPropertyTypes": true,
+  "noPropertyAccessFromIndexSignature": true,
+  "noImplicitReturns": true,
+  "noFallthroughCasesInSwitch": true,
+  "noUnusedLocals": true,
+  "noUnusedParameters": true
+}
+```
+
+**No `any` types allowed**:
+
+```typescript
+// ✅ Good: explicit types
+function validatePassword(password: string, minLength: number): boolean {
+  return password.length >= minLength;
+}
+
+// ❌ Bad: any type
+function validatePassword(password: any): boolean {
+  return password.length >= 8; // ❌ unsafe
+}
+```
+
+**Prettier formatting**:
+
+- 120 char width
+- 2-space indentation
+- Semicolons required
+- Double quotes (not single)
+- Trailing comma: none
+
+**File organization**:
+
+- TypeScript source: `static/js/*.ts`
+- Output: `static/js/*.js` (minified ES modules)
+- CSS input: `tailwind.css` (Tailwind directives)
+- CSS output: `static/styles.css` (PostCSS processed)
+
+## Accessibility Standards (WCAG 2.2 AAA)
+
+**Required compliance** - not optional:
+
+### Keyboard Navigation
+
+- All interactive elements focusable with Tab
+- Visual focus indicators (4px outline, 7:1 contrast)
+- Logical tab order (top to bottom, left to right)
+- No keyboard traps
+- Skip links where needed
+
+### Screen Readers
+
+- Semantic HTML: `<button>`, `<input>`, `<label>`, not `<div onclick>`
+- ARIA labels on icon-only buttons: `aria-label="Submit"`
+- Error messages: `aria-describedby` linking to error text
+- Live regions for dynamic content: `aria-live="polite"`
+- Form field associations: `<label for="id">` + `<input id="id">`
+
+### Color & Contrast
+
+- Text: 7:1 contrast ratio (AAA)
+- Large text (18pt+): 4.5:1 minimum
+- Focus indicators: 3:1 against adjacent colors
+- Dark mode: same contrast requirements
+- Never rely on color alone (use icons, text, patterns)
+
+### Responsive & Adaptive
+
+- Responsive: layout adapts to viewport size
+- Text zoom: 200% without horizontal scroll
+- Adaptive density: spacing adjusts for user preferences
+- Touch targets: 44×44 CSS pixels minimum (mobile)
+
+### Examples
+
+**✅ Good: Accessible button**
+
+```html
+<button type="submit" class="btn-primary focus:ring-4 focus:ring-blue-300" aria-label="Submit password change">
+  <svg aria-hidden="true">...</svg>
+  Change Password
+</button>
+```
+
+**❌ Bad: Inaccessible div-button**
+
+```html
+<div onclick="submit()" class="button">❌ not keyboard accessible Submit</div>
+```
+
+**✅ Good: Form with error handling**
+
+```html
+<form>
+  <label for="password">New Password</label>
+  <input
+    id="password"
+    type="password"
+    aria-describedby="password-error"
+    aria-invalid="true"
+    autocomplete="new-password"
+  />
+  <div id="password-error" role="alert">Password must be at least 8 characters</div>
+</form>
+```
+
+**❌ Bad: Form without associations**
+
+```html
+<form>
+  <div>Password</div>
+  ❌ not a label, no association <input type="password" /> ❌ no autocomplete, no error linkage
+  <div style="color: red">Error</div>
+  ❌ no role="alert", only color
+</form>
+```
+
+## Tailwind CSS Patterns
+
+**Use utility classes**, not custom CSS:
+
+**✅ Good: Utility classes**
+
+```html
+<button
+  class="rounded-lg bg-blue-600 px-4 py-2 font-semibold text-white hover:bg-blue-700 focus:ring-4 focus:ring-blue-300"
+>
+  Submit
+</button>
+```
+
+**❌ Bad: Custom CSS**
+
+```html
+<button class="custom-button">Submit</button>
+<style>
+  .custom-button {
+    background: blue;
+  } /* ❌ Use Tailwind utilities */
+</style>
+```
+
+**Dark mode support**:
+
+```html
+<div class="bg-white text-gray-900 dark:bg-gray-900 dark:text-gray-100">Content</div>
+```
+
+**Responsive design**:
+
+```html
+<div class="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
+  <!-- Responsive grid: 1 col mobile, 2 tablet, 3 desktop -->
+</div>
+```
+
+**Focus states (required)**:
+
+```html
+<button class="focus:ring-4 focus:ring-blue-300 focus:outline-none">
+  <!-- 4px focus ring, 7:1 contrast -->
+</button>
+```
+
+## TypeScript Patterns
+
+**Strict null checking**:
+
+```typescript
+// ✅ Good: handle nulls explicitly
+function getElement(id: string): HTMLElement | null {
+  return document.getElementById(id);
+}
+
+const el = getElement("password");
+if (el) {
+  // ✅ null check
+  el.textContent = "Hello";
+}
+
+// ❌ Bad: assume non-null
+const el = getElement("password");
+el.textContent = "Hello"; // ❌ may crash if null
+```
+
+**Type guards**:
+
+```typescript
+// ✅ Good: type guard for forms
+function isHTMLFormElement(element: Element): element is HTMLFormElement {
+  return element instanceof HTMLFormElement;
+}
+
+const form = document.querySelector("form");
+if (form && isHTMLFormElement(form)) {
+  form.addEventListener("submit", handleSubmit);
+}
+```
+
+**No unsafe array access**:
+
+```typescript
+// ✅ Good: check array bounds
+const items = ["a", "b", "c"];
+const first = items[0]; // string | undefined (noUncheckedIndexedAccess)
+if (first) {
+  console.log(first.toUpperCase());
+}
+
+// ❌ Bad: unsafe access
+console.log(items[0].toUpperCase()); // ❌ may crash if empty array
+```
+
+## PR/Commit Checklist
+
+**Before committing frontend code**:
+
+- [ ] Run `pnpm js:build` (TypeScript strict check)
+- [ ] Run `pnpm prettier --write internal/web/`
+- [ ] Verify keyboard navigation works
+- [ ] Test with screen reader (VoiceOver/NVDA)
+- [ ] Check contrast ratios (7:1 for text)
+- [ ] Test dark mode
+- [ ] Verify password manager autofill works
+- [ ] No console errors in browser
+- [ ] Test on mobile viewport (responsive)
+
+**Accessibility checklist**:
+
+- [ ] All interactive elements keyboard accessible
+- [ ] Focus indicators visible (4px outline, 7:1 contrast)
+- [ ] ARIA labels on icon-only buttons
+- [ ] Form fields properly labeled
+- [ ] Error messages linked with aria-describedby
+- [ ] No color-only information conveyance
+- [ ] Touch targets ≥44×44 CSS pixels (mobile)
+
+**Performance checklist**:
+
+- [ ] Minified JS (via `pnpm js:minify`)
+- [ ] CSS optimized (cssnano via PostCSS)
+- [ ] No unused Tailwind classes (purged automatically)
+- [ ] No console.log in production code
+
+## Good vs Bad Examples
+
+**✅ Good: Type-safe DOM access**
+
+```typescript
+function setupPasswordToggle(): void {
+  const toggle = document.getElementById("toggle-password");
+  const input = document.getElementById("password");
+
+  if (!toggle || !(input instanceof HTMLInputElement)) {
+    return; // Guard against missing elements
+  }
+
+  toggle.addEventListener("click", () => {
+    input.type = input.type === "password" ? "text" : "password";
+  });
+}
+```
+
+**❌ Bad: Unsafe DOM access**
+
+```typescript
+function setupPasswordToggle() {
+  const toggle = document.getElementById("toggle-password")!; // ❌ non-null assertion
+  const input = document.getElementById("password") as any; // ❌ any type
+
+  toggle.addEventListener("click", () => {
+    input.type = input.type === "password" ? "text" : "password"; // ❌ may crash
+  });
+}
+```
+
+**✅ Good: Accessible form validation**
+
+```typescript
+function showError(input: HTMLInputElement, message: string): void {
+  const errorId = `${input.id}-error`;
+  let errorEl = document.getElementById(errorId);
+
+  if (!errorEl) {
+    errorEl = document.createElement("div");
+    errorEl.id = errorId;
+    errorEl.setAttribute("role", "alert");
+    errorEl.className = "text-red-600 dark:text-red-400 text-sm mt-1";
+    input.parentElement?.appendChild(errorEl);
+  }
+
+  errorEl.textContent = message;
+  input.setAttribute("aria-invalid", "true");
+  input.setAttribute("aria-describedby", errorId);
+}
+```
+
+**❌ Bad: Inaccessible validation**
+
+```typescript
+function showError(input: any, message: string) {
+  // ❌ any type
+  input.style.borderColor = "red"; // ❌ color only, no text
+  alert(message); // ❌ blocks UI, not persistent
+}
+```
+
+## When Stuck
+
+**TypeScript issues**:
+
+1. **Type errors**: Check `tsconfig.json` flags, use proper types (no `any`)
+2. **Null errors**: Add null checks or type guards
+3. **Module errors**: Ensure ES module syntax (`import`/`export`)
+4. **Build errors**: `pnpm install` to refresh dependencies
+
+**CSS issues**:
+
+1. **Styles not applying**: Check Tailwind purge config, rebuild with `pnpm css:build`
+2. **Dark mode broken**: Use `dark:` prefix on utilities
+3. **Responsive broken**: Use `md:`, `lg:` breakpoint prefixes
+4. **Custom classes**: Don't - use Tailwind utilities instead
+
+**Accessibility issues**:
+
+1. **Keyboard nav broken**: Check tab order, focus indicators
+2. **Screen reader confusion**: Verify ARIA labels, semantic HTML
+3. **Contrast failure**: Use darker colors, test with dev tools
+4. **See**: [../../docs/accessibility.md](../../docs/accessibility.md)
+
+**Browser dev tools**:
+
+- Accessibility tab: Check ARIA, contrast, structure
+- Lighthouse: Run accessibility audit (aim for 100 score)
+- Console: No errors in production code
+
+## Testing Workflow
+
+**Manual testing required** (no automated frontend tests yet):
+
+1. **Visual testing**: Check all pages in light/dark mode
+2. **Keyboard testing**: Tab through all interactive elements
+3. **Screen reader testing**: Use VoiceOver (Cmd+F5) or NVDA
+4. **Responsive testing**: Test mobile, tablet, desktop viewports
+5. **Browser testing**: Chrome, Firefox, Safari, Edge
+6. **Password manager**: Test autofill with 1Password, LastPass, etc.
+
+**Accessibility testing tools**:
+
+- Browser dev tools Lighthouse
+- axe DevTools extension
+- WAVE browser extension
+- Manual keyboard/screen reader testing (required)
+
+**Integration testing**: Go backend tests exercise full request/response flow including frontend templates
--- a/references/examples/simple-ldap-go/AGENTS.md
+++ b/references/examples/simple-ldap-go/AGENTS.md
@@ -0,0 +1,27 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: 2025-09-29 -->
+
+# AGENTS.md (root)
+
+This file explains repo-wide conventions and where to find scoped rules.
+**Precedence:** the **closest `AGENTS.md`** to the files you're changing wins. Root holds global defaults only.
+
+## Global rules
+- Keep diffs small; add tests for new code paths
+- Ask first before: adding heavy deps, running full e2e suites, or repo-wide rewrites
+- Never commit secrets or sensitive data to the repository
+- Follow Go 1.24 conventions and idioms
+- Maintain minimum test coverage of 40%
+
+## Minimal pre-commit checks
+- Typecheck (all packages): `go build -v ./...`
+- Lint/format (file scope): `gofmt -w <file.go>` and `~/go/bin/golangci-lint run ./...`
+- Unit tests (fast): `go test -v -race -short -timeout=10s ./...`
+
+## Index of scoped AGENTS.md
+- `./examples/AGENTS.md` — Example applications and usage patterns
+- `./testutil/AGENTS.md` — Testing utilities and container management
+- `./docs/AGENTS.md` — Documentation and guides
+
+## When instructions conflict
+- The nearest `AGENTS.md` wins. Explicit user prompts override files.
+- For Go-specific patterns, defer to language idioms and standard library conventions
--- a/references/examples/simple-ldap-go/examples-AGENTS.md
+++ b/references/examples/simple-ldap-go/examples-AGENTS.md
@@ -0,0 +1,45 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: 2025-09-29 -->
+
+# AGENTS.md — Examples
+
+## Overview
+Example applications demonstrating library usage patterns for authentication, user management, performance optimization, context handling, and error patterns. Entry points are the main.go files in each subdirectory.
+
+## Setup & environment
+- Install: `go mod download`
+- Run example: `go run examples/<name>/main.go`
+- Env: Examples use environment variables from `.env` files when present
+
+## Build & tests (prefer file-scoped)
+- Typecheck a file: `go build -v examples/<name>/main.go`
+- Format a file: `gofmt -w examples/<name>/main.go`
+- Run example: `go run examples/<name>/main.go`
+
+## Code style & conventions
+- Examples should be self-contained and runnable
+- Use clear variable names that explain the concept
+- Include comments explaining non-obvious patterns
+- Error handling should demonstrate best practices
+- Keep examples focused on a single concept
+
+## Security & safety
+- Never include real credentials in examples
+- Use placeholder values like "ldap.example.com"
+- Document required permissions clearly
+- Examples should fail gracefully without real LDAP server
+
+## PR/commit checklist
+- Examples must compile without errors
+- Include README.md explaining the example's purpose
+- Test example with both real and mock LDAP servers if possible
+- Ensure examples follow library best practices
+
+## Good vs. bad examples
+- Good: `authentication/main.go` (clear flow, error handling)
+- Good: `context-usage/main.go` (proper context propagation)
+- Pattern to follow: Simple, focused, well-commented demonstrations
+
+## When stuck
+- Check the main library documentation in ../docs/
+- Review similar examples in sibling directories
+- Ensure you have the latest library version
--- a/references/examples/t3x-rte-ckeditor-image/AGENTS.md
+++ b/references/examples/t3x-rte-ckeditor-image/AGENTS.md
@@ -0,0 +1,348 @@
+# AI Agent Development Guide
+
+**Project:** rte_ckeditor_image - TYPO3 CKEditor 5 Image Extension
+**Type:** TYPO3 CMS Extension (PHP 8.2+ + JavaScript/ES6)
+**License:** GPL-2.0-or-later
+
+## 📋 Documentation Structure
+
+This project uses a three-tier documentation system:
+
+- **[claudedocs/](claudedocs/)** - AI session context (Markdown, gitignored, temporary)
+- **[Documentation/](Documentation/)** - Official TYPO3 docs (RST, published, permanent)
+- **Root** - Project essentials (README, CONTRIBUTING, SECURITY, LICENSE)
+
+See **[claudedocs/INDEX.md](claudedocs/INDEX.md)** for AI context navigation and **[Documentation/AGENTS.md](Documentation/AGENTS.md)** for TYPO3 documentation system guide.
+
+## 🎯 Quick Start
+
+```bash
+# First time setup
+composer install
+make help                    # See all available targets
+
+# Development workflow
+make lint                    # Run all linters
+make format                  # Fix code style
+make test                    # Run tests
+make ci                      # Full CI check (pre-commit)
+
+# Composer shortcuts (if make unavailable)
+composer ci:test:php:lint    # PHP syntax check
+composer ci:test:php:phpstan # Static analysis
+composer ci:test:php:cgl     # Code style check
+composer ci:cgl              # Fix code style
+```
+
+## 🏗️ Setup
+
+### Prerequisites
+
+- **PHP:** 8.2-8.9 with extensions: dom, libxml
+- **Composer:** Latest stable
+- **TYPO3:** 13.4+ (cms-core, cms-backend, cms-frontend, cms-rte-ckeditor)
+- **direnv:** Optional but recommended
+
+### Installation
+
+```bash
+# Clone and install
+git clone https://github.com/netresearch/t3x-rte_ckeditor_image.git
+cd t3x-rte_ckeditor_image
+composer install
+
+# Enable direnv (optional)
+direnv allow
+```
+
+## 🔧 Build & Test Commands
+
+### Fast Quality Checks (Pre-commit)
+
+```bash
+make lint          # PHP lint + PHPStan + style check
+make format        # Auto-fix code style
+make typecheck     # PHPStan static analysis
+```
+
+### Full CI Suite
+
+```bash
+make ci            # Complete CI pipeline
+make test          # All tests (when available)
+```
+
+### Individual Commands
+
+```bash
+# PHP Linting
+composer ci:test:php:lint
+
+# Static Analysis
+composer ci:test:php:phpstan
+
+# Code Style Check
+composer ci:test:php:cgl
+
+# Code Style Fix
+composer ci:cgl
+
+# Rector (PHP Modernization)
+composer ci:test:php:rector
+composer ci:rector              # Apply changes
+```
+
+## 📝 Code Style
+
+### PHP Standards
+
+- **Base:** PSR-12 + PER-CS 2.0
+- **Strict types:** Required in all files (`declare(strict_types=1);`)
+- **Header comments:** Auto-managed by PHP-CS-Fixer
+- **Config:** `Build/.php-cs-fixer.dist.php`
+
+### Key Rules
+
+```php
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the package netresearch/rte-ckeditor-image.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE file that was distributed with this source code.
+ */
+
+namespace Netresearch\RteCKEditorImage\Controller;
+
+// Imports: Classes, constants, functions
+use TYPO3\CMS\Core\Utility\GeneralUtility;
+
+// Alignment on = and =>
+$config = [
+    'short'  => 'value',
+    'longer' => 'another',
+];
+```
+
+### JavaScript Standards
+
+- **ES6 modules:** CKEditor 5 plugin format
+- **No npm tooling:** TYPO3-managed assets
+- **Style:** Follow CKEditor 5 conventions
+- **Location:** `Resources/Public/JavaScript/`
+
+## 🔒 Security
+
+- **No secrets in VCS:** Use TYPO3's environment configuration
+- **Dependency scanning:** Renovate enabled (see `renovate.json`)
+- **Static analysis:** PHPStan with strict rules
+- **TYPO3 security:** Follow TYPO3 Security Guidelines
+- **File uploads:** Use FAL (File Abstraction Layer)
+- **XSS prevention:** All output escaped via Fluid templates
+
+## ✅ PR/Commit Checklist
+
+Before committing:
+
+1. ✅ **Lint passed:** `make lint` or `composer ci:test:php:lint`
+2. ✅ **Style fixed:** `make format` or `composer ci:cgl`
+3. ✅ **Static analysis:** `composer ci:test:php:phpstan` (no new errors)
+4. ✅ **Rector check:** `composer ci:test:php:rector` (no suggestions)
+5. ✅ **Docs updated:** Update relevant docs/ files if API changed
+6. ✅ **CHANGELOG:** Add entry if user-facing change
+7. ✅ **Conventional Commits:** Use format: `type(scope): message`
+8. ✅ **Small PRs:** Keep ≤300 net LOC changed
+
+### Commit Format
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer]
+```
+
+**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+**Scopes:** `backend`, `frontend`, `config`, `docs`, `build`
+
+**Examples:**
+```
+feat(backend): add image processing hook for WebP
+fix(frontend): resolve style drop-down disabled for typo3image
+docs(api): update DataHandling API reference
+```
+
+## 🎓 Good vs Bad Examples
+
+### ✅ Good: TYPO3 Pattern
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Netresearch\RteCKEditorImage\Controller;
+
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use TYPO3\CMS\Core\Resource\ResourceFactory;
+
+final class SelectImageController
+{
+    public function __construct(
+        private readonly ResourceFactory $resourceFactory
+    ) {
+    }
+
+    public function infoAction(ServerRequestInterface $request): ResponseInterface
+    {
+        $fileUid = (int)($request->getQueryParams()['fileId'] ?? 0);
+        // Implementation...
+    }
+}
+```
+
+### ❌ Bad: Missing strict types, no DI
+
+```php
+<?php
+namespace Netresearch\RteCKEditorImage\Controller;
+
+class SelectImageController
+{
+    public function infoAction($request)
+    {
+        $fileUid = $_GET['fileId'];  // Direct superglobal access
+        $factory = new ResourceFactory();  // No DI
+    }
+}
+```
+
+### ✅ Good: CKEditor 5 Plugin
+
+```javascript
+export default class Typo3Image extends Core.Plugin {
+    static get requires() {
+        return ['StyleUtils', 'GeneralHtmlSupport'];
+    }
+
+    init() {
+        const editor = this.editor;
+        this.listenTo(styleUtils, 'isStyleEnabledForBlock', (event, [style]) => {
+            // Event handling...
+        });
+    }
+}
+```
+
+### ❌ Bad: Missing dependencies
+
+```javascript
+class Typo3Image extends Core.Plugin {
+    // Missing requires() - breaks style integration
+    init() {
+        // Implementation...
+    }
+}
+```
+
+## 🆘 When Stuck
+
+1. **AI Context:** Start with [claudedocs/INDEX.md](claudedocs/INDEX.md) for project navigation
+2. **Architecture:** Review [claudedocs/ARCHITECTURE.md](claudedocs/ARCHITECTURE.md)
+3. **Security:** Check [claudedocs/SECURITY.md](claudedocs/SECURITY.md)
+4. **API Reference:** See [claudedocs/API_REFERENCE.md](claudedocs/API_REFERENCE.md)
+5. **Development Guide:** Follow [claudedocs/DEVELOPMENT_GUIDE.md](claudedocs/DEVELOPMENT_GUIDE.md)
+6. **TYPO3 Docs Guide:** Read [Documentation/AGENTS.md](Documentation/AGENTS.md)
+7. **Published Manual:** https://docs.typo3.org/p/netresearch/rte-ckeditor-image/main/en-us/
+8. **TYPO3 Core Docs:** https://docs.typo3.org/
+9. **Issues:** https://github.com/netresearch/t3x-rte_ckeditor_image/issues
+
+### Common Issues
+
+- **Style drop-down disabled:** Missing `GeneralHtmlSupport` dependency (v13.0.0+)
+- **Images not in frontend:** Missing static template include
+- **PHPStan errors:** Run `composer ci:test:php:phpstan:baseline` to update baseline
+- **Code style fails:** Run `composer ci:cgl` to auto-fix
+
+## 📐 House Rules
+
+### Commits & PRs
+
+- **Atomic commits:** One logical change per commit
+- **Conventional Commits:** Required format (see checklist)
+- **Small PRs:** Target ≤300 net LOC changed
+- **Branch naming:** `feature/short-description`, `fix/issue-123`
+
+### Design Principles
+
+- **SOLID:** Single responsibility, Open/closed, Liskov, Interface segregation, Dependency inversion
+- **KISS:** Keep it simple, stupid
+- **DRY:** Don't repeat yourself
+- **YAGNI:** You aren't gonna need it
+- **Composition > Inheritance:** Prefer composition
+- **Law of Demeter:** Minimize coupling
+
+### Dependencies
+
+- **Latest stable:** Use current TYPO3 13.4+ versions
+- **Renovate:** Auto-updates enabled
+- **Major updates:** Require changelog review + migration notes
+- **Composer:** Lock file committed
+
+### API & Versioning
+
+- **SemVer:** Semantic versioning (MAJOR.MINOR.PATCH)
+- **TYPO3 compatibility:** Follow TYPO3 versioning
+- **Breaking changes:** Increment major version
+- **Deprecations:** Add `@deprecated` tag + removal plan
+
+### Testing
+
+- **TYPO3 Testing Framework:** Use `typo3/testing-framework`
+- **Functional tests:** For database/integration scenarios
+- **Unit tests:** For isolated logic
+- **Test location:** `Tests/Functional/`, `Tests/Unit/`
+
+### Licensing
+
+- **License:** AGPL-3.0-or-later
+- **SPDX:** Use SPDX identifiers
+- **Headers:** Auto-managed by PHP-CS-Fixer
+- **Third-party:** Document in CHANGELOG
+
+## 🔗 Related Files
+
+**Root Documentation:**
+- **[README.md](README.md)** - Project overview and quick links
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contribution guidelines
+- **[SECURITY.md](SECURITY.md)** - Security policy
+- **[LICENSE](LICENSE)** - GPL-2.0-or-later license
+
+**AI Session Context (gitignored):**
+- **[claudedocs/INDEX.md](claudedocs/INDEX.md)** - Navigation hub
+- **[claudedocs/PROJECT_OVERVIEW.md](claudedocs/PROJECT_OVERVIEW.md)** - Project summary
+- **[claudedocs/ARCHITECTURE.md](claudedocs/ARCHITECTURE.md)** - System design
+- **[claudedocs/DEVELOPMENT_GUIDE.md](claudedocs/DEVELOPMENT_GUIDE.md)** - Development workflow
+- **[claudedocs/API_REFERENCE.md](claudedocs/API_REFERENCE.md)** - PHP API docs
+- **[claudedocs/SECURITY.md](claudedocs/SECURITY.md)** - Security analysis
+
+**Official TYPO3 Documentation:**
+- **[Documentation/](Documentation/)** - RST documentation (published)
+- **[Documentation/AGENTS.md](Documentation/AGENTS.md)** - TYPO3 docs system guide
+
+**Configuration:**
+- **[composer.json](composer.json)** - Dependencies & scripts
+- **[Build/](Build/)** - Development tools configuration
+
+## 📚 Additional Resources
+
+- **Repository:** https://github.com/netresearch/t3x-rte_ckeditor_image
+- **Packagist:** https://packagist.org/packages/netresearch/rte-ckeditor-image
+- **TYPO3 Ext:** https://extensions.typo3.org/extension/rte_ckeditor_image
+- **TYPO3 Docs:** https://docs.typo3.org/
+- **CKEditor 5:** https://ckeditor.com/docs/ckeditor5/
--- a/references/examples/t3x-rte-ckeditor-image/Classes-AGENTS.md
+++ b/references/examples/t3x-rte-ckeditor-image/Classes-AGENTS.md
@@ -0,0 +1,392 @@
+# Classes/AGENTS.md
+
+<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-10-15 -->
+
+**Scope:** PHP backend components (Controllers, EventListeners, DataHandling, Utils)
+**Parent:** [../AGENTS.md](../AGENTS.md)
+
+## 📋 Overview
+
+PHP backend implementation for TYPO3 CKEditor Image extension. Components:
+
+### Controllers
+- **SelectImageController** - Image browser wizard, file selection, image info API
+- **ImageRenderingController** - Image rendering and processing for frontend
+- **ImageLinkRenderingController** - Link-wrapped image rendering
+
+### EventListeners
+- **RteConfigurationListener** - PSR-14 event for RTE configuration injection
+
+### DataHandling
+- **RteImagesDbHook** - Database hooks for image magic reference handling
+- **RteImageSoftReferenceParser** - Soft reference parsing for RTE images
+
+### Backend Components
+- **RteImagePreviewRenderer** - Backend preview rendering
+
+### Utilities
+- **ProcessedFilesHandler** - File processing and manipulation utilities
+
+## 🏗️ Architecture Patterns
+
+### TYPO3 Patterns
+- **FAL (File Abstraction Layer):** All file operations via ResourceFactory
+- **PSR-7 Request/Response:** HTTP message interfaces for controllers
+- **PSR-14 Events:** Event-driven configuration and hooks
+- **Dependency Injection:** Constructor-based DI (TYPO3 v13+)
+- **Service Configuration:** `Configuration/Services.yaml` for DI registration
+
+### File Structure
+```
+Classes/
+├── Backend/
+│   └── Preview/
+│       └── RteImagePreviewRenderer.php
+├── Controller/
+│   ├── ImageLinkRenderingController.php
+│   ├── ImageRenderingController.php
+│   └── SelectImageController.php
+├── DataHandling/
+│   └── SoftReference/
+│       └── RteImageSoftReferenceParser.php
+├── Database/
+│   └── RteImagesDbHook.php
+├── EventListener/
+│   └── RteConfigurationListener.php
+└── Utils/
+    └── ProcessedFilesHandler.php
+```
+
+## 🔧 Build & Tests
+
+```bash
+# PHP-specific quality checks
+make lint                      # All linters (syntax + PHPStan + Rector + style)
+composer ci:test:php:lint      # PHP syntax check
+composer ci:test:php:phpstan   # Static analysis
+composer ci:test:php:rector    # Rector modernization check
+composer ci:test:php:cgl       # Code style check
+
+# Fixes
+make format                    # Auto-fix code style
+composer ci:cgl               # Alternative: fix style
+composer ci:rector            # Apply Rector changes
+
+# Full CI
+make ci                       # Complete pipeline
+```
+
+## 📝 Code Style
+
+### Required Patterns
+
+**1. Strict Types (Always First)**
+```php
+<?php
+
+declare(strict_types=1);
+```
+
+**2. File Header (Auto-managed by PHP-CS-Fixer)**
+```php
+/**
+ * This file is part of the package netresearch/rte-ckeditor-image.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE file that was distributed with this source code.
+ */
+```
+
+**3. Import Order**
+- Classes first
+- Functions second
+- Constants third
+- One blank line before namespace
+
+**4. Type Hints**
+- All parameters must have type hints
+- All return types must be declared
+- Use nullable types `?Type` when appropriate
+- Use union types `Type1|Type2` for PHP 8+
+
+**5. Property Types**
+```php
+private ResourceFactory $resourceFactory;        // Required type declaration
+private readonly ResourceFactory $factory;       // Readonly for immutability
+```
+
+**6. Alignment**
+```php
+$config = [
+    'short'  => 'value',       // Align on =>
+    'longer' => 'another',
+];
+```
+
+## 🔒 Security
+
+### FAL (File Abstraction Layer)
+- **Always use FAL:** Never direct file system access
+- **ResourceFactory:** For retrieving files by UID
+- **File validation:** Check isDeleted(), isMissing()
+- **ProcessedFile:** Use process() for image manipulation
+
+```php
+// ✅ Good: FAL usage
+$file = $this->resourceFactory->getFileObject($id);
+if ($file->isDeleted() || $file->isMissing()) {
+    throw new \Exception('File not found');
+}
+
+// ❌ Bad: Direct file access
+$file = file_get_contents('/var/www/uploads/' . $filename);
+```
+
+### Input Validation
+- **Type cast superglobals:** `(int)($request->getQueryParams()['id'] ?? 0)`
+- **Validate before use:** Check ranges, formats, existence
+- **Exit on error:** Use HTTP status codes with `HttpUtility::HTTP_STATUS_*`
+
+### XSS Prevention
+- **Fluid templates:** Auto-escaping enabled by default
+- **JSON responses:** Use `JsonResponse` class
+- **Localization:** Via `LocalizationUtility::translate()`
+
+## ✅ PR/Commit Checklist
+
+### PHP-Specific Checks
+1. ✅ **Strict types:** `declare(strict_types=1);` in all files
+2. ✅ **Type hints:** All parameters and return types declared
+3. ✅ **PHPStan:** Zero errors (`composer ci:test:php:phpstan`)
+4. ✅ **Code style:** PSR-12/PER-CS2.0 compliant (`make format`)
+5. ✅ **Rector:** No modernization suggestions (`composer ci:test:php:rector`)
+6. ✅ **FAL usage:** No direct file system access
+7. ✅ **DI pattern:** Constructor injection, no `new ClassName()`
+8. ✅ **PSR-7:** Request/Response for controllers
+9. ✅ **Documentation:** PHPDoc for public methods
+
+## 🎓 Good vs Bad Examples
+
+### ✅ Good: Controller Pattern
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Netresearch\RteCKEditorImage\Controller;
+
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use TYPO3\CMS\Core\Http\JsonResponse;
+use TYPO3\CMS\Core\Resource\ResourceFactory;
+
+final class SelectImageController
+{
+    public function __construct(
+        private readonly ResourceFactory $resourceFactory
+    ) {
+    }
+
+    public function infoAction(ServerRequestInterface $request): ResponseInterface
+    {
+        $fileUid = (int)($request->getQueryParams()['fileId'] ?? 0);
+
+        if ($fileUid <= 0) {
+            return new JsonResponse(['error' => 'Invalid file ID'], 400);
+        }
+
+        $file = $this->resourceFactory->getFileObject($fileUid);
+
+        return new JsonResponse([
+            'uid'    => $file->getUid(),
+            'width'  => $file->getProperty('width'),
+            'height' => $file->getProperty('height'),
+        ]);
+    }
+}
+```
+
+### ❌ Bad: Anti-patterns
+
+```php
+<?php
+// ❌ Missing strict types
+namespace Netresearch\RteCKEditorImage\Controller;
+
+// ❌ Missing PSR-7 types
+class SelectImageController
+{
+    // ❌ No constructor DI
+    public function infoAction($request)
+    {
+        // ❌ Direct superglobal access
+        $fileUid = $_GET['fileId'];
+
+        // ❌ No DI - manual instantiation
+        $factory = new ResourceFactory();
+
+        // ❌ No type safety, no validation
+        $file = $factory->getFileObject($fileUid);
+
+        // ❌ Manual JSON encoding
+        header('Content-Type: application/json');
+        echo json_encode(['uid' => $file->getUid()]);
+        exit;
+    }
+}
+```
+
+### ✅ Good: EventListener Pattern
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Netresearch\RteCKEditorImage\EventListener;
+
+use TYPO3\CMS\Backend\Routing\UriBuilder;
+use TYPO3\CMS\RteCKEditor\Form\Element\Event\AfterPrepareConfigurationForEditorEvent;
+
+final class RteConfigurationListener
+{
+    public function __construct(
+        private readonly UriBuilder $uriBuilder
+    ) {
+    }
+
+    public function __invoke(AfterPrepareConfigurationForEditorEvent $event): void
+    {
+        $configuration = $event->getConfiguration();
+        $configuration['style']['typo3image'] = [
+            'routeUrl' => (string)$this->uriBuilder->buildUriFromRoute('rteckeditorimage_wizard_select_image'),
+        ];
+        $event->setConfiguration($configuration);
+    }
+}
+```
+
+### ❌ Bad: EventListener Anti-pattern
+
+```php
+<?php
+namespace Netresearch\RteCKEditorImage\EventListener;
+
+class RteConfigurationListener
+{
+    // ❌ Wrong signature - not invokable
+    public function handle($event)
+    {
+        // ❌ Manual instantiation instead of DI
+        $uriBuilder = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(UriBuilder::class);
+
+        // ❌ Array access without type safety
+        $config = $event->getConfiguration();
+        $config['style']['typo3image']['routeUrl'] = $uriBuilder->buildUriFromRoute('rteckeditorimage_wizard_select_image');
+        $event->setConfiguration($config);
+    }
+}
+```
+
+### ✅ Good: FAL Usage
+
+```php
+protected function getImage(int $id): File
+{
+    try {
+        $file = $this->resourceFactory->getFileObject($id);
+
+        if ($file->isDeleted() || $file->isMissing()) {
+            throw new FileNotFoundException('File not found or deleted', 1234567890);
+        }
+    } catch (\Exception $e) {
+        throw new FileNotFoundException('Could not load file', 1234567891, $e);
+    }
+
+    return $file;
+}
+```
+
+### ❌ Bad: Direct File Access
+
+```php
+// ❌ Multiple issues
+protected function getImage($id)  // Missing return type, no type hint
+{
+    // ❌ Direct file system access, bypassing FAL
+    $path = '/var/www/html/fileadmin/' . $id;
+
+    // ❌ No validation, no error handling
+    if (file_exists($path)) {
+        return file_get_contents($path);
+    }
+
+    return null;  // ❌ Should throw exception or return typed null
+}
+```
+
+## 🆘 When Stuck
+
+### Documentation
+- **API Reference:** [docs/API/Controllers.md](../docs/API/Controllers.md) - Controller APIs
+- **Event Listeners:** [docs/API/EventListeners.md](../docs/API/EventListeners.md) - PSR-14 events
+- **Data Handling:** [docs/API/DataHandling.md](../docs/API/DataHandling.md) - Database hooks
+- **Architecture:** [docs/Architecture/Overview.md](../docs/Architecture/Overview.md) - System design
+
+### TYPO3 Resources
+- **FAL Documentation:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Fal/Index.html
+- **PSR-14 Events:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Events/Index.html
+- **Dependency Injection:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/DependencyInjection/Index.html
+- **Controllers:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Backend/Controllers/Index.html
+
+### Common Issues
+- **ResourceFactory errors:** Check file exists, not deleted, proper UID
+- **DI not working:** Verify `Configuration/Services.yaml` registration
+- **PHPStan errors:** Update baseline: `composer ci:test:php:phpstan:baseline`
+- **Type errors:** Enable strict_types, add all type hints
+
+## 📐 House Rules
+
+### Controllers
+- **Extend framework controllers:** ElementBrowserController for browsers
+- **Final by default:** Use `final class` unless inheritance required
+- **PSR-7 types:** ServerRequestInterface → ResponseInterface
+- **JSON responses:** Use `JsonResponse` class
+- **Validation first:** Validate all input parameters at method start
+
+### EventListeners
+- **Invokable:** Use `__invoke()` method signature
+- **Event type hints:** Type-hint specific event classes
+- **Immutability aware:** Get, modify, set configuration/state
+- **Final classes:** Event listeners should be final
+
+### DataHandling
+- **Soft references:** Implement soft reference parsing for data integrity
+- **Database hooks:** Use for maintaining referential integrity
+- **Transaction safety:** Consider rollback scenarios
+
+### Dependencies
+- **Constructor injection:** All dependencies via constructor
+- **Readonly properties:** Use `readonly` for immutable dependencies
+- **Interface over implementation:** Depend on interfaces when available
+- **GeneralUtility::makeInstance:** Only for factories or when DI unavailable
+
+### Error Handling
+- **Type-specific exceptions:** Use TYPO3 exception hierarchy
+- **HTTP status codes:** Via HttpUtility constants
+- **Meaningful messages:** Include context in exception messages
+- **Log important errors:** Use TYPO3 logging framework
+
+### Testing
+- **Functional tests:** For controllers, database operations
+- **Unit tests:** For utilities, isolated logic
+- **Mock FAL:** Use TYPO3 testing framework FAL mocks
+- **Test location:** `Tests/Functional/` and `Tests/Unit/`
+
+## 🔗 Related
+
+- **[Resources/AGENTS.md](../Resources/AGENTS.md)** - JavaScript/CKEditor integration
+- **[Tests/AGENTS.md](../Tests/AGENTS.md)** - Testing patterns
+- **[Configuration/Services.yaml](../Configuration/Services.yaml)** - DI container configuration
+- **[docs/API/](../docs/API/)** - Complete API documentation
--- a/scripts/detect-project.sh
+++ b/scripts/detect-project.sh
@@ -0,0 +1,199 @@
+#!/usr/bin/env bash
+# Detect project type, language, version, and build tools
+set -euo pipefail
+
+PROJECT_DIR="${1:-.}"
+cd "$PROJECT_DIR"
+
+# Initialize variables
+LANGUAGE="unknown"
+VERSION="unknown"
+BUILD_TOOL="unknown"
+FRAMEWORK="none"
+PROJECT_TYPE="unknown"
+QUALITY_TOOLS=()
+TEST_FRAMEWORK="unknown"
+HAS_DOCKER=false
+CI="none"
+
+# Detect language and version
+detect_language() {
+    if [ -f "go.mod" ]; then
+        LANGUAGE="go"
+        VERSION=$(grep '^go ' go.mod | awk '{print $2}' || echo "unknown")
+        BUILD_TOOL="go"
+        TEST_FRAMEWORK="testing"
+
+        # Detect Go project type
+        if [ -d "cmd" ]; then
+            PROJECT_TYPE="go-cli"
+        elif grep -q "github.com/gofiber/fiber" go.mod 2>/dev/null; then
+            PROJECT_TYPE="go-web-app"
+            FRAMEWORK="fiber"
+        elif grep -q "github.com/labstack/echo" go.mod 2>/dev/null; then
+            PROJECT_TYPE="go-web-app"
+            FRAMEWORK="echo"
+        elif grep -q "github.com/gin-gonic/gin" go.mod 2>/dev/null; then
+            PROJECT_TYPE="go-web-app"
+            FRAMEWORK="gin"
+        else
+            PROJECT_TYPE="go-library"
+        fi
+
+        # Detect Go quality tools
+        [ -f ".golangci.yml" ] || [ -f ".golangci.yaml" ] && QUALITY_TOOLS+=("golangci-lint")
+        command -v gofmt &>/dev/null && QUALITY_TOOLS+=("gofmt")
+
+    elif [ -f "composer.json" ]; then
+        LANGUAGE="php"
+        VERSION=$(jq -r '.require.php // "unknown"' composer.json 2>/dev/null || echo "unknown")
+        BUILD_TOOL="composer"
+
+        # Detect PHP framework
+        if jq -e '.require."typo3/cms-core"' composer.json &>/dev/null; then
+            PROJECT_TYPE="php-typo3"
+            FRAMEWORK="typo3"
+            TYPO3_VERSION=$(jq -r '.require."typo3/cms-core"' composer.json 2>/dev/null || echo "unknown")
+        elif jq -e '.require."laravel/framework"' composer.json &>/dev/null; then
+            PROJECT_TYPE="php-laravel"
+            FRAMEWORK="laravel"
+        elif jq -e '.require."symfony/symfony"' composer.json &>/dev/null; then
+            PROJECT_TYPE="php-symfony"
+            FRAMEWORK="symfony"
+        else
+            PROJECT_TYPE="php-library"
+        fi
+
+        # Detect PHP quality tools
+        jq -e '.require."phpstan/phpstan"' composer.json &>/dev/null && QUALITY_TOOLS+=("phpstan")
+        jq -e '.require."friendsofphp/php-cs-fixer"' composer.json &>/dev/null && QUALITY_TOOLS+=("php-cs-fixer")
+        [ -f "phpunit.xml" ] || [ -f "phpunit.xml.dist" ] && TEST_FRAMEWORK="phpunit"
+
+    elif [ -f "package.json" ]; then
+        LANGUAGE="typescript"
+        VERSION=$(jq -r '.engines.node // "unknown"' package.json 2>/dev/null || echo "unknown")
+
+        # Detect JS/TS framework
+        if jq -e '.dependencies."next"' package.json &>/dev/null; then
+            PROJECT_TYPE="typescript-nextjs"
+            FRAMEWORK="next.js"
+            BUILD_TOOL="npm"
+        elif jq -e '.dependencies."react"' package.json &>/dev/null; then
+            PROJECT_TYPE="typescript-react"
+            FRAMEWORK="react"
+            BUILD_TOOL="npm"
+        elif jq -e '.dependencies."vue"' package.json &>/dev/null; then
+            PROJECT_TYPE="typescript-vue"
+            FRAMEWORK="vue"
+            BUILD_TOOL="npm"
+        elif jq -e '.dependencies."express"' package.json &>/dev/null; then
+            PROJECT_TYPE="typescript-node"
+            FRAMEWORK="express"
+            BUILD_TOOL="npm"
+        else
+            PROJECT_TYPE="typescript-library"
+            BUILD_TOOL="npm"
+        fi
+
+        # Check for yarn/pnpm
+        [ -f "yarn.lock" ] && BUILD_TOOL="yarn"
+        [ -f "pnpm-lock.yaml" ] && BUILD_TOOL="pnpm"
+
+        # Detect quality tools
+        jq -e '.devDependencies."eslint"' package.json &>/dev/null && QUALITY_TOOLS+=("eslint")
+        jq -e '.devDependencies."prettier"' package.json &>/dev/null && QUALITY_TOOLS+=("prettier")
+        jq -e '.devDependencies."typescript"' package.json &>/dev/null && QUALITY_TOOLS+=("tsc")
+
+        # Detect test framework
+        if jq -e '.devDependencies."jest"' package.json &>/dev/null; then
+            TEST_FRAMEWORK="jest"
+        elif jq -e '.devDependencies."vitest"' package.json &>/dev/null; then
+            TEST_FRAMEWORK="vitest"
+        fi
+
+    elif [ -f "pyproject.toml" ]; then
+        LANGUAGE="python"
+        VERSION=$(grep 'requires-python' pyproject.toml | cut -d'"' -f2 2>/dev/null || echo "unknown")
+
+        # Detect Python build tool
+        if grep -q '\[tool.poetry\]' pyproject.toml 2>/dev/null; then
+            BUILD_TOOL="poetry"
+        elif grep -q '\[tool.hatch\]' pyproject.toml 2>/dev/null; then
+            BUILD_TOOL="hatch"
+        else
+            BUILD_TOOL="pip"
+        fi
+
+        # Detect framework
+        if grep -q 'django' pyproject.toml 2>/dev/null; then
+            PROJECT_TYPE="python-django"
+            FRAMEWORK="django"
+        elif grep -q 'flask' pyproject.toml 2>/dev/null; then
+            PROJECT_TYPE="python-flask"
+            FRAMEWORK="flask"
+        elif grep -q 'fastapi' pyproject.toml 2>/dev/null; then
+            PROJECT_TYPE="python-fastapi"
+            FRAMEWORK="fastapi"
+        elif [ -d "scripts" ] && [ "$(find scripts -name '*.py' | wc -l)" -gt 3 ]; then
+            PROJECT_TYPE="python-cli"
+        else
+            PROJECT_TYPE="python-library"
+        fi
+
+        # Detect quality tools
+        grep -q 'ruff' pyproject.toml 2>/dev/null && QUALITY_TOOLS+=("ruff")
+        grep -q 'black' pyproject.toml 2>/dev/null && QUALITY_TOOLS+=("black")
+        grep -q 'mypy' pyproject.toml 2>/dev/null && QUALITY_TOOLS+=("mypy")
+        grep -q 'pytest' pyproject.toml 2>/dev/null && TEST_FRAMEWORK="pytest"
+    fi
+}
+
+# Detect if Makefile exists
+if [ -f "Makefile" ]; then
+    BUILD_TOOL="make"
+fi
+
+# Detect Docker
+[ -f "Dockerfile" ] || [ -f "docker-compose.yml" ] && HAS_DOCKER=true
+
+# Detect CI
+if [ -d ".github/workflows" ]; then
+    CI="github-actions"
+elif [ -f ".gitlab-ci.yml" ]; then
+    CI="gitlab-ci"
+elif [ -f ".circleci/config.yml" ]; then
+    CI="circleci"
+fi
+
+# Run detection
+detect_language
+
+# Output JSON
+# Handle empty quality_tools array
+if [ ${#QUALITY_TOOLS[@]} -eq 0 ]; then
+    TOOLS_JSON="[]"
+else
+    TOOLS_JSON="$(printf '%s\n' "${QUALITY_TOOLS[@]}" | jq -R . | jq -s .)"
+fi
+
+jq -n \
+    --arg type "$PROJECT_TYPE" \
+    --arg lang "$LANGUAGE" \
+    --arg ver "$VERSION" \
+    --arg build "$BUILD_TOOL" \
+    --arg framework "$FRAMEWORK" \
+    --argjson docker "$HAS_DOCKER" \
+    --argjson tools "$TOOLS_JSON" \
+    --arg test "$TEST_FRAMEWORK" \
+    --arg ci "$CI" \
+    '{
+        type: $type,
+        language: $lang,
+        version: $ver,
+        build_tool: $build,
+        framework: $framework,
+        has_docker: $docker,
+        quality_tools: $tools,
+        test_framework: $test,
+        ci: $ci
+    }'
--- a/scripts/detect-scopes.sh
+++ b/scripts/detect-scopes.sh
@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+# Detect directories that should have scoped AGENTS.md files
+set -euo pipefail
+
+PROJECT_DIR="${1:-.}"
+cd "$PROJECT_DIR"
+
+MIN_FILES=5  # Minimum files to warrant scoped AGENTS.md
+
+# Get project info
+PROJECT_INFO=$(bash "$(dirname "$0")/detect-project.sh" "$PROJECT_DIR")
+LANGUAGE=$(echo "$PROJECT_INFO" | jq -r '.language')
+
+scopes=()
+
+# Function to count source files in a directory
+count_source_files() {
+    local dir="$1"
+    local pattern="$2"
+    find "$dir" -maxdepth 3 -type f -name "$pattern" 2>/dev/null | wc -l
+}
+
+# Function to add scope
+add_scope() {
+    local path="$1"
+    local type="$2"
+    local count="$3"
+
+    scopes+=("{\"path\": \"$path\", \"type\": \"$type\", \"files\": $count}")
+}
+
+# Language-specific scope detection
+case "$LANGUAGE" in
+    "go")
+        # Check common Go directories
+        [ -d "internal" ] && {
+            count=$(count_source_files "internal" "*.go")
+            [ "$count" -ge "$MIN_FILES" ] && add_scope "internal" "backend-go" "$count"
+        }
+
+        [ -d "pkg" ] && {
+            count=$(count_source_files "pkg" "*.go")
+            [ "$count" -ge "$MIN_FILES" ] && add_scope "pkg" "backend-go" "$count"
+        }
+
+        [ -d "cmd" ] && {
+            count=$(count_source_files "cmd" "*.go")
+            [ "$count" -ge 3 ] && add_scope "cmd" "cli" "$count"
+        }
+
+        [ -d "examples" ] && {
+            count=$(count_source_files "examples" "*.go")
+            [ "$count" -ge 3 ] && add_scope "examples" "examples" "$count"
+        }
+
+        [ -d "testutil" ] && {
+            count=$(count_source_files "testutil" "*.go")
+            [ "$count" -ge 3 ] && add_scope "testutil" "testing" "$count"
+        }
+
+        [ -d "docs" ] && {
+            count=$(find docs -type f \( -name "*.md" -o -name "*.rst" \) | wc -l)
+            [ "$count" -ge 3 ] && add_scope "docs" "documentation" "$count"
+        }
+        ;;
+
+    "php")
+        # Check common PHP directories
+        [ -d "Classes" ] && {
+            count=$(count_source_files "Classes" "*.php")
+            [ "$count" -ge "$MIN_FILES" ] && add_scope "Classes" "backend-php" "$count"
+        }
+
+        [ -d "src" ] && {
+            count=$(count_source_files "src" "*.php")
+            [ "$count" -ge "$MIN_FILES" ] && add_scope "src" "backend-php" "$count"
+        }
+
+        [ -d "Tests" ] && {
+            count=$(count_source_files "Tests" "*.php")
+            [ "$count" -ge 3 ] && add_scope "Tests" "testing" "$count"
+        }
+
+        [ -d "tests" ] && {
+            count=$(count_source_files "tests" "*.php")
+            [ "$count" -ge 3 ] && add_scope "tests" "testing" "$count"
+        }
+
+        [ -d "Documentation" ] && {
+            count=$(find Documentation -type f \( -name "*.rst" -o -name "*.md" \) | wc -l)
+            [ "$count" -ge 3 ] && add_scope "Documentation" "documentation" "$count"
+        }
+
+        [ -d "Resources" ] && {
+            count=$(find Resources -type f | wc -l)
+            [ "$count" -ge 5 ] && add_scope "Resources" "resources" "$count"
+        }
+        ;;
+
+    "typescript")
+        # Check common TypeScript/JavaScript directories
+        [ -d "src" ] && {
+            count=$(count_source_files "src" "*.ts")
+            ts_count=$count
+            count=$(count_source_files "src" "*.tsx")
+            tsx_count=$count
+
+            if [ "$tsx_count" -ge "$MIN_FILES" ]; then
+                add_scope "src" "frontend-typescript" "$tsx_count"
+            elif [ "$ts_count" -ge "$MIN_FILES" ]; then
+                add_scope "src" "backend-typescript" "$ts_count"
+            fi
+        }
+
+        [ -d "components" ] && {
+            count=$(count_source_files "components" "*.tsx")
+            [ "$count" -ge "$MIN_FILES" ] && add_scope "components" "frontend-typescript" "$count"
+        }
+
+        [ -d "pages" ] && {
+            count=$(count_source_files "pages" "*.tsx")
+            [ "$count" -ge 3 ] && add_scope "pages" "frontend-typescript" "$count"
+        }
+
+        [ -d "app" ] && {
+            count=$(count_source_files "app" "*.tsx")
+            [ "$count" -ge 3 ] && add_scope "app" "frontend-typescript" "$count"
+        }
+
+        [ -d "server" ] || [ -d "backend" ] && {
+            dir=$([ -d "server" ] && echo "server" || echo "backend")
+            count=$(count_source_files "$dir" "*.ts")
+            [ "$count" -ge "$MIN_FILES" ] && add_scope "$dir" "backend-typescript" "$count"
+        }
+
+        [ -d "__tests__" ] || [ -d "tests" ] && {
+            dir=$([ -d "__tests__" ] && echo "__tests__" || echo "tests")
+            count=$(count_source_files "$dir" "*.test.ts")
+            [ "$count" -ge 3 ] && add_scope "$dir" "testing" "$count"
+        }
+        ;;
+
+    "python")
+        # Check common Python directories
+        [ -d "src" ] && {
+            count=$(count_source_files "src" "*.py")
+            [ "$count" -ge "$MIN_FILES" ] && add_scope "src" "backend-python" "$count"
+        }
+
+        [ -d "tests" ] && {
+            count=$(count_source_files "tests" "*.py")
+            [ "$count" -ge 3 ] && add_scope "tests" "testing" "$count"
+        }
+
+        [ -d "scripts" ] && {
+            count=$(count_source_files "scripts" "*.py")
+            [ "$count" -ge 3 ] && add_scope "scripts" "cli" "$count"
+        }
+
+        [ -d "docs" ] && {
+            count=$(find docs -type f \( -name "*.md" -o -name "*.rst" \) | wc -l)
+            [ "$count" -ge 3 ] && add_scope "docs" "documentation" "$count"
+        }
+        ;;
+esac
+
+# Check for web subdirectories (cross-language)
+if [ -d "internal/web" ]; then
+    count=$(find internal/web -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) | wc -l)
+    [ "$count" -ge "$MIN_FILES" ] && add_scope "internal/web" "frontend-typescript" "$count"
+fi
+
+# Output JSON
+if [ ${#scopes[@]} -eq 0 ]; then
+    echo '{"scopes": []}'
+else
+    echo "{\"scopes\": [$(IFS=,; echo "${scopes[*]}")]}"
+fi
--- a/scripts/extract-commands.sh
+++ b/scripts/extract-commands.sh
@@ -0,0 +1,183 @@
+#!/usr/bin/env bash
+# Extract build commands from various build tool files
+set -euo pipefail
+
+PROJECT_DIR="${1:-.}"
+cd "$PROJECT_DIR"
+
+# Get project info
+PROJECT_INFO=$(bash "$(dirname "$0")/detect-project.sh" "$PROJECT_DIR")
+LANGUAGE=$(echo "$PROJECT_INFO" | jq -r '.language')
+BUILD_TOOL=$(echo "$PROJECT_INFO" | jq -r '.build_tool')
+
+# Initialize command variables
+TYPECHECK_CMD=""
+LINT_CMD=""
+FORMAT_CMD=""
+TEST_CMD=""
+BUILD_CMD=""
+DEV_CMD=""
+
+# Extract from Makefile
+extract_from_makefile() {
+    [ ! -f "Makefile" ] && return
+
+    # Extract targets with ## comments
+    while IFS= read -r line; do
+        if [[ $line =~ ^([a-zA-Z_-]+):.*\#\#(.*)$ ]]; then
+            target="${BASH_REMATCH[1]}"
+            description="${BASH_REMATCH[2]}"
+
+            case "$target" in
+                lint|check) LINT_CMD="make $target" ;;
+                format|fmt) FORMAT_CMD="make $target" ;;
+                test|tests) TEST_CMD="make $target" ;;
+                build) BUILD_CMD="make $target" ;;
+                typecheck|types) TYPECHECK_CMD="make $target" ;;
+                dev|serve) DEV_CMD="make $target" ;;
+            esac
+        fi
+    done < Makefile
+}
+
+# Extract from package.json
+extract_from_package_json() {
+    [ ! -f "package.json" ] && return
+
+    TYPECHECK_CMD=$(jq -r '.scripts.typecheck // .scripts["type-check"] // empty' package.json 2>/dev/null)
+    [ -n "$TYPECHECK_CMD" ] && TYPECHECK_CMD="npm run typecheck" || TYPECHECK_CMD="npx tsc --noEmit"
+
+    LINT_CMD=$(jq -r '.scripts.lint // empty' package.json 2>/dev/null)
+    [ -n "$LINT_CMD" ] && LINT_CMD="npm run lint" || LINT_CMD="npx eslint ."
+
+    FORMAT_CMD=$(jq -r '.scripts.format // empty' package.json 2>/dev/null)
+    [ -n "$FORMAT_CMD" ] && FORMAT_CMD="npm run format" || FORMAT_CMD="npx prettier --write ."
+
+    TEST_CMD=$(jq -r '.scripts.test // empty' package.json 2>/dev/null)
+    [ -n "$TEST_CMD" ] && TEST_CMD="npm test"
+
+    BUILD_CMD=$(jq -r '.scripts.build // empty' package.json 2>/dev/null)
+    [ -n "$BUILD_CMD" ] && BUILD_CMD="npm run build"
+
+    DEV_CMD=$(jq -r '.scripts.dev // .scripts.start // empty' package.json 2>/dev/null)
+    [ -n "$DEV_CMD" ] && DEV_CMD="npm run dev"
+}
+
+# Extract from composer.json
+extract_from_composer_json() {
+    [ ! -f "composer.json" ] && return
+
+    LINT_CMD=$(jq -r '.scripts.lint // .scripts["cs:check"] // empty' composer.json 2>/dev/null)
+    [ -n "$LINT_CMD" ] && LINT_CMD="composer run lint"
+
+    FORMAT_CMD=$(jq -r '.scripts.format // .scripts["cs:fix"] // empty' composer.json 2>/dev/null)
+    [ -n "$FORMAT_CMD" ] && FORMAT_CMD="composer run format"
+
+    TEST_CMD=$(jq -r '.scripts.test // empty' composer.json 2>/dev/null)
+    [ -n "$TEST_CMD" ] && TEST_CMD="composer run test" || TEST_CMD="vendor/bin/phpunit"
+
+    TYPECHECK_CMD=$(jq -r '.scripts.phpstan // .scripts["stan"] // empty' composer.json 2>/dev/null)
+    [ -n "$TYPECHECK_CMD" ] && TYPECHECK_CMD="composer run phpstan" || {
+        if [ -f "phpstan.neon" ] || [ -f "Build/phpstan.neon" ]; then
+            TYPECHECK_CMD="vendor/bin/phpstan analyze"
+        fi
+    }
+}
+
+# Extract from pyproject.toml
+extract_from_pyproject() {
+    [ ! -f "pyproject.toml" ] && return
+
+    # Check for ruff
+    if grep -q '\[tool.ruff\]' pyproject.toml; then
+        LINT_CMD="ruff check ."
+        FORMAT_CMD="ruff format ."
+    fi
+
+    # Check for black
+    if grep -q 'black' pyproject.toml; then
+        FORMAT_CMD="black ."
+    fi
+
+    # Check for mypy
+    if grep -q 'mypy' pyproject.toml; then
+        TYPECHECK_CMD="mypy ."
+    fi
+
+    # Check for pytest
+    if grep -q 'pytest' pyproject.toml; then
+        TEST_CMD="pytest"
+    fi
+}
+
+# Language-specific defaults
+set_language_defaults() {
+    case "$LANGUAGE" in
+        "go")
+            [ -z "$TYPECHECK_CMD" ] && TYPECHECK_CMD="go build -v ./..."
+            [ -z "$LINT_CMD" ] && {
+                if [ -f ".golangci.yml" ] || [ -f ".golangci.yaml" ]; then
+                    LINT_CMD="golangci-lint run ./..."
+                fi
+            }
+            [ -z "$FORMAT_CMD" ] && FORMAT_CMD="gofmt -w ."
+            [ -z "$TEST_CMD" ] && TEST_CMD="go test -v -race -short ./..."
+            [ -z "$BUILD_CMD" ] && BUILD_CMD="go build -v ./..."
+            ;;
+
+        "php")
+            [ -z "$TYPECHECK_CMD" ] && {
+                if [ -f "phpstan.neon" ] || [ -f "Build/phpstan.neon" ]; then
+                    TYPECHECK_CMD="vendor/bin/phpstan analyze"
+                fi
+            }
+            [ -z "$LINT_CMD" ] && LINT_CMD="vendor/bin/php-cs-fixer fix --dry-run"
+            [ -z "$FORMAT_CMD" ] && FORMAT_CMD="vendor/bin/php-cs-fixer fix"
+            [ -z "$TEST_CMD" ] && TEST_CMD="vendor/bin/phpunit"
+            ;;
+
+        "typescript")
+            [ -z "$TYPECHECK_CMD" ] && TYPECHECK_CMD="npx tsc --noEmit"
+            [ -z "$LINT_CMD" ] && LINT_CMD="npx eslint ."
+            [ -z "$FORMAT_CMD" ] && FORMAT_CMD="npx prettier --write ."
+            [ -z "$TEST_CMD" ] && {
+                if [ -f "jest.config.js" ] || [ -f "jest.config.ts" ]; then
+                    TEST_CMD="npm test"
+                elif grep -q 'vitest' package.json 2>/dev/null; then
+                    TEST_CMD="npx vitest"
+                fi
+            }
+            ;;
+
+        "python")
+            [ -z "$LINT_CMD" ] && LINT_CMD="ruff check ."
+            [ -z "$FORMAT_CMD" ] && FORMAT_CMD="ruff format ."
+            [ -z "$TYPECHECK_CMD" ] && TYPECHECK_CMD="mypy ."
+            [ -z "$TEST_CMD" ] && TEST_CMD="pytest"
+            ;;
+    esac
+}
+
+# Run extraction
+extract_from_makefile
+extract_from_package_json
+extract_from_composer_json
+extract_from_pyproject
+set_language_defaults
+
+# Output JSON
+jq -n \
+    --arg typecheck "$TYPECHECK_CMD" \
+    --arg lint "$LINT_CMD" \
+    --arg format "$FORMAT_CMD" \
+    --arg test "$TEST_CMD" \
+    --arg build "$BUILD_CMD" \
+    --arg dev "$DEV_CMD" \
+    '{
+        typecheck: $typecheck,
+        lint: $lint,
+        format: $format,
+        test: $test,
+        build: $build,
+        dev: $dev
+    }'
--- a/scripts/generate-agents.sh
+++ b/scripts/generate-agents.sh
@@ -0,0 +1,292 @@
+#!/usr/bin/env bash
+# Main AGENTS.md generator script
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(dirname "$SCRIPT_DIR")"
+TEMPLATE_DIR="$SKILL_DIR/templates"
+
+# Source helper library
+source "$SCRIPT_DIR/lib/template.sh"
+
+# Default options
+PROJECT_DIR="${1:-.}"
+STYLE="${STYLE:-thin}"
+DRY_RUN=false
+UPDATE_ONLY=false
+FORCE=false
+VERBOSE=false
+
+# Parse flags
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --style=*)
+            STYLE="${1#*=}"
+            shift
+            ;;
+        --dry-run)
+            DRY_RUN=true
+            shift
+            ;;
+        --update)
+            UPDATE_ONLY=true
+            shift
+            ;;
+        --force)
+            FORCE=true
+            shift
+            ;;
+        --verbose|-v)
+            VERBOSE=true
+            shift
+            ;;
+        --help|-h)
+            cat <<EOF
+Usage: generate-agents.sh [PROJECT_DIR] [OPTIONS]
+
+Generate AGENTS.md files for a project following the public agents.md convention.
+
+Options:
+  --style=thin|verbose    Template style (default: thin)
+  --dry-run               Preview what will be created
+  --update                Update existing files only
+  --force                 Force regeneration of existing files
+  --verbose, -v           Verbose output
+  --help, -h              Show this help message
+
+Examples:
+  generate-agents.sh .                    # Generate thin root + scoped files
+  generate-agents.sh . --dry-run          # Preview changes
+  generate-agents.sh . --style=verbose    # Use verbose root template
+  generate-agents.sh . --update           # Update existing files
+EOF
+            exit 0
+            ;;
+        *)
+            PROJECT_DIR="$1"
+            shift
+            ;;
+    esac
+done
+
+cd "$PROJECT_DIR"
+
+log() {
+    [ "$VERBOSE" = true ] && echo "[INFO] $*" >&2
+}
+
+error() {
+    echo "[ERROR] $*" >&2
+    exit 1
+}
+
+# Detect project
+log "Detecting project type..."
+PROJECT_INFO=$("$SCRIPT_DIR/detect-project.sh" "$PROJECT_DIR")
+[ "$VERBOSE" = true ] && echo "$PROJECT_INFO" | jq . >&2
+
+LANGUAGE=$(echo "$PROJECT_INFO" | jq -r '.language')
+VERSION=$(echo "$PROJECT_INFO" | jq -r '.version')
+PROJECT_TYPE=$(echo "$PROJECT_INFO" | jq -r '.type')
+
+[ "$LANGUAGE" = "unknown" ] && error "Could not detect project language"
+
+# Detect scopes
+log "Detecting scopes..."
+SCOPES_INFO=$("$SCRIPT_DIR/detect-scopes.sh" "$PROJECT_DIR")
+[ "$VERBOSE" = true ] && echo "$SCOPES_INFO" | jq . >&2
+
+# Extract commands
+log "Extracting build commands..."
+COMMANDS=$("$SCRIPT_DIR/extract-commands.sh" "$PROJECT_DIR")
+[ "$VERBOSE" = true ] && echo "$COMMANDS" | jq . >&2
+
+# Generate root AGENTS.md
+ROOT_FILE="$PROJECT_DIR/AGENTS.md"
+
+if [ -f "$ROOT_FILE" ] && [ "$FORCE" = false ] && [ "$UPDATE_ONLY" = false ]; then
+    log "Root AGENTS.md already exists, skipping (use --force to regenerate)"
+elif [ "$DRY_RUN" = true ]; then
+    echo "[DRY-RUN] Would create/update: $ROOT_FILE"
+else
+    log "Generating root AGENTS.md..."
+
+    # Select template
+    if [ "$STYLE" = "verbose" ]; then
+        TEMPLATE="$TEMPLATE_DIR/root-verbose.md"
+    else
+        TEMPLATE="$TEMPLATE_DIR/root-thin.md"
+    fi
+
+    # Prepare template variables
+    declare -A vars
+    vars[TIMESTAMP]=$(get_timestamp)
+    vars[LANGUAGE_CONVENTIONS]=$(get_language_conventions "$LANGUAGE" "$VERSION")
+    vars[TYPECHECK_CMD]=$(echo "$COMMANDS" | jq -r '.typecheck')
+    vars[LINT_CMD]=$(echo "$COMMANDS" | jq -r '.lint')
+    vars[FORMAT_CMD]=$(echo "$COMMANDS" | jq -r '.format' | sed 's/^/ (file scope): /')
+    vars[TEST_CMD]=$(echo "$COMMANDS" | jq -r '.test')
+    vars[SCOPE_INDEX]=$(build_scope_index "$SCOPES_INFO")
+
+    # Verbose template additional vars
+    if [ "$STYLE" = "verbose" ]; then
+        vars[PROJECT_DESCRIPTION]="TODO: Add project description"
+        vars[VERSION]="$VERSION"
+        vars[BUILD_TOOL]=$(echo "$PROJECT_INFO" | jq -r '.build_tool')
+        vars[FRAMEWORK]=$(echo "$PROJECT_INFO" | jq -r '.framework')
+        vars[PROJECT_TYPE]="$PROJECT_TYPE"
+        vars[BUILD_CMD]=$(echo "$COMMANDS" | jq -r '.build')
+        vars[QUALITY_STANDARDS]="TODO: Add quality standards"
+        vars[SECURITY_SPECIFIC]="TODO: Add security-specific guidelines"
+        vars[TEST_COVERAGE]="40"
+        vars[TEST_FAST_CMD]=$(echo "$COMMANDS" | jq -r '.test')
+        vars[TEST_FULL_CMD]=$(echo "$COMMANDS" | jq -r '.test')
+        vars[ARCHITECTURE_DOC]="./docs/architecture.md"
+        vars[API_DOC]="./docs/api.md"
+        vars[CONTRIBUTING_DOC]="./CONTRIBUTING.md"
+    fi
+
+    # Language-specific conflict resolution
+    case "$LANGUAGE" in
+        "go")
+            vars[LANGUAGE_SPECIFIC_CONFLICT_RESOLUTION]="- For Go-specific patterns, defer to language idioms and standard library conventions"
+            ;;
+        *)
+            vars[LANGUAGE_SPECIFIC_CONFLICT_RESOLUTION]=""
+            ;;
+    esac
+
+    # Render template
+    render_template "$TEMPLATE" "$ROOT_FILE" vars
+
+    echo "✅ Created: $ROOT_FILE"
+fi
+
+# Generate scoped AGENTS.md files
+SCOPE_COUNT=$(echo "$SCOPES_INFO" | jq '.scopes | length')
+
+if [ "$SCOPE_COUNT" -eq 0 ]; then
+    log "No scopes detected (directories with <$MIN_FILES source files)"
+else
+    log "Generating $SCOPE_COUNT scoped AGENTS.md files..."
+
+    while read -r scope; do
+        SCOPE_PATH=$(echo "$scope" | jq -r '.path')
+        SCOPE_TYPE=$(echo "$scope" | jq -r '.type')
+        SCOPE_FILE="$PROJECT_DIR/$SCOPE_PATH/AGENTS.md"
+
+        if [ -f "$SCOPE_FILE" ] && [ "$FORCE" = false ] && [ "$UPDATE_ONLY" = false ]; then
+            log "Scoped AGENTS.md already exists: $SCOPE_PATH, skipping"
+            continue
+        fi
+
+        if [ "$DRY_RUN" = true ]; then
+            echo "[DRY-RUN] Would create/update: $SCOPE_FILE"
+            continue
+        fi
+
+        # Select template based on scope type
+        SCOPE_TEMPLATE="$TEMPLATE_DIR/scoped/$SCOPE_TYPE.md"
+
+        if [ ! -f "$SCOPE_TEMPLATE" ]; then
+            log "No template for scope type: $SCOPE_TYPE, skipping $SCOPE_PATH"
+            continue
+        fi
+
+        # Prepare scoped template variables
+        declare -A scope_vars
+        scope_vars[TIMESTAMP]=$(get_timestamp)
+        scope_vars[SCOPE_NAME]=$(basename "$SCOPE_PATH")
+        scope_vars[SCOPE_DESCRIPTION]=$(get_scope_description "$SCOPE_TYPE")
+        scope_vars[FILE_PATH]="<file>"
+        scope_vars[HOUSE_RULES]=""
+
+        # Language-specific variables
+        case "$SCOPE_TYPE" in
+            "backend-go")
+                scope_vars[GO_VERSION]="$VERSION"
+                scope_vars[GO_MINOR_VERSION]=$(echo "$VERSION" | cut -d. -f2)
+                scope_vars[GO_TOOLS]="golangci-lint, gofmt"
+                scope_vars[ENV_VARS]="See .env.example"
+                scope_vars[BUILD_CMD]=$(echo "$COMMANDS" | jq -r '.build')
+                ;;
+
+            "backend-php")
+                scope_vars[PHP_VERSION]="$VERSION"
+                FRAMEWORK=$(echo "$PROJECT_INFO" | jq -r '.framework')
+                scope_vars[FRAMEWORK]="$FRAMEWORK"
+                scope_vars[PHP_EXTENSIONS]="json, mbstring, xml"
+                scope_vars[ENV_VARS]="See .env.example"
+                scope_vars[PHPSTAN_LEVEL]="10"
+                scope_vars[BUILD_CMD]=$(echo "$COMMANDS" | jq -r '.build')
+
+                if [ "$FRAMEWORK" = "typo3" ]; then
+                    scope_vars[FRAMEWORK_CONVENTIONS]="- TYPO3-specific: Use dependency injection, follow TYPO3 CGL"
+                    scope_vars[FRAMEWORK_DOCS]="- TYPO3 documentation: https://docs.typo3.org"
+                else
+                    scope_vars[FRAMEWORK_CONVENTIONS]=""
+                    scope_vars[FRAMEWORK_DOCS]=""
+                fi
+                ;;
+
+            "frontend-typescript")
+                scope_vars[NODE_VERSION]="$VERSION"
+                FRAMEWORK=$(echo "$PROJECT_INFO" | jq -r '.framework')
+                scope_vars[FRAMEWORK]="$FRAMEWORK"
+                scope_vars[PACKAGE_MANAGER]=$(echo "$PROJECT_INFO" | jq -r '.build_tool')
+                scope_vars[ENV_VARS]="See .env.example"
+                scope_vars[BUILD_CMD]=$(echo "$COMMANDS" | jq -r '.build')
+                scope_vars[DEV_CMD]=$(echo "$COMMANDS" | jq -r '.dev')
+                scope_vars[CSS_APPROACH]="CSS Modules"
+
+                case "$FRAMEWORK" in
+                    "react")
+                        scope_vars[FRAMEWORK_CONVENTIONS]="- Use functional components with hooks\n- Avoid class components"
+                        scope_vars[FRAMEWORK_DOCS]="https://react.dev"
+                        ;;
+                    "next.js")
+                        scope_vars[FRAMEWORK_CONVENTIONS]="- Use App Router (app/)\n- Server Components by default"
+                        scope_vars[FRAMEWORK_DOCS]="https://nextjs.org/docs"
+                        ;;
+                    "vue")
+                        scope_vars[FRAMEWORK_CONVENTIONS]="- Use Composition API\n- Avoid Options API for new code"
+                        scope_vars[FRAMEWORK_DOCS]="https://vuejs.org/guide"
+                        ;;
+                    *)
+                        scope_vars[FRAMEWORK_CONVENTIONS]=""
+                        scope_vars[FRAMEWORK_DOCS]=""
+                        ;;
+                esac
+                ;;
+
+            "cli")
+                scope_vars[LANGUAGE]="$LANGUAGE"
+                CLI_FRAMEWORK="standard"
+                [ -f "go.mod" ] && grep -q "github.com/spf13/cobra" go.mod 2>/dev/null && CLI_FRAMEWORK="cobra"
+                [ -f "go.mod" ] && grep -q "github.com/urfave/cli" go.mod 2>/dev/null && CLI_FRAMEWORK="urfave/cli"
+                scope_vars[CLI_FRAMEWORK]="$CLI_FRAMEWORK"
+                scope_vars[BUILD_OUTPUT_PATH]="./bin/"
+                scope_vars[SETUP_INSTRUCTIONS]="- Build: $(echo "$COMMANDS" | jq -r '.build')"
+                scope_vars[BUILD_CMD]=$(echo "$COMMANDS" | jq -r '.build')
+                scope_vars[RUN_CMD]="./bin/$(basename "$PROJECT_DIR")"
+                scope_vars[TEST_CMD]=$(echo "$COMMANDS" | jq -r '.test')
+                scope_vars[LINT_CMD]=$(echo "$COMMANDS" | jq -r '.lint')
+                ;;
+        esac
+
+        # Render template
+        render_template "$SCOPE_TEMPLATE" "$SCOPE_FILE" scope_vars
+
+        echo "✅ Created: $SCOPE_FILE"
+
+    done < <(echo "$SCOPES_INFO" | jq -c '.scopes[]')
+fi
+
+if [ "$DRY_RUN" = true ]; then
+    echo ""
+    echo "[DRY-RUN] No files were modified. Remove --dry-run to apply changes."
+fi
+
+echo ""
+echo "✅ AGENTS.md generation complete!"
+[ "$SCOPE_COUNT" -gt 0 ] && echo "   Generated: 1 root + $SCOPE_COUNT scoped files"
--- a/scripts/validate-structure.sh
+++ b/scripts/validate-structure.sh
@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+# Validate AGENTS.md structure compliance
+set -euo pipefail
+
+PROJECT_DIR="${1:-.}"
+cd "$PROJECT_DIR"
+
+ERRORS=0
+WARNINGS=0
+
+error() {
+    echo "❌ ERROR: $*"
+    ((ERRORS++))
+}
+
+warning() {
+    echo "⚠️  WARNING: $*"
+    ((WARNINGS++))
+}
+
+success() {
+    echo "✅ $*"
+}
+
+# Check if file has managed header
+check_managed_header() {
+    local file="$1"
+
+    if grep -q "^<!-- Managed by agent:" "$file"; then
+        success "Managed header present: $file"
+        return 0
+    else
+        warning "Missing managed header: $file"
+        return 1
+    fi
+}
+
+# Check if root is thin (≤50 lines or has scope index)
+check_root_is_thin() {
+    local file="$1"
+    local line_count=$(wc -l < "$file")
+
+    if [ "$line_count" -le 50 ]; then
+        success "Root is thin: $line_count lines"
+        return 0
+    elif grep -q "## Index of scoped AGENTS.md" "$file"; then
+        success "Root has scope index (verbose style acceptable)"
+        return 0
+    else
+        error "Root is bloated: $line_count lines and no scope index"
+        return 1
+    fi
+}
+
+# Check if root has precedence statement
+check_precedence_statement() {
+    local file="$1"
+
+    if grep -qi "precedence" "$file" && grep -qi "closest.*AGENTS.md.*wins" "$file"; then
+        success "Precedence statement present"
+        return 0
+    else
+        error "Missing precedence statement in root"
+        return 1
+    fi
+}
+
+# Check if scoped file has all 9 sections
+check_scoped_sections() {
+    local file="$1"
+    local required_sections=(
+        "## Overview"
+        "## Setup & environment"
+        "## Build & tests"
+        "## Code style & conventions"
+        "## Security & safety"
+        "## PR/commit checklist"
+        "## Good vs. bad examples"
+        "## When stuck"
+    )
+
+    local missing=()
+
+    for section in "${required_sections[@]}"; do
+        if ! grep -q "^$section" "$file"; then
+            missing+=("$section")
+        fi
+    done
+
+    if [ ${#missing[@]} -eq 0 ]; then
+        success "All required sections present: $file"
+        return 0
+    else
+        error "Missing sections in $file: ${missing[*]}"
+        return 1
+    fi
+}
+
+# Check if scope index links work
+check_scope_links() {
+    local root_file="$1"
+
+    if ! grep -q "## Index of scoped AGENTS.md" "$root_file"; then
+        return 0  # No index, skip check
+    fi
+
+    # Extract links from scope index
+    local links=$(sed -n '/## Index of scoped AGENTS.md/,/^##/p' "$root_file" | grep -o '\./[^)]*AGENTS.md' || true)
+
+    if [ -z "$links" ]; then
+        warning "Scope index present but no links found"
+        return 1
+    fi
+
+    local broken=()
+    while read -r link; do
+        # Remove leading ./
+        local clean_link="${link#./}"
+        local full_path="$PROJECT_DIR/$clean_link"
+
+        if [ ! -f "$full_path" ]; then
+            broken+=("$link")
+        fi
+    done <<< "$links"
+
+    if [ ${#broken[@]} -eq 0 ]; then
+        success "All scope index links work"
+        return 0
+    else
+        error "Broken scope index links: ${broken[*]}"
+        return 1
+    fi
+}
+
+# Main validation
+echo "Validating AGENTS.md structure in: $PROJECT_DIR"
+echo ""
+
+# Check root AGENTS.md
+ROOT_FILE="$PROJECT_DIR/AGENTS.md"
+
+if [ ! -f "$ROOT_FILE" ]; then
+    error "Root AGENTS.md not found"
+else
+    echo "=== Root AGENTS.md ==="
+    check_managed_header "$ROOT_FILE"
+    check_root_is_thin "$ROOT_FILE"
+    check_precedence_statement "$ROOT_FILE"
+    check_scope_links "$ROOT_FILE"
+    echo ""
+fi
+
+# Check scoped AGENTS.md files
+SCOPED_FILES=$(find "$PROJECT_DIR" -name "AGENTS.md" -not -path "$ROOT_FILE" 2>/dev/null || true)
+
+if [ -n "$SCOPED_FILES" ]; then
+    echo "=== Scoped AGENTS.md Files ==="
+    while read -r file; do
+        rel_path="${file#$PROJECT_DIR/}"
+        echo "Checking: $rel_path"
+        check_managed_header "$file"
+        check_scoped_sections "$file"
+        echo ""
+    done <<< "$SCOPED_FILES"
+fi
+
+# Summary
+echo "=== Validation Summary ==="
+if [ $ERRORS -eq 0 ] && [ $WARNINGS -eq 0 ]; then
+    echo "✅ All checks passed!"
+    exit 0
+elif [ $ERRORS -eq 0 ]; then
+    echo "⚠️  Validation passed with $WARNINGS warning(s)"
+    exit 0
+else
+    echo "❌ Validation failed with $ERRORS error(s) and $WARNINGS warning(s)"
+    exit 1
+fi
--- a/templates/root-thin.md
+++ b/templates/root-thin.md
@@ -0,0 +1,24 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md (root)
+
+This file explains repo-wide conventions and where to find scoped rules.
+**Precedence:** the **closest `AGENTS.md`** to the files you're changing wins. Root holds global defaults only.
+
+## Global rules
+- Keep diffs small; add tests for new code paths
+- Ask first before: adding heavy deps, running full e2e suites, or repo-wide rewrites
+- Never commit secrets or sensitive data to the repository
+{{LANGUAGE_CONVENTIONS}}
+
+## Minimal pre-commit checks
+- Typecheck: {{TYPECHECK_CMD}}
+- Lint/format: {{LINT_CMD}}{{FORMAT_CMD}}
+- Tests: {{TEST_CMD}}
+
+## Index of scoped AGENTS.md
+{{SCOPE_INDEX}}
+
+## When instructions conflict
+- The nearest `AGENTS.md` wins. Explicit user prompts override files.
+{{LANGUAGE_SPECIFIC_CONFLICT_RESOLUTION}}
--- a/templates/root-verbose.md
+++ b/templates/root-verbose.md
@@ -0,0 +1,63 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md (root)
+
+**Precedence:** The **closest AGENTS.md** to changed files wins. Root holds global defaults only.
+
+## Project Overview
+{{PROJECT_DESCRIPTION}}
+
+**Tech Stack**: {{LANGUAGE}} {{VERSION}}, {{BUILD_TOOL}}, {{FRAMEWORK}}
+**Type**: {{PROJECT_TYPE}}
+
+## Global Rules
+- Keep PRs small (~≤300 net LOC)
+- Conventional Commits: `type(scope): subject`
+- Ask before: heavy deps, full e2e, repo rewrites
+- Never commit secrets or PII
+{{LANGUAGE_CONVENTIONS}}
+
+## Development Workflow
+1. Create feature branch: `git checkout -b feature/description`
+2. Make changes with tests
+3. Run pre-commit checks (see below)
+4. Commit with conventional format
+5. Push and create PR
+6. Address review feedback
+7. Merge when approved
+
+## Pre-commit Checks
+**Always run before committing:**
+- Typecheck: {{TYPECHECK_CMD}}
+- Lint: {{LINT_CMD}}
+- Format: {{FORMAT_CMD}}
+- Tests: {{TEST_CMD}}
+- Build: {{BUILD_CMD}}
+
+## Code Quality Standards
+{{QUALITY_STANDARDS}}
+
+## Security & Safety
+- Never commit secrets, credentials, or PII
+- Validate all user inputs
+- Use parameterized queries for database access
+- Keep dependencies updated
+{{SECURITY_SPECIFIC}}
+
+## Testing Requirements
+- Write tests for new features
+- Maintain {{TEST_COVERAGE}}% minimum coverage
+- Run fast tests locally: {{TEST_FAST_CMD}}
+- Run full suite in CI: {{TEST_FULL_CMD}}
+
+## Index of Scoped AGENTS.md
+{{SCOPE_INDEX}}
+
+## When Instructions Conflict
+Nearest AGENTS.md wins. User prompts override files.
+{{LANGUAGE_SPECIFIC_CONFLICT_RESOLUTION}}
+
+## Documentation
+- Architecture: {{ARCHITECTURE_DOC}}
+- API docs: {{API_DOC}}
+- Contributing: {{CONTRIBUTING_DOC}}
--- a/templates/scoped/backend-go.md
+++ b/templates/scoped/backend-go.md
@@ -0,0 +1,77 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+## Overview
+{{SCOPE_DESCRIPTION}}
+
+## Setup & environment
+- Install: `go mod download`
+- Go version: {{GO_VERSION}}
+- Required tools: {{GO_TOOLS}}
+- Environment variables: {{ENV_VARS}}
+
+## Build & tests (prefer file-scoped)
+- Typecheck a file: `go build -v {{FILE_PATH}}`
+- Format a file: `gofmt -w {{FILE_PATH}}`
+- Lint a file: `golangci-lint run {{FILE_PATH}}`
+- Test a file: `go test -v -race -short {{FILE_PATH}}`
+- Build: {{BUILD_CMD}}
+
+## Code style & conventions
+- Follow Go 1.{{GO_MINOR_VERSION}} idioms
+- Use standard library over external deps when possible
+- Errors: wrap with `fmt.Errorf("context: %w", err)`
+- Naming: `camelCase` for private, `PascalCase` for exported
+- Struct tags: use canonical form (json, yaml, etc.)
+- Comments: complete sentences ending with period
+- Package docs: first sentence summarizes purpose
+
+## Security & safety
+- Validate all inputs from external sources
+- Use `context.Context` for cancellation and timeouts
+- Avoid goroutine leaks: always ensure termination paths
+- Sensitive data: never log or include in errors
+- SQL: use parameterized queries only
+- File paths: validate and sanitize user-provided paths
+
+## PR/commit checklist
+- [ ] Tests pass: `go test -v -race ./...`
+- [ ] Lint clean: `golangci-lint run ./...`
+- [ ] Formatted: `gofmt -w .`
+- [ ] No goroutine leaks
+- [ ] Error messages are descriptive
+- [ ] Public APIs have godoc comments
+
+## Good vs. bad examples
+**Good**: Descriptive error wrapping
+```go
+if err := db.Query(); err != nil {
+    return fmt.Errorf("failed to query users table: %w", err)
+}
+```
+
+**Bad**: Generic error messages
+```go
+if err := db.Query(); err != nil {
+    return fmt.Errorf("error: %w", err)
+}
+```
+
+**Good**: Proper context usage
+```go
+func (s *Service) FetchData(ctx context.Context, id string) error {
+    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+    defer cancel()
+    return s.client.Get(ctx, id)
+}
+```
+
+## When stuck
+- Check Go documentation: https://pkg.go.dev
+- Review existing patterns in this codebase
+- Check root AGENTS.md for project-wide conventions
+- Run `go doc <package>` for standard library help
+
+## House Rules (optional)
+{{HOUSE_RULES}}
--- a/templates/scoped/backend-php.md
+++ b/templates/scoped/backend-php.md
@@ -0,0 +1,85 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+## Overview
+{{SCOPE_DESCRIPTION}}
+
+## Setup & environment
+- Install: `composer install`
+- PHP version: {{PHP_VERSION}}
+- Framework: {{FRAMEWORK}}
+- Required extensions: {{PHP_EXTENSIONS}}
+- Environment variables: {{ENV_VARS}}
+
+## Build & tests (prefer file-scoped)
+- Typecheck a file: `vendor/bin/phpstan analyze {{FILE_PATH}} --level={{PHPSTAN_LEVEL}}`
+- Format a file: `vendor/bin/php-cs-fixer fix {{FILE_PATH}}`
+- Lint a file: `php -l {{FILE_PATH}}`
+- Test a file: `vendor/bin/phpunit {{FILE_PATH}}`
+- Build: {{BUILD_CMD}}
+
+## Code style & conventions
+- Follow PSR-12 coding standard
+- Use strict types: `declare(strict_types=1);`
+- Type hints: always use for parameters and return types
+- Naming: `camelCase` for methods, `PascalCase` for classes
+- Visibility: always declare (public, protected, private)
+- PHPDoc: required for public APIs, include `@param` and `@return`
+{{FRAMEWORK_CONVENTIONS}}
+
+## Security & safety
+- Validate and sanitize all user inputs
+- Use prepared statements for database queries
+- Escape output in templates
+- Never use `eval()` or dynamic code execution
+- Sensitive data: never log or expose in errors
+- CSRF protection: enable for all forms
+- XSS protection: escape all user-generated content
+
+## PR/commit checklist
+- [ ] Tests pass: `vendor/bin/phpunit`
+- [ ] PHPStan Level {{PHPSTAN_LEVEL}} clean: `vendor/bin/phpstan analyze`
+- [ ] PSR-12 compliant: `vendor/bin/php-cs-fixer fix --dry-run`
+- [ ] No deprecated functions used
+- [ ] Public methods have PHPDoc
+- [ ] Security: inputs validated, outputs escaped
+
+## Good vs. bad examples
+**Good**: Proper type hints and strict types
+```php
+declare(strict_types=1);
+
+public function calculateTotal(int $quantity, float $price): float
+{
+    return $quantity * $price;
+}
+```
+
+**Bad**: Missing type hints
+```php
+public function calculateTotal($quantity, $price)
+{
+    return $quantity * $price;
+}
+```
+
+**Good**: Prepared statements
+```php
+$stmt = $db->prepare('SELECT * FROM users WHERE id = :id');
+$stmt->execute(['id' => $userId]);
+```
+
+**Bad**: String concatenation
+```php
+$result = $db->query("SELECT * FROM users WHERE id = " . $userId);
+```
+
+## When stuck
+- Check PHP documentation: https://www.php.net
+- {{FRAMEWORK_DOCS}}
+- Review existing patterns in this codebase
+- Check root AGENTS.md for project-wide conventions
+
+## House Rules (optional)
+{{HOUSE_RULES}}
--- a/templates/scoped/cli.md
+++ b/templates/scoped/cli.md
@@ -0,0 +1,84 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+## Overview
+{{SCOPE_DESCRIPTION}}
+
+Command-line interface tools and entry points.
+
+## Setup & environment
+{{SETUP_INSTRUCTIONS}}
+- CLI framework: {{CLI_FRAMEWORK}}
+- Build output: {{BUILD_OUTPUT_PATH}}
+
+## Build & tests (prefer file-scoped)
+- Build CLI: {{BUILD_CMD}}
+- Run CLI: {{RUN_CMD}}
+- Test: {{TEST_CMD}}
+- Lint: {{LINT_CMD}}
+
+## Code style & conventions
+- Use flag parsing library consistently ({{CLI_FRAMEWORK}})
+- Provide `--help` for all commands and subcommands
+- Use `--version` to display version information
+- Exit codes: 0 = success, 1 = general error, 2 = usage error
+- Output: structured (JSON) for scripts, human-readable for interactive
+- Errors: write to stderr, not stdout
+- Progress: show for long-running operations
+- Interactive prompts: support non-interactive mode with flags
+
+## Security & safety
+- Validate all file paths and prevent directory traversal
+- Never execute user-provided code without explicit confirmation
+- Sensitive data: never log or display in plain text
+- Config files: validate schema and permissions
+- Network operations: timeout and retry with backoff
+
+## PR/commit checklist
+- [ ] `--help` text is clear and accurate
+- [ ] `--version` displays correct version
+- [ ] Exit codes are correct
+- [ ] Errors go to stderr
+- [ ] Long operations show progress
+- [ ] Works in non-interactive mode
+- [ ] Tests cover main workflows
+
+## Good vs. bad examples
+**Good**: Proper error handling
+```{{LANGUAGE}}
+if err := runCommand(); err != nil {
+    fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+    os.Exit(1)
+}
+```
+
+**Bad**: Errors to stdout
+```{{LANGUAGE}}
+if err := runCommand(); err != nil {
+    fmt.Println("Error:", err)
+}
+```
+
+**Good**: Clear help text
+```
+Usage: myapp <command> [options]
+
+Commands:
+  init     Initialize a new project
+  build    Build the project
+  deploy   Deploy to production
+
+Options:
+  --config string   Config file path (default: config.yaml)
+  --verbose         Enable verbose output
+```
+
+## When stuck
+- Review {{CLI_FRAMEWORK}} documentation
+- Check existing commands for patterns
+- Test with `--help` to ensure clarity
+- Check root AGENTS.md for project conventions
+
+## House Rules (optional)
+{{HOUSE_RULES}}
--- a/templates/scoped/frontend-typescript.md
+++ b/templates/scoped/frontend-typescript.md
@@ -0,0 +1,96 @@
+<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: {{TIMESTAMP}} -->
+
+# AGENTS.md — {{SCOPE_NAME}}
+
+## Overview
+{{SCOPE_DESCRIPTION}}
+
+## Setup & environment
+- Install: `npm install` or `yarn install`
+- Node version: {{NODE_VERSION}}
+- Framework: {{FRAMEWORK}}
+- Package manager: {{PACKAGE_MANAGER}}
+- Environment variables: {{ENV_VARS}}
+
+## Build & tests (prefer file-scoped)
+- Typecheck a file: `npx tsc --noEmit {{FILE_PATH}}`
+- Lint a file: `npx eslint {{FILE_PATH}}`
+- Format a file: `npx prettier --write {{FILE_PATH}}`
+- Test a file: `npm test {{FILE_PATH}}`
+- Build: {{BUILD_CMD}}
+- Dev server: {{DEV_CMD}}
+
+## Code style & conventions
+- TypeScript strict mode enabled
+- Use functional components with hooks (React)
+- Naming: `camelCase` for variables/functions, `PascalCase` for components
+- File naming: `ComponentName.tsx`, `utilityName.ts`
+- Imports: group and sort (external, internal, types)
+- CSS: {{CSS_APPROACH}} (CSS Modules, Tailwind, styled-components, etc.)
+{{FRAMEWORK_CONVENTIONS}}
+
+## Security & safety
+- Sanitize user inputs before rendering
+- Use `dangerouslySetInnerHTML` only with sanitized content
+- Validate environment variables at build time
+- Never expose secrets in client-side code
+- Use HTTPS for all API calls
+- Implement CSP headers
+- WCAG 2.2 AA accessibility compliance
+
+## PR/commit checklist
+- [ ] Tests pass: `npm test`
+- [ ] TypeScript compiles: `npx tsc --noEmit`
+- [ ] Lint clean: `npm run lint`
+- [ ] Formatted: `npm run format`
+- [ ] Accessibility: keyboard navigation works, ARIA labels present
+- [ ] Responsive: tested on mobile, tablet, desktop
+- [ ] Performance: no unnecessary re-renders
+
+## Good vs. bad examples
+**Good**: Proper TypeScript typing
+```typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+function UserCard({ user }: { user: User }): JSX.Element {
+  return <div>{user.name}</div>;
+}
+```
+
+**Bad**: Using `any`
+```typescript
+function UserCard({ user }: { user: any }) {
+  return <div>{user.name}</div>;
+}
+```
+
+**Good**: Accessible button
+```tsx
+<button
+  onClick={handleClick}
+  aria-label="Close dialog"
+  type="button"
+>
+  <CloseIcon />
+</button>
+```
+
+**Bad**: Non-semantic click handler
+```tsx
+<div onClick={handleClick}>
+  <CloseIcon />
+</div>
+```
+
+## When stuck
+- Check {{FRAMEWORK}} documentation: {{FRAMEWORK_DOCS}}
+- Review TypeScript handbook: https://www.typescriptlang.org/docs/
+- Check root AGENTS.md for project-wide conventions
+- Review existing components for patterns
+
+## House Rules (optional)
+{{HOUSE_RULES}}