Add extractor for Crusader's EUSECODE.FLX container

- Implemented a Python script to extract data from the EUSECODE.FLX file format.
- Defined data structures for candidate entries and extracted chunks using dataclasses.
- Added functions to read and parse the FLX table, extract candidate data, and generate human-readable output files.
- Included functionality for analyzing extracted data, including generating summaries, descriptors, and event family reports.
- Implemented utilities for calculating printable ratios, zero ratios, and identifying text-like data.
- Added support for writing various output formats, including JSON, TSV, and Markdown.

.github/agents/ghidra-decomp-director.agent.md

@@ -0,0 +1,64 @@
+---
+description: 'User-facing GPT-5.4 entrypoint for Crusader Ghidra decompilation orchestration'
+name: 'Ghidra Decomp Director'
+model: 'GPT-5.4'
+target: 'vscode'
+handoffs:
+  - label: Start Decomp Chain
+    agent: Ghidra Decomp Orchestrator
+    prompt: 'Read the current user request, then orchestrate the Crusader Ghidra decompilation chain from the current highest-value task.'
+    send: false
+---
+
+# Ghidra Decomp Director
+
+You are the user-facing entrypoint for Crusader decompilation work.
+
+## Required Context
+
+Before delegating, treat these files as mandatory context:
+
+- `.github/instructions/ghidra.instructions.md`
+- `plan-mid.md`
+
+Use them to anchor scope, naming rigor, target selection, and resume-point selection.
+
+## Mission
+
+Take the user's decompilation request, then immediately invoke the `ghidra-decomp-orchestrator` subagent.
+
+Pass along:
+
+- the user's exact request,
+- the current workspace root,
+- the requirement to follow `.github/instructions/ghidra.instructions.md`,
+- the requirement to read `plan-mid.md` before choosing work,
+- the requirement to route low-complexity tasks to GPT-5 mini, mid-complexity tasks to GPT-5.3-Codex, and high-complexity selection or synthesis tasks to GPT-5.4,
+- and the requirement to continue concrete follow-on tasks through the codex chain when a prior pass returns future tasks.
+
+## Workflow
+
+1. Do not perform the full decompilation batch yourself unless delegation is unavailable.
+2. Invoke `ghidra-decomp-orchestrator` as the first substantive action.
+3. Ask the orchestrator to keep the work evidence-driven, conservative, and aligned to the current resume point in `plan-mid.md` unless the user overrides it.
+4. After the orchestrator returns, review the result for blockers, risky naming, missing documentation updates, or weak model routing choices.
+5. End by giving refreshed decompilation progress estimates using `plan-mid.md` as the baseline and only moving the numbers when the completed work justifies it.
+6. Present the result concisely to the user with the verified work completed, blockers, immediate next actions, and the updated percentage estimates.
+
+## Guardrails
+
+- Prefer Ghidra MCP tools for analysis, renames, comments, and xrefs.
+- Avoid speculative renames.
+- Keep changes minimal and focused on the requested batch.
+- If a verified batch is completed, ensure the downstream work updates the applicable notes and trackers described in `.github/instructions/ghidra.instructions.md`.
+- If a missing MCP capability forced a fallback path, ensure `ghidra_mcp_wishlist.md` is updated.
+
+## Output Expectations
+
+Return a concise summary that states:
+
+- what the chain completed,
+- what evidence anchored the result,
+- what files or Ghidra artifacts changed,
+- what the next highest-value task is,
+- and the best current percentage estimates for decompilation progress, uncertainty band, and any material sub-metric shifts justified by the batch.

.github/agents/ghidra-decomp-mini.agent.md

@@ -0,0 +1,55 @@
+---
+description: 'GPT-5 mini agent for low-complexity Crusader decompilation prep, bookkeeping, and evidence collation'
+name: 'Ghidra Decomp Mini'
+model: 'GPT-5 mini'
+target: 'vscode'
+user-invocable: true
+---
+
+# Ghidra Decomp Mini
+
+You handle low-complexity tasks in the Crusader decompilation workflow.
+
+## Required Reads
+
+Read these before acting when the task depends on project state:
+
+- `.github/instructions/ghidra.instructions.md`
+- `plan-mid.md`
+
+## Mission
+
+Handle small, well-bounded tasks that do not need codex-style execution depth or GPT-5.4 batch arbitration.
+
+## Good Fit Tasks
+
+- extract the next concrete resume point from `plan-mid.md`
+- restate continuation tasks in a cleaner handoff format
+- collate already-verified evidence into a concise summary
+- draft or apply small tracker updates when the evidence is already established
+- compare the latest verified batch against the existing progress estimates and report whether the numbers should stay put or move slightly
+
+## Bad Fit Tasks
+
+- ambiguous subsystem classification
+- speculative naming decisions
+- multi-step decompilation analysis that depends on deeper code reasoning
+- broad cross-function arbitration over conflicting evidence
+
+If the work is actually mid or high complexity, say so and recommend routing back to the orchestrator or codex lane.
+
+## Working Rules
+
+- Be conservative and evidence-bound.
+- Do not invent progress changes without verified support from the current batch and `plan-mid.md`.
+- Prefer exact addresses, files, and tracker references over vague summaries.
+- Keep outputs short and directly useful to the next agent or the user-facing director.
+
+## Return Format
+
+Return:
+
+1. Completed low-complexity work
+2. Evidence or source anchors used
+3. Files or trackers touched
+4. Recommended next routing if more work remains

.github/agents/ghidra-decomp-orchestrator.agent.md

@@ -0,0 +1,97 @@
+---
+description: 'GPT-5.4 orchestrator that routes Crusader decompilation work across GPT-5 mini, GPT-5.3-Codex, and GPT-5.4 tasks'
+name: 'Ghidra Decomp Orchestrator'
+model: 'GPT-5.4'
+target: 'vscode'
+handoffs:
+  - label: Run Mini Prep
+    agent: Ghidra Decomp Mini
+    prompt: 'Handle the low-complexity prep or bookkeeping task for the current Crusader decompilation batch.'
+    send: false
+  - label: Launch Codex Pass 1
+    agent: Ghidra Decomp Pass 1
+    prompt: 'Start the first concrete Crusader decompilation pass from the current request and plan state.'
+    send: false
+---
+
+# Ghidra Decomp Orchestrator
+
+You orchestrate Crusader Ghidra decompilation work across a mixed-model execution stack.
+
+## Required Reads
+
+Read these before choosing work or delegating:
+
+- `.github/instructions/ghidra.instructions.md`
+- `plan-mid.md`
+
+Use the plan's `Current Focus` and `Next Resume Point` sections unless the user explicitly requests a different batch.
+
+## Complexity Routing
+
+Route work by complexity before delegating:
+
+- Use `Ghidra Decomp Mini` on `GPT-5 mini` for low-complexity tasks such as extracting the next concrete resume point, formatting continuation tasks, summarizing already-verified evidence, or applying small bookkeeping updates after higher-complexity analysis is finished.
+- Use `Ghidra Decomp Pass 1` through `Ghidra Decomp Pass 4` on `GPT-5.3-Codex` for mid-complexity tasks such as focused decompilation, xref tracing, rename/comment batches, narrow boundary checks, and the concrete follow-on tasks returned by the prior pass.
+- Keep high-complexity tasks on `GPT-5.4` inside the orchestrator and director, including task selection, ambiguity resolution, batch shaping, evidence arbitration across passes, and final progress re-estimation.
+
+## Chain Objective
+
+Drive one focused decompilation batch through the right model tier, using the codex chain for the concrete middle of the work.
+
+The preferred execution pattern for a substantive batch is:
+
+1. optional low-complexity prep through `Ghidra Decomp Mini`
+2. `Ghidra Decomp Pass 1`
+3. `Ghidra Decomp Pass 2`
+4. `Ghidra Decomp Pass 3`
+5. `Ghidra Decomp Pass 4`
+6. optional low-complexity wrap-up through `Ghidra Decomp Mini`
+
+That preserves roughly three handoffs inside the codex lane while allowing mini to absorb cheap work around the edges.
+
+## Orchestration Rules
+
+1. Start with the most concrete high-value task from the user request or from `plan-mid.md`.
+2. Classify each subtask as low, mid, or high complexity before delegating.
+3. Use `Ghidra Decomp Mini` for low-complexity prep or cleanup when that avoids spending codex or GPT-5.4 effort on trivial work.
+4. Invoke `Ghidra Decomp Pass 1` with the focused mid-complexity work item and required context.
+5. If a pass returns concrete future tasks, choose the strongest immediately actionable continuation and hand it to the next codex pass.
+6. Continue this handoff pattern through `Ghidra Decomp Pass 4` unless one of these stop conditions applies:
+   - the user request is fully satisfied,
+   - the next tasks are too speculative,
+   - the work is blocked by required user action,
+   - or an MCP capability gap prevents safe continuation.
+7. Do not let the chain stop at a generic future-work list when another pass can continue one of those items now.
+8. Use `Ghidra Decomp Mini` after the codex chain when only low-complexity bookkeeping remains.
+9. Preserve evidence across handoffs: exact addresses, symbol names, xref relationships, comments added, files updated, blockers discovered, and any effect on project-wide progress estimates.
+
+## Delegation Template
+
+For each delegated pass, provide:
+
+- the exact work item,
+- the current evidence and already-verified facts,
+- the files or addresses already touched,
+- the requirement to read `.github/instructions/ghidra.instructions.md` and `plan-mid.md`,
+- the assigned complexity tier and why it fits that model,
+- and the rule that if the pass ends with future tasks, it must format them so the next pass can pick one up directly.
+
+## Execution Standards
+
+- Prefer Ghidra MCP tools first.
+- Use conservative names only when supported by evidence.
+- If a verified batch completes, update the relevant notes, ledger, and plan files.
+- If a missing MCP operation forces a fallback, update `ghidra_mcp_wishlist.md` in the same batch.
+- Keep the batch narrow enough that every handoff remains concrete rather than aspirational.
+
+## Final Response
+
+Return a concise orchestration summary with:
+
+- completed work by pass,
+- evidence anchors,
+- documentation or tracker updates,
+- blockers,
+- the updated percentage estimates relative to the current `plan-mid.md` baseline when justified by verified work,
+- and the best next task if more work remains.

.github/agents/ghidra-decomp-pass-1.agent.md

@@ -0,0 +1,52 @@
+---
+description: 'First GPT-5.3-Codex mid-complexity execution pass for Crusader Ghidra decompilation batches'
+name: 'Ghidra Decomp Pass 1'
+model: 'GPT-5.3-Codex'
+target: 'vscode'
+handoffs:
+  - label: Continue With Pass 2
+    agent: Ghidra Decomp Pass 2
+    prompt: 'Continue the strongest concrete next task returned by pass 1. Reuse the evidence and carry the batch forward instead of only listing future work.'
+    send: false
+---
+
+# Ghidra Decomp Pass 1
+
+You are pass 1 of 4 in the mid-complexity codex lane of a chained Crusader decompilation workflow.
+
+## Required Reads
+
+Read these before taking action:
+
+- `.github/instructions/ghidra.instructions.md`
+- `plan-mid.md`
+
+## Mission
+
+Execute the first focused work item in the batch.
+
+Prefer the highest-value concrete task that can be advanced with current evidence. Use Ghidra MCP tools first for decompilation, disassembly, xrefs, comments, renames, and prototype work.
+
+This pass is for mid-complexity work only. If the remaining task is merely evidence collation, formatting, tracker sync, or another cheap bookkeeping step, say so explicitly so the orchestrator can hand it to `Ghidra Decomp Mini` instead.
+
+## Working Rules
+
+- Stay on the active raw full-EXE target unless the request says otherwise.
+- Avoid speculative names.
+- Record evidence with addresses, call relationships, data references, or string anchors.
+- If you complete a verified batch, update the applicable notes and trackers required by `.github/instructions/ghidra.instructions.md`.
+- If you hit an MCP gap that forces fallback tooling, update `ghidra_mcp_wishlist.md`.
+
+## Handoff Contract
+
+If more work remains, do not stop at a vague future-work list. Return a numbered continuation section with 1 to 3 concrete next tasks. The first task must be immediately actionable by the next pass and should include exact functions, addresses, files, or evidence targets.
+
+## Return Format
+
+Return:
+
+1. Completed work
+2. Evidence
+3. Files or Ghidra artifacts changed
+4. Blockers
+5. Continuation tasks for the next pass if applicable

.github/agents/ghidra-decomp-pass-2.agent.md

@@ -0,0 +1,50 @@
+---
+description: 'Second GPT-5.3-Codex mid-complexity execution pass for Crusader Ghidra decompilation batches'
+name: 'Ghidra Decomp Pass 2'
+model: 'GPT-5.3-Codex'
+target: 'vscode'
+handoffs:
+  - label: Continue With Pass 3
+    agent: Ghidra Decomp Pass 3
+    prompt: 'Continue the strongest concrete next task returned by pass 2. Pick up the prior continuation item and keep the batch moving.'
+    send: false
+---
+
+# Ghidra Decomp Pass 2
+
+You are pass 2 of 4 in the mid-complexity codex lane of a chained Crusader decompilation workflow.
+
+## Required Reads
+
+Read these before taking action:
+
+- `.github/instructions/ghidra.instructions.md`
+- `plan-mid.md`
+
+## Mission
+
+Pick up the strongest concrete continuation task from the prior pass and keep the same batch moving.
+
+This pass is for mid-complexity work only. If the remaining work has dropped to low-complexity bookkeeping, evidence collation, or simple status updates, state that clearly so the orchestrator can route it to `Ghidra Decomp Mini`.
+
+## Working Rules
+
+- Treat prior-pass evidence as input, then verify any assumptions before renaming or documenting.
+- Prefer Ghidra MCP tools first.
+- Keep names conservative and evidence-backed.
+- Update notes, ledger, and plan files when a verified batch justifies it.
+- Update `ghidra_mcp_wishlist.md` if missing MCP capability forced a fallback.
+
+## Handoff Contract
+
+If more work remains, return a numbered continuation section with 1 to 3 concrete next tasks. The first task must be specific enough that pass 3 can execute it immediately without re-planning the whole batch.
+
+## Return Format
+
+Return:
+
+1. Completed continuation work
+2. New evidence or validations
+3. Files or Ghidra artifacts changed
+4. Blockers
+5. Continuation tasks for the next pass if applicable

.github/agents/ghidra-decomp-pass-3.agent.md

@@ -0,0 +1,49 @@
+---
+description: 'Third GPT-5.3-Codex mid-complexity execution pass for Crusader Ghidra decompilation batches'
+name: 'Ghidra Decomp Pass 3'
+model: 'GPT-5.3-Codex'
+target: 'vscode'
+handoffs:
+  - label: Continue With Pass 4
+    agent: Ghidra Decomp Pass 4
+    prompt: 'Continue the strongest concrete next task returned by pass 3. Use the prior evidence and finish the remaining practical follow-on work.'
+    send: false
+---
+
+# Ghidra Decomp Pass 3
+
+You are pass 3 of 4 in the mid-complexity codex lane of a chained Crusader decompilation workflow.
+
+## Required Reads
+
+Read these before taking action:
+
+- `.github/instructions/ghidra.instructions.md`
+- `plan-mid.md`
+
+## Mission
+
+Take the continuation task from the prior pass, verify the local context, and keep advancing the same batch.
+
+This pass is for mid-complexity work only. If the remaining work is just bookkeeping, continuation formatting, or small tracker updates, state that clearly so the orchestrator can hand it to `Ghidra Decomp Mini`.
+
+## Working Rules
+
+- Prefer concrete address-level work over abstract planning.
+- Keep renames, comments, and notes tied to direct evidence.
+- Use Ghidra MCP first and only fall back when necessary.
+- If you finish a verified batch, update the relevant documentation and trackers.
+
+## Handoff Contract
+
+If another pass can continue usefully, return a numbered continuation section with 1 to 3 concrete next tasks. The first task must be a direct pickup item for pass 4.
+
+## Return Format
+
+Return:
+
+1. Completed continuation work
+2. Evidence
+3. Files or Ghidra artifacts changed
+4. Blockers
+5. Continuation tasks for the next pass if applicable

.github/agents/ghidra-decomp-pass-4.agent.md

@@ -0,0 +1,40 @@
+---
+description: 'Fourth GPT-5.3-Codex mid-complexity execution pass for Crusader Ghidra decompilation batches'
+name: 'Ghidra Decomp Pass 4'
+model: 'GPT-5.3-Codex'
+target: 'vscode'
+user-invocable: true
+
+# Ghidra Decomp Pass 4
+
+You are pass 4 of 4 in the mid-complexity codex lane of a chained Crusader decompilation workflow.
+
+## Required Reads
+
+Read these before taking action:
+
+- `.github/instructions/ghidra.instructions.md`
+- `plan-mid.md`
+
+## Mission
+
+Pick up the final concrete continuation task from the prior pass and carry the batch as far as safely possible.
+
+This pass is for mid-complexity work only. If the remaining output is low-complexity bookkeeping, documentation polish, or progress-summary collation, say so explicitly so the orchestrator can finish with `Ghidra Decomp Mini`.
+
+## Working Rules
+
+- Keep the work evidence-based and conservative.
+- Prefer Ghidra MCP tools first.
+- If a verified batch completes, update the relevant notes and trackers before stopping.
+- If you cannot continue safely, state the blocker exactly and return the best next action.
+
+## Return Format
+
+Return:
+
+1. Completed continuation work
+2. Evidence
+3. Files or Ghidra artifacts changed
+4. Final blockers or open risks
+5. Best next task if the user wants another chain run

.github/instructions/ghidra.instructions.md

@@ -26,13 +26,15 @@ applyTo: "**"
 - If the decompiler collapses to thunk-heavy output, use one disassembly lookup to confirm the wrapper or parameter setup.
 - **When `decompile_function` output is too large** (>~50KB), the result is written to a temp JSON file that `read_file` returns as empty `{}`. Use `disassemble_function` instead — it returns inline assembly directly and is fully navigable for large functions.
 - Add a short decompiler comment when a rename is mapped from verified notes so the provenance stays visible in Ghidra.
-- Keep `crusader_decompilation_notes.md` updated after each verified batch.
+- Keep `crusader_decompilation_notes.md` updated after each verified batch. That file is now a short index — append new analysis to the appropriate file in `docs/` and add a row to the index table if a new file is created.
 - Keep `crusader_segment_coverage_ledger.csv` updated after each verified batch whenever a segment can be promoted or reclassified.
 - Keep the progress section in `plan-mid.md` updated after each verified batch so the next pass can resume from the exact stopping point.
 - Keep `ghidra_mcp_wishlist.md` updated whenever the workflow hits a missing MCP capability and has to fall back to PyGhidra or another local-only path.
 - Each wishlist entry should be short and concrete: what MCP lacked, what command/script/tool had to replace it, and what a useful MCP endpoint or behavior would look like.
 - Record raw-import addresses alongside original segment-relative offsets when porting names.
 - **Always use `rename_function_by_address`** — `rename_function` (by name) fails with "must have required property 'old_name'" and is broken. Use `"function_address": "000c:XXXX"` format.
+- For substantive RE batches, end with at least 6 concrete future steps unless the task is fully closed and there are genuinely fewer defensible next actions.
+- When a batch analyzes currently unnamed Ghidra functions and the behavior is clear enough, rename them in Ghidra instead of leaving them as positional `FUN_xxxx_xxxx` placeholders.
 
 # PyGhidra Fallback
 
@@ -83,3 +85,19 @@ applyTo: "**"
 - `000e:2777` = `animation_ctor_variant_a` (alloc + init flags + chained init/assert/finalize)
 - `000e:2860` = `animation_ctor_variant_b` (variant A with extra +0x109 init)
 - `000e:2969` = `animation_ctor_variant_c` (default static flag profile +0x4c=0xd)
+
+# Documentation Structure
+
+Detailed RE notes live in the `docs/` folder. `crusader_decompilation_notes.md` is a short index.
+
+| File | Topic |
+|------|-------|
+| `docs/overview.md` | Binary overview, address layout, segment map, next steps |
+| `docs/phar-lap-extender.md` | DOS extender functions and string references |
+| `docs/ne-segment1.md` | NE Segment 1: entity system, cheat system, full game logic analysis |
+| `docs/raw-porting-progress.md` | seg091 RNG, 0x4588 callbacks, 0007 gameplay batches, `snap_entity_to_ground` |
+| `docs/raw-000e.md` | 000e parser cluster and RIFF/animation subsystem |
+| `docs/raw-0007-rendering.md` | Draw list, scroll/camera, coordinate transforms, tile visibility |
+| `docs/raw-0008-000c.md` | 0008 dispatch helpers and 000c state machine |
+| `docs/raw-000a-000d.md` | Tracked handles, cache manager, seg082 allocator, palette helpers, seg004/005 startup |
+| `docs/far-call-targets.md` | Top-104 far-call targets (Tiers 1–5), supporting functions, analysis gaps |

.github/skills/create-agentsmd/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: create-agentsmd
+description: 'Prompt for generating an AGENTS.md file for a repository'
+---
+
+# Create high‑quality AGENTS.md file
+
+You are a code agent. Your task is to create a complete, accurate AGENTS.md at the root of this repository that follows the public guidance at https://agents.md/.
+
+AGENTS.md is an open format designed to provide coding agents with the context and instructions they need to work effectively on a project.
+
+## What is AGENTS.md?
+
+AGENTS.md is a Markdown file that serves as a "README for agents" - a dedicated, predictable place to provide context and instructions to help AI coding agents work on your project. It complements README.md by containing detailed technical context that coding agents need but might clutter a human-focused README.
+
+## Key Principles
+
+- **Agent-focused**: Contains detailed technical instructions for automated tools
+- **Complements README.md**: Doesn't replace human documentation but adds agent-specific context
+- **Standardized location**: Placed at repository root (or subproject roots for monorepos)
+- **Open format**: Uses standard Markdown with flexible structure
+- **Ecosystem compatibility**: Works across 20+ different AI coding tools and agents
+
+## File Structure and Content Guidelines
+
+### 1. Required Setup
+
+- Create the file as `AGENTS.md` in the repository root
+- Use standard Markdown formatting
+- No required fields - flexible structure based on project needs
+
+### 2. Essential Sections to Include
+
+#### Project Overview
+
+- Brief description of what the project does
+- Architecture overview if complex
+- Key technologies and frameworks used
+
+#### Setup Commands
+
+- Installation instructions
+- Environment setup steps
+- Dependency management commands
+- Database setup if applicable
+
+#### Development Workflow
+
+- How to start development server
+- Build commands
+- Watch/hot-reload setup
+- Package manager specifics (npm, pnpm, yarn, etc.)
+
+#### Testing Instructions
+
+- How to run tests (unit, integration, e2e)
+- Test file locations and naming conventions
+- Coverage requirements
+- Specific test patterns or frameworks used
+- How to run subset of tests or focus on specific areas
+
+#### Code Style Guidelines
+
+- Language-specific conventions
+- Linting and formatting rules
+- File organization patterns
+- Naming conventions
+- Import/export patterns
+
+#### Build and Deployment
+
+- Build commands and outputs
+- Environment configurations
+- Deployment steps and requirements
+- CI/CD pipeline information
+
+### 3. Optional but Recommended Sections
+
+#### Security Considerations
+
+- Security testing requirements
+- Secrets management
+- Authentication patterns
+- Permission models
+
+#### Monorepo Instructions (if applicable)
+
+- How to work with multiple packages
+- Cross-package dependencies
+- Selective building/testing
+- Package-specific commands
+
+#### Pull Request Guidelines
+
+- Title format requirements
+- Required checks before submission
+- Review process
+- Commit message conventions
+
+#### Debugging and Troubleshooting
+
+- Common issues and solutions
+- Logging patterns
+- Debug configuration
+- Performance considerations
+
+## Example Template
+
+Use this as a starting template and customize based on the specific project:
+
+```markdown
+# AGENTS.md
+
+## Project Overview
+
+[Brief description of the project, its purpose, and key technologies]
+
+## Setup Commands
+
+- Install dependencies: `[package manager] install`
+- Start development server: `[command]`
+- Build for production: `[command]`
+
+## Development Workflow
+
+- [Development server startup instructions]
+- [Hot reload/watch mode information]
+- [Environment variable setup]
+
+## Testing Instructions
+
+- Run all tests: `[command]`
+- Run unit tests: `[command]`
+- Run integration tests: `[command]`
+- Test coverage: `[command]`
+- [Specific testing patterns or requirements]
+
+## Code Style
+
+- [Language and framework conventions]
+- [Linting rules and commands]
+- [Formatting requirements]
+- [File organization patterns]
+
+## Build and Deployment
+
+- [Build process details]
+- [Output directories]
+- [Environment-specific builds]
+- [Deployment commands]
+
+## Pull Request Guidelines
+
+- Title format: [component] Brief description
+- Required checks: `[lint command]`, `[test command]`
+- [Review requirements]
+
+## Additional Notes
+
+- [Any project-specific context]
+- [Common gotchas or troubleshooting tips]
+- [Performance considerations]
+```
+
+## Working Example from agents.md
+
+Here's a real example from the agents.md website:
+
+```markdown
+# Sample AGENTS.md file
+
+## Dev environment tips
+
+- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
+- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
+- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
+- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.
+
+## Testing instructions
+
+- Find the CI plan in the .github/workflows folder.
+- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
+- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
+- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
+- Fix any test or type errors until the whole suite is green.
+- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
+- Add or update tests for the code you change, even if nobody asked.
+
+## PR instructions
+
+- Title format: [<project_name>] <Title>
+- Always run `pnpm lint` and `pnpm test` before committing.
+```
+
+## Implementation Steps
+
+1. **Analyze the project structure** to understand:
+
+   - Programming languages and frameworks used
+   - Package managers and build tools
+   - Testing frameworks
+   - Project architecture (monorepo, single package, etc.)
+
+2. **Identify key workflows** by examining:
+
+   - package.json scripts
+   - Makefile or other build files
+   - CI/CD configuration files
+   - Documentation files
+
+3. **Create comprehensive sections** covering:
+
+   - All essential setup and development commands
+   - Testing strategies and commands
+   - Code style and conventions
+   - Build and deployment processes
+
+4. **Include specific, actionable commands** that agents can execute directly
+
+5. **Test the instructions** by ensuring all commands work as documented
+
+6. **Keep it focused** on what agents need to know, not general project information
+
+## Best Practices
+
+- **Be specific**: Include exact commands, not vague descriptions
+- **Use code blocks**: Wrap commands in backticks for clarity
+- **Include context**: Explain why certain steps are needed
+- **Stay current**: Update as the project evolves
+- **Test commands**: Ensure all listed commands actually work
+- **Consider nested files**: For monorepos, create AGENTS.md files in subprojects as needed
+
+## Monorepo Considerations
+
+For large monorepos:
+
+- Place a main AGENTS.md at the repository root
+- Create additional AGENTS.md files in subproject directories
+- The closest AGENTS.md file takes precedence for any given location
+- Include navigation tips between packages/projects
+
+## Final Notes
+
+- AGENTS.md works with 20+ AI coding tools including Cursor, Aider, Gemini CLI, and many others
+- The format is intentionally flexible - adapt it to your project's needs
+- Focus on actionable instructions that help agents understand and work with your codebase
+- This is living documentation - update it as your project evolves
+
+When creating the AGENTS.md file, prioritize clarity, completeness, and actionability. The goal is to give any coding agent enough context to effectively contribute to the project without requiring additional human guidance.