@anyforge/mcp-server 3.6.0 → 3.9.0

package/README.md

@@ -13,6 +13,12 @@ Firebase login.
 > (`apps/www/content/docs/mcp-server.md`). This README is the in-repo
 > developer reference; the docs page is the canonical install walkthrough.
 
+> **No key needed for OAuth-capable clients.** This package needs an
+> `sk_anyforge_…` key. Claude (via the AnyForge listing in its connectors
+> directory), Claude Code, VS Code, Cursor and any other client that supports
+> MCP authorization can instead connect to the hosted endpoint
+> `https://crew.anyforge.ai/api/mcp` and sign in with OAuth.
+
 ## Platform guide for connected agents
 
 The server advertises a static `anyforge-platform` guide without tenant data or
@@ -72,8 +78,77 @@ Use the equivalent stdio MCP config (`command: npx`, `args: ["tsx",
 
 ## Tools
 
+Code Studio tools require `@anyforge/mcp-server` **3.8.0 or later** and a
+deployed Studio API. For stdio clients use `npx -y @anyforge/mcp-server@^3.8.0`
+after its npm release, then restart the client to refresh its tool catalogue.
+Hosted HTTP follows the application deployment and does not depend on the
+installed stdio package version.
+
+Code Studio tools require explicit `studio:read`, `studio:write`,
+`studio:execute`, or `studio:publish` scopes; ordinary and legacy keys do not
+inherit them. Owners and operators can request these scopes, and editors can
+request them only when their company owner enables developer Studio access.
+External coding runs use audited coding, reads and reviews. Hosted commands and
+orchestration require browser Studio; crew launches and PR ready/merge require
+confirmation there. See the portable `references/code-studio.md` guide for the
+complete capability and local/remote workspace boundary.
+
 | Tool | Scope | Description |
 |------|-------|-------------|
+| `anyforge_branch_studio_session` | studio:write | Fork a session with explicit conversation/files/both scope. File scope also requires studio:execute and checkpoints; rewind requires exact workspace revisions. Does not undo external GitHub actions. For branch, reuse the same idempotencyKey when retrying; inspect incomplete preparation before retrying. |
+| `anyforge_rewind_studio_session` | studio:write | Rewind a session with explicit conversation/files/both scope. File scope also requires studio:execute and checkpoints; rewind requires exact workspace revisions. Does not undo external GitHub actions. For branch, reuse the same idempotencyKey when retrying; inspect incomplete preparation before retrying. |
+| `anyforge_update_studio_review_finding` | studio:write | Record a finding disposition with rationale and the revision containing a claimed fix. A fixed status does not imply independent verification; request a linked re-review to verify. |
+| `anyforge_get_studio_pr_comments` | studio:read | Read paged inline PR review comments and reviewed file/line/commit provenance. |
+| `anyforge_get_studio_pr_jobs` | studio:read | Read CI job identifiers for the exact PR head and a workflow run from its checks. Follow nextPage before claiming complete evidence. |
+| `anyforge_get_studio_pr_logs` | studio:read | Read a bounded CI log page only for a job belonging to this exact PR head. Preserve nextOffset to continue. |
+| `anyforge_request_studio_review` | studio:execute | Enqueue a durable, budgeted specialist review of an exact checkpoint, branch or PR. Returns a run ID; inspect its events and structured review artifacts. Reviewers cannot publish changes. |
+| `anyforge_list_studio_crew_batches` | studio:read | Read the session crew batches and unexpired proposals, including aggregate progress and limits. |
+| `anyforge_get_studio_crew_batch` | studio:read | Read one owned Studio crew batch. Active crews remain governed by their own gates. |
+| `anyforge_preview_studio_crew_batch` | studio:write | Persist a proposal for existing/new work items, planned or expedited crews, dependencies and aggregate limits. Starts nothing. Also requires studio:publish because orchestration can reach external systems. Open Code Studio to confirm the returned proposal; API/MCP arguments cannot attest human confirmation. |
+| `anyforge_cancel_studio_crew_batch` | studio:execute | Cancel queued starts; already active crews require separate stop actions. Also requires studio:publish. |
+| `anyforge_retry_studio_crew_batch` | studio:execute | Create a new proposal for failed/cancelled work; open Code Studio to confirm execution. This action never starts crews. Also requires studio:publish. |
+| `anyforge_list_studio_sessions` | studio:read | List your owned remote Code Studio sessions and their active/latest run IDs. |
+| `anyforge_create_studio_session` | studio:write | Prepare a direct coding session or attach it to an existing initiative. Does not start execution. Context is a reference; local edits are not uploaded to the remote checkout. additionalRepos needs an explicit repoFullName. |
+| `anyforge_get_studio_usage` | studio:read | Read the owned session recorded billing subtotal from the newest 200 rows, grouped by model/product/run/leg. Preserve `truncated`, `coverage` and `pending`; historical coverage may be incomplete or unavailable, so this is not a complete session bill. Provider cost and platform fee remain separate fields. |
+| `anyforge_get_studio_session` | studio:read | Read one owned Studio session and its reconnect IDs. |
+| `anyforge_update_studio_session` | studio:write | Update a session title, repository, branch, additional repositories or initiative. Does not execute code. additionalRepos replaces the whole list; null or [] clears it. |
+| `anyforge_get_studio_context` | studio:read | Inspect effective context provenance, instructions, skills, graph/document snapshots and MCP availability. Does not expose credentials. |
+| `anyforge_add_studio_context` | studio:write | Attach a bounded context snapshot to a prepared prompt. No code execution; explicitly identify local versus remote provenance. |
+| `anyforge_list_studio_runs` | studio:read | List durable runs for your session. |
+| `anyforge_start_studio_run` | studio:execute | Start a durable coding run in the remote workspace. Can spend tokens and edit files. External runs are limited to audited coding, reads and reviews; hosted shell, browser, outbound connectors, Oracle and crew/workflow/approval actions require the browser Studio surface. Use planned=true for analysis only. Dedicated Git push and draft PR tools need studio:publish; ready/merge require confirmation in Code Studio. |
+| `anyforge_get_studio_run` | studio:read | Read run status, usage and any pending user question. |
+| `anyforge_get_studio_run_events` | studio:read | Read ordered durable run events after a sequence cursor. Persist nextCursor to reconnect without replaying earlier events. |
+| `anyforge_control_studio_run` | studio:execute | Pause, cancel, resume, steer or answer a pending question. Answer requires its current questionId. Resuming may execute code and spend tokens. |
+| `anyforge_get_studio_changes` | studio:read | Read remote workspace revision, Git state and changes. Does not create a workspace or install dependencies. |
+| `anyforge_list_studio_artifacts` | studio:read | Read checkpoint and structured reviewer artifacts for this session. |
+| `anyforge_get_studio_review` | studio:read | Read structured reviewer findings, dispositions and review target provenance. |
+| `anyforge_create_studio_checkpoint` | studio:execute | Capture remote workspace files, including staged and untracked changes, as a persistent checkpoint. |
+| `anyforge_get_studio_checkpoint` | studio:read | Read checkpoint metadata and exact revision. |
+| `anyforge_diff_studio_checkpoint` | studio:read | Read the remote workspace diff for a saved checkpoint. |
+| `anyforge_read_studio_checkpoint_file` | studio:read | Read a bounded file window from a persistent checkpoint. |
+| `anyforge_restore_studio_checkpoint` | studio:execute | Restore a checkpoint into the remote workspace after comparing its current revision. Saves a safety checkpoint first; does not rewind external GitHub actions. |
+| `anyforge_stage_studio_files` | studio:execute | Stage explicitly selected remote files after checking the current revision. |
+| `anyforge_commit_studio_files` | studio:execute | Commit reviewed remote changes. Read changes and confirm file scope before committing; does not push. |
+| `anyforge_push_studio_branch` | studio:publish | Publish the exact remote Git HEAD to its branch. Rejects changed HEAD and default-branch pushes. |
+| `anyforge_get_studio_pull_request` | studio:read | Read a session repository pull request, checks, review decision and merge blockers. |
+| `anyforge_create_studio_pull_request` | studio:publish | Create or reuse a draft PR for the persisted session branch after checking its exact pushed HEAD. Uses your connected GitHub identity. Does not mark ready or merge. |
+| `anyforge_update_studio_pull_request` | studio:publish | Update metadata or mark a session branch PR as draft using its exact expectedHeadSha. Open Code Studio to review and confirm ready/merge; tool arguments cannot authorize those actions. |
+| `anyforge_search_studio_sessions` | studio:read | Search your own Studio sessions by title, repository, branch or folder, newest first. Set conversations=true (q of 2+ characters) to also search message text, five sessions per page. Follow nextCursor; conversationsLimited means a session had more messages than were searched. |
+| `anyforge_archive_studio_sessions` | studio:write | Archive all of your own unarchived Studio sessions (CI auto-fix monitors excluded). Transcripts are kept and each session can be unarchived with update_studio_session. Call again while remaining is true. |
+| `anyforge_list_studio_decisions` | studio:read | List your Studio runs waiting on you: each owned session whose current run asked a question, with the question and its options. Answer with control_studio_run. |
+| `anyforge_list_studio_models` | studio:read | List the models your company and personal credentials can run, grouped by provider, for the model argument of start_studio_run. A provider with ok=false is not configured or not reachable. Cached for 30 minutes unless refresh=true. |
+| `anyforge_get_studio_quota` | studio:read | Read the remaining quota of the Anthropic subscription Studio runs on for you. oauth=false means runs use an API key, which has no subscription window. |
+| `anyforge_get_studio_conversation` | studio:read | Read an owned session's conversation, oldest first: your messages, the agent's replies and, with includeTools=true, each round's tool calls and results. Long text is clipped and flagged truncated. A page can hold fewer than limit messages; follow nextCursor until it is null. |
+| `anyforge_list_studio_tasks` | studio:read | Read the session's task list (the agent's to-do items), newest change first. |
+| `anyforge_compact_studio_session` | studio:execute | Compact the session's stored history: older messages are replaced by one summary so the next run starts lean. Deletes the summarized messages and cannot be undone. Spends a small model call on your credential. Refused while a run is active. |
+| `anyforge_list_studio_verifications` | studio:read | Read the session's verification reports (newest 20): diagnostics, tests, lint, typecheck, build and acceptance checks with their evidence and the exact source they ran against. Running a new verification requires the browser Studio surface. |
+| `anyforge_get_studio_environment` | studio:read | Inspect the existing remote checkout's environment readiness: detected toolchain, dependencies and setup scripts. Never clones, installs or loads secrets; preparing the environment requires the browser Studio surface. |
+| `anyforge_list_studio_outcomes` | studio:read | Read the accepted, needs-rework and abandoned outcomes recorded for the session's runs, with the verification each was bound to. Pass runId for one run's outcome history. Outcomes are recorded by a person in Code Studio. |
+| `anyforge_list_studio_workspace_files` | studio:read | List a directory of the live remote workspace (omit path for the root). Never creates a checkout: a session without one returns workspace_missing. |
+| `anyforge_read_studio_workspace_file` | studio:read | Read a line window of a file in the live remote workspace, including unsaved agent edits. offset is the first line (default 1), limit the line count (default 500, maximum 2000). Never creates a checkout. |
+| `anyforge_inspect_studio_code` | studio:read | Run a language-service query on a live workspace file: diagnostics (default), definition, references, hover, completions, or rename (a preview of the edits; apply with rename_studio_symbol). line and column are 1-based. Pass revision to refuse a changed workspace. |
+| `anyforge_write_studio_workspace_file` | studio:execute | Create an empty file or save a file's complete content in the live remote workspace, without a model run. Name the repository, branch and revision you read, so a changed workspace is refused. Each write saves a checkpoint first. Does not commit or push. |
+| `anyforge_rename_studio_symbol` | studio:execute | Apply a language-service rename of the symbol at a 1-based line and column across the live remote workspace. Preview it first with inspect_studio_code operation=rename. Name the repository, branch and revision you read; a changed workspace is refused. Does not commit. |
 | `anyforge_list_pending_approvals` | read | List HIL approvals awaiting a decision |
 | `anyforge_get_approval_detail` | read | Read one approval's plan / ADR / security context |
 | `anyforge_submit_approval` | approve | Approve or reject a HIL (resumes the crew) |
@@ -86,7 +161,9 @@ Use the equivalent stdio MCP config (`command: npx`, `args: ["tsx",
 | `anyforge_restore_program_intake_version` | write | Republish an earlier intake definition version as a new version |
 | `anyforge_get_intake_request_details` | read | Read one program intake request's answers against its program's intake definition: each field's state, answer, who gave it, and whether it can be edited |
 | `anyforge_edit_intake_request_details` | write | Set, confirm or clear a program intake request's answers by hand (validated against the definition; audited; no re-approval, no follower notice) |
-| `anyforge_update_program` | write | Update a program's name / status / owner / target date / coverage goal / tags |
+| `anyforge_update_program` | write | Update a program's name / status / owner / lead / long-lived flag / target date / coverage goal / tags / change freezes |
+| `anyforge_set_program_status_line` | write | Write or clear a program's status line, shown on a report's program status board |
+| `anyforge_set_program_request_intake` | write | Turn a program's incoming requests on (creates its Incoming Requests initiative) or off |
 | `anyforge_delete_program` | write | Delete a program; `deleteChildren: true` also deletes child initiatives + work items (else they're detached) |
 | `anyforge_set_program_milestones` | write | Set a program's milestones/waves and the initiatives assigned to each (whole-array replace; an initiative sits in at most one wave) |
 | `anyforge_get_program_rollup` | read | Read a program's rolled-up progress, initiative/work-item counts, token budget/spend, and risks — the console program header numbers |
@@ -101,7 +178,7 @@ Use the equivalent stdio MCP config (`command: npx`, `args: ["tsx",
 | `anyforge_get_initiative` | read | Initiative + crew and work-item rows + burn-down; long text is excerpted unless `shape: "full"` |
 | `anyforge_get_initiative_spec` | read | Read the active ICE spec, its readiness, what backlog approval will decide (`approvalGate`), and any submission awaiting human review |
 | `anyforge_propose_initiative_spec` | write | Submit an ICE spec for human review; it becomes active only when a person reviews and publishes it in the Console |
-| `anyforge_update_initiative` | write | Update a (non-system) initiative — only the fields you pass change |
+| `anyforge_update_initiative` | write | Update a (non-system) initiative — only the fields you pass change, including its owning team (`teamId`); an argument the tool does not declare is refused and nothing is changed |
 | `anyforge_delete_initiative` | write | Delete a DRAFT initiative (archive via update once it's past DRAFT) |
 | `anyforge_list_initiative_comments` | read | List an initiative's Discussion comments — the same threaded comments the console shows |
 | `anyforge_post_initiative_comment` | write | Post a Discussion comment on an initiative (reply with `parentId`), into the thread the console renders |
@@ -138,10 +215,10 @@ Use the equivalent stdio MCP config (`command: npx`, `args: ["tsx",
 | `anyforge_get_cluster_charter` | read | Read one theme's charter and outstanding lines |
 | `anyforge_approve_backlog` | approve | Approve a proposed backlog (HIL #1), optionally deferring chosen items (`deferItemIds`, `deferReason`) |
 | `anyforge_approve_task_proposal` | approve | Approve a mid-flight task proposal |
-| `anyforge_list_work_items` | read | List backlog items + crew state. Use `itemId` for a full work-item id or queue code, `search` for partial code/title matches, and `includeArchived: true` to include archived items. Also supports status, owner, assignee, program, initiative, priority and type filters. Returns ONE PAGE (50 default, 200 max) — continue with `nextCursor`. Unknown arguments are rejected; the page echoes `appliedFilters` |
-| `anyforge_get_work_item` | read | Get one work item by its returned id |
+| `anyforge_list_work_items` | read | List backlog items + crew state. Use `itemId` for a full work-item id or queue code, `search` for partial code/title matches, and `includeArchived: true` to include archived items. Also supports status, owner, assignee, program, initiative, team (a team slug, including the teams beneath it), priority and type filters. Returns ONE PAGE (50 default, 200 max) — continue with `nextCursor`. Unknown arguments are rejected; the page echoes `appliedFilters` |
+| `anyforge_get_work_item` | read | Get one work item by its returned id, with `assigneeName`, `blockerOwnerName` and `createdByName` beside the uids (null when nobody visible is named; list items carry them too) |
 | `anyforge_create_work_item` | write | Create a work item with routing, migration, incident, intake, estimate, and evidence fields |
-| `anyforge_update_work_item` | write | Edit, assign, begin, expedite, dispatch, confirm, drop (with optional `droppedReason`), archive, close, or reopen a work item |
+| `anyforge_update_work_item` | write | Edit, assign, begin, expedite, dispatch, confirm, drop (with optional `droppedReason`), archive, close, or reopen a work item. Each action takes only its own fields: one it does not read is refused (`unsupported_fields`) and nothing is changed. There is no `status` argument |
 | `anyforge_retry_work_item` | write | Terminate a work item's crew and dispatch a fresh one on the same branch; recovers missing/phantom crew records from work-item + initiative defaults |
 | `anyforge_list_work_item_comments` | read | List the work item's discussion thread, separate from crew transcripts; every comment carries a boolean `clientVisible` |
 | `anyforge_post_work_item_comment` | write | Add a discussion comment to a work item; internal unless `clientVisible: true` shares it with the client as it is written |
@@ -155,7 +232,10 @@ Use the equivalent stdio MCP config (`command: npx`, `args: ["tsx",
 | `anyforge_resume_crew` | approve | Resume a PAUSED/HALTED crew |
 | `anyforge_halt_crew` | approve | Halt a crew |
 | `anyforge_amend_crew` | approve | Continue & finish — send a crew at its HIL gate back to the engineer with guidance. Optional `postToPullRequest` also posts the notes on the pull request; left out, the organization setting decides (off by default) |
-| `anyforge_create_program` | write | Create a program (cross-initiative grouping) |
+| `anyforge_fix_crew_ci` | approve | Fix CI: send a crew whose pull request has failing checks back to the Engineer to fix them on the same PR. Works from PR review (HIL_SHIP) or a HALTED/PAUSED crew that has a PR; refused when GitHub does not report CI as failing. Requires `approve` scope and spends crew tokens. Only call when the operator asks. |
+| `anyforge_resume_crew_with_pr` | approve | Review & approve: take a HALTED or PAUSED crew's already-open pull request through the specialist reviews to the approve & merge gate, without re-running the Engineer. Omit prUrl to use the PR stored on the crew. A merged PR is refused. Requires `approve` scope. |
+| `anyforge_decide_crew_permission` | approve | Approve or deny the permission a crew in PERMISSION_PENDING is waiting on (see pendingPermissionRequest on anyforge_get_crew). A tool permission applies for the rest of the run; an MCP write approval decides that one call. Pass approvalId to refuse a decision on a newer request. Requires `approve` scope. Only call when the operator decides. |
+| `anyforge_create_program` | write | Create a program (cross-initiative grouping), optionally with a lead and as long-lived |
 | `anyforge_create_initiative` | write | Create a (DRAFT) initiative, optionally under a program |
 | `anyforge_dispatch_architect` | write | Decompose an initiative into a backlog (→ HIL #1) |
 | `anyforge_list_repo_index` | read | List the org repo index (activity, coverage, analyzed) — discover codebases to scope |
@@ -181,14 +261,23 @@ Use the equivalent stdio MCP config (`command: npx`, `args: ["tsx",
 | `anyforge_run_workflow` | write | Dispatch a run of a workflow (returns the QUEUED run); runs pause at gate steps for an operator decision |
 | `anyforge_get_workflow_run` | read | Get a workflow run's status and per-step progress; gate decisions are made on the Console run page |
 | `anyforge_resolve_workflow_gate` | approve | Resolve a run paused at a gate (`approve` / `amend` / `reject`; `amend` carries guidance in `comment`) |
+| `anyforge_retry_workflow_run` | write | Retry a `FAILED` run from the step that failed: finished steps and a map's answered items are kept, spend keeps accumulating; refused for a failed crew step. Runs on the company key |
 | `anyforge_list_observability_signals` | read | List production-error triage signals (filter by `status`) |
 | `anyforge_accept_observability_signal` | write | Accept a signal into a governed incident under the KTLO program |
 | `anyforge_dismiss_observability_signal` | write | Dismiss a production-error signal as noise |
 | `anyforge_list_audit_events` | audit:read | Read one page of the hash-chained audit trail, oldest first, with each entry's `sequence`, `hash` and `prevHash` (filter by `eventType`, `actor`, `from`, `to`; page with `cursor`). Needs a key minted with the explicit `audit:read` scope by an owner |
+| `anyforge_list_members` | read | List the workspace's approved members with uid, name, email, role and whether they can be assigned work. Assignment takes the uid, not an email; `q` finds a person by name or email |
 | `anyforge_invite_person` | people:invite | Invite one person, or refresh their pending invitation: `role` is operator, editor, viewer or filer (never owner), `email` on a verified company domain, optional `teamIds` and `notify`. Needs an owner's key with the `people:invite` scope |
 | `anyforge_list_people_invitations` | people:invite | List the invitations a `people:invite` key could have written, pending and accepted |
 | `anyforge_withdraw_person_invitation` | people:invite | Withdraw a pending invitation by email address (an accepted or owner invitation cannot be withdrawn this way) |
 | `anyforge_list_page_spaces` | read | List the Pages spaces you can read, with each space's key and what you may do there |
+| `anyforge_list_pages` | read | Browse a space by id, with its settings/revision and paginated page metadata; follow `nextCursor` while `hasMore` is true |
+| `anyforge_create_page_space` | write | Create a space as a workspace Owner |
+| `anyforge_update_page_space` | write | Change settings, access, main page or archive state as a space admin; requires `ifRevision` |
+| `anyforge_list_page_versions` | read | Paginated history metadata; readers see only published history |
+| `anyforge_restore_page_version` | write | Restore an older version as a new save; requires current `ifVersion` and keeps history |
+| `anyforge_set_page_publishing` | write | Set live or publish-to-update mode and replace reviewers as the page owner or space admin |
+| `anyforge_publish_page` | write | Publish, request publication, or approve a pending request as a named reviewer |
 | `anyforge_search_pages` | read | Search the pages you can read (by meaning, or by title); each match has its page id, space, section and snippet |
 | `anyforge_get_page` | read | Read one page: title, space, version, owner and markdown body (`version` for an older one) |
 | `anyforge_create_page` | write | Create a page in a space you can edit (`space` key, `title`, optional `content` and `parentId`), owned by you |
@@ -196,6 +285,13 @@ Use the equivalent stdio MCP config (`command: npx`, `args: ["tsx",
 | `anyforge_move_page` | write | Move a page under another page, to the top level, or to a position among its siblings |
 | `anyforge_archive_page` | write | Archive a page (kept with its history, hidden from the tree and search), or restore it |
 | `anyforge_propose_page_edit` | write | Propose find/replace edits as suggestions an editor accepts or rejects in the page; nothing changes until they do (live pages only) |
+| `anyforge_list_reports` | read | List the Insights reports, most recently edited first: id, title, description, widget count, updatedAt and Console `url`; one page at a time (follow `meta.nextCursor`) |
+| `anyforge_get_report` | read | Read one report: settings (`datesShown`, `trendDays`, `textSize`), whether a share link is live, and every widget definition with its query |
+| `anyforge_create_report` | write | Create an empty report (`title`, optional `description` and `datesShown`), owned by you; needs a role that edits reports |
+| `anyforge_update_report` | write | Change the title, description or settings, and edit widgets by id (`addWidgets`, `replaceWidgets`, `removeWidgetIds`) or replace the whole list (`widgets`). Every widget is validated as a Console save is; a refusal saves nothing |
+| `anyforge_preview_report_query` | read | Run one report query against live data without saving anything: total, rows and a text summary (program, strategy and cycles snapshots included); needs a role that edits reports |
+| `anyforge_describe_report_catalog` | read | The report data catalog: sources, measures, group-bys, filter fields and widget types; needs a role that edits reports |
+| `anyforge_list_report_filter_values` | read | The values a query filter field may take: an enum's closed set, or real ids with names (`query` looks one up by name); needs a role that edits reports |
 | `anyforge_triage_ticket` | read | Run or continue a Support Triage interview — classification, readiness scoring, owning-team routing — and get a paste-ready rendering plus the structured draft; pass the same `sessionId` to continue an interview. Never files anything itself |
 | `anyforge_list_triage_eval_cases` | read | List permitted triage eval cases; historical cases require Owner/Operator |
 | `anyforge_upsert_triage_eval_cases` | write | Create or update triage eval cases in bulk; pass an existing case's `id` to update it in place |
@@ -206,12 +302,27 @@ Use the equivalent stdio MCP config (`command: npx`, `args: ["tsx",
 | `anyforge_get_triage_evidence_snapshot` | read | Read a saved company snapshot; Owner/Operator only |
 | `anyforge_get_triage_eval_run` | read | Poll a queued triage eval run by id and read its completed result |
 
+Work item labels (the Console's Labels field) are `tags`.
+`anyforge_create_work_item` takes `tags`. On `anyforge_update_work_item` with
+`action: "update"`, `addTags` and `removeTags` change some labels against the
+labels stored at write time and need no revision, so a script can relabel many
+items without reading each first. `tags` replaces the whole list and needs
+`ifClassificationRevision`, the `classificationRevision` that
+`anyforge_get_work_item` returns. A labels-only update works at any status,
+`DONE`, `DROPPED` and archived items included, and its result carries the
+item's labels and `classificationRevision` after the write.
+
 `anyforge_update_work_item` advertises the complete action enum: `advance`,
-`approve_refinement`, `dispatch`, `complete`, `update`, `reorder`, `archive`,
-`unarchive`, `close-as-fixed`, `reopen`, `mark-incident`, `drop`,
-`confirm-repo`, `assign`, `begin`, `dismiss-automation-suggestion`,
-`expedite`, `link-external`, `verification`, `add-evidence`,
-`remove-evidence`, `share-evidence`, and `undefer`. `undefer` returns an item
+`approve_refinement`, `approve-and-route`, `move-initiative`, `dispatch`,
+`complete`, `update`, `reorder`, `archive`, `unarchive`, `close-as-fixed`,
+`reopen`, `mark-incident`, `drop`, `confirm-repo`, `assign`, `begin`,
+`dismiss-automation-suggestion`, `expedite`, `block`, `unblock`,
+`link-external`, `verification`, `add-evidence`, `remove-evidence`,
+`share-evidence`, `undefer`, `set-cycle`, `link-pull-request`,
+`unlink-pull-request`, `link-work-item`, and `unlink-work-item`.
+`link-work-item` with `linkedWorkItemId` and `linkType` (`relates_to` or
+`duplicates`) connects two work items at any status, done and dropped
+included; `unlink-work-item` with the same fields removes the link. `undefer` returns an item
 deferred at plan
 approval to the ordinary backlog flow. Use `drop` for an obsolete
 unfinished item and pass `droppedReason` when the reconciliation needs an audit
@@ -265,7 +376,7 @@ Every tool advertises 2025-06-18 MCP metadata so clients can present it well:
 
 - **Title + behaviour annotations** — a human-readable `title` plus hints
   (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) derived
-  from the tool's verb, matching the read/write/approve column above. Clients use
+  from the tool's verb, matching the explicit policies and Scope column above. Clients use
   these to, e.g., auto-run read-only tools and confirm before a `delete_*`. They
   are advisory only: the control API still re-checks the key's scopes on every
   call, so annotations never widen access.
@@ -376,15 +487,17 @@ npm pack --dry-run   # verify the tarball: dist/ + README + package.json only
 
 Publishing is automated. **Push a `mcp-server-v<version>` tag** and the
 `.github/workflows/publish-mcp-server.yml` workflow builds and runs
-`npm publish` (scoped public). Keep the tag version in sync with
+`npm publish` (scoped public), after a locked install, type check, build and
+tarball inspection. Re-running a tag whose version is already on npm skips
+publication. Keep the tag version in sync with
 `package.json`:
 
 ```bash
 cd packages/control/mcp-server
-npm version patch          # bumps package.json, e.g. 2.0.0 → 2.0.1
-git commit -am "chore(mcp): release mcp-server vX.Y.Z"   # if not committed by npm version
-git tag mcp-server-v$(node -p "require('./package.json').version")
-git push origin main --tags
+npm version minor --no-git-tag-version  # update package.json and package-lock.json
+# Commit and merge the reviewed version change before tagging that merge:
+git tag mcp-server-vX.Y.Z <reviewed-merge-sha>
+git push origin refs/tags/mcp-server-vX.Y.Z
 ```
 
 > The workflow needs an `NPM_TOKEN` repo secret (an npm **automation**