docs: fix sync gaps found in v0.6.0-to-v0.6.15 audit

[jackgranatowski]

• llm-guide.md: update version header from 0.6.10/693 to 0.6.15/686
  (header is not covered by check:llm-guide CI gate)
• CHANGELOG.md: remove duplicate v0.6.4 entry and duplicate v0.6.0 entry
  (release process ran twice; merge undici CVE fix into the richer entry)
• CHANGELOG.md: add ⚠️ Breaking Changes to v0.6.11 for error color removal
  and source token rename (were undocumented in release notes)
• migration.md: rename section header from "0.6.x → 0.7.0" to
  "0.6.10 → 0.6.11" — changes were introduced in v0.6.11, not v0.7.0

Co-Authored-By: Claude Sonnet 4.6 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01XN8wtM6HyC6DEoCrNkoAKh

Summary by CodeRabbit

• Documentation
  • Updated the changelog with breaking token name changes, including the shift from error tokens to danger tokens and renamed brand/status source tokens.
  • Added a security-related note about a dependency override used to address high-severity CVEs.
  • Refreshed migration guidance and version references to reflect the latest release.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1b093ef9-3b37-4e78-9cea-55b5f3f85849

📥 Commits

Reviewing files that changed from the base of the PR and between 222f137 and fc3bd0e.

📒 Files selected for processing (3)

• CHANGELOG.md
• docs/llm-guide.md
• docs/migration.md

---

📝 Walkthrough

Walkthrough

Updates the changelog for 0.6.11 token breaking changes, removes older release-note sections, adds an undici pin note, and adjusts version headings in the llm guide and migration guide.

Changes

Release notes and version docs

Layer / File(s)	Summary
0.6.11 breaking changes CHANGELOG.md	The 0.6.11 breaking-changes entry removes --sf-color-error and renames brand/status source tokens to -source-light and -source-dark.
Changelog history cleanup CHANGELOG.md	The changelog removes the older 0.6.4 subsection, trims the earlier 0.6.0 breaking-changes and bug-fix block, and adds an undici override pin under 0.6.0 bug fixes.
Doc version headings docs/llm-guide.md, docs/migration.md	The llm guide version marker changes to 0.6.15, and the migration guide heading changes to SLASHED 0.6.10 → 0.6.11.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 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 matches the docs audit fix and sync-gap cleanup across versions v0.6.0 to v0.6.15.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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/framework-sync-audit-mnifml

---

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

[qodo-code-review]

PR Summary by Qodo

Docs: fix changelog, migration notes, and LLM guide version sync (v0.6.0–0.6.15)
📝 Documentation 🕐 Less than 10 minutes

Description

• Fix duplicated/incorrect CHANGELOG entries across v0.6.0–v0.6.4.
• Document v0.6.11 breaking token changes that were missing from release notes.
• Align migration guide + LLM reference header with actual introduced versions/counts.

Diagram

graph TD
  Release["Release audit (v0.6.x)"] --> Changelog["CHANGELOG.md"] --> Readers["Users/maintainers"]
  Release --> Migration["docs/migration.md"] --> Readers
  Release --> LLM["docs/llm-guide.md"] --> Readers
  CI(["CI gates"]) --> LLM

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Automate doc-header + changelog consistency checks in CI

• ➕ Prevents future drift (e.g., llm-guide header not covered by current gate).
• ➕ Can detect duplicate version headings or missing breaking-change sections early.
• ➖ Adds CI complexity/maintenance and may require defining strict formatting rules.
• ➖ May generate noise/false positives if release notes are intentionally flexible.

2. Generate CHANGELOG/migration sections from release metadata

• ➕ Single source of truth reduces manual duplication and omissions.
• ➕ Easier to ensure breaking changes are consistently recorded.
• ➖ More up-front tooling/process change than a simple docs correction PR.
• ➖ May not fit current release workflow or contributor expectations.

Recommendation: For this PR, the direct documentation corrections are the right scope and lowest-risk fix. As a follow-up, consider extending CI to validate the llm-guide header fields (version/token count) and adding a lightweight duplicate-version check for CHANGELOG headings to prevent recurrence.

Files changed (3) +7 / -19

Documentation (3) +7 / -19

CHANGELOG.mdFix duplicate entries and document v0.6.11 breaking token changes +5/-17

Fix duplicate entries and document v0.6.11 breaking token changes

• Removes duplicated v0.6.4 and v0.6.0 sections caused by repeated release runs and consolidates the undici CVE pin into the richer v0.6.0 notes. Adds an explicit ⚠️ Breaking Changes section to v0.6.11 documenting error token removal and source-token renames.

CHANGELOG.md

llm-guide.mdUpdate LLM guide header to v0.6.15 and current token count +1/-1

Update LLM guide header to v0.6.15 and current token count

• Updates the top-of-file version/tokens header from 0.6.10/693 to 0.6.15/686 to reflect the audited state.

docs/llm-guide.md

migration.mdCorrect migration section header to match actual introduction version +1/-1

Correct migration section header to match actual introduction version

• Renames the migration section header from "0.6.x → 0.7.0" to "0.6.10 → 0.6.11" to align the guidance with when the documented changes were introduced.

docs/migration.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 5 rules

1. Migration token names wrong 🐞 Bug ≡ Correctness

Description

In the newly-labeled “SLASHED 0.6.10 → 0.6.11” section, the guide tells users to remove overrides
for --sf-color-error-source-light/--sf-color-error-source-dark, but those token names do not
exist in the registry. The removed tokens are --sf-color-error-light and --sf-color-error-dark,
so following the guide will leave the real stale overrides in place.

Code

docs/migration.md[6]

+## SLASHED 0.6.10 → 0.6.11

Relevance

⭐⭐⭐ High

Team has accepted fixing non-canonical/phantom token names in docs to match registry/API (PR #270,
#48).

PR-#270
PR-#48
PR-#387

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The migration guide explicitly references --sf-color-error-source-*, while the registry’s removed
error tokens are --sf-color-error-light/--sf-color-error-dark (and --sf-color-text--on-error
is also removed). This demonstrates a name mismatch that would cause incorrect migration steps.

docs/migration.md[23-33]
token-registry.json[576-604]
token-registry.json[1225-1233]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The migration instructions for the 0.6.10 → 0.6.11 upgrade reference `--sf-color-error-source-light` / `--sf-color-error-source-dark`, but the token registry shows the removed error source tokens were named `--sf-color-error-light` / `--sf-color-error-dark`.

## Issue Context
- `token-registry.json` lists `--sf-color-error-light` and `--sf-color-error-dark` as removed.
- `docs/migration.md` currently instructs removing overrides to `--sf-color-error-source-*`, which appears to be a non-existent name.

## Fix Focus Areas
- docs/migration.md[6-34]

## Suggested change
- Update the bullet to instruct removal of `--sf-color-error-light` / `--sf-color-error-dark` (the old 0.6.10 names) instead of `--sf-color-error-source-*`.
- Consider adding an explicit replacement note for `--sf-color-text--on-error` → `--sf-color-text--on-danger`, since the registry also marks `--sf-color-text--on-error` as removed.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Ambiguous removed token list 🐞 Bug ≡ Correctness

Description

The v0.6.11 breaking-change entry lists removed tokens using bare suffixes like -dark/-light,
which are not valid token names and can mislead users copying them. The canonical removed tokens are
fully-prefixed names like --sf-color-error-dark/--sf-color-error-light (and
--sf-color-text--on-error) in the registry.

Code

CHANGELOG.md[62]

+- **tokens:** removed `--sf-color-error` family (7 tokens: `--sf-color-error`, `-dark`, `-light`, `-muted`, `-strong`, `-subtle`, `--sf-color-text--on-error`) — use `--sf-color-danger` equivalents; see `docs/migration.md`

Relevance

⭐ Low

Team previously rejected expanding shorthand token refs in docs/prose (PR #383), suggesting suffix
shorthand is acceptable.

PR-#383

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The changelog bullet contains bare -dark/-light suffixes, while the token registry shows the
exact removed token names with the full --sf-color-error-* prefix (and
--sf-color-text--on-error).

CHANGELOG.md[59-63]
token-registry.json[576-604]
token-registry.json[1225-1233]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`CHANGELOG.md` v0.6.11 “Breaking Changes” uses shorthand backticked suffixes (`-dark`, `-light`, etc.) that are not standalone token names.

## Issue Context
The canonical removed tokens are fully-qualified in `token-registry.json` (e.g. `--sf-color-error-dark`) and users will likely copy/paste from the changelog during upgrades.

## Fix Focus Areas
- CHANGELOG.md[59-63]

## Suggested change
Replace the shorthand list with fully-qualified token names, e.g.:
- `--sf-color-error`
- `--sf-color-error-dark`
- `--sf-color-error-light`
- `--sf-color-error-muted`
- `--sf-color-error-strong`
- `--sf-color-error-subtle`
- `--sf-color-text--on-error`

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---