docs: refresh test + root READMEs (20-tool surface, retired mocks, e2e shelving)

[Knapp-Kevin]

What

Documentation accuracy refresh for three READMEs, reconciled against current main (post-split, post-#556).

• tests/README.md — corrects a live drift on main: it claimed "all 4 tools" / "prints the 5 registered tool names", but the server registers 20 (EXPECTED_TOOL_NAMES: 18 bicameral.* ledger/session tools + the 2 code-locator primitives validate_symbols/get_neighbors). Now points at EXPECTED_TOOL_NAMES as the drift-proof source of truth. Also drops the retired-mock framing + dead test_phase0_mocks.py, fixes the install to pip install -e ".[test]", and adds sociable-testing + "what CI runs" sections.
• README.md — adds two truthful CI badges (lint+types, secret-scan — both workflows exist on main) and a gold-standard "at a glance" overview table. No existing prose rewritten.
• tests/e2e/README.md — reflects the ci: shelve v0 e2e workflow — dispatch-only, remove PR trigger #556 shelving (workflow is dispatch-only, no longer a PR gate; it previously called itself "the canonical CI test"), points to the replacement RFQ RFQ: replacement e2e validation strategy for v0 user flows #555, and corrects "six" → five automated flows (1–5).

Why

Docs-as-contract: the tests/README tool count was ~4× off and referenced a retired subsystem; the e2e README advertised PR triggers that #556 removed. No code or governance artifacts touched.

Refs

• Reflects the e2e workflow shelving in ci: shelve v0 e2e workflow — dispatch-only, remove PR trigger #556 and its replacement RFQ RFQ: replacement e2e validation strategy for v0 user flows #555.
• Overview table notes broader security/governance CI gates tracked in CI: add security/governance gates (CodeQL, Scorecard, Bandit, SBOM, dependency-review) for badge parity + SOC 2 #557.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added GitHub Actions status badges to the main README showing lint, type-checking, and secret scanning results
  • Redesigned testing documentation with a new phase-gated regression test strategy using environment variable toggles
  • Enhanced test environment configuration guidance and setup documentation
  • Noted that v0 user flow e2e tests are now manual-only and removed from automatic PR validation

[coderabbitai]

Warning

Review limit reached

@jinhongkuan, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 59 minutes and 56 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, 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 include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e3ad47f3-6d66-4203-9306-c5738cbd87d1

📥 Commits

Reviewing files that changed from the base of the PR and between afa875f and aaeb675.

📒 Files selected for processing (1)

• tests/README.md

📝 Walkthrough

Walkthrough

Documentation updates across three README files establish project maturity/footprint visibility, restructure MCP regression test guidance around phase-gated real-adapter testing with environment toggles, and document the shelved e2e user-flow suite's transition to manual dispatch.

Changes

Testing & Project Documentation

Layer / File(s)	Summary
Project Overview: Badges and Maturity Table README.md	Added GitHub Actions status badges for lint/type checking and secret scanning; introduced a new "Maturity / Footprint / Trust boundary / Assurance" overview table at the top of the README.
Test Regression Strategy: Phase-Gating and Real Adapters tests/README.md	Rewrote test documentation to describe a new phase-gated model toggled via environment variables (SURREAL_URL=memory://, USE_REAL_CODE_LOCATOR, USE_REAL_LEDGER), replacing mock-based testing with real adapters and in-process SurrealDB. Added quickstart section with smoke-test and full-suite commands, detailed Phase gates table, updated Environment variables and Packaging smoke sections, documented sociable testing defaults, and clarified CI regression scope.
E2E Suite Status: Shelved to Manual Dispatch tests/e2e/README.md	Documented the v0 user flow e2e suite as shelved from PR automation; limited automated flows to five (1–5) and added explicit manual dispatch instructions via GitHub Actions. Repositioned scripts/sim_issue_108_flows.py as the preferred local fast-iteration path. Updated "CI" section to reflect dispatch-only operation (no PR trigger) and referenced RFQ #555 as the replacement validation strategy.

🎯 2 (Simple) | ⏱️ ~8 minutes

🐰 The docs now dance in phases bright,
Real adapters test with all their might,
E2E rests, awaiting the call,
Project status shines for one and all! 🎭

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately and specifically summarizes the main changes: documentation refresh of test and root READMEs with focus on the 20-tool surface, retired mocks, and e2e shelving.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/readme-upcycle-2026-06-08

---

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

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

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@tests/README.md`:
- Line 45: Update the README table entry for SURREAL_URL to match the test
fixture default: change the default value from
`surrealkv://~/.bicameral/ledger.db` to `memory://` so it aligns with the
`SURREAL_URL` default used in the test fixture (see conftest's SURREAL_URL
default); ensure the description still notes that `memory://` is for in-process
tests with no persistence.

🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: bb9cdb25-2094-463d-bd7f-ac3bad0ead1b

📥 Commits

Reviewing files that changed from the base of the PR and between b214e4e and afa875f.

📒 Files selected for processing (3)

• README.md
• tests/README.md
• tests/e2e/README.md