taktcli 0.8.2__tar.gz → 0.8.4__tar.gz

{taktcli-0.8.2 → taktcli-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taktcli
-Version: 0.8.2
+Version: 0.8.4
 Summary: Authorized GraphQL CLI for Takt — full GraphQL surface from the shell, stdlib-only core
 Author: Takt
 License: MIT
@@ -230,6 +230,7 @@ Every MCP tool maps to a verb:
 | `create_wiki` | `wikis create` |
 | *(none — CLI-only; GraphQL `updateWiki` / `renameWiki`)* | `wikis update <slug>` |
 | *(none — CLI-only; GraphQL `wikiRenamePreview`)* | `wikis rename-preview <slug> --new-slug S` |
+| *(none — CLI-only; GraphQL `deleteWiki` / `wikiDeletePreview`)* | `wikis delete <slug> --yes` / `--dry-run` |
 | `get_project_wiki` | `wikis get <project>` |
 | `request_upload_url_and_headers` + `confirm_upload` | `file upload <path>` (composite) |
 | `get_file_url` | `file url <id>` |
@@ -254,7 +255,7 @@ Notes:
 - The `wiki` page verbs take `--wiki SLUG` (default `$TAKT_WIKI`)
   and stream big markdown through `--content-file` / `--old-file` / `--new-file`
   (`-` = stdin).
-- The wiki-container verbs are `wikis list/create/get/update` (entity = **Wiki**). The
+- The wiki-container verbs are `wikis list/create/get/update/rename-preview/delete` (entity = **Wiki**). The
   old `workspace list/create/get` verbs are a hard error naming the replacement
   for one release — *workspace* is being reclaimed to mean the tenant, and
   nothing else.
@@ -284,9 +285,10 @@ Successful metadata updates print `{"updateWiki":{"slug":…, "name":…,
 `--yes-rewrite-links`; omitting confirmation exits `3` before sending a request.
 Confirmation does not bypass the server's check that the caller is a human
 workspace OWNER (`FORBIDDEN` otherwise). The rename rewrites every `[[old/…]]`
-mention and app URL into the wiki (`https://takt.sh/wiki/old/…`,
-`/w/<workspace>/wiki/old/…`, relative `/wiki/old/…`) across the workspace's pages,
-tasks, comments, results and descriptions, in one transaction, and prints
+mention and app URL into the wiki (`https://app.takt.sh/wiki/old/…` and legacy
+`https://takt.sh/wiki/old/…` links, `/w/<workspace>/wiki/old/…`, relative
+`/wiki/old/…`) across the workspace's pages, tasks, comments, results and
+descriptions, in one transaction, and prints
 `{"renameWiki":{"wiki":{…},"report":{"oldSlug","newSlug","pages","tasks",
 "comments","results","links","unfixable"}}}`. `unfixable` lists what Takt cannot
 reach (env such as `WIKI_SLUG`/`TAKT_WIKI`, CLAUDE.md, skills, scripts,
@@ -297,6 +299,31 @@ fails, the metadata edit does not run.
 `rename-preview` runs `wikiRenamePreview` and prints the same report without
 writing anything. It is gated like the rename.
 
+### Delete a Wiki container
+
+```bash
+taktcli wikis delete knowledge --dry-run
+taktcli wikis delete knowledge --yes
+```
+
+Deleting is **permanent**: there is no trash and no undo. Without `--yes` the
+command exits `3` before sending a request; `--dry-run` runs `wikiDeletePreview`
+and prints the report without writing anything (with or without `--yes`). Both are
+gated like a slug rename: a human workspace OWNER (`FORBIDDEN` otherwise, agents
+included).
+
+`deleteWiki` removes the wiki, its pages, their embeddings and its search feedback in
+one transaction. Projects linked to it lose their wiki. Every `[[knowledge/…]]`
+mention elsewhere in the workspace (task titles and descriptions, comments, result
+labels and content, other wikis' pages, project/wiki/workspace descriptions)
+becomes plain text `knowledge/… (deleted)`. A token whose wiki allowlist named it
+loses that entry; a list left empty stays empty (confined to nothing). It prints
+`{"deleteWiki":{"slug","pages","projects","tasks","comments","results",
+"otherPages","links","unfixable"}}`: `pages` deleted, `projects` that lost their
+wiki, rows marked per surface, `links` marked, and `unfixable` (app URLs to the
+wiki, which now 404, and external config such as `WIKI_SLUG`/`TAKT_WIKI`, CLAUDE.md,
+skills and scripts).
+
 ## Output & exit codes
 
 Default output is pretty JSON of the unwrapped `.data` payload. `--compact` =

{taktcli-0.8.2 → taktcli-0.8.4}/README.md

@@ -214,6 +214,7 @@ Every MCP tool maps to a verb:
 | `create_wiki` | `wikis create` |
 | *(none — CLI-only; GraphQL `updateWiki` / `renameWiki`)* | `wikis update <slug>` |
 | *(none — CLI-only; GraphQL `wikiRenamePreview`)* | `wikis rename-preview <slug> --new-slug S` |
+| *(none — CLI-only; GraphQL `deleteWiki` / `wikiDeletePreview`)* | `wikis delete <slug> --yes` / `--dry-run` |
 | `get_project_wiki` | `wikis get <project>` |
 | `request_upload_url_and_headers` + `confirm_upload` | `file upload <path>` (composite) |
 | `get_file_url` | `file url <id>` |
@@ -238,7 +239,7 @@ Notes:
 - The `wiki` page verbs take `--wiki SLUG` (default `$TAKT_WIKI`)
   and stream big markdown through `--content-file` / `--old-file` / `--new-file`
   (`-` = stdin).
-- The wiki-container verbs are `wikis list/create/get/update` (entity = **Wiki**). The
+- The wiki-container verbs are `wikis list/create/get/update/rename-preview/delete` (entity = **Wiki**). The
   old `workspace list/create/get` verbs are a hard error naming the replacement
   for one release — *workspace* is being reclaimed to mean the tenant, and
   nothing else.
@@ -268,9 +269,10 @@ Successful metadata updates print `{"updateWiki":{"slug":…, "name":…,
 `--yes-rewrite-links`; omitting confirmation exits `3` before sending a request.
 Confirmation does not bypass the server's check that the caller is a human
 workspace OWNER (`FORBIDDEN` otherwise). The rename rewrites every `[[old/…]]`
-mention and app URL into the wiki (`https://takt.sh/wiki/old/…`,
-`/w/<workspace>/wiki/old/…`, relative `/wiki/old/…`) across the workspace's pages,
-tasks, comments, results and descriptions, in one transaction, and prints
+mention and app URL into the wiki (`https://app.takt.sh/wiki/old/…` and legacy
+`https://takt.sh/wiki/old/…` links, `/w/<workspace>/wiki/old/…`, relative
+`/wiki/old/…`) across the workspace's pages, tasks, comments, results and
+descriptions, in one transaction, and prints
 `{"renameWiki":{"wiki":{…},"report":{"oldSlug","newSlug","pages","tasks",
 "comments","results","links","unfixable"}}}`. `unfixable` lists what Takt cannot
 reach (env such as `WIKI_SLUG`/`TAKT_WIKI`, CLAUDE.md, skills, scripts,
@@ -281,6 +283,31 @@ fails, the metadata edit does not run.
 `rename-preview` runs `wikiRenamePreview` and prints the same report without
 writing anything. It is gated like the rename.
 
+### Delete a Wiki container
+
+```bash
+taktcli wikis delete knowledge --dry-run
+taktcli wikis delete knowledge --yes
+```
+
+Deleting is **permanent**: there is no trash and no undo. Without `--yes` the
+command exits `3` before sending a request; `--dry-run` runs `wikiDeletePreview`
+and prints the report without writing anything (with or without `--yes`). Both are
+gated like a slug rename: a human workspace OWNER (`FORBIDDEN` otherwise, agents
+included).
+
+`deleteWiki` removes the wiki, its pages, their embeddings and its search feedback in
+one transaction. Projects linked to it lose their wiki. Every `[[knowledge/…]]`
+mention elsewhere in the workspace (task titles and descriptions, comments, result
+labels and content, other wikis' pages, project/wiki/workspace descriptions)
+becomes plain text `knowledge/… (deleted)`. A token whose wiki allowlist named it
+loses that entry; a list left empty stays empty (confined to nothing). It prints
+`{"deleteWiki":{"slug","pages","projects","tasks","comments","results",
+"otherPages","links","unfixable"}}`: `pages` deleted, `projects` that lost their
+wiki, rows marked per surface, `links` marked, and `unfixable` (app URLs to the
+wiki, which now 404, and external config such as `WIKI_SLUG`/`TAKT_WIKI`, CLAUDE.md,
+skills and scripts).
+
 ## Output & exit codes
 
 Default output is pretty JSON of the unwrapped `.data` payload. `--compact` =

{taktcli-0.8.2 → taktcli-0.8.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "taktcli"
-version = "0.8.2"
+version = "0.8.4"
 description = "Authorized GraphQL CLI for Takt — full GraphQL surface from the shell, stdlib-only core"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -25,10 +25,14 @@ testpaths = ["tests"]
 
 [tool.setuptools.packages.find]
 include = ["taktcli*"]
+exclude = ["*.__pycache__"]
 
 [tool.setuptools.package-data]
 taktcli = ["skills/**/*"]
 
+[tool.setuptools.exclude-package-data]
+"*" = ["**/__pycache__/*", "*.py[cod]", "**/*.py[cod]"]
+
 [build-system]
 requires = ["setuptools>=75"]
 build-backend = "setuptools.build_meta"

{taktcli-0.8.2 → taktcli-0.8.4}/taktcli/commands/wikis.py

@@ -59,6 +59,19 @@ def register(subparsers) -> None:
     add_output_args(p)
     p.set_defaults(func=rename_preview)
 
+    p = verbs.add_parser(
+        "delete",
+        help="permanently delete a Wiki and its pages (workspace OWNER); marks refs to it as (deleted)",
+    )
+    p.add_argument("slug", help="Wiki slug (explicit; does not use TAKT_WIKI)")
+    p.add_argument("--yes", action="store_true", help="confirm the permanent delete")
+    p.add_argument(
+        "--dry-run", action="store_true",
+        help="print what the delete would remove and mark, without changing anything",
+    )
+    add_output_args(p)
+    p.set_defaults(func=delete)
+
     p = verbs.add_parser("get", help="get a project's Wiki")
     p.add_argument("project")
     add_output_args(p)
@@ -129,6 +142,25 @@ def rename_preview(args) -> int:
     return run_op(args, document, {"slug": args.slug, "newSlug": args.new_slug})
 
 
+DELETE_REPORT_FIELDS = "slug pages projects tasks comments results otherPages links unfixable"
+
+
+def delete(args) -> int:
+    """Permanently delete a Wiki via ``deleteWiki`` and print its report; ``--dry-run`` previews.
+
+    Refuses (exit 3) without ``--yes`` unless ``--dry-run``: there is no undo.
+    """
+    if args.dry_run:
+        document = f"query($slug:String!){{wikiDeletePreview(slug:$slug){{{DELETE_REPORT_FIELDS}}}}}"
+        return run_op(args, document, {"slug": args.slug})
+    if not args.yes:
+        raise ConfigError(
+            f"deleting wiki '{args.slug}' is permanent: pass --yes to confirm, or --dry-run to preview"
+        )
+    document = f"mutation($slug:String!){{deleteWiki(slug:$slug){{{DELETE_REPORT_FIELDS}}}}}"
+    return run_op(args, document, {"slug": args.slug})
+
+
 def get(args) -> int:
     document = (
         "query($slug:String!){"

{taktcli-0.8.2 → taktcli-0.8.4}/taktcli/skills/takt/SKILL.md

@@ -15,6 +15,29 @@ description: >
 
 Takt is a task board plus a wiki. `taktcli` is its CLI: argv in, GraphQL out, JSON on stdout.
 
+## Index
+
+Read a chapter with `sed -n 'A,Bp'` on this file. Long references have their own indexes.
+
+- [Quick start](#quick-start): lines 34–40. Check identity, choose a mode and read current state before acting.
+- [Modes](#modes): lines 41–53. Choose CLI lookup, wiki exploration or the worker loop and its detailed reference.
+- [Setup](#setup): lines 54–62. Resolve CLI version, credentials, project and wiki.
+- [Rules](#rules): lines 63–71. Check shell conventions, exit codes and task ownership before writes.
+- [Get a task done end to end](#get-a-task-done-end-to-end): lines 72–94. Start a task, attach results and hand it off for review.
+- [Track your progress in Takt](#track-your-progress-in-takt): lines 95–106. Record milestones, session pointers, outputs and follow-up work.
+- [Find what the wiki knows](#find-what-the-wiki-knows): lines 107–118. Choose literal, keyword or semantic search and read relevant sections.
+- [Write back what you learned](#write-back-what-you-learned): lines 119–129. Update, create, verify or flag wiki knowledge before review.
+- [Recover from an error](#recover-from-an-error): lines 130–143. Diagnose status, dependency, validation, CLI and transport failures.
+- [Don't use](#dont-use): lines 144–149. Replace deprecated task and wiki commands with supported verbs.
+- [Maintain this skill](#maintain-this-skill): lines 150–156. Recalculate indexes, validate the contract and locate the canonical source.
+
+## Quick start
+
+1. Check `taktcli --version` and `taktcli whoami`; resolve credentials, project and wiki with [Setup](#setup).
+2. Choose a [mode](#modes) and read its reference. Use each reference's index to fetch only the chapter you need.
+3. Read current state: `taktcli get <id>` for a task, `taktcli board --project <p>` for a board, or `taktcli wiki search "topic" --wiki <w>` for knowledge.
+4. Before changing a task, read the [rules](#rules). The worker loop is `run` → implement and verify → attach results → REVIEW; never take a DRAFT task.
+
 ## Modes
 
 | Invoke | Alias | Use it to | Read |
@@ -123,3 +146,11 @@ More: [cli.md](references/cli.md#errors).
 - `claim`, `release`, `--lease`: deprecated aliases. Use `run`, `stop`, nothing.
 - `workspace list|create|get`: use `wikis`.
 - `status <id> CANCELLED`: use `task transition <id> cancel`.
+
+## Maintain this skill
+
+Every agent-facing Markdown file over 100 physical lines needs a complete `## Index` within its first 100 lines. Index every body `##` chapter with an anchor, inclusive line range and reason to read it. Keep this entrypoint's complete quick start within the same budget. Short references can stay unindexed.
+
+After editing, run this skill's `scripts/markdown_index.py` with the existing Python interpreter, then repeat with `--check`. It updates ranges in existing entries; authors maintain chapter links and descriptions. Run `--check --quick-start SKILL.md` from the skill directory to check the entrypoint's quick-start budget. Explicit paths resolve from the caller's working directory; the helper's default scope is its own skill's `SKILL.md` and `references/`.
+
+For repo edits, the canonical source, repository links, tests and publication are covered in [plumbing.md](references/plumbing.md#maintaining-the-skill).

{taktcli-0.8.2 → taktcli-0.8.4}/taktcli/skills/takt/references/cli.md

@@ -2,14 +2,17 @@
 
 Look up a verb, a flag, an output shape or an error. The tables cover real usage; `taktcli <noun> <verb> --help` is the ground truth for the installed version.
 
-## Contents
-- Contract
-- Verbs
-- Quick reference
-- Ordering and paging
-- Errors
-- Verbs that don't exist
-- FAQ
+## Index
+
+Read a chapter with `sed -n 'A,Bp'` on this file.
+
+- [Contract](#contract): lines 17–30. Check installation, authentication, output, shell and identifier conventions.
+- [Verbs](#verbs): lines 31–44. Find the supported command groups and their verbs.
+- [Quick reference](#quick-reference): lines 45–73. Look up common task, wiki, file and administration commands.
+- [Ordering and paging](#ordering-and-paging): lines 74–87. Choose sorting, limits and offsets and interpret result envelopes.
+- [Errors](#errors): lines 88–103. Recover from GraphQL, transport and usage failures.
+- [Verbs that don't exist](#verbs-that-dont-exist): lines 104–118. Replace common invented commands and flags with supported forms.
+- [FAQ](#faq): lines 119–129. Resolve project and wiki selection, large text and command discovery questions.
 
 ## Contract
 
@@ -122,5 +125,5 @@ Don't use: `claim` / `release` / `--lease` (deprecated aliases of `run` / `stop`
 | search results are ordered by date | you passed `--order-by UPDATED_AT`, or you're on `wiki list`/`wiki grep`. Check `order` in the output. |
 | does `run` lock the task? | no. Whoever dispatches decides who works it; check before starting a RUNNING task. |
 | cancel a task? | `taktcli task transition <id> cancel` |
-| a wiki container vs a page? | `wikis …` acts on whole wikis; `wiki …` on pages. `wikis update <slug> --name N` renames a wiki's display name; `--new-slug S --yes-rewrite-links` changes its slug and rewrites every link to it (OWNER only, `wikis rename-preview` first). |
+| a wiki container vs a page? | `wikis …` acts on whole wikis; `wiki …` on pages. `wikis update <slug> --name N` renames a wiki's display name; `--new-slug S --yes-rewrite-links` changes its slug and rewrites every link to it (OWNER only, `wikis rename-preview` first). `wikis delete <slug> --yes` deletes it permanently and marks links to it `(deleted)` (OWNER only, `--dry-run` first). |
 | find mentions of a task | `wiki grep "web-42" --wiki <w>` (literal; never `--regex` on `[[…]]`) |

{taktcli-0.8.2 → taktcli-0.8.4}/taktcli/skills/takt/references/plumbing.md

@@ -1,14 +1,18 @@
 # Plumbing — auth, output, gql, files, admin
 
-## Contents
-- Auth
-- Output and exit codes
-- Output shapes
-- gql and schema
-- Files and media
-- Projects, labels, wikis
-- Defaults and versions
-- The bundled skill
+## Index
+
+Read a chapter with `sed -n 'A,Bp'` on this file.
+
+- [Auth](#auth): lines 17–43. Resolve credentials and endpoints, log in and handle refresh failures.
+- [Output and exit codes](#output-and-exit-codes): lines 44–50. Parse stdout and stderr and branch on the command's exit code.
+- [Output shapes](#output-shapes): lines 51–62. Find result fields for common queries, search and grep.
+- [gql and schema](#gql-and-schema): lines 63–78. Discover the schema and pass typed variables or large text to GraphQL.
+- [Files and media](#files-and-media): lines 79–91. Upload, download, attach and reference media files.
+- [Projects, labels, wikis](#projects-labels-wikis): lines 92–118. Manage project metadata, labels and owner-gated wiki rename or deletion.
+- [Defaults and versions](#defaults-and-versions): lines 119–123. Check default limits and which installed CLI version is running.
+- [The bundled skill](#the-bundled-skill): lines 124–139. Show or install packaged skills and understand overwrite protection.
+- [Maintaining the skill](#maintaining-the-skill): lines 140–156. Update source indexes, run checks and keep distributed copies accurate.
 
 ## Auth
 
@@ -102,12 +106,15 @@ taktcli wikis get <project-slug>
 taktcli wikis update <slug> --name N | --description TEXT | --description-file d.md
 taktcli wikis rename-preview <slug> --new-slug S
 taktcli wikis update <slug> --new-slug S --yes-rewrite-links [--name N …]
+taktcli wikis delete <slug> --dry-run
+taktcli wikis delete <slug> --yes
 ```
 
 - `wikis create` makes a wiki; `wiki create` makes a page.
 - `wikis update` needs an explicit slug and at least one field; omitted fields stay.
 - Renaming a slug needs a human workspace OWNER, so an agent token gets `FORBIDDEN`. `--new-slug S` also needs `--yes-rewrite-links`. The rename rewrites every `[[old/…]]` mention and app URL to the wiki (`/wiki/old/…`, `/w/<ws>/wiki/old/…`) in page titles, content and summaries, task titles and descriptions, comments, result labels and content, and project, wiki and workspace descriptions of the workspace. It prints `renameWiki.report`: `pages`, `tasks`, `comments` and `results` (rows changed), `links` (occurrences rewritten) and `unfixable` (what you must update by hand, such as `WIKI_SLUG`/`TAKT_WIKI` env, CLAUDE.md, skills, scripts and bookmarks). The old slug 404s, and there is no redirect.
 - `wikis rename-preview` returns the same report without writing anything. Run it first, and update the external config it lists after the rename.
+- `wikis delete` is **permanent** (no trash, no undo) and gated like a rename: a human workspace OWNER, so an agent token gets `FORBIDDEN`. It refuses without `--yes`; `--dry-run` prints the preview instead. The wiki's pages, their embeddings and its search feedback go with it; projects linked to it lose their wiki. Every `[[slug/…]]` mention elsewhere in the workspace (task titles and descriptions, comments, results, other wikis' pages, descriptions) becomes plain `slug/… (deleted)`. It prints the report: `pages` (deleted), `projects` (slugs that lost their wiki), `tasks`, `comments`, `results`, `otherPages` (rows marked), `links` (mentions marked) and `unfixable` (app URLs to the wiki, which now 404, and external config such as `WIKI_SLUG`/`TAKT_WIKI`, CLAUDE.md, skills and scripts). A token confined to that wiki keeps working only for what else it was confined to; confined to nothing, it reads nothing.
 
 ## Defaults and versions
 
@@ -129,3 +136,21 @@ taktcli skill install --aliases            # also takt-cli, explore-wiki, takt-w
 ```
 
 Install copies the files and writes `VERSION` (the version, then a `sha256  path` line per file). It refuses to replace a copy that was edited, has no `VERSION`, is a symlink, or comes from a newer taktcli; `--force` overrides. An identical copy is left alone (`"action": "unchanged"`).
+
+## Maintaining the skill
+
+The canonical source is `cli/taktcli/skills/`, shipped directly in the wheel. `.claude/skills/takt` links to the package's `takt` directory, and each repo alias's `SKILL.md` links to its package entrypoint. Edit the package sources on a task branch; there is no copy or sync step. The explore-wiki hook stays repo-only under `.claude/skills/explore-wiki/hooks/`. Use the project's existing Python interpreter; the bundled `scripts/markdown_index.py` needs only the standard library.
+
+From the repo root:
+
+```bash
+npm run skills:index
+npm run skills:check
+npm run test:cli
+```
+
+`skills:index` recalculates chapter ranges in the source entrypoint and references. Authors add or remove entries and write their descriptions; the helper only replaces numbers. A chapter starts at its `##` heading and ends before the next `##`, or at EOF. Fenced examples and frontmatter do not create chapters, but count toward physical line numbers.
+
+`skills:check` validates the canonical indexes without writing. The CLI tests enforce complete coverage, exact ranges, the early-index budget and the entrypoint's complete quick start by line 100. They also check repository links, parser regressions and the text returned by `skill show` and copied by `skill install`. These checks run in forge PR CI and the CLI release workflow.
+
+Recalculate after the final content edit, then check and test before publishing the task branch and PR. The wheel ships the updated skill on the next CLI release; a repo edit alone does not update an installed package or a separately registered platform copy. If publishing to another surface, validate the exact distributed Markdown: inserted headers or reflowed text invalidate its ranges.

{taktcli-0.8.2 → taktcli-0.8.4}/taktcli/skills/takt/references/tasks.md

@@ -1,15 +1,18 @@
 # Tasks — states, start/stop, pointers, results, deps, watch
 
-## Contents
-- Statuses and the two lanes
-- Pick from the board
-- Start, stop, hand back
-- Session pointers in meta
-- Finish in order
-- Results and comments
-- Dependencies and subtasks
-- Watch for events
-- Notifications
+## Index
+
+Read a chapter with `sed -n 'A,Bp'` on this file.
+
+- [Statuses and the two lanes](#statuses-and-the-two-lanes): lines 17–47. Choose legal status edges or lifecycle actions and check dependency gates.
+- [Pick from the board](#pick-from-the-board): lines 48–59. Find ready work and re-fetch a task before acting.
+- [Start, stop, hand back](#start-stop-hand-back): lines 60–70. Start or release work without locks, leases or ownership assumptions.
+- [Session pointers in meta](#session-pointers-in-meta): lines 71–96. Record a session under its tool and role without overwriting another worker.
+- [Finish in order](#finish-in-order): lines 97–111. Attach outputs before review and use DONE only within its authorized scope.
+- [Results and comments](#results-and-comments): lines 112–126. Read dependency outputs, attach results and post feedback.
+- [Dependencies and subtasks](#dependencies-and-subtasks): lines 127–141. Inspect or update dependencies and create or reparent subtasks.
+- [Watch for events](#watch-for-events): lines 142–154. Stream changes and handle reconnects and tasks already ready at startup.
+- [Notifications](#notifications): lines 155–162. Inspect unread notifications and mark them read.
 
 ## Statuses and the two lanes
 

{taktcli-0.8.2 → taktcli-0.8.4}/taktcli/skills/takt/references/wiki.md

@@ -1,13 +1,16 @@
 # Wiki — find, read, write, flag
 
-## Contents
-- Find the wiki
-- List pages
-- Search
-- Read
-- Write back
-- Flag what you can't fix
-- Conventions
+## Index
+
+Read a chapter with `sed -n 'A,Bp'` on this file.
+
+- [Find the wiki](#find-the-wiki): lines 15–27. Resolve the wiki slug from instructions, a project or the wiki list.
+- [List pages](#list-pages): lines 28–40. Filter pages by folder, labels, status or content and interpret the envelope.
+- [Search](#search): lines 41–56. Choose grep, keyword, semantic or related-task search and page through hits.
+- [Read](#read): lines 57–71. Fetch a page, heading or line slice and follow relevant mentions.
+- [Write back](#write-back): lines 72–87. Edit, create, move or retire knowledge using the appropriate verb.
+- [Flag what you can't fix](#flag-what-you-cant-fix): lines 88–107. Label knowledge problems and inspect search feedback.
+- [Conventions](#conventions): lines 108–116. Check page paths, index links, mentions, media and publication status.
 
 ## Find the wiki
 

{taktcli-0.8.2 → taktcli-0.8.4}/taktcli/skills/takt/references/worker.md

@@ -7,18 +7,21 @@ Pick or receive a task, groom it if needed, start it, do the work, attach result
 /takt worker <project>     work the project's READY tasks in priority order
 ```
 
-## Contents
-- 1. Resolve
-- 2. Pick a task
-- 3. Groom if vague
-- 4. Start and record a pointer
-- 5. Load context
-- 6. Implement and verify
-- 7. Finish: results, wiki, REVIEW
-- 8. Handle review feedback
-- 9. Hand back or fail
-- 10. Next task
-- Recover from an error
+## Index
+
+Read a chapter with `sed -n 'A,Bp'` on this file.
+
+- [1. Resolve](#1-resolve): lines 26–34. Resolve the task or project argument and its wiki.
+- [2. Pick a task](#2-pick-a-task): lines 35–54. Select eligible ready work without taking another worker's task.
+- [3. Groom if vague](#3-groom-if-vague): lines 55–66. Enrich unclear work or split it before starting implementation.
+- [4. Start and record a pointer](#4-start-and-record-a-pointer): lines 67–86. Re-fetch, start and record an orchestrator-provided session pointer.
+- [5. Load context](#5-load-context): lines 87–98. Read task feedback, dependencies and relevant wiki knowledge.
+- [6. Implement and verify](#6-implement-and-verify): lines 99–112. Isolate the branch, verify scope and tests and publish its PR.
+- [7. Finish: results, wiki, REVIEW](#7-finish-results-wiki-review): lines 113–128. Attach outputs and write back knowledge before the review hand-off.
+- [8. Handle review feedback](#8-handle-review-feedback): lines 129–140. Verify findings, publish fixes and respect merge authority.
+- [9. Hand back or fail](#9-hand-back-or-fail): lines 141–150. Explain blockers, release work or mark it failed.
+- [10. Next task](#10-next-task): lines 151–158. Refresh the board and sequence dependent tasks within the authorized scope.
+- [Recover from an error](#recover-from-an-error): lines 159–169. Handle lifecycle, dependency, test and context failures.
 
 ## 1. Resolve
 
@@ -105,7 +108,7 @@ Then read the tasks and `[[wiki/path]]` pages the description mentions, and run
 | frontend | if the project ships design guidance and a design skill, use them for the visual work, then finish wiring and tests yourself |
 | progress | `taktcli task comment <id> --body-file note.md` at milestones and decisions |
 
-Commit in small steps, push, open a PR (body via a file).
+Verify the repo, assigned task branch, remote, PR base and staged diff. Commit in small steps and push the task branch. Update the existing PR for that head/base, or open one (body via a file). Follow an explicit draft, stacked-base, branch-only or no-PR override.
 
 ## 7. Finish: results, wiki, REVIEW
 
@@ -151,7 +154,7 @@ Feedback arrives as PR comments, task comments, or the task returning to READY.
 2. Low on context → finish the current task cleanly (commit, REVIEW), report, suggest a fresh session.
 3. Otherwise back to step 2, preferring related tasks.
 
-Several related tasks with one PR each (an epic's subtasks): finish one through REVIEW and merge before starting the next, rebased on the merged result. One PR per task keeps reviews small; bundle only mechanically identical changes. Load shared context once for the whole run.
+Several related tasks with one PR each (an epic's subtasks): finish one through REVIEW, then wait for an authorized merge before starting a dependent task, or stack the next PR on the specified branch if instructed. One PR per task keeps reviews small; bundle only mechanically identical changes. Load shared context once for the whole run.
 
 ## Recover from an error
 

taktcli-0.8.4/taktcli/skills/takt/scripts/markdown_index.py

@@ -0,0 +1,148 @@
+import argparse
+import re
+import sys
+from pathlib import Path
+
+
+HEAD_LINES = 100
+ROOT = Path(__file__).resolve().parents[1]
+HEADING = re.compile(r'^ {0,3}(#{1,6})\s+(.+?)\s*#*\s*$')
+FENCE = re.compile(r'^ {0,3}(`{3,}|~{3,})(.*)$')
+ENTRY = re.compile(r'^- \[(?P<label>[^\]]+)\]\(#(?P<anchor>[^)]+)\): lines (?P<start>\d+)[–-](?P<end>\d+)\. (?P<summary>\S.*)$')
+
+
+def headings(lines):
+    result = []
+    used = set()
+    fence = None
+    frontmatter = bool(lines and lines[0].strip() == '---')
+    for number, raw in enumerate(lines, 1):
+        line = raw.rstrip('\r\n')
+        if frontmatter:
+            if number > 1 and line.strip() in ('---', '...'):
+                frontmatter = False
+            continue
+        marker = FENCE.match(line)
+        if marker:
+            token, suffix = marker.groups()
+            if fence is None:
+                fence = token
+            elif token[0] == fence[0] and len(token) >= len(fence) and not suffix.strip():
+                fence = None
+            continue
+        match = HEADING.match(line)
+        if fence or not match:
+            continue
+        level, title = len(match[1]), match[2]
+        visible = re.sub(r'!?\[([^\]]+)\]\([^)]*\)', r'\1', title)
+        base = re.sub(r'\s', '-', re.sub(r'[^\w\s-]', '', visible.lower()))
+        slug = base
+        suffix = 0
+        while slug in used:
+            suffix += 1
+            slug = f'{base}-{suffix}'
+        used.add(slug)
+        result.append((number, level, title, slug))
+    return result
+
+
+def structure(text):
+    lines = text.splitlines(keepends=True)
+    chapters = [heading for heading in headings(lines) if heading[1] == 2]
+    indexes = [heading for heading in chapters if heading[2] == 'Index']
+    sections = {}
+    for position, (start, _, title, slug) in enumerate(chapters):
+        if title == 'Index':
+            continue
+        end = chapters[position + 1][0] - 1 if position + 1 < len(chapters) else len(lines)
+        sections[slug] = (title, start, end)
+    entries = []
+    if len(indexes) == 1:
+        start = indexes[0][0]
+        end = next((heading[0] - 1 for heading in chapters if heading[0] > start), len(lines))
+        entries = [(number, ENTRY.fullmatch(lines[number - 1].rstrip('\r\n')))
+                   for number in range(start + 1, end + 1)
+                   if lines[number - 1].startswith('- ')]
+    return lines, chapters, indexes, sections, entries
+
+
+def document_errors(text, *, check_ranges=True, quick_start=False):
+    lines, chapters, indexes, sections, entries = structure(text)
+    if len(lines) <= HEAD_LINES and not indexes:
+        return ['An indexed ## Quick start is required.'] if quick_start else []
+    if len(indexes) != 1:
+        return ['Expected exactly one ## Index for a document longer than 100 lines.']
+    errors = []
+    if not sections:
+        errors.append('Add meaningful ## chapters for the index to address.')
+    if chapters[0] != indexes[0]:
+        errors.append('Place ## Index before the first body chapter.')
+    if not entries or any(match is None for _, match in entries):
+        return errors + ['Use - [Chapter](#anchor): lines A–B. When to read it. for every entry.']
+    index_end = next((heading[0] - 1 for heading in chapters if heading[0] > indexes[0][0]), len(lines))
+    if index_end > HEAD_LINES:
+        errors.append('The complete index must fit within the first 100 lines.')
+    anchors = [match['anchor'] for _, match in entries]
+    if len(anchors) != len(set(anchors)):
+        errors.append('A chapter appears more than once in the index.')
+    missing = sections.keys() - set(anchors)
+    unknown = set(anchors) - sections.keys()
+    if missing:
+        errors.append(f'Unindexed chapters: {", ".join(sorted(missing))}.')
+    if unknown:
+        errors.append(f'Unknown chapter anchors: {", ".join(sorted(unknown))}.')
+    if check_ranges:
+        for _, match in entries:
+            if match['anchor'] in sections:
+                title, start, end = sections[match['anchor']]
+                if (int(match['start']), int(match['end'])) != (start, end):
+                    errors.append(f'{title}: expected lines {start}–{end}; run markdown_index.py.')
+    if quick_start and ('quick-start' not in sections or sections['quick-start'][2] > HEAD_LINES):
+        errors.append('The complete ## Quick start must fit within the first 100 lines.')
+    return errors
+
+
+def reindex(text):
+    errors = document_errors(text, check_ranges=False)
+    if errors:
+        raise ValueError('\n'.join(errors))
+    lines, _, _, sections, entries = structure(text)
+    for number, match in entries:
+        _, start, end = sections[match['anchor']]
+        line = lines[number - 1]
+        lines[number - 1] = line[:match.start('start')] + f'{start}–{end}' + line[match.end('end'):]
+    return ''.join(lines)
+
+
+def documents(paths):
+    return sorted({file for path in paths for file in (path.rglob('*.md') if path.is_dir() else [path])})
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Recalculate or check early chapter indexes in Markdown files over 100 lines.')
+    parser.add_argument('paths', nargs='*', type=Path, help='Files or directories; default: this skill and its references.')
+    parser.add_argument('--check', action='store_true', help='Report missing indexes and stale ranges without writing files.')
+    parser.add_argument('--quick-start', action='store_true', help='Also require an indexed Quick start ending by line 100.')
+    args = parser.parse_args()
+    failures = []
+    files = documents(args.paths or [ROOT / 'SKILL.md', ROOT / 'references'])
+    for path in files:
+        with path.open(encoding='utf-8', newline='') as source:
+            text = source.read()
+        errors = document_errors(text, check_ranges=args.check, quick_start=args.quick_start)
+        failures.extend(f'{path}: {error}' for error in errors)
+        if not args.check and not errors:
+            updated = reindex(text)
+            if updated != text:
+                with path.open('w', encoding='utf-8', newline='') as target:
+                    target.write(updated)
+                print(f'Updated {path}')
+    if failures:
+        print('\n'.join(failures), file=sys.stderr)
+        return 1
+    print(f'{"Checked" if args.check else "Indexed"} {len(files)} Markdown files.')
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())