docs: clean up and enrich security model documentation

[spoorcc]

Summary

• Remove duplication — the security model page repeated the three-tier traceability diagram, compliance-only control listing, OSCAL artifact links, and control register reference that are already in the auto-generated compliance_track.rst; replaced with a single forwarding paragraph.
• Distribution channels — add winget alongside PyPI and GitHub Releases; hyperlink all three to their respective pages.
• Inline hyperlinks — add links to MIT licence, Article 13 (CRA), GitHub Actions / GitLab CI / Jenkins, and OJEU throughout the security model prose.
• Fix rendered titles — gap analysis section headings in compliance_track.rst used **:ref:…** which RST cannot render (inline role inside bold); switched the generator to .. rubric:: so the cross-reference links resolve correctly.
• Expand OSCAL Artifacts section — explain what OSCAL is, what problem it solves for downstream integrators, and link directly to both artifact files in the repo.
• Glossary term refs — add :term: cross-references for CRA, EN 40000, STRIDE, SDLC, Archive, Manifest, Metadata, Destination, Vendoring, Superproject, OSCAL, SBOM, SLSA, Sigstore, Attestation, VSA, ECR, SARIF throughout security.rst and security_pipeline.rst; convert the compliance.py generator to use :term:\OSCAL`` in the generated page.
• New glossary entries — add SDLC, CVE, and ECR (all appear in the security pages but were previously undefined).
• Seealso boxes — add .. seealso:: blocks on security.rst and security_pipeline.rst pointing readers to the glossary.

Test plan

• Build the Sphinx docs (make -C doc html) and check that all :term: refs resolve without warnings
• Verify the gap analysis headings in compliance_track.rst render as bold rubrics with working anchor links
• Confirm the distribution channel links (PyPI, GitHub Releases, winget) open the correct pages
• Confirm the seealso boxes appear on both security pages

🤖 Generated with Claude Code

https://claude.ai/code/session_01E1Kh1r5dX7VEP6AScUtgrN

---

Generated by Claude Code

Summary by CodeRabbit

• Documentation
  • Enhanced security and compliance documentation with improved cross-referencing, formatting, and term definitions using Sphinx markup.
  • Added three new glossary entries: CVE, ECR, and SDLC with relevant cross-references.
  • Reorganized compliance gap analysis sections and expanded OSCAL artifact documentation for improved clarity.
  • Updated security model and pipeline documentation with refined terminology and better formatting.

[coderabbitai]

Warning

Review limit reached

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

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

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

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

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6e4367dc-bc89-42b0-88f0-5107480ac5a8

📥 Commits

Reviewing files that changed from the base of the PR and between 8f0554c and a564d75.

📒 Files selected for processing (1)

• doc/explanation/security_pipeline.rst

Walkthrough

Documentation-only update: the compliance.py RST renderer switches gap-analysis headings from bold text to .. rubric:: directives and expands the OSCAL Artifacts narrative. The auto-generated compliance_track.rst reflects those changes. security.rst is refactored with :term: roles and a condensed CRA section. security_pipeline.rst gains a seealso block and term markup. glossary.rst adds CVE, ECR, and SDLC entries.

Changes

CRA Compliance Docs: Rendering, Narrative, Cross-References, and Glossary

Layer / File(s)	Summary
compliance.py renderer: rubric directive, OSCAL term markup, expanded OSCAL Artifacts security/compliance.py	Gap-analysis entry titles now emit .. rubric:: {title} instead of **{title}**. "OSCAL" is wrapped in :term: markup. The OSCAL Artifacts text block is replaced with expanded narrative and bullets naming both shipped OSCAL 1.2.2 artifacts and their regeneration command.
compliance_track.rst: OSCAL statement, rubric headings, Artifacts section doc/explanation/compliance_track.rst	Adds a sentence noting machine-readable artifacts are encoded in OSCAL 1.2.2. C-043/C-044/C-046 gap entries are reformatted to .. rubric:: directives with :ref:-linked control IDs. The OSCAL Artifacts section is expanded with fuller prose and a bullet list of both artifacts.
security.rst: term references, CRA section condensed, seealso block doc/explanation/security.rst	Introductory text adopts :term: roles for CRA/EN 40000/STRIDE. Distribution channel entries gain inline hyperlinks; the CRA applicability paragraph uses :term: and an Article 13 link. The detailed CRA compliance subsection is replaced by a short paragraph pointing to compliance_track. A .. seealso:: glossary block is appended.
security_pipeline.rst term markup, Artifacts table, and glossary entries doc/explanation/security_pipeline.rst, doc/reference/glossary.rst	security_pipeline.rst gains a .. seealso:: block and converts STRIDE, OSCAL, Attestation, Sigstore, SBOM, and VSA to :term: references; the Artifacts-at-a-glance table rows for the OSCAL component definition and attestation categories are refined. glossary.rst adds CVE, ECR, and SDLC definitions with cross-references.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• dfetch-org/dfetch#1282: Directly overlaps with this PR's changes to gap-analysis rubric formatting and the OSCAL Artifacts narrative in doc/explanation/compliance_track.rst.
• dfetch-org/dfetch#1284: Both modify security/compliance.py RST output for gap analysis and update OSCAL 1.2.2 references in compliance_track.rst.
• dfetch-org/dfetch#1271: Both update the CRA compliance track generation flow in security/compliance.py and doc/explanation/compliance_track.rst, including OSCAL artifact and gap-analysis rendering.

Suggested labels

documentation

🚥 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 title 'docs: clean up and enrich security model documentation' accurately reflects the main changes: removing duplication from security documentation and adding cross-references and hyperlinks to improve it.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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 claude/security-model-duplication-so5o3q

---

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 `@doc/explanation/security_pipeline.rst`:
- Line 107: The reStructuredText syntax for pluralizing the glossary term
reference on line 107 is incorrect. In the phrase containing `:term:`ECR`\s`,
the backslash escape sequence is malformed. Change `:term:`ECR`\s` to
`:term:`ECR`\ s` by adding a space after the backslash. The escaped space
(backslash followed by space) properly separates the role markup from the
following character while maintaining valid RST syntax for pluralization.

🪄 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: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 94472a36-fa16-4015-8ab1-aec78710bbc3

📥 Commits

Reviewing files that changed from the base of the PR and between ea7d0bd and 8f0554c.

📒 Files selected for processing (5)

• doc/explanation/compliance_track.rst
• doc/explanation/security.rst
• doc/explanation/security_pipeline.rst
• doc/reference/glossary.rst
• security/compliance.py