use anyhow::Result;
use serde_json::json;
use crate::cli::PrimeArgs;
pub fn execute(args: &PrimeArgs) -> Result<()> {
let documentation = generate(args.prelude);
if args.json {
println!(
"{}",
serde_json::to_string_pretty(&json!({"documentation": documentation}))?
);
} else {
println!("{documentation}");
}
Ok(())
}
pub fn generate(prelude_only: bool) -> String {
let prelude = r#"# agent-id — Portable agent identity registry
Use `agent-id` to register and look up the permanent human-readable identity for a coding-agent session.
The identity is keyed by the harness session ID. Do not invent a name or register a second name for the same session.
Session discovery, in order:
1. An explicit `SESSION_ID` argument or `--session-id ID`.
2. `AGENT_ID_SESSION_ID`.
The realm is discovered from `--realm NAME`, `AGENT_REALM` (for tests/overrides), or `$XDG_CONFIG_HOME/agent-id/realm` with `$HOME/.config/agent-id/realm` as the fallback. If no realm configuration exists, one is automatically selected and saved to the realm file.
The registry is durable and defaults to `$XDG_DATA_HOME/agent-id`, or `$HOME/.local/share/agent-id` when `XDG_DATA_HOME` is unset. Set `AGENT_ID_HOME` for tests or an isolated registry.
When you need to understand the identity system or discover other agents, run `agent-id prime`. The extension provides this guidance once per session branch, including tree navigation, without repeating it on every prompt.
A missing session ID is an error. A missing lookup is an error; register the session first.
## Examples
```bash
agent-id register "$AGENT_ID_SESSION_ID"
agent-id register --family Oak "$AGENT_ID_SESSION_ID"
agent-id lookup "$AGENT_ID_SESSION_ID"
agent-id annotate --summary "Implementing checkout retries" "$AGENT_ID_SESSION_ID"
agent-id annotate --clear-summary "$AGENT_ID_SESSION_ID"
agent-id annotate --state working "$AGENT_ID_SESSION_ID"
agent-id annotate --state blocked "$AGENT_ID_SESSION_ID"
agent-id annotate --clear-state "$AGENT_ID_SESSION_ID"
agent-id annotate --cwd "$PWD" "$AGENT_ID_SESSION_ID"
agent-id annotate --clear-cwd "$AGENT_ID_SESSION_ID"
agent-id register --json --family Oak "$AGENT_ID_SESSION_ID"
```
The default output is the full name. Use `--json` when a tool needs the session ID, name parts, realm, slug, optional timestamped summary, typed activity state, working directory, and created/updated timestamps."#;
if prelude_only {
return prelude.to_string();
}
format!(
"{prelude}\n\n## Commands\n\n### `agent-id register [SESSION_ID]` — Allocate a permanent identity\n\n```\n--family NAME Prefer a family name, useful for child agents\n--realm NAME Select the computer realm\n--session-id ID Provide the session ID explicitly\n--json Print the complete assignment as JSON\n```\n\nRegistration is idempotent: an existing session keeps its identity and receives a new `updated_at`.\n\n### `agent-id lookup [IDENTIFIER]` — Read an existing identity\n\nIDENTIFIER may be a session ID, canonical name, or slug. Without an explicit identifier, lookup uses the session environment.\n\n```\n--session-id ID Provide the session ID explicitly\n--json Print the complete assignment as JSON\n```\n\nFails if the identifier has not been registered.\n\n### `agent-id annotate [SESSION_ID]` — Update activity metadata\n\n```\n--summary TEXT Set a concise summary (maximum 240 characters)\n--clear-summary Remove the summary\n--state VALUE Set working, idle, waiting, blocked, or stopped\n--clear-state Remove the activity state\n--cwd PATH Set the current working directory\n--clear-cwd Remove the current working directory\n--session-id ID Provide the session ID explicitly\n--json Print the complete assignment as JSON\n```\n\nSummary, state, and working-directory updates are independent; omitted fields remain unchanged. State timestamps are generated by agent-id and are available in JSON as `state.updated_at`. Working-directory metadata is an optional host-provided path and is not inferred from prompt text.\n\n### `agent-id discover` — List recent identities\n\n```\n--limit N Maximum records (default 20; zero means all)\n--recent HOURS Only records updated within this many hours\n--realm NAME Only records in this realm\n--json Print the complete assignments as JSON\n```\n\nResults are sorted by `updated_at`, newest first. Human-readable results include summaries, states, and working directories when present; timestamps remain available in JSON.\n\n### `agent-id prune` — Remove old identity assignments\n\n```\n--before TIMESTAMP Delete records updated before this RFC 3339 timestamp\n--dry-run Preview matches without deleting\n--json Print the prune report as JSON\n```\n\nPruning applies by default and removes both session records and matching name claims.\n\n### `agent-id prime` — Print this workflow manual\n\n```\n--prelude Omit the command reference\n--json Wrap the manual in a JSON object\n```"
)
}