docs: align public guides with current release

[jeffhuber]

Closes #848

Summary

• distinguish the published v1.1.2 package docs from unreleased source behavior on main
• repair stale or invalid command examples, Jira transport wording, orchestrator guidance, and release chronology
• reorganize the README docs map and remove references to a private external repository
• add release-hygiene coverage for retired commands, private identifiers, chronology, and release boundaries
• isolate Jira credential tests from developer-machine profiles

Builder: codex

Verification

• python -m unittest discover -s tests (2,676 tests)
• ruff check .
• python -m build
• python -m twine check dist/*
• actionlint
• python scripts/privacy_scan.py --json
• local Markdown links and heading anchors (129 checked)
• generated easy-mode smoke and package command help validation

[jeffhuber]

Claude audit (merge-authority lane)

Head SHA: 68a794ebf99e318bd7e173b844fe17b25faf6986
Findings: P0=0, P1=0, P2=0, P3=1 (blocker policy: any P0/P1/P2 -> BLOCKED)

Claude Audit: PASS

Summary:

Docs-only consistency PR (README, CHANGELOG, and several docs/*.md files) plus matching test updates in tests/test_release_hygiene.py and tests/test_jira_adoption.py. Changes scrub a private repo name and other private identifiers from public docs, fix stale/incorrect CLI command examples (code-mower audit pr, code-mower tracker status), reorganize the README docs map, and update tracker-data-contract.md wording to reflect already-shipped Jira transport/PR-sync functionality (consistent with unchanged sections of the same doc and jira-cloud-setup.md). No source code is touched, all edits are backed by new/updated regression assertions, and no broken links, contradicted contracts, or missing validation were found.

Findings:

• [P3] Obfuscated string construction in privacy regression test -- tests/test_release_hygiene.py:7896
  Finding ID: claude:79e6adbea2238519934c
  The new test builds the disallowed private-identifier strings via string concatenation (e.g. "/Us" + "ers/" + "j" + "huber") instead of writing them as plain literals. This works and is a reasonable way to avoid re-introducing a literal private path/username into the source, but it reduces readability and could be replaced with a clearer comment explaining why the strings are split, or a single documented list. Non-blocking.

[gitar-bot]

💡 Quality: Orchestrator Hosts table states qualification as unconditional

The new table (lines 24-29) flatly states Codex, Claude Code, and Cursor are all "Qualified for the same session, telemetry, and lease contract," and only the prose note two lines below clarifies that the lease and Cursor qualification are unreleased on main (not in the published v1.1.2 package). A reader who copies or skims just the table (a common pattern for reference tables) could believe this is current v1.1.2 behavior. Consider adding a footnote marker directly in the table cells for the unreleased items (e.g. "Qualified for session coordination (unreleased on main)") rather than relying solely on the trailing paragraph.

Mark unreleased status inline per row instead of only in a trailing paragraph:

| Codex | Qualified for session coordination and controller telemetry; the working-copy lease is unreleased on `main` | ... |
| Claude Code | Qualified for the same session and telemetry; the lease is unreleased on `main` | ... |
| Cursor | Qualification, telemetry, and lease are unreleased on `main` (not in v1.1.2) | ... |

_{Was this helpful? React with 👍 / 👎}

[gitar-bot]

💡 Quality: New hygiene test doesn't cover examples/*/README.md or CONTRIBUTING.md

test_public_docs_match_current_commands_and_privacy_boundary only scans docs/*.md, README.md, and CHANGELOG.md for stale commands and private identifiers, but the README's docs map (this PR) links to examples/demo-calibration/README.md and examples/board-demo/README.md, which are also public-facing docs and aren't covered by this hygiene sweep. Widening the paths glob to include examples/**/*.md (and any other public root docs like CONTRIBUTING.md/SUPPORT.md) would close this gap for future edits, even though no leaks exist in those files today.

Include examples//*.md in the privacy/command hygiene scan:**

paths = (
    sorted((ROOT / "docs").rglob("*.md"))
    + sorted((ROOT / "examples").rglob("*.md"))
    + [ROOT / "README.md", ROOT / "CHANGELOG.md"]
)

_{Was this helpful? React with 👍 / 👎}

[gitar-bot]

Note

Automatic reviews are paused because your team has used its included automatic processing for this billing period (headroom scales with your seat count). You can still comment "Gitar review" to run one anytime, and automatic reviews resume on their own by October 1. Add seats for more headroom.
Learn more

Code Review 👍 Approved with suggestions 0 resolved / 2 findings

Aligns public guides with the current v1.1.2 release while documenting unreleased main-branch behavior, fixing stale command examples, Jira transport wording, orchestrator guidance, and release chronology. Two minor suggestions: add inline footnote markers in the Orchestrator Hosts table to clarify unreleased qualifications rather than relying on trailing prose, and expand the new release-hygiene test to cover examples/**/*.md and other public root docs alongside the current docs/*.md scope.

💡 Quality: Orchestrator Hosts table states qualification as unconditional

📄 docs/provider-matrix.md:24-33

The new table (lines 24-29) flatly states Codex, Claude Code, and Cursor are all "Qualified for the same session, telemetry, and lease contract," and only the prose note two lines below clarifies that the lease and Cursor qualification are unreleased on main (not in the published v1.1.2 package). A reader who copies or skims just the table (a common pattern for reference tables) could believe this is current v1.1.2 behavior. Consider adding a footnote marker directly in the table cells for the unreleased items (e.g. "Qualified for session coordination (unreleased on main)") rather than relying solely on the trailing paragraph.

Mark unreleased status inline per row instead of only in a trailing paragraph

| Codex | Qualified for session coordination and controller telemetry; the working-copy lease is unreleased on `main` | ... |
| Claude Code | Qualified for the same session and telemetry; the lease is unreleased on `main` | ... |
| Cursor | Qualification, telemetry, and lease are unreleased on `main` (not in v1.1.2) | ... |

💡 Quality: New hygiene test doesn't cover examples/*/README.md or CONTRIBUTING.md

📄 tests/test_release_hygiene.py:7952-7966

test_public_docs_match_current_commands_and_privacy_boundary only scans docs/*.md, README.md, and CHANGELOG.md for stale commands and private identifiers, but the README's docs map (this PR) links to examples/demo-calibration/README.md and examples/board-demo/README.md, which are also public-facing docs and aren't covered by this hygiene sweep. Widening the paths glob to include examples/**/*.md (and any other public root docs like CONTRIBUTING.md/SUPPORT.md) would close this gap for future edits, even though no leaks exist in those files today.

Include examples/**/*.md in the privacy/command hygiene scan

paths = (
    sorted((ROOT / "docs").rglob("*.md"))
    + sorted((ROOT / "examples").rglob("*.md"))
    + [ROOT / "README.md", ROOT / "CHANGELOG.md"]
)

🤖 Prompt for agents

Code Review: Aligns public guides with the current v1.1.2 release while documenting unreleased main-branch behavior, fixing stale command examples, Jira transport wording, orchestrator guidance, and release chronology. Two minor suggestions: add inline footnote markers in the Orchestrator Hosts table to clarify unreleased qualifications rather than relying on trailing prose, and expand the new release-hygiene test to cover `examples/**/*.md` and other public root docs alongside the current `docs/*.md` scope.

1. 💡 Quality: Orchestrator Hosts table states qualification as unconditional
   Files: docs/provider-matrix.md:24-33

   The new table (lines 24-29) flatly states Codex, Claude Code, and Cursor are all "Qualified for the same session, telemetry, and lease contract," and only the prose note two lines below clarifies that the lease and Cursor qualification are unreleased on `main` (not in the published v1.1.2 package). A reader who copies or skims just the table (a common pattern for reference tables) could believe this is current v1.1.2 behavior. Consider adding a footnote marker directly in the table cells for the unreleased items (e.g. "Qualified for session coordination *(unreleased on main)*") rather than relying solely on the trailing paragraph.

   Fix (Mark unreleased status inline per row instead of only in a trailing paragraph):
   | Codex | Qualified for session coordination and controller telemetry; the working-copy lease is unreleased on `main` | ... |
   | Claude Code | Qualified for the same session and telemetry; the lease is unreleased on `main` | ... |
   | Cursor | Qualification, telemetry, and lease are unreleased on `main` (not in v1.1.2) | ... |

2. 💡 Quality: New hygiene test doesn't cover examples/*/README.md or CONTRIBUTING.md
   Files: tests/test_release_hygiene.py:7952-7966

   `test_public_docs_match_current_commands_and_privacy_boundary` only scans `docs/*.md`, `README.md`, and `CHANGELOG.md` for stale commands and private identifiers, but the README's docs map (this PR) links to `examples/demo-calibration/README.md` and `examples/board-demo/README.md`, which are also public-facing docs and aren't covered by this hygiene sweep. Widening the `paths` glob to include `examples/**/*.md` (and any other public root docs like CONTRIBUTING.md/SUPPORT.md) would close this gap for future edits, even though no leaks exist in those files today.

   Fix (Include examples/**/*.md in the privacy/command hygiene scan):
   paths = (
       sorted((ROOT / "docs").rglob("*.md"))
       + sorted((ROOT / "examples").rglob("*.md"))
       + [ROOT / "README.md", ROOT / "CHANGELOG.md"]
   )

Options

Display: compact → Counting what did not apply, without listing it.

Comment with these commands to change the behavior for this request:

Compact

gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}