dctracker 1.5.0__tar.gz → 1.6.0__tar.gz

{dctracker-1.5.0 → dctracker-1.6.0}/MANIFEST.in

@@ -2,7 +2,10 @@
 # packaged asset must be grafted here as well as declared in package-data.
 graft dct/skills
 graft dct/hooks
-recursive-include dct/assets *.md
+graft dct/assets
 graft dct/web/templates
 graft dct/web/static
 global-exclude *.py[cod] .DS_Store
+graft dct/skill_sources
+include scripts/render_skills.py
+include docs/assistant-fallbacks.md

{dctracker-1.5.0 → dctracker-1.6.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: dctracker
-Version: 1.5.0
-Summary: Deterministic Context Tracker (dct) — cross-project tracking, changelog, and release tooling for Claude Code.
+Version: 1.6.0
+Summary: Deterministic Context Tracker (dct) — cross-project tracking, changelog, and release tooling for AI coding clients.
 Author-email: fotodeveloper <dev@fotodeveloper.com>
-License-Expression: MIT
+License-Expression: MIT AND 0BSD
 Project-URL: Homepage, https://dctools.dev
 Project-URL: Repository, https://github.com/fotodeveloper/dct
 Project-URL: Changelog, https://github.com/fotodeveloper/dct/blob/main/changelog.md
-Keywords: claude-code,mcp,tracking,changelog,sprints,developer-tools,cli
+Keywords: claude-code,codex,mcp,tracking,changelog,sprints,developer-tools,cli
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -19,26 +19,31 @@ Classifier: Topic :: Software Development
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: sqlalchemy>=2.0
-Requires-Dist: python-ulid>=2.0
-Requires-Dist: platformdirs>=4.9.6; sys_platform == "win32"
+License-File: dct/web/static/vendor/LICENSE.htmx.txt
+License-File: dct/web/static/vendor/LICENSE.uPlot.txt
+Requires-Dist: packaging>=26.3
+Requires-Dist: sqlalchemy>=2.0.52
+Requires-Dist: python-ulid>=4.0.1
+Requires-Dist: platformdirs>=4.11.8; sys_platform == "win32"
 Provides-Extra: pg
-Requires-Dist: psycopg[binary]; extra == "pg"
+Requires-Dist: psycopg[binary]>=3.3.5; extra == "pg"
 Provides-Extra: mcp
-Requires-Dist: mcp<3,>=2; extra == "mcp"
+Requires-Dist: mcp<3,>=2.2; extra == "mcp"
 Provides-Extra: web
-Requires-Dist: flask>=3.0; extra == "web"
-Requires-Dist: markdown>=3.5; extra == "web"
+Requires-Dist: flask>=3.1.3; extra == "web"
+Requires-Dist: markdown>=3.10.3; extra == "web"
 Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest>=9.1.1; extra == "dev"
+Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.8.0; extra == "dev"
 Provides-Extra: all
-Requires-Dist: psycopg[binary]; extra == "all"
-Requires-Dist: mcp<3,>=2; extra == "all"
-Requires-Dist: flask>=3.0; extra == "all"
-Requires-Dist: markdown>=3.5; extra == "all"
-Requires-Dist: pytest; extra == "all"
-Requires-Dist: pytest-cov; extra == "all"
+Requires-Dist: psycopg[binary]>=3.3.5; extra == "all"
+Requires-Dist: mcp<3,>=2.2; extra == "all"
+Requires-Dist: flask>=3.1.3; extra == "all"
+Requires-Dist: markdown>=3.10.3; extra == "all"
+Requires-Dist: pytest>=9.1.1; extra == "all"
+Requires-Dist: pytest-cov>=7.1.0; extra == "all"
+Requires-Dist: pytest-xdist>=3.8.0; extra == "all"
 Dynamic: license-file
 
 # dct — Deterministic Context Tracker
@@ -48,7 +53,9 @@ Dynamic: license-file
 [![CI](https://github.com/fotodeveloper/dct/actions/workflows/ci.yml/badge.svg)](https://github.com/fotodeveloper/dct/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/fotodeveloper/dct/blob/main/LICENSE)
 
-dct gives AI coding assistants persistent, queryable memory: project state read from a database instead of guessed. One database shared by all your projects tracks issues, todos, changelog entries, plans, sprints, decisions, and session handoffs. The MCP (Model Context Protocol) server and CLI work with any MCP-capable assistant (Cursor, Windsurf, Zed, and friends); [Claude Code](https://claude.com/claude-code) gets the deepest integration, with 13 slash-command skills and 4 automation hooks on top of the 55 MCP tools.
+dct makes your work state queryable: what is open, which checkpoints block completion, what was decided, and where the next session should resume. One user-scoped database connects issues, todos, changelog entries, plans, sprints, decisions, and session handoffs across your projects. Assistants and scripts retrieve that state through 76 MCP tools or the CLI instead of reconstructing it from a conversation.
+
+[Claude Code](https://claude.com/claude-code) has the established integration. DCT 1.6.0 packages both clients with 14 slash-command skills, 4 Claude automation hooks and experimental native Codex hooks; availability and limits differ by client. See the [capability matrix](https://github.com/fotodeveloper/dct/blob/main/docs/integrations.md#capability-matrix).
 
 Part of the **dc tools** family ([dctools.dev](https://dctools.dev)) — *deterministic context* for AI-assisted development.
 
@@ -56,19 +63,19 @@ Part of the **dc tools** family ([dctools.dev](https://dctools.dev)) — *determ
 
 You have a dozen side projects. Every AI coding session starts cold — the assistant has no memory of what you decided last week, which bug you were mid-fix on, or why you picked SQLite over Postgres. So you re-explain, or it guesses.
 
-The usual trackers don't fill the gap. Your assistant can drive GitHub Issues these days (`gh`, the official MCP server), but issues live per-repo on someone else's server, with no notion of a cross-project view, a sprint in flight, a session handoff, or a gate that keeps an item open until you've validated it — and Jira is heavier still. `TODO.md` files rot the moment you stop grooming them. Assistant memory files (CLAUDE.md, auto-memory) help, but they're prose: un-queryable, unstructured, and invisible to your other tools. dct is the structured half — typed items with priorities, state, and gates that any session, script, or MCP client can query.
+A conversation explains the work, but does not provide a reliable query for its current state. dct stores typed items, explicit checkpoint outcomes, sprint membership, decisions, and handoffs in a shared ledger. Markdown plans remain files; their indexed state links planning to execution. The next assistant can read the same records as your CLI or dashboard.
 
 dct is built for exactly this:
 
 - **One user-scoped database** across all your projects — one place to ask "what's open everywhere?" Local-first: SQLite by default, so your tracking data stays on your machine, with first-class PostgreSQL support when you want a server-grade backend.
 - **A full tracking model** — issues, todos, features, ideas, and improvements, each with priority, notes, and per-item checkpoints; gate checkpoints (dogfood, security, review, approval) keep an item open until they pass.
 - **Your markdown plans, indexed** — specs, roadmaps, and ADRs stay plain markdown files; dct anchors their sections and checkpoints in the database, so plan state is queryable and promotable to items and sprints.
-- **MCP-native** — the assistant reads and writes tracking directly: no copy-paste, no context loss.
+- **MCP-native** — the assistant queries and updates the tracking ledger through structured tools.
 - **Changelog-first releases** — entries accumulate as you work (your assistant writes them); release day is one command.
 - **Soft-delete ledger** — notes, checkpoints, and handoffs are removed from view at most; nothing is ever hard-deleted.
 - **Session handoffs** — end a session with a handoff prompt; the next one picks up where you left off.
 
-The day-to-day learning curve is your assistant's, not yours. There is no UI to master and no required syntax: after a one-time `dct init` you keep talking the way you already do — "track this", "I fixed it", "what's open?" — and the assistant does the bookkeeping. The slash commands below are optional shortcuts for the same moves, and every one of them is equally an MCP tool and a CLI command, so the whole workflow runs on any MCP client.
+With a configured client, you can ask your assistant to "track this", "record what changed", or "show the next checkpoint". Packaged skills explain when to use DCT and how to interpret the results. Their availability depends on the client; generic MCP integrations require you to supply equivalent workflow instructions.
 
 ## What a session looks like
 
@@ -82,7 +89,7 @@ Created issue #12 in myproj (P2, open)
 Changelog entry added (unreleased) — issue #12 resolved
 
 > /handoff
-Sprint set (1 item); handoff prompt stored for the next session
+Sprint preserved; handoff prompt stored for the next session
 
 # next morning, new session
 > /pickup
@@ -90,11 +97,13 @@ Handoff: "Frontmatter crash is fixed; release when CI is green."
 Proposed first action: /release
 ```
 
-No forms, no context switch. `/handoff` and `/pickup` are Claude Code slash commands; on any other MCP client the same moves are the `handoff_work` and `pickup_work` tools. The three loops behind this session — tracking, session, release — are described below.
+No forms, no context switch. Handoff and pickup workflows are packaged as skills for Claude Code and Codex; other MCP clients can use the `handoff_work` and `pickup_work` tools directly. The example uses Claude Code skills, including `/release`; Codex currently packages `clog`, `commit`, `dct-import`, `dct-init`, `handoff`, `pickup`, `plan-resolve-uncertain`, `plan-status`, `release`, `track`, `track-list`, `track-resolve`, `track-update`, `triage`. The tracking, session, and release workflows are described below.
 
 ## Installation
 
-Pick one — whichever matches your Python workflow. The distribution is named **`dctracker`** (PyPI); the installed command is **`dct`**. Prerequisites: Python 3.11+. Claude Code is needed only for the skills/hooks integration; the CLI and MCP server work with any MCP client.
+**Release availability:** DCT **1.6.0** includes the shared CLI/MCP surface, Claude Code and Codex integration installers, `dct integrate`, `dct doctor`, and packaged workflow skills for both clients. Native Codex hooks remain experimental and require the host capabilities and explicit trust described below.
+
+Pick one — whichever matches your Python workflow. The distribution is named **`dctracker`** (PyPI); the installed command is **`dct`**. Prerequisites: Python 3.11+. Client-specific skills and hooks require the corresponding host. The CLI and MCP server work independently of either client.
 
 ```bash
 # Option A: uv tool (recommended — isolated, upgradable)
@@ -103,7 +112,7 @@ uv tool install 'dctracker[mcp,pg]'
 # (skip it if you stay on the SQLite default), web = the local dashboard.
 
 # From source (dev):
-uv tool install --editable /path/to/dct --with 'mcp' --with 'psycopg[binary]'
+uv tool install --editable '/path/to/dct[mcp,pg]'
 # Or straight from GitHub, no clone (e.g. to try main before a release):
 uv tool install 'dctracker[mcp,pg] @ git+https://github.com/fotodeveloper/dct'
 
@@ -127,34 +136,67 @@ dct server --help
 dct plan --help  # plan subcommands
 ```
 
-### First run
+### First run with Claude Code
 
 ```bash
 dct init
 ```
 
-The interactive wizard walks through the one-time global bootstrap:
+The interactive wizard walks through the one-time global bootstrap. In DCT 1.6.0, `dct init` without a terminal refuses before setup effects; run it in a terminal, or use the explicit integration/project commands for automation:
 
 1. **Database backend** — `sqlite` (default, zero setup at the platform data dir, e.g. `~/.local/share/dctools/dct.db`) or `postgresql` (you supply the URL). It test-connects before saving.
-2. **Register projects** — for each project it asks slug / path / name, then **auto-detects the version** from `VERSION`, `pyproject.toml`, `package.json`, `Cargo.toml`, or `src-tauri/tauri.conf.json`. If none matches, you get an interactive prompt (`0.0.1` / `0.1.0` / `1.0.0` shortcuts); in non-tty contexts it stores `current_version=NULL` and reminds you to set it later. Register more any time with `dct project add`.
+2. **Register projects** — for each project it asks slug / path / name, then **auto-detects the version** from `VERSION`, `pyproject.toml`, `package.json`, `Cargo.toml`, or `src-tauri/tauri.conf.json`. If none matches, you get an interactive prompt (`0.0.1` / `0.1.0` / `1.0.0` shortcuts). Register more any time with `dct project add`; that separate command can run without a terminal, storing `current_version=NULL` when no version is detected and reminding you to set it later.
 3. **MCP server** — registered at **user scope** in `~/.claude.json` (via `claude mcp add --scope user`, with a direct-edit fallback), so `/track`, `/clog`, `/release`, and the MCP tools are available in **every** Claude Code session, from any directory.
 4. **Skills + hooks** — symlinks the skills into `~/.claude/skills/` and the four hooks into `~/.claude/hooks/`. Both ship inside the package; with an editable/dev install the symlinks point at the repo, so a fix goes live without reinstall.
 5. **Hook wiring** — with your consent, merges the hooks into `~/.claude/settings.json`. The merge is idempotent, backs up the file before the first write, and never touches hooks you already have. Re-run any time with `dct hooks wire`.
-6. **CLAUDE.md snippet** — with your consent, appends the packaged dct instructions to your personal `~/.claude/CLAUDE.md`. This is what makes plain phrases like "track this" reliable. The block is marker-managed and idempotent: re-runs refresh it, your own content is never touched, and the file is backed up before the first write. Decline and paste it later from [dct/assets/claude-md-snippet.md](https://github.com/fotodeveloper/dct/blob/main/dct/assets/claude-md-snippet.md).
+6. **dct reference + CLAUDE.md pointer** — installs the on-demand [dct reference](https://github.com/fotodeveloper/dct/blob/main/dct/assets/dct-reference.md) and offers a short managed pointer in your personal `~/.claude/CLAUDE.md`. DCT 1.6.0 places the shared reference in the platform config directory (`~/.config/dctools/dct-reference.md` on POSIX, honoring `XDG_CONFIG_HOME`) and preserves Claude's owned `~/.claude/dct-reference.md` compatibility alias. The pointer renders the actual resolved path. Re-runs preserve bytes outside its markers, and upgrades refresh only an existing block. An edited or foreign reference is preserved and reported before any pointer is rewritten. The reference is installed even when attaching the pointer is declined.
 
 The wizard closes with a reminder to **start a new Claude Code session** — skills, hooks, and MCP tools all load at session start. Steps 3–6 are the Claude Code integration; without Claude Code, use the wizard for steps 1–2 and register the server in your own client instead — next section.
 
 `dct init` writes the config to the platform config dir (`~/.config/dctools/dct.toml`; existing `~/.claude/dct.toml` installs keep working — `dct migrate-home` moves them), `~/.claude.json` (MCP entry), the skill/hook symlinks, and (opt-in) the settings.json wiring — see [docs/architecture.md](https://github.com/fotodeveloper/dct/blob/main/docs/architecture.md) for the full config reference and scope model.
 
-### Other MCP clients (Cursor, Windsurf, Zed)
+### Codex
 
-The 13 skills and 4 hooks are Claude Code integrations; everything else — the 55 MCP tools and the CLI — works from any MCP client. Register `dct server` as a stdio server in your client's MCP config, e.g. for Cursor (`~/.cursor/mcp.json`):
+Install DCT 1.6.0 or later, then configure the Codex integration:
+
+```bash
+uv tool install 'dctracker[mcp]>=1.6.0'
+dct integrate install codex
+dct doctor --client codex --json
+```
+
+Reconnect/start a fresh Codex session. The adapter installs MCP configuration,
+`clog`, `commit`, `dct-import`, `dct-init`, `handoff`, `pickup`, `plan-resolve-uncertain`, `plan-status`, `release`, `track`, `track-list`, `track-resolve`, `track-update`, `triage` skills, and managed `AGENTS.md`
+instructions. It preserves existing configuration and reports conflicting
+files. The 14 packaged workflows share complete contracts; their availability is separate from client/runtime acceptance evidence. `dct-init`, `dct-import` and `plan-resolve-uncertain` require explicit invocation. Both clients receive their complete workflow contracts from one authored source.
+
+Native hooks are **experimental**: changelog checks, stop reminders and
+apply-patch autoscan require the supported host events, runtime dependencies,
+and review/trust through `/hooks`. Plan mirroring additionally requires the
+client to expose and emit `update_plan`; it records observed snapshots rather
+than synchronizing task status. It is not available merely because the assistant
+describes a plan in chat. Current runtime validation targets the local POSIX client.
+See the [integration guide and capability matrix](https://github.com/fotodeveloper/dct/blob/main/docs/integrations.md)
+for repair, upgrade, uninstall, runtime diagnostics and limitations.
+
+Fresh Claude → Codex handoff and the installed pickup skill were exercised on
+an isolated database without passing the previous transcript. A controlled
+nine-session comparison measured median main-model input of 24,926 tokens for
+one DCT pickup tool versus 23,006 for exactly the same response bytes read from a
+file, an increase of approximately 8.35%. All trials returned the correct answer;
+cache behavior varied, and separate guardian work means these main-task figures
+are not complete billing totals. DCT's demonstrated benefit here is recovering
+structured work state, not token savings. See the [acceptance evidence](https://github.com/fotodeveloper/dct/blob/main/docs/codex-acceptance.md) and [controlled benchmark results](https://github.com/fotodeveloper/dct/blob/main/docs/benchmark-codex.md#controlled-results).
+
+### Other MCP clients: manual setup
+
+The 14 Claude Code skills, 4 Claude hooks and 14 Codex skills are host integrations. The 76 MCP tools and CLI provide the common tracking surface. Other clients use **generic MCP support with manual setup**; no client-specific skills, hook parity or acceptance test is implied. Register `dct server` as a stdio server using the configuration format required by your client. A common JSON shape is:
 
 ```json
 { "mcpServers": { "dct": { "command": "dct", "args": ["server"] } } }
 ```
 
-Then talk to your assistant as usual ("track this", "what's open?") — it drives the same tools. Slash-command equivalents: `/track` → `create_item`, `/track-list` → `list_items`, `/pickup` → `pickup_work`, `/handoff` → `handoff_work`, `/clog` → `add_changelog`, `/release` → `release_changelog`. To teach your assistant *when* to reach for them, adapt the [CLAUDE.md snippet](https://github.com/fotodeveloper/dct/blob/main/dct/assets/claude-md-snippet.md) to your client's rules file.
+Provide workflow instructions for your assistant to select and combine these tools. Relevant starting points: `/track` → `create_item`, `/track-list` → `list_items`, `/pickup` → `pickup_work`, `/handoff` → `handoff_work`, `/clog` → `add_changelog`, `/release` → the local `dct release` workflow (the ledger tools `release_changelog` / `advance_release` serve a project's own release tool). These tool mappings are not substitutes for complete commit/release workflows. To teach your assistant *when* to reach for them, adapt the [dct reference](https://github.com/fotodeveloper/dct/blob/main/dct/assets/dct-reference.md) for your client and point its rules file at it, as the [CLAUDE.md pointer](https://github.com/fotodeveloper/dct/blob/main/dct/assets/claude-md-snippet.md) does for Claude Code.
 
 ### Troubleshooting
 
@@ -200,14 +242,14 @@ when the database says so, not when the conversation has moved on.
 
 AI coding sessions end; your context shouldn't.
 
-**Ending a session — `/handoff`** flags the items you were working on as the
-current sprint and stores a short prompt for whoever comes next (usually
-you, tomorrow). **Starting a session — `/pickup`** reads the newest unconsumed
+**Ending a session — `/handoff`** stores a short prompt for whoever comes next
+(usually you, tomorrow). Sprint membership changes only when explicitly
+requested; otherwise it is preserved. **Starting a session — `/pickup`** reads the newest unconsumed
 handoff, shows the sprint with checkpoint progress, and proposes the first
 action, so the session starts in the middle of the work rather than from a
 cold "what were we doing?" The sprint is the durable set of what's in flight
-right now: it survives between sessions and cleans itself up — resolving an
-item drops it from the sprint automatically. Illustrative session start:
+right now: it survives between sessions. Resolving an item removes it from the open-work
+view while retaining its sprint membership as completion history. Illustrative session start:
 
 ```text
 > /pickup
@@ -221,7 +263,8 @@ Proposed first action: #12 — wire the theme toggle into settings.
 Handoffs live in the database: several can coexist per project
 (`scope` tags disambiguate parallel workstreams), consuming one preserves it
 in the ledger, and an unconsumed one can be amended in place. Available as
-skills in Claude Code, MCP tools, and the CLI — full catalogue in
+skills in Claude Code and the Codex integration, MCP tools, and
+the CLI — full catalogue in
 [docs/mcp-tools.md](https://github.com/fotodeveloper/dct/blob/main/docs/mcp-tools.md).
 
 ## The release loop: `/clog` → `/commit` → `/release`
@@ -237,13 +280,15 @@ changelog is already written:
 
 ```text
 > /release
-15 unreleased entries → stamped as 1.4.0
-changelog.md regenerated (Keep a Changelog format)
-release: v1.4.0 committed, project version bumped
+15 unreleased entries proven by commit trailers → plan approved as 1.4.0
+version files prepared (pyproject.toml) → approved, push target origin/main
+stamped · changelog.md section · version files · release: v1.4.0 · tag · pushed
 ```
 
-One command stamps the version, exports [Keep a Changelog](https://keepachangelog.com)
-markdown, and makes the release commit.
+One workflow plans the release from commit proof, shows the version files and
+the push target for approval, then stamps the version, writes the
+[Keep a Changelog](https://keepachangelog.com) section, makes the release
+commit and the tag and pushes them — each step verified and resumable.
 
 ## Plans: your markdown, indexed
 
@@ -252,8 +297,8 @@ them instead of replacing them: prose stays in the file (still the source of
 truth), while sections, checkpoints, and inline decisions get stable ULID
 anchors and live state (pending/done/rejected) in the database. In Claude
 Code a background hook re-scans the file on every edit; elsewhere, run
-`dct plan rescan <file>`. Uncertain section headings can be classified by an
-optional headless LLM call through your own `claude` CLI. A plan checkpoint
+`dct plan rescan <file>`. Local classification rules are the default and leave unknown headings
+unresolved; a configured command can optionally enrich them. A plan checkpoint
 can be promoted to a tracked item, a section to an item or a whole sprint —
 planning and tracking stay one system.
 
@@ -266,13 +311,13 @@ and promotion to items/sprints: **[docs/plans.md](https://github.com/fotodevelop
 - **Session handoffs** — end a session with a stored prompt; `/pickup` resumes the next one mid-work
 - **Hybrid changelog** — entries in DB, export to Keep a Changelog markdown at release; enforcement hook wired at init with your consent, then **on by default per project** (opt out via `dct project changelog <slug> off`) + **per-project changelog location** (repo root by default, or a subdir like `pkg/changelog.md`)
 - **Plans, specs, roadmaps, ADRs** — index markdown plans with stable ULID anchors; state in DB, content stays in markdown
-- **First-class sprints** — a named, goal-scoped *current work* set that survives across sessions and self-cleans as items resolve
+- **First-class sprints** — a named, goal-scoped *current work* set with persistent membership and completion history
 - **Decision records** — ADRs, sprint amendments, inline plan decisions with multi-anchor linkage
-- **LLM-assisted classification** — uncertain plan sections auto-resolved via `claude --print` (haiku by default; optional, uses your own `claude` CLI)
+- **Plan classification** — deterministic heading rules by default; optional configured-command enrichment
 - **Passive autoscan hook** — Claude Code PostToolUse hook re-scans plan-like files in background on every edit
-- **MCP server** — 55 tools over stdio via the official MCP SDK 2.0; works with any MCP client (Claude Code, Cursor, Windsurf, …)
+- **MCP server** — 76 tools over stdio via the official MCP SDK 2.x; client configuration and supported workflow features vary
 - **CLI** — fast `dct` command for hooks and scripts
-- **Skills** — Claude Code slash commands (`/track`, `/clog`, `/dct-import`, `/plan-status`, …)
+- **Skills** — Claude Code slash commands (`/track`, `/clog`, `/triage`, `/dct-import`, `/plan-status`, …); 14 Codex workflows
 - **Soft deletes** — ledger pattern, nothing is ever hard-deleted
 - **DB portable** — SQLite (zero setup) or PostgreSQL
 
@@ -301,9 +346,25 @@ dct tags merge test tests             # Fold "test" into "tests"
 dct clog add added "New Python parser support" --project myproj
 dct clog list --project myproj --unreleased
 dct clog count --project myproj       # Used by hooks
-dct clog release 1.1 --project myproj # Stamp unreleased → 1.1
+dct clog count --branch feat/x --include-unbranched   # This branch + unbranched/server-detected
+dct clog release 1.1 --project myproj --proposal-digest <p> --push-remote origin --push-branch main --push-url <url> --confirm  # Alias of `dct release apply` that derives the plan itself (after `dct release prepare`): commit, tag, push to the approved target (run from a checkout)
+dct clog release --patch --entries 12,15 --proposal-digest <p> --confirm --no-push   # Only these (proven) entries; a local release
+dct clog update 12 --branch feat/x    # Amend an unreleased entry
+dct clog delete 12                    # Soft-delete an unreleased entry
 dct clog export --project myproj --output changelog.md
 
+# Release workflow (each subcommand also takes --json)
+dct release plan --patch              # Read-only: proven / unproven entries, range, index state
+dct release attest --entries 16 --confirm             # Empty attestation commit for unproven entries
+dct release plan --patch --entries 12,15 --json       # The snapshot to approve (snapshot_digest)
+dct release prepare --patch --entries 12,15 --plan-digest <digest>         # Isolated version sync → the file list and the push target to approve
+dct release apply --patch --entries 12,15 --plan-digest <digest> --proposal-digest <p> --push-remote origin --push-branch main --push-url <url> --confirm  # Stamp, changelog, files, commit, tag, push to the approved target (or --no-push: local)
+dct release resume                    # Finish an interrupted release (verifies every effect; the stored consent, no new approval)
+dct release abandon --version 1.1 --reason "broken build" --confirm
+dct release reconstruct --version 1.0 --confirm       # Record a release made before release records
+dct release takeover --version 1.0 --no-push          # Preview: hand a record without consent to dct (then --takeover-digest <d> --confirm, resume)
+dct release version-files                             # Show the version-file contract (--set a,b | --none, --confirm)
+
 # Projects
 dct project add myproj /path/to/myproj --name "My Project"    # Version auto-detected
 dct project list
@@ -311,7 +372,7 @@ dct project detect                                            # Print current pr
 dct project rename myproj --slug myproj2 --name "Rebranded"   # Rename in-place, project_id stable
 dct project set-version myproj 1.1                            # Post-factum version fix
 dct project changelog myproj off      # Opt out of changelog enforcement (on by default)
-dct project changelog-path myproj docs/changelog.md           # Changelog outside repo root; default: changelog.md
+dct project changelog-path myproj docs/CHANGELOG.md           # Explicit Markdown changelog path (--detect: detect the tracked one again)
 
 # Plans
 dct plan rescan /path/to/docs/plans/2026-04-17-feature.md     # Idempotent rescan; hook entrypoint
@@ -344,7 +405,7 @@ dct config path                       # Show resolved config/data locations
 
 ## MCP Tools
 
-dct ships **55 MCP tools**. Zero-arg calls auto-detect the project from the session's working directory; pass `project=<slug>` to override. Write ops return a minimal ack (id + a few post-state fields); fetch full context with `get_item(id)` / `get_handoff(id)`. In Claude Code the tools register at user scope (callable as `mcp__dct__<name>`), with thirteen daily drivers always loaded and the rest fetched on demand; other MCP clients see the full flat catalogue. Whatever the client, start with `create_item`, `list_items`, `pickup_work`, and `handoff_work`:
+dct ships **76 MCP tools**. Zero-arg calls auto-detect the project from the session's working directory; pass `project=<slug>` to override. Write ops return a minimal ack (id + a few post-state fields); fetch full context with `get_item(id)` / `get_handoff(id)`. In Claude Code the tools register at user scope (callable as `mcp__dct__<name>`), with thirteen daily drivers always loaded and the rest fetched on demand; other clients control tool discovery and loading according to their own MCP implementation. Whatever the client, start with `create_item`, `list_items`, `pickup_work`, and `handoff_work`:
 
 | Tool | Purpose |
 |---|---|
@@ -379,7 +440,7 @@ If the preferred port (default `8787`) is busy, the daemon auto-selects the next
 
 ## Integration with Claude Code
 
-Claude Code is where dct runs deepest. `dct init` offers to attach the ready-made snippet that teaches your assistant *when* to reach for each skill and MCP tool (step 6 of the wizard); to add it manually, copy **[dct/assets/claude-md-snippet.md](https://github.com/fotodeveloper/dct/blob/main/dct/assets/claude-md-snippet.md)** into your personal `~/.claude/CLAUDE.md`.
+Claude Code has the established packaged integration. DCT 1.6.0 generates both clients' 14 skills, the full fallback and the concise reference from `dct/skill_sources`, with freshness checks in CI and package builds. `dct init` installs the shared reference and offers a short pointer in `~/.claude/CLAUDE.md`; the pointer names the actual resolved platform config path. Claude's owned legacy alias remains usable. Use the installer to render [the pointer template](https://github.com/fotodeveloper/dct/blob/main/dct/assets/claude-md-snippet.md); its `{{reference_path}}` slot is filled at installation. Both clients read the [reference](https://github.com/fotodeveloper/dct/blob/main/dct/assets/dct-reference.md) on demand, and per-client uninstall retains it for other clients. See [reference lifecycle details](https://github.com/fotodeveloper/dct/blob/main/docs/integrations.md#shared-reference-and-managed-pointers).
 
 ### Skills
 
@@ -391,13 +452,14 @@ Claude Code is where dct runs deepest. `dct init` offers to attach the ready-mad
 | `/track-resolve` | Resolve/close items |
 | `/clog` | Add changelog entry |
 | `/commit` | Conventional commit with version suffix + changelog gate |
-| `/release` | Stamp changelog + bump version + generate `changelog.md` |
+| `/release` | One workflow: proof plan → version files + push target approved → stamp, `changelog.md` section, version bump, commit, tag, push |
 | `/pickup` | Session start — read handoff, show sprint, propose first action |
 | `/handoff` | Session end — flag sprint items, write handoff prompt |
 | `/dct-import` | Discover + multi-select + ingest plan-like markdown files |
 | `/dct-init` | Bootstrap dct + register the current project (interactive) |
 | `/plan-status` | Cross-plan progress dashboard |
-| `/plan-resolve-uncertain` | Batch classify uncertain plan sections via haiku |
+| `/plan-resolve-uncertain` | Classify uncertain plan sections with configured rules/command or explicit manual choices |
+| `/triage` | Review findings through the triage ledger — record the consolidated findings, build and publish the page from the ledger, take an agent's proposals, close with the owner's answers |
 
 ## Global Hooks
 
@@ -422,7 +484,7 @@ dct reads its config from the platform config dir — `~/.config/dctools/dct.tom
 
 ```toml
 [database]
-url = "sqlite:////home/you/.local/share/dctools/dct.db"
+url = "sqlite:////path/to/dct.db"
 # or: url = "postgresql+psycopg://localhost:5432/dct"
 ```