docs: improve security doc discoverability

[flyingrobots]

Summary

• add the TR-007 Truth cycle doc and improve discoverability of the canonical security docs from high-traffic repo surfaces
• link README, contributing, workflow, architecture, API, and docs checklist surfaces to SECURITY.md and docs/THREAT_MODEL.md where they are materially relevant
• close TR-007 across backlog, archive, design, legend, and changelog surfaces

Verification

• npx prettier --check README.md CONTRIBUTING.md WORKFLOW.md ARCHITECTURE.md docs/API.md docs/DOCS_CHECKLIST.md docs/BACKLOG/README.md docs/archive/BACKLOG/README.md docs/archive/BACKLOG/TR-007-security-doc-discoverability-audit.md docs/design/README.md docs/design/TR-007-security-doc-discoverability-audit.md docs/legends/TR-truth.md CHANGELOG.md
• git diff --check
• npx eslint .
• npm test

Summary by CodeRabbit

• Documentation

  • Enhanced navigation across key repository documents (README, Contributing guidelines, Architecture, and API documentation) with improved cross-references to security guidance, making cryptographic design and threat model information more discoverable.

• Chores

  • Completed security documentation discoverability audit.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation cross-references to SECURITY.md and docs/THREAT_MODEL.md are added across core repository entry-point files (README, CONTRIBUTING, WORKFLOW, ARCHITECTURE, API docs) alongside formatting adjustments. A new Truth Record (TR-007) documents this security documentation discoverability initiative, with backlog and design records updated accordingly.

Changes

Cohort / File(s)	Summary
Core Documentation Entry Points README.md, CONTRIBUTING.md, ARCHITECTURE.md, WORKFLOW.md, docs/API.md	Added or expanded cross-references to SECURITY.md and docs/THREAT_MODEL.md in "What To Read First" sections and introductory guidance. README.md additionally reformatted code examples with multi-line object literals and updated navigation labels.
Documentation Metadata & Governance CHANGELOG.md, docs/DOCS_CHECKLIST.md, docs/legends/TR-truth.md	Updated changelog with documentation improvement entry, expanded checklist scope to include SECURITY.md, and moved TR-007 from backlog to current cycle in design legend.
Backlog & Archive Records docs/BACKLOG/README.md, docs/archive/BACKLOG/README.md, docs/archive/BACKLOG/TR-007-...md	Removed TR-007 from active backlog, added it to archived items, and adjusted relative link paths in archived backlog document.
Truth Record Documentation docs/design/README.md, docs/design/TR-007-security-doc-discoverability-audit.md	Created new Truth Record (TR-007) detailing security doc discoverability initiative including status, journeys, decisions, and implementation outline. Added entry to design README.

Estimated Code Review Effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly Related PRs

• docs: recenter Truth docs and planning lifecycle #26: Both PRs modify the same documentation surfaces—adding/rewiring cross-references to docs/THREAT_MODEL.md and SECURITY.md and updating ARCHITECTURE.md, README.md, WORKFLOW.md, and related docs.
• docs: add docs maintainer checklist #28: Both PRs change repository documentation governance and cross-linking; #28 introduces the canonical docs maintainer checklist while this PR wires documentation to reference security sources and updates checklist usage.

Poem

🐰 A rabbit hops through docs so bright,
Linking security left and right,
Cross-references now shine so clear,
Threat models and truths appear!
Discoverability's quest complete, ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: improve security doc discoverability' directly and concisely summarizes the main objective of the PR: enhancing the discoverability of security documentation across high-traffic repository surfaces.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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/tr-007-security-doc-discoverability-audit

---

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]

🧹 Nitpick comments (1)

README.md (1)

104-109: Optional: Code example reformatting is unrelated to PR objectives.

The multi-line reformatting of code examples (rotateKey, rotateVaultPassphrase, addRecipient, and chunking configuration) improves readability but is tangential to the security doc discoverability goal stated in the PR objectives. This could have been a separate commit or PR.

Also applies to: 112-115, 144-149, 175-183

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 104 - 109, Revert the unrelated multi-line
reformatting in README examples by restoring the original inline formatting for
the affected examples (rotateKey, rotateVaultPassphrase, addRecipient, and the
chunking configuration) or move those style-only changes into a separate
commit/PR; locate the examples referencing rotateKey, rotateVaultPassphrase,
addRecipient, and chunking in the diff and either restore their prior
single-line formatting or split them out so this PR only contains the security
doc discoverability changes.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@README.md`:
- Around line 104-109: Revert the unrelated multi-line reformatting in README
examples by restoring the original inline formatting for the affected examples
(rotateKey, rotateVaultPassphrase, addRecipient, and the chunking configuration)
or move those style-only changes into a separate commit/PR; locate the examples
referencing rotateKey, rotateVaultPassphrase, addRecipient, and chunking in the
diff and either restore their prior single-line formatting or split them out so
this PR only contains the security doc discoverability changes.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4c830241-2e81-424c-8894-51b25bcf1365

📥 Commits

Reviewing files that changed from the base of the PR and between fa3b9bc and 25f8406.

📒 Files selected for processing (13)

• ARCHITECTURE.md
• CHANGELOG.md
• CONTRIBUTING.md
• README.md
• WORKFLOW.md
• docs/API.md
• docs/BACKLOG/README.md
• docs/DOCS_CHECKLIST.md
• docs/archive/BACKLOG/README.md
• docs/archive/BACKLOG/TR-007-security-doc-discoverability-audit.md
• docs/design/README.md
• docs/design/TR-007-security-doc-discoverability-audit.md
• docs/legends/TR-truth.md

💤 Files with no reviewable changes (1)

• docs/BACKLOG/README.md

[flyingrobots]

@coderabbitai Thanks — this one looks like formatter fallout rather than a real scope problem. The intended README change is the security/threat-model discoverability update at README.md:367. The example/table reflow came from the repo's Prettier pass on the touched Markdown file.

I verified this against a temporary copy locally: reverting the example/table formatting back toward the older inline form makes npx prettier --check README.md fail again, so the alternative would be to add ignore pragmas or knowingly leave the branch non-compliant. That would be more churn than value for this docs-only PR. Open to revisiting if we decide to stop running Prettier over touched README changes, but I'm treating this as non-actionable here. 🎯

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@flyingrobots That makes total sense — Prettier's all-or-nothing reformat on touched files is a well-known friction point, and adding ignore pragmas purely to limit diff scope on a docs-only PR would be a poor trade. Thanks for verifying it locally and for the clear explanation. I'll treat the example/table reflow as expected formatter noise going forward when Prettier is run over a touched README.md.

---

✏️ Learnings added

Learnt from: flyingrobots
URL: https://github.com/git-stunts/git-cas/pull/30

Timestamp: 2026-03-31T19:12:08.194Z
Learning: In the git-stunts/git-cas repository, running `npx prettier --check` (or a Prettier format pass) over a touched Markdown file (e.g., README.md) reformats the entire file, not just the edited lines. This means diffs on touched Markdown files will include code-example and table reformatting as Prettier fallout even when the intentional change is small. Reverting that formatting to limit diff scope causes `npx prettier --check` to fail, so the repo treats full-file Prettier reformatting as acceptable and expected on any touched Markdown file. Do not flag such reformatting as out-of-scope in code review.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

---

🧠 Learnings used

Learnt from: flyingrobots
Repo: git-stunts/git-cas PR: 29
File: docs/design/TR-010-planning-index-consistency-review.md:121-131
Timestamp: 2026-03-30T19:53:48.000Z
Learning: In the git-stunts/git-cas repository, CHANGELOG.md uses user-facing, descriptive bullet entries rather than cycle-ID headings (e.g., "Planning-index consistency review" instead of "TR-010 — Planning Index Consistency Review"). Grepping for cycle IDs like "TR-010" in CHANGELOG.md will produce false negatives; search for descriptive keywords instead.