DecapodLabs/decapod

Presently, .decapod/README.md scaffold template uses verbiage and instructions not intended for human use. That readme is for the human only, so it doesn't need decapod commands. That file only exists in the project after they ran the one decapod command (decapod init) -- from there, they should just use the .decapod/config.toml and .decapod/OVERRIDE.md while pointing the user to the official user docs (mdbook) and also a brief explanation of the .decapod folder hierarchy.

Context Surfaced in PR #1162: agents guess decapod specs.refresh as a top-level subcommand (from AGENTS.md shorthand). It is not a CLI subcommand. Actual surfaces Intent Correct invocation RPC decapod rpc --op specs.refresh CLI flag during validate decapod validate --refresh-specs There is no top-level decapod specs.refresh command. Requested work Document both surfaces in docs/agent/command-contracts.md. Soften or expand any AGENTS.md / entrypoint shorthand that reads like a CLI subcommand. Optionally add an unknown-command recovery hint when agents type specs.refresh. Related PR #1162 #1122 (spec.refresh needs to bump specs contents — behavioral fix; this issue is docs/discoverability) #1079 (manifest path location) Non-goals Implementing a top-level specs.refresh alias (unless product decides otherwise) Changing refresh semantics (owned by #1122)

Context Surfaced in PR #1162: the first decapod govern trajectory record call failed with schema mismatches until the agent followed error-message enum hints. Those enums are not documented in docs/agent/command-contracts.md. Observed accepted enums (from CLI error recovery during #1162) trigger ∈ {human, webhook, cron, agent, grader, engine} grader_result ∈ {pass, fail, skipped} status ∈ {open, retrying, passed, failed, blocked} mutation_proposal ∈ {none, prompt, tool, config, rubric, policy} --check "name=status" where status ∈ {passed, failed, partial, unavailable} Initial incorrect guesses included trigger: "user_scope_confirmed", grader_result: "passed", status: "pass". Requested work Add the enum tables (or a linked schema snippet) to docs/agent/command-contracts.md under govern trajectory record. Optionally add a minimal payload example to docs/agent/payload-examples.md. Prefer documenting the same values the binary validates, not a second source of truth — if val

Context Surfaced in PR #1162 oddities while updating agent-facing indexes for contribution-conventions.md. Problem Three agent doc indexes list different subsets and use different structures: File Scope today docs/agent/README.md Agent corpus only; no mcp.md (PR #1162 added contribution-conventions) docs/agent/api-index.md Documentation Index Agent corpus including mcp.md + contribution-conventions docs/agent/llms.txt Agent corpus and full human book (docs/book/src/*) under a single "Decapod Agent Docs" framing (book is split under a second header after #1162-ish state, but historically mixed) Agents that only read one index miss docs listed in another. mcp.md is the clearest pre-existing gap in README. Requested work Pick one canonical source of truth for the agent corpus list (prefer api-index.md Documentation Index or generate from a shared list). Make README.md and the agent section of llms.txt derive from or match that list. Keep human-book entries under a clearly s

All 4 governance .json files have more fields than absolutely necessary. Claims doesn't need timestamps, etc. Cut all governance .json files (and schemas) down to bare essential to reduce overhead and drift.