docs-cli 1.4.0__tar.gz → 1.5.0__tar.gz

{docs_cli-1.4.0 → docs_cli-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docs-cli
-Version: 1.4.0
+Version: 1.5.0
 Summary: Prescriptive CLI for managing trees of structured Markdown docs.
 Project-URL: Homepage, https://github.com/ArtRichards/docs-cli
 Project-URL: Repository, https://github.com/ArtRichards/docs-cli

{docs_cli-1.4.0 → docs_cli-1.5.0}/docs/INDEX.md

@@ -5,13 +5,13 @@ This directory is the docs root for the `docs` CLI itself. We eat our own dog fo
 The hand-written preamble (this paragraph, and anything outside the marker block) is preserved by the tool. Only content between `<!-- docs:generated start -->` and `<!-- docs:generated end -->` is rewritten.
 
 <!-- docs:generated start -->
-_Generated 2026-05-27. 32 docs active, 1 archived._
+_Generated 2026-05-29. 35 docs active, 2 archived._
 
 ## Project — docs
 
 ### Active — Status
 
-- [status.md](status.md) — _status_ — **This is the single source of truth for project progress. Update only this file when milestones complete or phases…. Updated 2026-05-27.
+- [status.md](status.md) — _status_ — **This is the single source of truth for project progress. Update only this file when milestones complete or phases…. Updated 2026-05-29.
 
 ### Active — Charter
 
@@ -19,16 +19,17 @@ _Generated 2026-05-27. 32 docs active, 1 archived._
 
 ### Active — Plan
 
-- [plan.md](plan.md) — _plan_ — Three milestones to v1, then a migration helper, then a Claude Code skill wrapper. v1.1 picks up with packaging, then…. Updated 2026-05-27.
+- [plan.md](plan.md) — _plan_ — Three milestones to v1, then a migration helper, then a Claude Code skill wrapper. v1.1 picks up with packaging, then…. Updated 2026-05-29.
 
 ### Active — Spec
 
-- [cli.md](cli.md) — _spec_ — This spec defines the `docs` command-line surface: subcommands, flags, output formats, and exit codes. The on-disk…. Updated 2026-05-27.
-- [convention.md](convention.md) — _spec_ — This spec defines the on-disk convention that `docs` reads and writes. It is the portable, tool-independent part: any…. Updated 2026-05-27.
+- [cli.md](cli.md) — _spec_ — This spec defines the `docs` command-line surface: subcommands, flags, output formats, and exit codes. The on-disk…. Updated 2026-05-28.
+- [convention.md](convention.md) — _spec_ — This spec defines the on-disk convention that `docs` reads and writes. It is the portable, tool-independent part: any…. Updated 2026-05-28.
 
 ### Active — Milestone
 
-- [m11-pypi-publish.md](m11-pypi-publish.md) — _milestone_ — > **Stub-drafted 2026-05-27, post M10 closeout.** M11 enters > active state immediately — the M10 wheel + sdist already…. Updated 2026-05-27.
+- [m13-pypi-publish.md](m13-pypi-publish.md) — _milestone_ — > **Stub-drafted 2026-05-29, post M12 closeout.** M13 enters > active state immediately — the M12 wheel + sdist already…. Updated 2026-05-29.
+- [m12-project-rename.md](m12-project-rename.md) — _milestone_ — > **Stub-drafted 2026-05-28** following M11 closeout. M12 bundles > one operator-facing headline feature (`docs project…. Updated 2026-05-28.
 - [m7-migration-accuracy.md](m7-migration-accuracy.md) — _milestone_ — - Milestone: M7 (v1.1) - Title: Migration plan accuracy - Surface: extensions to `docs migrate`'s inference…. Updated 2026-05-25.
 - [m8-adoption-workflow.md](m8-adoption-workflow.md) — _milestone_ — - Milestone: M8 (v1.1) - Title: Adoption workflow — agent-driveable - Surface: new CLI flags + verbs (`--exclude`,…. Updated 2026-05-25.
 - [m9-pypi-publish.md](m9-pypi-publish.md) — _milestone_ — > **Stub-drafted 2026-05-24, post M6 scope reframe.** M9 enters > active state once M8 ships. The operative checklist…. Updated 2026-05-25.
@@ -41,6 +42,8 @@ _Generated 2026-05-27. 32 docs active, 1 archived._
 
 ### Active — Log
 
+- [m13-pypi-publish-impl.md](m13-pypi-publish-impl.md) — _log_ — Chronological log of work on M13 — PyPI publish 1.5.0. Append a section per runbook phase (operator prep → pre-publish…. Updated 2026-05-29.
+- [m12-project-rename-impl.md](m12-project-rename-impl.md) — _log_ — Chronological log of work on M12 — Project rename verb + M11 wart fixes + version SoT (v1.5.0). Append a section per…. Updated 2026-05-28.
 - [m10-adoption-polish-impl.md](m10-adoption-polish-impl.md) — _log_ — Chronological log of work on M10 — Adoption-flow polish + 1.3.0 carry-overs. Append a section per phase with objective,…. Updated 2026-05-27.
 - [m11-pypi-publish-impl.md](m11-pypi-publish-impl.md) — _log_ — Chronological log of work on M11 — PyPI publish `docs-cli` 1.4.0. Append a section per phase (Operator prep →…. Updated 2026-05-27.
 - [m7-migration-accuracy-log.md](m7-migration-accuracy-log.md) — _log_ — - Project: docs - Milestone: M7 — Migration plan accuracy - Started: 2026-05-24 - Progress: **Phase 1 complete; Phase 2…. Updated 2026-05-25.
@@ -60,15 +63,16 @@ _Generated 2026-05-27. 32 docs active, 1 archived._
 
 ### Active — Runbook
 
-- [release-runbook.md](release-runbook.md) — _runbook_ — The operator-driven checklist for shipping `docs-cli` to PyPI. This runbook drove **M9 — `docs-cli==1.3.0`** (shipped…. Updated 2026-05-25.
+- [release-runbook.md](release-runbook.md) — _runbook_ — The operator-driven checklist for shipping `docs-cli` to PyPI. This runbook drove **M9 — `docs-cli==1.3.0`** (shipped…. Updated 2026-05-27.
 
 ### Active — Reference
 
-- [architecture.md](architecture.md) — _reference_ — Single Python module at `src/docs_cli/cli.py`, exposed as the `docs` console-script via the `docs_cli.cli:main` entry…. Updated 2026-05-27.
+- [architecture.md](architecture.md) — _reference_ — Single Python module at `src/docs_cli/cli.py`, exposed as the `docs` console-script via the `docs_cli.cli:main` entry…. Updated 2026-05-28.
 - [definition-of-ready.md](definition-of-ready.md) — _reference_ — Gate-check before implementation begins. Implementation does not start until every item is green.. Updated 2026-05-22.
 - [test-strategy.md](test-strategy.md) — _reference_ — | Layer | Tool | Scope | |---|---|---| | Unit | pytest | Parser, walker, render, vocab loading. Pure-function focus. |…. Updated 2026-05-20.
 
 ## Archived
 
 - [archive/2026-05-27/m10-adoption-polish.md](archive/2026-05-27/m10-adoption-polish.md) — _milestone_ — - Milestone: M10 (v1.4.0) - Title: Adoption-flow polish + 1.3.0 carry-overs - Surface: two new CLI features (`docs…. Updated 2026-05-27.
+- [archive/2026-05-27/m11-pypi-publish.md](archive/2026-05-27/m11-pypi-publish.md) — _milestone_ — > **Stub-drafted 2026-05-27, post M10 closeout.** M11 enters > active state immediately — the M10 wheel + sdist already…. Updated 2026-05-27.
 <!-- docs:generated end -->

{docs_cli-1.4.0 → docs_cli-1.5.0}/docs/architecture.md

@@ -3,7 +3,7 @@
 Lifecycle: active
 Role: reference
 Project: docs
-Updated: 2026-05-27
+Updated: 2026-05-28
 
 Related:
 - implements: charter.md
@@ -24,20 +24,22 @@ inside the same wheel as package data.
 src/docs_cli/                            (Python 3.11+, stdlib only)
 ├── __init__.py                          ─ lazy re-export of `main`
 ├── cli.py                               ─ the CLI module (~3.8k lines)
-│   ├── dunder version                   (__version__ = "1.4.0")
+│   ├── dunder version                   (__version__ = importlib.metadata.version("docs-cli"))
 │   ├── config        — TOML load, Vocab merging, archive-dir resolution,
 │   │                   `[migrate]` per-tree overrides (M7),
 │   │                   `[exclude]` + `.docsignore` (M8)
 │   ├── model         — Doc dataclass; metadata block parser + editors
 │   ├── walker        — directory traversal, filter, archive detection
 │   ├── index         — INDEX.md render with marker-block preservation
-│   ├── archive       — atomic move + lifecycle edit (M2; M7 rename)
+│   ├── archive       — atomic move + lifecycle edit (M2; M7 rename;
+│   │                   M12 referring-edge rewrite)
 │   ├── mv            — rename + Related: rewrite across tree (M2)
 │   ├── new           — scaffolded doc creation (M2)
-│   ├── touch         — Updated: bump (M2)
+│   ├── touch         — Updated: bump (M2; M12 outside-root refusal)
 │   ├── check         — validation rules + exit-code matrix (M3)
 │   ├── list          — query view, human + --json (M3)
 │   ├── migrate       — foreign-tree inference + plan/apply (M4)
+│   ├── project       — rename verb (M12)
 │   ├── install-skill — materialise the bundled skill onto a host (M6)
 │   └── cli           — argparse dispatch, exit codes, --root resolution
 └── skill/                               ─ bundled Claude Code skill (M5)
@@ -50,6 +52,13 @@ src/docs_cli/                            (Python 3.11+, stdlib only)
         └── docs-toml-template.toml       (M8 F8; bundle-only starter)
 ```
 
+> Pinned by `tests/test_packaging.py` A3 to the bumping-target literal;
+> runtime read goes through stdlib `importlib.metadata` so a single
+> `pyproject.toml` version bump propagates to `docs --version`
+> automatically (M12). Fallback to `0.0.0+local` (M12 — OQ-4) if
+> `importlib.metadata.PackageNotFoundError` is raised — protects
+> fresh-clone runs without `pip install -e .`.
+
 **Sibling artifact: the Claude Code skill.** The Claude Code skill at
 `src/docs_cli/skill/` (M5) is **not** a `cli.py` module and adds no
 Python — it is a standalone Markdown artifact that *drives* the verbs

{docs_cli-1.4.0/docs → docs_cli-1.5.0/docs/archive/2026-05-27}/m11-pypi-publish.md

@@ -1,9 +1,10 @@
 # M11 — PyPI publish 1.4.0
 
-Lifecycle: active
+Lifecycle: archived
 Role: milestone
 Project: docs
 Updated: 2026-05-27
+Archived-reason: Milestone M11 complete; docs-cli==1.4.0 shipped to PyPI 2026-05-27
 
 Related:
 - parent-of: m11-pypi-publish-impl.md
@@ -161,12 +162,28 @@ runbook's sections are the phases (mirrors M9 exactly):
       stderr 0 bytes / `.docs.toml` auto-emitted) passed against
       TestPyPI-served wheel. Temporary `pyproject.toml` rename
       reverted cleanly. Rehearsal whl sha256 `3693b9f7…`.
-- [ ] Real PyPI publish — `docs-cli==1.4.0` live; sha256
-      chain-of-custody from build → upload → PyPI-served wheel
-      verified bit-perfect
-- [ ] Post-release — `v1.4.0` tag + GitHub release; doc closeouts
-      (M10 + M11); token re-scope rolls forward as M9 open follow-on
-      (operator UI work, async)
+- [x] Real PyPI publish — `docs-cli==1.4.0` LIVE on PyPI at
+      `https://pypi.org/project/docs-cli/1.4.0/`. Fresh Phase 4
+      build under canonical `name = "docs-cli"`; both artefacts
+      twine-check PASS; upload PASS (PyPI token validated).
+      Chain-of-custody **bit-perfect** — PyPI-served whl sha256
+      `7af7eb5c…` byte-identical to local Phase 4 build.
+      Throwaway-venv install from PyPI succeeded; full smoke +
+      M10 headline contract (`migrate --apply --quiet` → exit 0
+      / stdout 0 bytes / stderr 0 bytes / `.docs.toml`
+      auto-emitted) PASS against PyPI-served wheel.
+- [x] Post-release — `m11/milestone-setup` ff-merged into `main`
+      and pushed (`8998747..b8d8af3`); annotated `v1.4.0` tag
+      (tag-object `4de329b9…` → commit `b8d8af3`) pushed to
+      `origin`; GitHub release live at
+      `https://github.com/ArtRichards/docs-cli/releases/tag/v1.4.0`;
+      release notes amended post-create to drop stale "deferred
+      to M11" wording; doc closeouts (plan/status/INDEX +
+      dogfood snapshot) landed; `docs archive --cascade` ran
+      (milestone doc archived, impl log stays
+      `Lifecycle: active` per M8/M9/M10 pattern, release-runbook
+      + status declined). Token re-scope rolls forward as M9
+      open follow-on.
 
 Each ticks as the runbook's corresponding section completes.
 
@@ -223,28 +240,34 @@ truly silent; `.docs.toml` auto-emitted; `docs check` exit 0).
 
 M11 is complete when:
 
-- [ ] `pip install docs-cli==1.4.0` works from PyPI on a clean
+- [x] `pip install docs-cli==1.4.0` works from PyPI on a clean
       host with Python 3.11+ and produces a working `docs` command.
-- [ ] `docs --version` from the PyPI-installed wheel prints
-      `docs 1.4.0`.
-- [ ] `docs migrate --apply --quiet <foreign-tree>` from the
+      (Phase 4: throwaway venv `/tmp/docs-real-venv` install
+      succeeded first attempt.)
+- [x] `docs --version` from the PyPI-installed wheel prints
+      `docs 1.4.0`. (Phase 4 smoke.)
+- [x] `docs migrate --apply --quiet <foreign-tree>` from the
       PyPI-installed wheel produces empty stdout + empty stderr
       (the headline M10 contract — re-verified against the
-      published artefact, not just the local build).
-- [ ] `docs install-skill` from the PyPI-installed wheel places a
+      published artefact, not just the local build). (Phase 4
+      against synthetic `/tmp/m11-pypi-foreign/`: exit 0 / stdout
+      0 bytes / stderr 0 bytes.)
+- [x] `docs install-skill` from the PyPI-installed wheel places a
       host-correct skill that drives the verbs identically to the
-      in-repo install.
-- [ ] The `v1.4.0` tag and GitHub release exist at
+      in-repo install. (Phase 4: fresh / no-op / `--symlink`-
+      rejected cycle all behaved correctly.)
+- [x] The `v1.4.0` tag and GitHub release exist at
       `https://github.com/ArtRichards/docs-cli/releases/tag/v1.4.0`.
-- [ ] All Phase Checklist items above are ticked.
-- [ ] `docs/status.md` reflects M10 + M11 as Complete with the
-      actual publish date.
-- [ ] `docs/m11-pypi-publish-impl.md` carries a
-      milestone-completion summary describing what actually
-      happened (which `1.4.x` shipped — if TestPyPI surfaced a
-      bug forcing a `1.4.1` rebuild, the published version, the
-      sha256 of the published wheel + sdist, the publish
-      timestamp, any deviations from the runbook).
+- [x] All Phase Checklist items above are ticked.
+- [x] `docs/status.md` reflects M10 + M11 as Complete with the
+      actual publish date 2026-05-27.
+- [x] `docs/m11-pypi-publish-impl.md` carries a
+      milestone-completion summary with the published version
+      (`1.4.0` — no TestPyPI-surfaced regression forced a
+      `1.4.x` bump), wheel + sdist sha256, publish timestamp, and
+      deviations (CHANGELOG amend at Phase 5; JSON metadata
+      cache lag at both registries; TestPyPI squatter detour
+      rolled forward).
 
 ## OPEN QUESTIONS
 
@@ -253,3 +276,58 @@ walk (TestPyPI ownership status; token re-scope status; any
 runbook-deviation needed for v1.4 specifically) will be recorded
 in the Milestone-completion summary as they surface, mirroring
 the M9 pattern._
+
+_At milestone close (2026-05-27): no plan-level open questions
+emerged. TestPyPI ownership status was re-confirmed
+(squatter unchanged; detour rolls forward). Token re-scope
+status was passively confirmed (M9-era tokens still drove M11
+unchanged; re-scope remains the M9 async follow-on). One
+runbook-deviation surfaced (CHANGELOG amend at Phase 5 to
+update the M10-authored "deferred" wording) — see the impl
+log's milestone-completion summary for the full deviation
+list, deduplicated for future-release reference._
+
+## Milestone-completion summary
+
+**Complete 2026-05-27.** `docs-cli==1.4.0` is live on PyPI at
+`https://pypi.org/project/docs-cli/1.4.0/`. Annotated tag
+`v1.4.0` at commit `b8d8af3` pushed to `origin`. GitHub release
+at `https://github.com/ArtRichards/docs-cli/releases/tag/v1.4.0`.
+
+| | sha256 |
+|---|---|
+| `docs_cli-1.4.0-py3-none-any.whl` | `7af7eb5cb67a860e16d34fb6e8084207e4d3abf2d81fb013fef3b1721c4ec050` |
+| `docs_cli-1.4.0.tar.gz` | `0b0dd2ce1302b59cc862549a0d55fadf7210e27cfcd2e38b5f5f9ad31350c05b` |
+
+Chain-of-custody bit-perfect: the PyPI-served wheel sha256
+matches the local Phase 4 build byte-for-byte (verified via
+`pip download --no-deps`). Headline M10 contract verified
+against the PyPI-served wheel: `docs migrate --apply --quiet`
+against a synthetic foreign tree produced exit 0 / stdout 0
+bytes / stderr 0 bytes / `.docs.toml` auto-emitted / adopted
+tree passes `docs check`.
+
+Deviations recorded for v1.5+ releases:
+
+1. **CHANGELOG amend at Phase 5.** The M10-authored 1.4.0
+   entry said "deferred to M11"; M11 Phase 5 amended to
+   "Published to PyPI 2026-05-27 via M11" and `gh release edit`
+   pushed the corrected text into the public release notes
+   (the PyPI-served sdist's CHANGELOG carries the original
+   wording — immutable).
+2. **JSON metadata cache lag at TestPyPI + PyPI.** Both
+   `/pypi/<pkg>/json` endpoints lagged the simple index by
+   60-120s post-upload. Don't gate post-upload verification
+   on JSON refresh — `pip install` is the authoritative signal.
+3. **TestPyPI squatter detour rolls forward.** Bare `docs-cli`
+   on TestPyPI still parked at `0.1.0` (no author). M11
+   continued M9's `docs-cli-rehearsal` rehearsal-name detour.
+4. **Repo visibility flip N/A.** Already public from M9.
+5. **Token re-scope rolls forward.** M9 follow-on; bootstrap
+   "Entire account" tokens drove M11 unchanged.
+
+The release-runbook.md remains the operative reference for
+v1.5+ — augmented in spirit by these five deviations
+(deviation 1 in particular suggests authoring future
+implementation-milestone CHANGELOG entries with wording
+that survives the eventual publish event unchanged).

{docs_cli-1.4.0/src/docs_cli/skill/references → docs_cli-1.5.0/docs}/cli.md

@@ -3,7 +3,7 @@
 Lifecycle: active
 Role: spec
 Project: docs
-Updated: 2026-05-27
+Updated: 2026-05-28
 
 Related:
 - pairs-with: convention.md
@@ -71,6 +71,22 @@ Atomically archive a doc.
 
 Atomicity: the metadata edit happens in a tmp file, fsync'd, renamed; the move happens only after the edit succeeds; the index regen runs last. A failure leaves the original file untouched.
 
+**Referring-edge rewrite (M12).** After the move, `docs archive`
+rewrites every `Related: <verb>: <old-rel>` bullet across the active
+tree to point at `archive/<YYYY-MM-DD>/<basename>`. Mirrors `docs mv`'s
+walker (`rewrite_related_refs`) — only the `Related:` field is
+considered; prose markdown references are deliberately left alone.
+Archive-subtree docs are read-only and are NOT updated. The rewrite
+is part of the same atomic batch as the move + lifecycle edit: a
+single end-of-batch INDEX refresh covers everything.
+
+`--cascade` (M12 — OQ-D) extends this — when the cascade archives
+related docs B, C, …, the referring-edge rewrites for every moved doc
+run as a single atomic batch with one INDEX refresh at the end.
+Per-doc cascade-archive failures still surface but only docs that
+actually moved get their referring edges rewritten. Cascade remains
+one-hop only (M2 decision unchanged).
+
 Exits 1 on metadata-edit failure; 2 on archive-dir creation failure.
 
 ### `docs mv <old> <new>`
@@ -171,6 +187,129 @@ resolve to different docs roots) is **undefined behaviour and out of
 M10 scope** — the validate-all-first pass refuses with exit 1 + an
 "outside the resolved docs root" message.
 
+**Outside-docs-root refusal (M12 — OQ-C).** If `--root` is not given
+and no `.docs.toml` exists in the cwd's ancestor chain, `docs touch`
+refuses with exit 2 + stderr message
+`docs: touch: <path> is not under a docs root with .docs.toml; refusing`.
+The file is left unchanged and no INDEX refresh runs (avoiding the M11
+cascade-crash where a downstream walk failed on the first non-managed
+sibling). An explicit `--root <dir>` bypasses the refusal **only when**
+`<dir>/.docs.toml` exists; if `--root` is set but its `.docs.toml` is
+missing, `touch` refuses with
+`docs: touch: --root <root> does not contain .docs.toml; refusing`
+(exit 2) (M12 — OQ-11).
+
+### `docs project rename <new-name>`
+
+Rename the docs root's project (M12). Rewrites `.docs.toml`'s
+`[project] name = "<old>"` to `name = "<new>"` **and** every
+conformant `Project: <old>` line in every active doc, atomically, with
+a single end-of-batch INDEX refresh.
+
+```
+docs project rename <new-name> [--dry-run] [--quiet] [--root DIR]
+```
+
+`<new-name>` is required. A missing positional triggers argparse's
+default exit 2.
+
+**Resolution.** Operates on the docs root resolved from cwd via the
+standard upward `.docs.toml` walk, unless `--root` overrides it
+(M12 — OQ-1). If the resolved root has no `.docs.toml`, exits 2 with
+stderr `docs: project rename: <cwd> is not under a docs root with .docs.toml; refusing`.
+
+**Auto-normalisation (M12 — OQ-A).** The operator-supplied `<new-name>`
+is run through M7's `normalise_project_name()` (the same machinery
+`docs migrate` already uses). When the normalised form differs from
+the input, stderr carries one line (gated on `not --quiet`):
+
+```
+docs: project rename: normalised "<input>" to "<normalised>"
+```
+
+before the rewrite proceeds with the normalised value. The current
+`.docs.toml` `[project] name` value is read **as written** for the
+no-op comparison — no double-normalisation (M12 — OQ-3).
+
+**Empty-name rejection (M12 — OQ-9).** If post-normalisation
+`<new-name>` is empty or whitespace-only, refuses with exit 2 + stderr
+`docs: project rename: <input> normalises to empty string; project name must be non-empty`.
+
+**What gets rewritten** (success path):
+
+- `.docs.toml`'s `[project] name = "<old>"` line → `name = "<new>"`.
+- Every conformant `Project: <old>` line in every **active-tree** doc
+  → `Project: <new>`.
+- Docs that have no explicit `Project:` line implicitly resolve to the
+  docs-root project; on rename, a `Project: <new>` line is inserted
+  into those docs (consistent with M2's `set_metadata_field` behaviour
+  for missing-field cases).
+- `INDEX.md` regenerated once at end of batch.
+
+**Multi-project tolerance (M12 — OQ-B).** A tree whose active docs
+carry mixed `Project:` values (the M7-tolerated multi-project shape)
+is walked completely: docs whose `Project:` matches `<old>` are
+rewritten; docs with a non-matching `Project:` are reported in the
+success footer but never mutated.
+
+**Archive-subtree skip.** Docs under the configured `archive_dir` are
+read-only by convention (M3); `project rename` skips them and reports
+the count in the footer.
+
+**Atomic semantics.** Validate-all-first: parse every active doc,
+build the rewrite tuple + the sidecar plan; if any step in
+validate-and-prepare raises, exits 1 (or 2 for a malformed
+`.docs.toml`) with the offending path named on stderr and no on-disk
+mutation. After validation passes, every rewrite is committed via
+`atomic_write`, then `.docs.toml` is rewritten, then `INDEX.md` is
+refreshed exactly once.
+
+**`--dry-run`.** Prints one `docs: would rewrite Project: in <rel-path>`
+line per matching doc, plus
+`docs: would rewrite [project] name in .docs.toml: "<old>" -> "<new>"`,
+plus the footer. Exits 0; writes nothing.
+
+**No-op.** When the normalised `<new-name>` equals the sidecar's
+current `[project] name`, the verb is a no-op regardless of whether
+the active tree carries non-matching `Project:` docs (the rename has
+nothing to rewrite — non-matching docs hold a different project name
+and remain untouched). Prints (gated on `not --quiet`):
+
+```
+docs: project rename: <new> already current — no rewrites needed
+```
+
+to stderr; exits 0; no disk mutation; no INDEX refresh.
+
+**Success output (M12 — OQ-2).** A single human-readable stderr line
+(gated on `not --quiet`):
+
+```
+docs: project rename: <old> -> <new> (rewrote .docs.toml + <N> doc(s); <M> archived skipped; <K> non-matching project(s) untouched: <list>)
+```
+
+When `K == 0` **and** `M == 0`, the empty clauses are dropped to:
+
+```
+docs: project rename: <old> -> <new> (rewrote .docs.toml + <N> doc(s))
+```
+
+No `--json` mode in M12 (M12 — OQ-7).
+
+**What does NOT change.**
+
+- Prose markdown text mentioning the old name. Only the metadata
+  `Project:` field is rewritten — never `Related:` edges (which carry
+  no project signal) and never body prose. (Consistent with M2's
+  `docs mv` "Related: only, not prose" stance.)
+- Files outside the docs root.
+- Archive-subtree docs.
+
+**Exit codes.** 0 success / no-op / dry-run; 1 recoverable error
+(e.g. a doc with no editable metadata block); 2 hard error (malformed
+`.docs.toml`, no `.docs.toml` ancestor, empty post-normalised
+`<new-name>`).
+
 ### `docs install-skill [--dest DIR] [--copy|--symlink] [--force] [--quiet]`
 
 Materialise the bundled Claude Code skill onto the host.
@@ -524,4 +663,12 @@ total excluded count per top-level dir prefix
 | 1 | Recoverable error (file conflict, validation warning, missing input) |
 | 2 | Hard error (invalid vocab, atomic operation failure, validation errors) |
 
+M12-specific exit-code shape:
+
+| Verb | 0 | 1 | 2 |
+|---|---|---|---|
+| `project rename` | success / no-op / dry-run | doc lacks editable metadata block | malformed `.docs.toml`; no `.docs.toml` ancestor; empty post-normalised `<new-name>` |
+| `touch` (outside-root refusal) | — | — | no `.docs.toml` ancestor (cwd-resolved) or `--root` without `.docs.toml` |
+| `archive` (referring-edge) | success | referring doc has malformed metadata (move aborts) | archive-dir creation failure |
+
 CI integration: `docs check` returning 2 should fail the build.

{docs_cli-1.4.0 → docs_cli-1.5.0}/docs/convention.md

@@ -3,7 +3,7 @@
 Lifecycle: active
 Role: spec
 Project: docs
-Updated: 2026-05-27
+Updated: 2026-05-28
 
 Related:
 - pairs-with: cli.md
@@ -84,7 +84,7 @@ The block terminates at the first blank line whose next non-empty line is *not*
 
 | Field | Type | Meaning |
 |---|---|---|
-| `Project` | kebab-case slug | project this doc belongs to; defaults to `project.name` in `.docs.toml` if absent |
+| `Project` | kebab-case slug | project this doc belongs to; defaults to `project.name` in `.docs.toml` if absent. The CLI surface `docs project rename` rewrites this slug in lockstep across the sidecar and every doc that names it (M12). |
 | `Related` | list of `<verb>: <path>` | typed cross-references to other docs |
 | `Owner` | free-form | the human or team accountable for this doc |
 | `Tags` | comma-separated | free-form tags for filtering |