docs(archive): document capability retirement workflow

[clay-good]

Status

LGTM. This is ready for review.

What was missing

OpenSpec has supported first-class capability retirement since v1.8.0, but the archive command examples did not show how to use it. That made the released solution to #1750 easy to miss, especially for users coming from v1.7.0.

What it does

• Adds a copy-paste .openspec.yaml example with retire_capabilities: true.
• Shows the normal non-interactive archive command.
• States that mixed changes still apply their other capability deltas.
• States that an absent marker aborts before any files change.

Proof it works

• test/core/archive.test.ts: 215/215 passing.
• Focused mixed-change regression: 1/1 passing (applies a retirement and an ordinary update in the same archive).
• Build completed during dependency installation.
• git diff --check passes.

Notes / nits

• No runtime behavior changes. PR feat(archive): let a change retire a capability it empties #1484 implemented and shipped the underlying retirement path in v1.8.0.
• The full suite reached 4,209 passing tests, but the local sandbox prevented 16 loopback-listener tests from starting and exposed 4 machine-profile-sensitive failures outside this docs-only diff. The focused and complete archive suites are green.
• No changeset: this is a documentation-only clarification.

Closes #1750

Summary by CodeRabbit

• Documentation
  • Documented how to retire a capability when archiving a change.
  • Explained the required retirement setting and how capability specifications are updated or removed.
  • Clarified that archiving stops without the setting when retirement would affect files.

[cloudflare-workers-and-pages]

Deploying openspec-docs with    Cloudflare Pages

Latest commit:	6260a94
Status:	✅  Deploy successful!
Preview URL:	https://bf1b4c81.openspec-docs.pages.dev
Branch Preview URL:	https://codex-fix-1750-retire-capabi.openspec-docs.pages.dev

View logs

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 9941eb97-7fe5-463d-a898-2a05e2842aa3

📥 Commits

Reviewing files that changed from the base of the PR and between a0ddb60 and 6260a94.

📒 Files selected for processing (1)

• docs/cli.md

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

The CLI documentation now describes how to retire a capability during archive. It covers the retire_capabilities: true marker, command usage, live spec deletion, updates to other capability specs, and behavior when the marker is absent.

Changes

Capability retirement

Layer / File(s)	Summary
Document capability retirement docs/cli.md	Adds instructions for marking and archiving a capability retirement. Documents deletion of the live spec.md when the last requirement is removed and the abort behavior without the marker.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Merge Risk: ⚪ Minimal · up to 6260a

This documentation-only change clarifies the capability retirement workflow without changing product behavior. No actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: alfred-openspec, tabishb, showms

🚥 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 clearly and concisely describes the documentation change for the capability retirement workflow in the archive command.
Linked Issues check	✅ Passed	The documentation explains the first-class retirement workflow requested by issue #1750, including the required marker, mixed-capability changes, and safe abort behavior. The runtime implementation is…
Out of Scope Changes check	✅ Passed	The pull request changes only docs/cli.md, and the documented content directly supports issue #1750 and the stated documentation objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…

Full details: Linked Issues check

Explanation

The documentation explains the first-class retirement workflow requested by issue #1750, including the required marker, mixed-capability changes, and safe abort behavior. The runtime implementation is explicitly stated to exist in v1.8.0.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-1750-retire-capability

---

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

[alfred-openspec]

The exact head 6260a946 matches the shipped v1.8+ retirement contract. The example uses the required boolean metadata marker, preserves mixed-change behavior, and accurately states the pre-mutation abort when the marker is absent. The narrower spec.md wording is also correct because retirement prunes the capability directory only when it is empty. Every required hosted check is green. Approved.