docs(plans): (a) FTS5 + Mermaid output — plan PR (skeleton)

[SutuSebastian]

Summary

Opens the (a) FTS5 + Mermaid output plan PR per the shipping cadence in PR #58 (docs/research/non-goals-reassessment-2026-05.md § 5). Track-1 first ship after the research note merge.

Two non-goal flips in one plan because both are small (~50–150 LoC each) and demonstrate complementary moat alignment:

• § 2.1 FTS5 = moat B substrate growth (richer extracted structure)
• § 2.2 Mermaid = moat A output mode (verdicts as output, never primitives)

What's in the skeleton

• 6 pre-locked decisions (L.1–L.6) carried from the research note:
  • FTS5 default OFF (backwards-compat per § 6 Q2)
  • Toggle: BOTH config + --with-fts CLI flag
  • Mermaid output-mode-only (moat A clean)
  • Mermaid bounded-input contract (per § 1.7 — reject with scope-suggestion if > 50 edges)
  • Bundle one demo recipe (text-in-deprecated-functions) showing FTS5 ⨯ symbols ⨯ coverage JOIN
  • Cold-start sub-100ms preserved (FTS5 is index-time cost only)
• 7 open decisions (Q1–Q7) — source_fts schema, indexer integration, --full rebuild semantics on toggle change, Mermaid edge-count threshold, formatter input shape, CLI/config precedence, DB-size telemetry.
• High-level architecture split FTS5 + Mermaid + crosscut (bundled recipe, schema-bump migration, agent rule lockstep).
• 7 implementation slices (tracer-bullets) — substrate first, then recipe, then formatter, then bound check, then MCP/HTTP plumbing, then docs/agent rule lockstep, then changeset.
• Test approach with fixtures/golden/fts5-fixture/ reproducing the FTS5 JOIN composability.
• 6-row risks/non-goals including the abandonment escape hatch.

Doc-governance compliance

• Lives in docs/plans/fts5-mermaid.md per Rule 3.
• docs/README.md File Ownership row updated per Rule 4. Note: PR #59 also updates this row for c9-plugin-layer.md; the second-merged PR will need a small rebase to combine both entries.
• Cross-references with section-deep anchors per Rule 5.

Test plan

• bun run format:check passes
• All cross-refs to docs/research/non-goals-reassessment-2026-05.md resolve to existing section anchors
• CodeRabbit review on the skeleton structure
• Plan iteration via subsequent commits as Q1–Q7 crystallise

Iteration cadence

Each open decision (Q1–Q7) gets resolved via a separate commit on this branch with a "Resolution (YYYY-MM-DD)" subsection added inline (mirrors the research-note § 6 pattern). The plan stays in iterative state until impl-ready; merges with the impl PR per the cadence at T+0 → +1w.

Out of scope (separate PRs)

1. Impl itself — gated on this plan converging.
2. (b) C.9 plugin layer impl — separate cadence (T+2w → +5w).
3. The three follow-ups from PR docs(research): non-goals reassessment + cohort positioning + ship sequence (2026-05) #58: fallow.md cleanup, roadmap.md non-goals lockstep, Tier-2 plan-PR rule.

[changeset-bot]

⚠️ No Changeset found

Latest commit: fe55ac3

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Warning

Rate limit exceeded

@SutuSebastian has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 21 minutes and 35 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

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 configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b03dda9d-a111-4676-9a40-4d99a1fd6f41

📥 Commits

Reviewing files that changed from the base of the PR and between 33adbae and fe55ac3.

📒 Files selected for processing (2)

• docs/README.md
• docs/plans/fts5-mermaid.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch plan/fts5-mermaid

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 21 minutes and 35 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}