# AGENTS.md

## Repository Role

This repository is an analysis workspace for Claude Code framework internals.
The durable outputs are source-backed Markdown notes and the public-facing
HTML explainer.

Primary artifacts:

- `reference/`: source snapshots and reference materials. Do not edit unless explicitly requested.
- `knowledge-base/`: durable Markdown research notes.
- `knowledge-base/index.md`: active topic index.
- `advanced-site/Claude-Code-Analysis.html`: default public-facing HTML target.
- `reports/`: deeper rendered reports and supporting screenshots.

## Research Control Point

For every repository research session:

1. Read source files before making claims.
2. Preserve durable findings in `knowledge-base/`.
3. Add new focused topic files at `knowledge-base/<topic>.md`.
4. Update `knowledge-base/index.md` whenever a new topic file is added.
5. Update or explicitly evaluate `advanced-site/Claude-Code-Analysis.html` when a finding improves the external explanation.
6. If no knowledge-base or HTML update is warranted, state why in the final response.

## Evidence Standard

- Cite source paths and line numbers for implementation claims.
- Mark uncertain conclusions as draft, hypothesis, or needs follow-up.
- Keep source snapshots under `reference/` unchanged unless the user asks to refresh them.

## Existing Guides

Read these repository guides when doing substantial research:

- `knowledge-base/readme.md`
- `knowledge-base/agents.md`
- `knowledge-base/claude.md`