feat: implement comprehensive dual-audience documentation system#596
Merged
Conversation
- Establish human-facing mdBook in docs/book covering mental model, workflows, and reference. - Establish agent-facing API orientation corpus in docs/agent for deterministic orientation. - Update agent entrypoint templates (AGENTS.md, etc.) to mandate API index consultation. - Align code with documentation: implement container_workspaces configuration and validation. - Add GitHub Actions workflow for automatic mdBook deployment. - Update root README with documentation pointers.
alexhraber
commented
May 26, 2026
alexhraber
commented
May 26, 2026
Contributor
Author
alexhraber
left a comment
alexhraber
left a comment
There was a problem hiding this comment.
address comments
- Clean up README.md Quick Start section. - Implement tests/doc_alignment.rs to verify that documented commands and config keys match the implementation. - Expose project configuration in 'decapod capabilities --format json' to enable agent discovery and test verification. - Add 'DecapodProjectConfig::load' and 'discover_repo_root' for cleaner configuration management. - Update DecapodError with Config variant for better error reporting.
- Update build script to ingest docs/ directory into the embedded constitution graph. - Update 'decapod docs' command group to separate and display documentation files from constitution sections. - Shorten agent entrypoints and templates to comply with 120-line validation limit. - Fix invariant validation failures by using exact phrasing for mandates. - Relax validation rule for .decapod/ references to allow config.toml mentions in documentation.
- Add 'decapod docs build' command to autogenerate command contracts from CLI structure. - Implement surgical documentation updates via '--touched' flag. - Add GitHub Action '.github/workflows/docs_sync.yml' to automatically sync and commit doc changes back to PRs. - Update PR description with details on agent CLI helper and lookup loop resolution.
- Fix git diff logic in documentation sync workflow to use proper head/base SHAs. - Make 'decapod docs build' touched files optional to handle empty diffs gracefully. - Resolve formatting and clippy issues across the codebase.
- Update 'decapod docs build' to correctly handle multiple values for '--touched'. - Fix 'docs_sync.yml' to fetch origin/master before diffing to avoid 'bad object' errors.
- Add 'refresh' subcommand to 'init' for non-interactive updates of config and overrides. - Implement 'blend_overrides' logic to merge new constitution sections into existing OVERRIDE.md. - Update agent entrypoint sequence to: install -> refresh -> ingest -> validate. - Ensure 'init refresh' is documented in mandatory initialization and safety invariants.
- Update 'decapod init' to automatically refresh environment (blend overrides, sync config) if .decapod exists. - Addcrates.io version check to 'decapod capabilities' with automatic comparison. - Implement smart bootstrap logic in entrypoint templates: only install/init if a newer version is available. - Remove redundant 'init refresh' subcommand. - Update Safety Invariants to include version-aware gate checks.
- Implement automated environment refresh on 'decapod init' when .decapod exists. - Sidestep interactive manual entries for existing Decapod projects. - Preserve legacy entrypoint blending (backups) on initial initialization. - Integrate crates.io version check into 'decapod capabilities'. - Implement version-aware 'smart bootstrap' sequence in agent entrypoints. - Remove unused 'interactive_init_with' function.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR introduces Decapod's first robust documentation system, optimized for both human operators and AI agents.
Key Advancements
decapod docs listanddecapod docs show. This drastically reduces orientation latency and helps solve the lookup loop described in Issue container_workspace_required remediation is blocked by WORKSPACE_NO_CLAIMED_TODO #568.init refresh): Added a new quick-start step that sidesteps manual entries to syncconfig.tomldefaults and blend new constitution sections into existingOVERRIDE.mdfiles non-interactively..decapod/config.tomland surgical constitution overrides via.decapod/OVERRIDE.md.tests/doc_alignment.rs).Technical Highlights
docs/book/covering mental models and workflows.docs/agent/.The docs autoupdate and align with code changes at the PR level, ensuring the control plane's guidance is never out of sync with its capabilities.