v0.4.0: docs sync, health_check tool, A2A protocol, and CLI scan/split#113
Merged
Conversation
Bring the documentation in line with the current codebase and record the work that shipped since 0.3.0. Docs sync (was TODO.md Phases 1-4, now complete): - Supabase -> Neon / DATABASE_URL across the remaining stale instructional references (architecture, concepts, CLI, ENV, llms.txt/llms-full.txt, AGENTS.md, CLAUDE.md, CONTRIBUTING.md); legitimate cross-provider and historical mentions left intact - Google AI embeddings corrected to gemini-embedding-2-preview (3072d) - EXTRACTION_MODEL default corrected to claude-haiku-4-5-20251001 - Add health_check tool reference and bump tool count 25 -> 26 - Add scan/split CLI pages and document spotify/reddit/facebook/instagram converters - Add Agent-to-Agent (A2A) protocol reference page Changelog & tracking: - Add CHANGELOG [0.4.0] covering the shipped large-upload pipeline (GCS resumable, Cloud Tasks, Cloud Run, zip handler registry, dashboard UX), provider retries, and the docs sync; bump package.json to 0.4.0 - Trim TODO.md to the remaining Memory System Roadmap (Phases 5-14) - Archive completed plans and the improvement tracker to docs/archive/; update inbound references Verified: tool-sync-check, docs-check, markdownlint, and docs:build all pass.
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
WalkthroughThis PR is a comprehensive documentation release for version 0.4.0 that updates 30+ documentation files and configuration references to reflect infrastructure and feature changes. The package version is bumped to 0.4.0 with detailed CHANGELOG entries. The primary infrastructure change migrates database backing from Supabase PostgreSQL to Neon PostgreSQL with pgvector. Default embedding models are updated from text-embedding-004 (768 dimensions) to gemini-embedding-2-preview (3072 dimensions). New documentation is added for the health_check MCP tool (bringing tool count to 26), new CLI commands (scan and split for markdown file analysis and splitting), and the A2A protocol for agent-to-agent task delegation. Documentation references to planning artifacts are consolidated from docs/plans/ to docs/archive/. sequenceDiagram
participant ExternalAgent
participant TextrawlAgent
participant SearchPipeline
participant Postgres
ExternalAgent->>TextrawlAgent: GET /.well-known/agent.json
TextrawlAgent-->>ExternalAgent: agent card
ExternalAgent->>TextrawlAgent: POST /.well-known/agent/tasks (bearer)
TextrawlAgent->>SearchPipeline: route task text
SearchPipeline->>Postgres: query documents/chunks
Postgres-->>SearchPipeline: results
SearchPipeline-->>TextrawlAgent: task response
TextrawlAgent-->>ExternalAgent: delegated task result
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/guides/large-upload-e2e-preflight.md (1)
139-140:⚠️ Potential issue | 🔴 Critical | ⚡ Quick winInconsistent archive path reference within the same file.
The "Sources of truth" section (line 28) correctly updates the reference to
2026-06-06-phase4-cloud-run-activation.mdto use thedocs/archive/path, but the inline markdown link in the "Cloud Run env activation" section (line 140) still references the old../plans/path for the same file. This creates a broken link.
docs/guides/large-upload-e2e-preflight.md#L28-L29: Archive path correctly uses../archive/2026-06-06-phase4-cloud-run-activation.md— no change needed.docs/guides/large-upload-e2e-preflight.md#L139-L140: Update inline link from../plans/2026-06-06-phase4-cloud-run-activation.mdto../archive/2026-06-06-phase4-cloud-run-activation.mdto match the "Sources of truth" reference.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/guides/large-upload-e2e-preflight.md` around lines 139 - 140, Update the inline markdown link in the "Cloud Run env activation" section of docs/guides/large-upload-e2e-preflight.md by replacing the old ../plans/2026-06-06-phase4-cloud-run-activation.md path with the correct ../archive/2026-06-06-phase4-cloud-run-activation.md so it matches the "Sources of truth" reference; locate the link text in the Cloud Run env activation paragraph (the existing ../plans/... string) and update it to ../archive/... to fix the broken link.
🧹 Nitpick comments (2)
docs/architecture/index.mdx (1)
19-43: ⚡ Quick winSpecify language for text diagram block.
Code block at lines 19–43 should have a language specified for consistency and syntax highlighting. Use
```textor```asciito mark it as a text diagram.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/architecture/index.mdx` around lines 19 - 43, The ASCII diagram's fenced code block is missing a language specifier; update the opening fence that contains the MCP/Express/Tool/DB diagram to include a language (e.g., replace ``` with ```text or ```ascii) so the block is marked as a text diagram for consistent rendering and highlighting.Source: Coding guidelines
docs/architecture/a2a-protocol.mdx (1)
10-12: 💤 Low valueConsider using
httplanguage for HTTP method code blocks.The blocks showing
GET /.well-known/agent.jsonandPOST /.well-known/agent/tasksusetextas the language specifier. While technically compliant with the markup guideline, usinghttpwould enable better syntax highlighting for these HTTP methods.Optional: improve code block language specs
-```text +```http GET /.well-known/agent.json -``` +``` -```text +```http POST /.well-known/agent/tasks -``` +```Also applies to: 44-46
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/architecture/a2a-protocol.mdx` around lines 10 - 12, Update the fenced code blocks that contain the HTTP examples "GET /.well-known/agent.json" and "POST /.well-known/agent/tasks" (and the other occurrence at lines 44-46) to use the http language specifier instead of text; locate the three code fences that start with ```text and change them to ```http so the HTTP methods receive proper syntax highlighting while leaving the block contents unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/cli/split.mdx`:
- Around line 25-40: The docs table for the split command lists `--output <dir>`
default as `./converted` but the CLI treats `./converted` as a sentinel in
scripts/cli/split.ts (checking `options.output === './converted'` and passing
undefined to the splitter so output falls back to dirname(filePath)); update the
docs or code: either change the docs entry for `--output` to show the effective
default of "alongside source (defaults to source directory)" or modify the CLI
logic in scripts/cli/split.ts to stop treating `'./converted'` as a sentinel and
always pass `options.output` to the splitter; reference `options.output`,
`scripts/cli/split.ts`, and `createBaseCommand` when making the change so
behavior and docs stay consistent.
---
Outside diff comments:
In `@docs/guides/large-upload-e2e-preflight.md`:
- Around line 139-140: Update the inline markdown link in the "Cloud Run env
activation" section of docs/guides/large-upload-e2e-preflight.md by replacing
the old ../plans/2026-06-06-phase4-cloud-run-activation.md path with the correct
../archive/2026-06-06-phase4-cloud-run-activation.md so it matches the "Sources
of truth" reference; locate the link text in the Cloud Run env activation
paragraph (the existing ../plans/... string) and update it to ../archive/... to
fix the broken link.
---
Nitpick comments:
In `@docs/architecture/a2a-protocol.mdx`:
- Around line 10-12: Update the fenced code blocks that contain the HTTP
examples "GET /.well-known/agent.json" and "POST /.well-known/agent/tasks" (and
the other occurrence at lines 44-46) to use the http language specifier instead
of text; locate the three code fences that start with ```text and change them to
```http so the HTTP methods receive proper syntax highlighting while leaving the
block contents unchanged.
In `@docs/architecture/index.mdx`:
- Around line 19-43: The ASCII diagram's fenced code block is missing a language
specifier; update the opening fence that contains the MCP/Express/Tool/DB
diagram to include a language (e.g., replace ``` with ```text or ```ascii) so
the block is marked as a text diagram for consistent rendering and highlighting.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 9f768f03-c4ec-40a4-ab93-f6bee5dc48cb
📒 Files selected for processing (36)
AGENTS.mdCHANGELOG.mdCLAUDE.mdCONTRIBUTING.mdTODO.mddocs/ENV.mddocs/architecture/a2a-protocol.mdxdocs/architecture/embeddings.mdxdocs/architecture/index.mdxdocs/architecture/meta.jsondocs/archive/2026-05-31-large-upload-gcs-resumable-plan.mddocs/archive/2026-06-01-phase4-cloud-tasks-impl.mddocs/archive/2026-06-06-phase4-cloud-run-activation.mddocs/archive/2026-06-10-phase5-handler-registry-zip-impl.mddocs/archive/2026-06-10-phase6-dashboard-upload-ux-impl.mddocs/archive/IMPROVEMENT_TRACKER.mddocs/cli/batch-upload.mdxdocs/cli/index.mdxdocs/cli/meta.jsondocs/cli/scan.mdxdocs/cli/split.mdxdocs/concepts/index.mdxdocs/getting-started/configuration.mdxdocs/getting-started/introduction.mdxdocs/guides/email-import.mdxdocs/guides/large-upload-e2e-preflight.mddocs/mcp-tools/health-check.mdxdocs/mcp-tools/index.mdxdocs/mcp-tools/meta.jsondocs/mcp-tools/pg-analyze.mdxdocs/mcp-tools/pg-recommendations.mdxinfra/cloud-tasks/README.mdinfra/gcs/README.mdllms-full.txtllms.txtpackage.json
scripts/cli/split.ts treats --output './converted' as a sentinel and passes undefined to the splitter, so the effective output is the source file's directory. Update the split.mdx options table so the Default column reflects that rather than the misleading './converted'. Addresses CodeRabbit review on PR #113.
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
2 participants
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
Complete documentation sync for v0.4.0 release, including new MCP
health_checktool, A2A protocol discovery endpoint, and CLIscan/splitcommands. Updates all references from Supabase to Neon PostgreSQL, corrects Google AI embedding model togemini-embedding-2-preview(3072d), and archives completed implementation plans.Changes
Documentation sync (Phase 1–4 complete)
DATABASE_URLacross installation, configuration, RUNBOOK, guides, and error tablestext-embedding-004(768d) togemini-embedding-2-preview(3072d) in architecture and configuration docsEXTRACTION_MODELtoclaude-haiku-4-5-20251001New documentation pages
docs/mcp-tools/health-check.mdx— Per-component diagnostic tool (database, documents, chunks, memory, conversations, insights)docs/architecture/a2a-protocol.mdx— Agent-to-Agent discovery protocol via/.well-known/agent.jsonand task delegation endpointdocs/cli/scan.mdx— Analyze converted markdown for upload readiness and flag oversized filesdocs/cli/split.mdx— Break large markdown files into uploadable parts at heading boundariesCLI documentation updates
scanandsplitcommand entries to CLI indexMetadata and navigation
docs/mcp-tools/meta.jsonto includehealth-checkunder new "Stats & Diagnostics" sectiondocs/cli/meta.jsonto includescanandsplitpagesdocs/architecture/meta.jsonto includea2a-protocolpageArchived implementation plans
docs/archive/TODO.mdto focus on remaining Memory System RoadmapVersion bump
package.jsonversion to0.4.0CHANGELOG.mdwith v0.4.0 release notesMiscellaneous updates
llms.txtandllms-full.txtto reference Neon instead of SupabaseCONTRIBUTING.mdto reference Neon setupAGENTS.mdandCLAUDE.mdto remove Supabase referencesdocs/ENV.mdwith corrected Google AI model namedocs/concepts/index.mdxwith correct embedding dimensionsType of Change
Checklist
Related Issues
Closes documentation sync backlog (Phases 1–4 complete per CHANGELOG v0.4.0)
https://claude.ai/code/session_01Cq9wB4tnXXsmw524qDp7MF