Why agent context ships with the scaffold

If you use coding agents, the repository is part of the user interface. A 200-file monorepo dumped into a context window is not documentation—it is noise with good intentions.

Arche generates a small map so agents know where to look next.

The problem with “just read the codebase”

Agents are good at local edits and bad at global orientation when every session starts cold. Teams responded with:

• Giant README.md files nobody maintains
• Duplicate .cursor/rules and .claude/rules trees that contradict each other
• Copy-pasted “production ready” claims with no verification path

Arche’s answer is boring on purpose: one canonical AGENTS.md, scoped .docs/ topics, and .plans/active/ for approved work.

What gets generated

AGENTS.md              # Start here — other agent files point here
CLAUDE.md -> AGENTS.md # When the preset enables it
.docs/                 # Architecture, deploy, features (internal)
.plans/active/         # One in-flight plan at a time
arche.json             # Reproducibility metadata (command + choices)

We explicitly do not generate duplicate rule forests. If your team wants Cursor rules, add them as a conscious choice—not as hidden template bloat.

How agents should work

1. Read root AGENTS.md
2. Read the nearest workspace AGENTS.md when touching a package
3. Load one matching .plans/active/ file for approved work
4. Pull a single .docs/ topic when the task needs depth

That workflow is documented on Agent context with a visual map.

Humans still matter

Agent context does not replace:

• Code review
• Your deployment env matrix
• Deciding whether a preset is appropriate

It reduces repeated orientation cost at the start of a session. The Philosophy page explains what Arche refuses to claim—agents should inherit that honesty.

Repair path

Renamed packages or changed deploy conventions? Regenerate context:

bun run dev:cli -- add agent-docs ./my-app

Same CLI, no mystery side channel.