Conversation
Create comprehensive documentation organized into four sections: - Root: README, SETUP, CONFIG, CHECKLIST, GUARDRAILS, INVENTORY - mcp/: TOOLS, ENV, TRANSPORT, DEPLOY, CONNECT, DEV, PATTERNS - repo/: REPO, RECIPES, SCRIPTS, RULES, MEMORY - stack/: ARCH, TECH, PRE-REQS All content is derived from the actual codebase (CLAUDE.md, Cargo.toml, axon.json, .env.example, Justfile, docker/, crates/). No template placeholders remain. Existing docs/ content is preserved and cross-linked.
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 28 minutes and 51 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (33)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ccaee6d779
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | Endpoint | Method | Description | | ||
| |----------|--------|-------------| | ||
| | `/mcp` | POST | MCP JSON-RPC with streamable-http | | ||
| | `/health` | GET | Health check | |
There was a problem hiding this comment.
This table documents GET /health as an MCP HTTP endpoint, but run_http_server only registers "/mcp" in crates/mcp/server.rs, so health probes against port 8001 will return 404. Any user or automation following this doc for liveness checks will incorrectly treat a healthy MCP server as down.
Useful? React with 👍 / 👎.
|
|
||
| ## Lifecycle action families | ||
|
|
||
| These actions require a `subaction`. All support: `start`, `status`, `cancel`, `list`, `cleanup`, `clear`, `recover`. |
There was a problem hiding this comment.
The doc says all lifecycle families support start/status/cancel/list/cleanup/clear/recover, but graph does not: GraphSubaction only allows build/status/explore/stats in crates/mcp/schema.rs. Clients implementing from this sentence will send unsupported subactions like graph:start and hit invalid_params errors.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
This PR introduces a new structured documentation set under docs/ (root + mcp/, repo/, stack/) and updates docs/README.md to act as the new central index while keeping links to the existing “legacy” docs.
Changes:
- Added new structured docs for stack architecture/tech/prereqs, MCP transport/tools/patterns/dev, and repo rules/recipes/scripts/memory.
- Added root reference docs (
SETUP.md,CONFIG.md,GUARDRAILS.md,CHECKLIST.md,INVENTORY.md). - Rewrote
docs/README.mdinto a high-level product + doc navigation entry point.
Reviewed changes
Copilot reviewed 30 out of 30 changed files in this pull request and generated 13 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/README.md | Replaces the old index with a structured navigation page that links new + existing docs. |
| docs/SETUP.md | Adds a step-by-step setup guide for local + Docker workflows. |
| docs/CONFIG.md | Adds an environment variable + axon.json configuration reference. |
| docs/CHECKLIST.md | Adds a release-quality checklist (build, infra, security, docs). |
| docs/GUARDRAILS.md | Adds security guardrails and operational safety notes. |
| docs/INVENTORY.md | Adds a component inventory across MCP/CLI/infra/workers/crates. |
| docs/mcp/CLAUDE.md | Index page for MCP documentation. |
| docs/mcp/TOOLS.md | Documents the single MCP tool and action/subaction API surface. |
| docs/mcp/ENV.md | Documents MCP-specific environment variables and lite-mode behavior. |
| docs/mcp/TRANSPORT.md | Documents stdio/HTTP/both transport configuration. |
| docs/mcp/DEPLOY.md | Documents local/Docker/lite deployment patterns for MCP. |
| docs/mcp/CONNECT.md | Documents client connection setup (Claude Code/Codex/Gemini). |
| docs/mcp/DEV.md | Documents MCP development workflow and testing. |
| docs/mcp/PATTERNS.md | Documents MCP code patterns (dispatch/artifacts/errors/capabilities). |
| docs/repo/CLAUDE.md | Index page for repo documentation. |
| docs/repo/REPO.md | Documents repository structure and key directories/files. |
| docs/repo/RECIPES.md | Documents Justfile recipes. |
| docs/repo/SCRIPTS.md | Documents scripts in scripts/ by category. |
| docs/repo/RULES.md | Documents coding rules, policies, and enforced conventions. |
| docs/repo/MEMORY.md | Documents “bd/beads” persistence workflow and session protocol. |
| docs/stack/CLAUDE.md | Index page for stack documentation. |
| docs/stack/ARCH.md | Documents architecture overview (modes, workers, flows, ports). |
| docs/stack/TECH.md | Documents technology choices and key dependency stack. |
| docs/stack/PRE-REQS.md | Documents prerequisite tools/versions and infra service ports. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | Component | Technology | Version | Purpose | | ||
| |-----------|-----------|---------|---------| | ||
| | Core binary | Rust | 1.94+ (edition 2024) | CLI, MCP server, workers, backend bridge | | ||
| | Web UI | TypeScript + Next.js | Node 22+ | Dashboard, Pulse workspace | |
There was a problem hiding this comment.
The documented Web UI runtime requirement (Node 22+) is out of sync with the repository’s actual requirement. apps/web/package.json sets engines.node to >=24, so this should be updated here (and anywhere else Node is mentioned) to avoid dev setup failures.
| | Web UI | TypeScript + Next.js | Node 22+ | Dashboard, Pulse workspace | | |
| | Web UI | TypeScript + Next.js | Node 24+ | Dashboard, Pulse workspace | |
| | Redis | 8.2-alpine | Queue state, cancel flags, caching | | ||
| | RabbitMQ | 4.0-management | AMQP job queue with 6 queues | | ||
| | Qdrant | v1.13.1 | Vector database (dense + sparse search) | | ||
| | TEI | HuggingFace latest | Text embedding generation | |
There was a problem hiding this comment.
The TEI image/version listed as “HuggingFace latest” doesn’t match docker-compose.services.yaml (ghcr.io/huggingface/text-embeddings-inference:89-latest). Consider documenting the pinned tag (or explicitly stating where it’s pinned) so operators know what will actually run.
| | TEI | HuggingFace latest | Text embedding generation | | |
| | TEI | `ghcr.io/huggingface/text-embeddings-inference:89-latest` (pinned in `docker-compose.services.yaml`) | Text embedding generation | |
| | just | latest | `cargo install just` | Task runner | | ||
| | Node.js | 22+ | [nodejs.org](https://nodejs.org/) | Web UI runtime | | ||
| | pnpm | 9+ | `corepack enable` | Web UI package manager | | ||
| | jq | 1.6+ | System package manager | JSON parsing in scripts | |
There was a problem hiding this comment.
Node/pnpm versions here don’t match the repo’s enforced engines. apps/web/package.json requires Node >=24 and pnpm >=10, but this table (and the verify snippet below) says Node 22+ and pnpm 9+. Please align these to prevent developers from setting up an incompatible toolchain.
| ```bash | ||
| rustc --version # rustc 1.94.x | ||
| cargo --version # cargo 1.94.x | ||
| docker --version # Docker 24+ | ||
| docker compose version # Docker Compose v2+ | ||
| just --version # just x.y.z | ||
| node --version # v22.x.x | ||
| pnpm --version # 9.x.x | ||
| jq --version # jq-1.6+ | ||
| python3 --version # Python 3.10+ |
There was a problem hiding this comment.
The version-check examples still reference Node 22 / pnpm 9, but apps/web/package.json requires Node >=24 and pnpm >=10. Please update these expected outputs so the “Verify” section reflects the actual supported versions.
| | Node.js | 22+ | Web UI (Next.js) | | ||
| | pnpm | 9+ | Web UI package manager | |
There was a problem hiding this comment.
This prerequisites table lists Node.js 22+ and pnpm 9+, but the web app enforces newer versions (apps/web/package.json has engines.node: >=24 and engines.pnpm: >=10). Please update these to match the enforced engines to avoid setup confusion.
| | Node.js | 22+ | Web UI (Next.js) | | |
| | pnpm | 9+ | Web UI package manager | | |
| | Node.js | 24+ | Web UI (Next.js) | | |
| | pnpm | 10+ | Web UI package manager | |
| Error responses: | ||
|
|
||
| ```json | ||
| { | ||
| "ok": false, | ||
| "error": "description of the failure" | ||
| } | ||
| ``` |
There was a problem hiding this comment.
The documented error response shape ({ "ok": false, "error": ... }) does not match how the MCP server actually reports failures. In the implementation, failures are returned as MCP JSON-RPC errors (invalid_params, internal_error, etc.) via rmcp::ErrorData, not as an AxonToolResponse JSON envelope. Please update this section to reflect the real wire behavior.
| ### Response modes | ||
|
|
||
| | Mode | Behavior | | ||
| |------|----------| | ||
| | `path` (default) | Write result to `.cache/axon-mcp/` artifact file, return metadata (path, bytes, sha256, preview) | | ||
| | `inline` | Return full result inline (capped/truncated) | | ||
| | `both` | Write artifact and return inline content | | ||
| | `auto_inline` | Inline if payload is below `AXON_INLINE_BYTES_THRESHOLD` (default 8192), otherwise artifact | | ||
|
|
There was a problem hiding this comment.
The artifact metadata described here (path/bytes/sha256/preview, etc.) is out of sync with the current MCP artifact response shape. The implementation returns a data object containing response_mode plus fields like artifact (with path, relative_path, bytes, line_count, sha256) and sometimes shape / inline / truncated; it does not include a preview field as described. Please align this section with crates/mcp/server/artifacts/respond.rs so consumers can parse responses correctly.
| ### Schema parsing | ||
|
|
||
| Input is parsed strictly with serde in `crates/mcp/schema.rs`: | ||
|
|
||
| ```rust | ||
| #[derive(Deserialize)] | ||
| pub struct McpInput { | ||
| pub action: Action, | ||
| pub subaction: Option<Subaction>, | ||
| pub url: Option<String>, | ||
| pub urls: Option<Vec<String>>, | ||
| pub query: Option<String>, | ||
| pub response_mode: Option<ResponseMode>, | ||
| // ... per-action fields | ||
| } | ||
| ``` |
There was a problem hiding this comment.
The schema parsing example is stale: the MCP request type is a tagged enum (AxonRequest with #[serde(tag = "action", rename_all = "snake_case")]) rather than a single McpInput struct as shown. Updating this to match crates/mcp/schema.rs will prevent contributors from following an incorrect model when adding fields/actions.
| ## Artifact response pattern | ||
|
|
||
| Heavy operations write results to artifact files instead of returning inline: | ||
|
|
||
| ``` | ||
| 1. Handler executes operation | ||
| 2. Result serialized to JSON | ||
| 3. Written to $AXON_MCP_ARTIFACT_DIR/<hash>.json | ||
| 4. MCP response returns compact metadata: | ||
| - path: artifact file path | ||
| - bytes: file size | ||
| - line_count: lines in artifact | ||
| - sha256: content hash | ||
| - preview: first N lines | ||
| - preview_truncated: boolean | ||
| ``` |
There was a problem hiding this comment.
The “Artifact response pattern” section lists response fields like preview, preview_truncated, and implies artifacts are always written when using default behavior. The current implementation can return response_mode: "auto-inline" (no artifact write) when response_mode is omitted and the payload is below AXON_INLINE_BYTES_THRESHOLD, and the artifact metadata fields differ (see crates/mcp/server/artifacts/respond.rs). Please update this section to match actual behavior/field names.
| ## Verifying connection | ||
|
|
||
| ```bash | ||
| # HTTP health check | ||
| curl -s http://localhost:8001/health | ||
|
|
||
| # Test via doctor | ||
| axon doctor | ||
|
|
There was a problem hiding this comment.
This verification snippet uses curl -s http://localhost:8001/health, but the MCP HTTP server only mounts /mcp (no /health route). Please update the example to use a working verification step (e.g., a tools/list or tools/call request against /mcp, or axon doctor).
Summary
docs/organized into four sections: root (README, SETUP, CONFIG, CHECKLIST, GUARDRAILS, INVENTORY), mcp/ (TOOLS, ENV, TRANSPORT, DEPLOY, CONNECT, DEV, PATTERNS), repo/ (REPO, RECIPES, SCRIPTS, RULES, MEMORY), and stack/ (ARCH, TECH, PRE-REQS)Test plan
Summary by cubic
Adds a structured documentation system under
docs/with four sections: root,mcp/,repo/, andstack/, built from real project files. Also bumps version to0.35.1and updatesCHANGELOG.md.docs/into root,mcp/(TOOLS, ENV, TRANSPORT, DEPLOY, CONNECT, DEV, PATTERNS),repo/(REPO, RECIPES, SCRIPTS, RULES, MEMORY), andstack/(ARCH, TECH, PRE-REQS).Cargo.toml,axon.json,.env.example,Justfile,docker/, andcrates/.docs/README.mdwith links between old and new pages.0.35.1inCargo.tomland.codex-plugin/plugin.json; addedCHANGELOG.mdentry.Written for commit ab5e47c. Summary will update on new commits.