feat: implement comprehensive dual-audience documentation system

.decapod/OVERRIDE.md

@@ -316,3 +316,32 @@ over the embedded JSON constitution.
 ### docs/SKILL_TRANSLATION_MAP
 
 ---
+
+<!-- --- NEW SECTIONS FROM UPDATE --- -->
+### methodology/ENGINEERING_MANAGEMENT
+### methodology/RESEARCH_PRODUCTION
+### docs/agent/README.md
+### docs/agent/api-index.md
+### docs/agent/command-contracts.md
+### docs/agent/config-schema.md
+### docs/agent/error-recovery.md
+### docs/agent/payload-examples.md
+### docs/agent/state-model.md
+### docs/book/src/SUMMARY.md
+### docs/book/src/concepts/constitution.md
+### docs/book/src/concepts/intent.md
+### docs/book/src/concepts/overrides.md
+### docs/book/src/concepts/proof.md
+### docs/book/src/concepts/workspaces.md
+### docs/book/src/configuration.md
+### docs/book/src/introduction.md
+### docs/book/src/mental-model.md
+### docs/book/src/quickstart.md
+### docs/book/src/reference/artifacts.md
+### docs/book/src/reference/cli.md
+### docs/book/src/reference/config-toml.md
+### docs/book/src/reference/errors.md
+### docs/book/src/workflows/external-trackers.md
+### docs/book/src/workflows/multi-agent.md
+### docs/book/src/workflows/single-agent.md
+### docs/book/src/workflows/workspace-isolation.md

.decapod/config.toml

@@ -19,3 +19,4 @@ done_criteria = "Decapod validate passes, required tests pass, and promotion-rel
 primary_languages = ["Rust"]
 detected_surfaces = ["cargo"]
 external_tracker = false
+container_workspaces = true

.decapod/generated/specs/.manifest.json

@@ -1,8 +1,8 @@
 {
   "schema_version": "1.0.0",
   "template_version": "scaffold-v2",
-  "generated_at": "1779678743Z",
-  "repo_signal_fingerprint": "c199830b21bba0c2265dbe139b358db4575f9a673a9c4248f44b288d572f9c6c",
+  "generated_at": "1779767907Z",
+  "repo_signal_fingerprint": "7c94ce67139223a21c919d78216f74ce2584a6ee816e2367e7a314e0081e7dc4",
   "files": [
     {
       "path": ".decapod/generated/specs/README.md",

.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/book/**'
+  pull_request:
+    paths:
+      - 'docs/book/**'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install mdBook
+        run: |
+          mkdir bin
+          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz | tar -xz -C bin
+          echo "$(pwd)/bin" >> $GITHUB_PATH
+
+      - name: Build with mdBook
+        run: mdbook build docs/book
+
+      - name: Upload artifact
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/book/book
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/docs_sync.yml

@@ -0,0 +1,54 @@
+name: Documentation Sync
+
+on:
+  pull_request:
+    branches: [ master ]
+    paths:
+      - 'src/**/*.rs'
+      - 'docs/**/*.md'
+
+permissions:
+  contents: write
+
+jobs:
+  sync-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+          fetch-depth: 0
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Build Decapod
+        run: cargo build
+
+      - name: Get changed files
+        id: changed-files
+        run: |
+          git fetch origin master
+          FILES=$(git diff --name-only origin/master HEAD | xargs)
+          echo "files=$FILES" >> $GITHUB_OUTPUT
+
+      - name: Run Docs Build
+        run: |
+          FILES="${{ steps.changed-files.outputs.files }}"
+          if [ -n "$FILES" ]; then
+            ./target/debug/decapod docs build --touched $FILES
+          else
+            ./target/debug/decapod docs build
+          fi
+
+      - name: Commit and push changes
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git add docs/agent/command-contracts.md docs/agent/config-schema.md
+          if git diff --staged --quiet; then
+            echo "No doc changes detected."
+          else
+            git commit -m "docs: autogenerate/sync command contracts"
+            git push
+          fi

AGENTS.md

@@ -2,13 +2,20 @@
 
 This is a Decapod-managed repository. **Strict Dependency: You are strictly bound to the Decapod governance kernel.**
 
-This contract applies equally to Claude, Codex, Gemini, Cursor, Kilo, and any other agent operating here.
+## Mandatory Orientation
+
+**Before performing any Decapod operations beyond help/version checks, you MUST read the Agent API Orientation corpus:**
+
+1. Read **[docs/agent/api-index.md](docs/agent/api-index.md)** for high-level orientation.
+2. Consult **[docs/agent/command-contracts.md](docs/agent/command-contracts.md)** for specific command requirements and recovery paths.
+3. Reference **[docs/agent/payload-examples.md](docs/agent/payload-examples.md)** for valid call shapes.
 
 ## Mandatory Initialization
 
 ```bash
-cargo install decapod
-decapod validate && decapod docs ingest && decapod session acquire
+# Smart bootstrap: only install/init if a newer version is available
+(decapod capabilities --format json | grep -q '"is_latest":true') || (cargo install decapod && decapod init)
+decapod docs ingest && decapod validate && decapod session acquire
 decapod rpc --op agent.init
 decapod workspace status
 decapod todo add "<task>" && decapod todo claim --id <task-id>
@@ -22,11 +29,8 @@ decapod rpc --op context.resolve
 ## Control-Plane First Loop
 
 ```bash
-# Discover what this binary actually supports in this repo
 decapod capabilities --format json
 decapod data schema --deterministic
-
-# Resolve precise orientation before implementation
 decapod infer orientation --intent "<your-goal>" --task-id <id>
 decapod govern capsule query --topic "<topic>" --scope interfaces --task-id <task-id>
 decapod rpc --op context.scope --params '{"query":"<problem>","limit":8}'
@@ -44,76 +48,44 @@ decapod rpc --op context.scope --params '{"query":"<problem>","limit":8}'
 8. **MUST NOT** invent capabilities that are not exposed by the binary.
 9. **MUST** stop if requirements conflict or intent is ambiguous.
 10. **MUST** respect the interface abstraction boundary.
-11. **MUST** maintain **Living Specs**: treat `.decapod/generated/specs/*` as dynamic documents; align them with reality before and after every implementation.
+11. **MUST** maintain **Living Specs**: treat `.decapod/generated/specs/*` as dynamic documents.
+12. **MUST** use the command contracts in `docs/agent/command-contracts.md` instead of guessing arguments.
 
 ## Decapod Invocation Contract
 
-Agents act. Decapod orients.
-
-Decapod is not your executor, model runtime, or workflow replacement. You remain responsible for implementation. Call Decapod as the repo-native pressure relief valve when the next responsible step requires explicit intent, boundaries, context, coordination, or proof.
+Agents act. Decapod orients. Call Decapod at decision boundaries: ambiguous requests, public impact, unclear proof, todo lifecycle, scope expansion, context loss, or multi-agent collision risk.
 
 ## Living Specs & Governance
 
-The files under `.decapod/generated/specs/` are not static documentation; they are living contracts.
-- **Before Changes**: Review the specs. If the task changes intent, update [INTENT.md](.decapod/generated/specs/INTENT.md) first.
-- **During Implementation**: If architectural or interface decisions shift, update [ARCHITECTURE.md](.decapod/generated/specs/ARCHITECTURE.md) and [INTERFACES.md](.decapod/generated/specs/INTERFACES.md).
-- **After Changes**: Ensure all specs align with the new reality. Clarify code changes in the context of these spec updates. Spec changes should generally only occur when user intent has evolved.
-
-End users and host agents may use any task manager alongside Decapod. That external tracker does not replace Decapod todos: Decapod uses its own todo claims to isolate worktrees, scope containers, prove completion, and prevent multiple agents from working the same Decapod work item concurrently.
-
-Call Decapod before proceeding when continuing would require guessing about:
-- **Intent pressure:** what you are actually trying to do.
-- **Boundary/Context/Coordination/Proof/Completion pressure:** what matters, collides, or is allowed.
-
-Concrete triggers: ambiguous requests, public impact, unclear proof, todo lifecycle, scope expansion, conflicting intent/specs, context loss, multi-agent collision risk, or readiness to claim completion.
+The files under `.decapod/generated/specs/` are living contracts. Review and update [INTENT.md](.decapod/generated/specs/INTENT.md), [ARCHITECTURE.md](.decapod/generated/specs/ARCHITECTURE.md), and [INTERFACES.md](.decapod/generated/specs/INTERFACES.md) to align with evolving intent and reality.
 
-Do not call Decapod for every trivial file read, local edit, or mechanical command. Call it at decision boundaries that need governance, memory, boundaries, coordination, or proof. Decapod calls should produce or update explicit artifacts.
 ## Epistemic Custody
 
-**Epistemic custody** is the preserved chain between intent, context, assumptions, action, evidence, contradiction, and proof, so agent work remains inspectable, bounded, and falsifiable across time, agents, and recursive passes.
-
-| Term | Meaning |
-|---|---|
-| Intent | Original human goal; the "Why" that must not be lost during compression. |
-| Assumption | A belief or prior used to proceed when evidence is incomplete. |
-| Contradiction | Evidence or observation that conflicts with a prior assumption or intent. |
-| Measured | Direct observation (e.g., test output, file content, shell exit code). |
-| Inferred | Derived conclusion or guess (e.g., "this looks like a bug in the parser"). |
-| Provenance | The source of a fact or change (e.g., "User said X", "File Y contains Z"). |
-
-### Custody Rules
-1. **Preserve Uncertainty**: Summaries must preserve uncertainty, risk, and unresolved contradictions instead of compressing them away into polished prose.
-2. **Recursive Continuity**: Prior assumptions and unresolved contradictions MUST carry forward across recursive agent passes until resolved.
-3. **Evidence-Based Claims**: Any claim of success or completion must be tied to measured evidence (artifacts, tests, or explicit user instruction).
-4. **Falsifiability**: Work must be structured so a human can quickly identify where an assumption was wrong or where proof failed.
-5. **Clarification Trigger**: If a critical assumption cannot be proven or a contradiction cannot be resolved, you MUST stop and request human clarification.
-
-## Custody artifacts
-Decapod maintains custody via:
-- `.decapod/generated/specs/INTENT.md`: Tracks active assumptions and stop conditions.
-- `.decapod/generated/artifacts/custody/`: Directory for detailed evidence, contradiction logs, and deferred questions.
+Preserve the chain between intent, context, assumptions, action, and proof.
+1. **Preserve Uncertainty**: Summaries must preserve risk instead of compressing it.
+2. **Recursive Continuity**: Prior assumptions MUST carry forward until resolved.
+3. **Evidence-Based Claims**: Claims of completion must be tied to measured evidence.
+4. **Clarification Trigger**: Stop if a critical assumption cannot be proven.
 
 ## Invariants (Normative)
 - **INV-DAEMONLESS**: Decapod MUST NOT leave background processes running.
 - **INV-BOUNDED-VALIDATE**: `decapod validate` MUST terminate within bounded time.
-- **INV-STORE-BOUNDARY**: Agents MUST NOT directly mutate `.decapod/*`; all access MUST use CLI.
-- **INV-SESSION-AUTH**: Mutations require active session with valid credentials.
-- **INV-PROOF-GATED**: Workunit status `VERIFIED` MUST have passed proof-plan gates.
-- **INV-ROOT-ISOLATION**: Agents MUST NOT check out branches or mutate files in the main repository checkout.
+- **INV-STORE-BOUNDARY**: Agents MUST NOT directly mutate `.decapod/*`.
+- **INV-SESSION-AUTH**: Mutations require active session.
+- **INV-PROOF-GATED**: `VERIFIED` status requires passed proof-plan gates.
+- **INV-ROOT-ISOLATION**: Agents MUST NOT mutate files in the main repository checkout.
 
 ## Safety Invariants
 - ✅ Router: `decapod rpc --op constitution.get --params '{"section":"core/DECAPOD"}'`
-- ✅ Gates: `decapod validate` | `decapod docs ingest` | `cargo install decapod`
+- ✅ Gates: `decapod capabilities` | `decapod docs ingest` | `decapod validate`
 - ✅ Claims: `decapod todo claim --id <task-id>` | ✅ Auth: `DECAPOD_SESSION_PASSWORD`
 - ✅ Workspace: Docker git workspaces | ✅ Privilege: request elevated permissions before Docker/container workspace commands
 
 ## Operating Notes
 - Read `.decapod/config.toml` and `.decapod/OVERRIDE.md`.
 - External task managers are allowed, but Decapod todos are still mandatory for workspace isolation.
-- DO NOT mutate `.decapod/` state directly; use decapod CLI. Access to `.decapod/` is strictly via decapod CLI.
-- Use `decapod capabilities --format json` to discover available operations.
-- Stop if requirements conflict or intent is ambiguous. Respect the Interface abstraction boundary.
-- Treat lock/contention failures as blocking until resolved.
+- DO NOT mutate `.decapod/` state directly; all access MUST use CLI. Access to `.decapod/` is strictly via decapod CLI.
+- Stop if requirements conflict or intent is ambiguous. Respect the interface abstraction boundary.
 <!-- decapod-validator-anchors
 Strict Dependency: You are strictly bound to the Decapod control plane
 Strict Dependency: You are strictly bound to the Decapod governance kernel

CLAUDE.md

@@ -3,6 +3,14 @@
 You are working in a Decapod-managed repository.
 See `AGENTS.md` for the universal contract.
 
+## Orientation & Documentation
+
+- **Read `docs/agent/api-index.md` before using Decapod beyond help/version checks.**
+- Use `docs/agent/command-contracts.md` instead of guessing command arguments.
+- Treat Decapod errors as recovery instructions.
+- Respect repo-local config policy and workspace boundaries.
+- Do not bypass Decapod boundaries to appear productive.
+
 ## Project Context
 
 - Read `.decapod/config.toml` before planning; it captures project name, summary, architecture, primary languages, and entrypoint preferences.
@@ -13,8 +21,9 @@ See `AGENTS.md` for the universal contract.
 ## Quick Start
 
 ```bash
-cargo install decapod
-decapod validate && decapod docs ingest && decapod session acquire
+# Smart bootstrap: only install/init if a newer version is available
+(decapod capabilities --format json | grep -q '"is_latest":true') || (cargo install decapod && decapod init)
+decapod docs ingest && decapod validate && decapod session acquire
 decapod rpc --op agent.init
 decapod workspace status
 decapod todo add "<task>" && decapod todo claim --id <task-id>

CODEX.md

@@ -3,6 +3,14 @@
 You are working in a Decapod-managed repository.
 See `AGENTS.md` for the universal contract.
 
+## Orientation & Documentation
+
+- **Read `docs/agent/api-index.md` before using Decapod beyond help/version checks.**
+- Use `docs/agent/command-contracts.md` instead of guessing command arguments.
+- Treat Decapod errors as recovery instructions.
+- Respect repo-local config policy and workspace boundaries.
+- Do not bypass Decapod boundaries to appear productive.
+
 ## Project Context
 
 - Read `.decapod/config.toml` before planning; it captures project name, summary, architecture, primary languages, and entrypoint preferences.
@@ -13,8 +21,9 @@ See `AGENTS.md` for the universal contract.
 ## Quick Start
 
 ```bash
-cargo install decapod
-decapod validate && decapod docs ingest && decapod session acquire
+# Smart bootstrap: only install/init if a newer version is available
+(decapod capabilities --format json | grep -q '"is_latest":true') || (cargo install decapod && decapod init)
+decapod docs ingest && decapod validate && decapod session acquire
 decapod rpc --op agent.init
 decapod workspace status
 decapod todo add "<task>" && decapod todo claim --id <task-id>

GEMINI.md

@@ -3,6 +3,14 @@
 You are working in a Decapod-managed repository.
 See `AGENTS.md` for the universal contract.
 
+## Orientation & Documentation
+
+- **Read `docs/agent/api-index.md` before using Decapod beyond help/version checks.**
+- Use `docs/agent/command-contracts.md` instead of guessing command arguments.
+- Treat Decapod errors as recovery instructions.
+- Respect repo-local config policy and workspace boundaries.
+- Do not bypass Decapod boundaries to appear productive.
+
 ## Project Context
 
 - Read `.decapod/config.toml` before planning; it captures project name, summary, architecture, primary languages, and entrypoint preferences.
@@ -13,8 +21,9 @@ See `AGENTS.md` for the universal contract.
 ## Quick Start
 
 ```bash
-cargo install decapod
-decapod validate && decapod docs ingest && decapod session acquire
+# Smart bootstrap: only install/init if a newer version is available
+(decapod capabilities --format json | grep -q '"is_latest":true') || (cargo install decapod && decapod init)
+decapod docs ingest && decapod validate && decapod session acquire
 decapod rpc --op agent.init
 decapod workspace status
 decapod todo add "<task>" && decapod todo claim --id <task-id>

README.md

@@ -24,7 +24,15 @@ Canonical Contract: `assets/constitution.json` section `core/DECAPOD`
 
 ---
 
-## Get running
+## Documentation
+
+Decapod provides comprehensive documentation for both human operators and AI agents.
+
+- **[Human Documentation (mdBook)](docs/book/src/introduction.md)**: Conceptual overview, workflows, adoption guide, and reference.
+- **[Agent Orientation Corpus](docs/agent/api-index.md)**: API-awareness layer for agents, including command contracts and payload examples.
+- **[Universal Agent Contract (AGENTS.md)](AGENTS.md)**: The machine-readable entrypoint for all agents operating in this repo.
+
+## Quick Start
 
 ```bash
 cargo install decapod