docs: update README and CLAUDE.md for current state (March 26)

[EtanHey]

Summary

Repo maintenance — update docs to reflect 7 PRs merged today (#102-107).

README.md

• Numbers: 281K chunks (was 224K), 1,204 tests (was 1,083), 11 MCP tools (was 9)
• New sections: Lifecycle tools (brain_supersede/archive), real-time watcher, Axiom telemetry
• Architecture diagram: added watcher, Axiom, dedup coordination flows
• Enrichment: updated from MLX/Ollama to Groq/Gemini (current reality)
• Comparison table: added chunk lifecycle and watcher rows
• CLI reference: added brainlayer watch
• Config: added AXIOM_TOKEN and BRAINLAYER_ENRICH_RATE

CLAUDE.md

• Fixed stale MLX enrichment reference → Groq primary
• Added Real-time JSONL Watcher, Chunk Lifecycle, Session Dedup sections
• Updated tool count, Data & Locks paths

Cleanup

• .gitignore: added .claude/, .mcp.json.bak, progress trackers
• enrichment_controller.py: rate configurable via env var
• Closed stale PR feat: enrichment backfill script + compact instructions #97 (enrichment backfill, conflicted with current CLAUDE.md)

Remaining uncommitted files (not in this PR)

• scripts/backfill_orchestrate.sh — working backfill orchestration script
• scripts/batch_submit_paced.py — batch submission utility
• tests/eval_mcp_brainlayer.json — eval fixture

🤖 Generated with Claude Code

Note

Update README and CLAUDE.md to reflect current architecture and features

• Updates docs to reflect the current state: Groq as primary enrichment backend with Gemini/Ollama fallback, 11 MCP tools (up from 9), and 1,204 Python + 54 Swift tests.
• Adds documentation for the real-time JSONL watcher (brainlayer watch), Axiom telemetry, chunk lifecycle fields, and session dedup coordination via /tmp/brainlayer_session_*.json.
• Documents new AXIOM_TOKEN and BRAINLAYER_ENRICH_RATE env vars; the latter now controls the default rate in enrich_realtime, falling back to 0.2 if unset.
• Updates .gitignore to exclude .mcp.json.bak, .claude/, and scripts/.kg_rebuild_progress.json.

📊 Macroscope summarized 7bd42a1. 2 files reviewed, 1 issue evaluated, 0 issues filtered, 1 comment posted

🗂️ Filtered Issues

[coderabbitai]

Warning

Rate limit exceeded

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

⌛ 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: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4c4aa681-0093-4a28-8981-a9fa2d394e6b

📥 Commits

Reviewing files that changed from the base of the PR and between b6bb0b1 and 7bd42a1.

📒 Files selected for processing (4)

• .gitignore
• CLAUDE.md
• README.md
• src/brainlayer/enrichment_controller.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/repo-maintenance-march26

---

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.}

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[macroscopeapp]

🟢 Low brainlayer/enrichment_controller.py:117

The default argument float(os.environ.get("BRAINLAYER_ENRICH_RATE", "0.2")) is evaluated at module import time, so an invalid environment variable (e.g., "fast" or empty string) causes ValueError and crashes the module import before any code can handle it. Consider moving the parsing into the function body to defer validation until runtime.

     rate_per_second: float = float(
-        os.environ.get("BRAINLAYER_ENRICH_RATE", "0.2")
-    ),  # Default 12 RPM. Tier 1 allows 2000 RPM (~33/s)
+    ),  # Default 12 RPM. Tier 1 allows 2000 RPM (~33/s)
     max_retries: int = 12,

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file src/brainlayer/enrichment_controller.py around lines 117-119:

The default argument `float(os.environ.get("BRAINLAYER_ENRICH_RATE", "0.2"))` is evaluated at module import time, so an invalid environment variable (e.g., `"fast"` or empty string) causes `ValueError` and crashes the module import before any code can handle it. Consider moving the parsing into the function body to defer validation until runtime.

Evidence trail:
src/brainlayer/enrichment_controller.py lines 115-122 (REVIEWED_COMMIT) - shows `rate_per_second: float = float(os.environ.get("BRAINLAYER_ENRICH_RATE", "0.2"))` as a function parameter default value. Python documentation confirms default argument values are evaluated once at function definition time (import time for top-level functions): https://docs.python.org/3/reference/compound_stmts.html#function-definitions