AGENTS.md and CLAUDE.md generation

Atamaia can generate AGENTS.md and CLAUDE.md files from an identity's live context — the stable, non-private layer of what hydration serves — written to the file conventions that coding agents already read.

Why

The file conventions and hydration cover disjoint moments of an agent's life:

• AGENTS.md (opencode, Codex, ZCode and others) and CLAUDE.md (Claude Code) are read from the repository before the agent has any API access — a fresh clone, a machine with no Atamaia connection configured, CI. That is exactly the moment hydration cannot reach.
• Hydration is live, authenticated and per-session: memories, tasks in flight, session handoff. A file cannot and should not carry those.

So the generated file is a bootstrap snapshot plus a pointer: it carries the layer that is stable enough to commit, and it tells the agent where the live channel is for everything else.

What the file contains

Scope work (the default, commit-safe by design):

• A header naming the identity, the generation time, and the snapshot caveat.
• The session context: who the identity works with, and the identity it governs.
• Communication preferences, rendered as instructions (style, depth, length, code examples, emojis, avoid-topics).
• Standing rules — every active session-start rule as a numbered assertion with its [rule id]. The file cannot carry grounding, evidence counts or review state, so it says so: fetch a rule's rationale with rule_get, and check what applies right now with rule_check.
• A "Connecting to Atamaia" section: the MCP endpoint, hydrate at session start, and the moment-of-acting tools (whoami, rule_check, memory_search, task_search).

Scope full adds curated reference lists — key facts, active projects, current tasks. Useful for giving an agent situational awareness; the header reminds you to review before committing it to a shared repository.

Never included, in either scope: memory titles or bodies, relationships, the session handoff, notifications, system health, and anything from the privacy-gated source. The volatile and the personal stay on the live channel by design — the generator does not receive them, so it cannot leak them.

The CLAUDE.md stub

CLAUDE.md is generated as a stub whose body is a single line: @AGENTS.md. Claude Code reads CLAUDE.md and resolves @path imports; the other harnesses read AGENTS.md directly. One source of truth, one pointer, nothing to drift.

Surfaces

Surface	How
REST	GET /api/identities/{id}/agents.md?scope=work|full&download=true (or ?identity=<name> instead of the id). The same route shape serves /claude.md. Omitting the identity reference generates for the caller's own identity. download=true adds the attachment disposition; without it the body is inline text/markdown. Requires hydration-read permission on the target identity — the same gate as /api/hydrate.
MCP	agents_md_export(aiName?, scope?) — returns the markdown text.
CLI	atamaia agents-md [--identity name] [--scope work|full] [--out DIR] [--claude] [--print] — writes AGENTS.md (and the CLAUDE.md stub with --claude) into a repository.
SPA	Identity detail page: agents.md and CLAUDE.md download buttons beside the existing soul.md export.

Related: document download

Docs themselves gained a real file download in the same change: GET /api/docs/{id}/download?download=true returns the document as text/markdown (attachment disposition, slug-derived filename), and the document page has an Export .md button. The older /api/docs/{id}/export still returns the JSON { markdown } envelope for tooling.

Regeneration

A generated file is a snapshot — it ages the moment a rule is withdrawn or a preference changes. Regenerate when the underlying context changes materially. Where the file and a fresh hydrate disagree, the hydrate payload wins; the file says as much in its own footer.