docs: weekly review 2026-06-25

[vasylenko]

Summary

Weekly documentation review. Inventoried user-facing docs (README.md, docs/user/NPM.md, FAQ/InstallGuide/FeatureGrid website copy) and maintainer-facing docs (CLAUDE.md, docs/dev/SPECIFICATION.md, SECURITY.md, MCP_STANDARDS.md, CODE_STYLE.md, BEAR_DATABASE_SCHEMA.md, evals/README.md, CHANGELOG.md, CI/release workflows) and cross-checked every specific claim — env vars, tool counts, file/line references, Z_OPT bump behavior per URL action, OCC inform/enforce mechanics, install commands, license — against the actual source. The docs in this repo are unusually well-maintained; the review surfaced exactly one stale cross-reference, fixed below.

Changes

• docs/dev/MCP_STANDARDS.md — Cross-reference to SPECIFICATION.md quoted a section title, "Optimistic Concurrency Control (Inform Half)", that doesn't exist verbatim. The actual structure is a level-3 heading ### Optimistic Concurrency Control containing a separate level-4 subsection #### Inform half. Updated the quoted reference to "Optimistic Concurrency Control" → "Inform half" so it matches the real heading structure.

No Issues Found

These checklist areas were verified clean — listed to show the check was performed, not skipped:

• Reference Accuracy — File/line citations in SPECIFICATION.md (e.g. database.ts:59 for PRAGMA busy_timeout = 3000) and BEAR_DATABASE_SCHEMA.md's per-URL-action Z_OPT bump claims (/add-text, /create, /add-tags, /add-file, /archive) all verified against src/infra/database.ts, src/tools/note-tools.ts, and src/tools/tag-tools.ts.
• Configuration Options — UI_DEBUG_TOGGLE, UI_ENABLE_NEW_NOTE_CONVENTION, UI_ENABLE_CONTENT_REPLACEMENT env vars and their defaults match across README.md, docs/user/NPM.md, manifest.json user_config, and src/config.ts.
• Feature Behavior Descriptions — OCC inform/enforce mechanics (checkRevisionGate, awaitRevisionIncrement, timeout sentinels) in SPECIFICATION.md match src/tools/responses.ts and src/operations/notes.ts exactly, including the documented +2 first-edit-after-creation jump. Tool gating counts (4 read-only, 1 off-only, 8 write) match tests/system/registration-gate.test.ts.
• Installation and Setup — npm/Claude Code/Codex/Gemini CLI install commands in README.md, NPM.md, and website/src/data/site.ts are consistent; Node engine requirement (^24.13.0) matches package.json/manifest.json across all docs and website copy.
• Architecture Spec — SPECIFICATION.md's "Intentional Exclusions" and "Key Design Constraints" claims (Bear DB path, journal mode, FTS5 tokenizer/BM25 weights, schema discovery) verified against src/infra/fts-index.ts, src/infra/database.ts, and src/infra/bear-schema.ts.
• Cross-Document Consistency — License (Apache-2.0) consistent across package.json, manifest.json, LICENSE.md, and website JSON-LD. Tool counts and version strings consistent across README.md, NPM.md, manifest.json, package.json, and website components.

🤖 Generated with Claude Code

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
bear-notes-mcp	Ready	Preview, Comment	Jun 25, 2026 12:12am

[vasylenko]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[Copilot]

Pull request overview

This PR updates maintainer-facing documentation to fix a stale cross-reference in the MCP standards doc so it matches the actual heading structure in docs/dev/SPECIFICATION.md.

Changes:

• Updated the SPECIFICATION.md cross-reference from a non-existent quoted heading to the correct "Optimistic Concurrency Control" → "Inform half" structure.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud