@withpica/mcp-server 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,1850 @@
+# Changelog
+
+All notable changes to `@withpica/mcp-server` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> **Rule of the road:** every version bump to this package MUST land with a
+> matching entry here in the same commit. See the project's "npm publish
+> discipline" memory entry for the enforcement rationale.
+
+## [Unreleased]
+
+## [2.48.0] - 2026-05-03
+
+### Changed
+
+- **Tool description scrub (PR #188).** Stripped internal-only ADR pointers and
+  email-vendor names from user-visible tool descriptions across batch A
+  (agreement-types, agreements, bulk, collaborators, credits), batch B
+  (app-tools, feedback, projects, enrichment, recordings), and batch C.
+  Replaced ADR-N references with the concept the ADR documented (e.g.
+  "ADR-198 round-trip" → "verify the credit persisted") and removed
+  Postmark from collaborator bulk-invite description and elicitation
+  warning text. Tool descriptions surface to third-party agents and shouldn't
+  reveal internal infrastructure choices.
+
+- **recovery_hints expansion (PR #188).** Annotation fix + additional
+  recovery hints for tools that fan out across sections.
+
+- **`pica_releases_show` best-effort catch markers (ADR-224 convention).** Marked
+  the two best-effort catches in `releases-rich.show()` (tracks + cover-art
+  fallbacks) with `/* best-effort */` to match the ADR-224 Phase 4 lint
+  convention. No behaviour change — the catches were already documented inline;
+  this just makes the marker greppable so future scope extensions to `_show`
+  tools recognise the intent. Surface audit confirmed all 9 `_inspect` tools
+  addressed, 22 `_list` tools clean, no swallow patterns elsewhere.
+
+## [2.47.0] - 2026-05-02
+
+### Added
+
+- **ADR-222 W3 — sync placements MCP tool surface (6 tools).**
+  - `pica_sync_placements_query` — list placements with filters (work_id, status, verification_status, brand, production_company, person_id, recording_id, source_license_enquiry_id, min_fee, currency).
+  - `pica_sync_placements_inspect` — fetch one placement with linked recordings, sources, agreement, and parties.
+  - `pica_sync_placements_create` — atomic create (placement + draft sync_license agreement + ≥1 agreement_party + recordings + evidence sources in a single Postgres transaction). Empty `contacts[]` rejects with structured `MISSING_CONTACT` (`next_tool: "pica_people_query"`). New people auto-created inline via `person_name` instead of `person_id`.
+  - `pica_sync_placements_update` — patch placement fields. Operator-only when `verification_status='operator_verified'|'disputed'` or `confidentiality_level` changes (throws structured `OPERATOR_REQUIRED`); illegal status transitions throw `INVALID_TRANSITION`.
+  - `pica_sync_placements_delete` — operator-only hard delete (two-step confirmation token). Customer agents receive structured `OPERATOR_REQUIRED` with `next_tool: "pica_sync_placements_update"` pointing at the soft-delete path (`status: 'terminated'`).
+  - `pica_sync_placements_cite` — attach an evidence source; auto-recomputes `verification_status` (any non-attestation kind → `evidence_attached`).
+
+  All 4 mutating tools wrapped with `withBillingGate`. Stdio path delegates to `pica.syncPlacements.*` (new `@withpica/mcp-sdk` resource). HTTP transport mirrors via the shared `ToolRegistry`. Paired with W4's REST routes at `/api/admin/sync-placements`.
+
+- **`pica://schemas/sync-placement-required` workflow schema resource (ADR-214).** Required + recommended fields for `pica_sync_placements_create` plus 4 companion call entries (inspect / update / cite / delete) and a worked example. Embeds the three `sync_placements` CHECK enums (`status` 5 values, `verification_status` 5 values, `confidentiality_level` 3 values) via the build-time generator + `schema-mirror.json` extension. Lives on both stdio (via the schema generator) and HTTP transport (`UI_RESOURCE_DEFS` in `app/api/mcp/route.ts`).
+
+- **`WorkflowTag` union expanded 15 → 16 values** (added `sync-placement-required`). All 6 sync-placement tools tagged with this workflow; `lint-required-schemas` enforces forward + inverse coverage.
+
+- **`schema-mirror.json` extended with `sync_placements` table** for status / verification_status / confidentiality_level CHECK enum embedding.
+
+- **6 cost-model entries in `lib/billing/tool-cost-model.ts`** (READ for query/inspect, WRITE for create/update/delete/cite). Unblocks ADR-180 lint cost-model coverage check; ADR-215 shadow-metering will record `billable_events` rows on these tools from first call.
+
+- **`sync_placements` discovery category** in `mcp-server/src/tools/discovery.ts` — layered-discovery agents (ChatGPT, Claude.ai connectors with `MCP_LAYERED_DISCOVERY=1`) can find the 6 tools via `pica_discover`.
+
+- **MCP scope mapping** for the 6 tools under existing `read:agreements` (query + inspect) and `write:agreements` (create + update + delete + cite). Bundled under the agreements scope rather than minting a new public scope for one feature — every placement is backed by a sync_license agreement.
+
+- **Four group-membership tools (ADR-223 Phase 5).** Customers can now
+  manage group → member relationships on people directly via AI:
+  - `pica_group_add_member` — add a person to a group person row.
+    Server-side trigger enforces parent.is_group=true and same-org
+    constraint; tool surfaces friendly errors at the route layer.
+    Defaults: `role='member'`, `receive_notifications=true` (opt-out
+    per membership). Wrapped in `withBillingGate`.
+  - `pica_group_remove_member` — set `left_at` on the active row.
+    Rows are never deleted; member history is preserved.
+  - `pica_group_list_members` — active members by default;
+    `include_inactive=true` for history.
+  - `pica_person_list_groups` — inverse: every group a person is or
+    was a member of.
+    Role enum: `member`, `founder`, `lead`, `touring_member`,
+    `session`, `guest`, `producer_in_residence`. Free-text `role_label`
+    for variants outside the enum. Tools route through `mcp-sdk`
+    `groups` resource → `/admin/groups/*` and
+    `/admin/people/{id}/groups` HTTP routes.
+
+### Changed
+
+- **`@withpica/mcp-sdk` peer bumped to `^1.20.0`.** Required for the
+  new `groups` and `syncPlacements` resources; older SDK versions lack
+  `PicaClient.groups` and `PicaClient.syncPlacements`.
+
+### Notes
+
+- The 4 mutating sync-placement tools (`_create`, `_update`, `_delete`, `_cite`) need ADR-198 holdout contract specs in the sibling `Good-FM/pica-holdout-tests` repo. Coordinator follow-up — Path A from W3 Stage 1 audit §11.E.
+- The brief's references to a `mcp-server/src/__tests__/contract-baseline.json` file and a `lint:contract-baseline` script are out of date; both were removed in ADR-180 Phase 3 (the lint chain is now fully strict by default — `scripts/lint-mcp-tools.ts` runs as part of `prepublishOnly`). W3 reinterpreted Stage 4 as ADR-180 metadata + cost-model + taxonomy entries (all added) plus ADR-198 holdout contracts (sibling repo, follow-up).
+
+## [2.46.0] - 2026-05-02
+
+### Changed
+
+- **`pica_update_my_identity` now accepts `full_name`.** Customers can
+  update the name on their PICA account via AI (e.g., fix typos from
+  signup). Routes to `user_profiles.full_name`; rolls back via
+  `revertMyIdentity` if the agent-action stamp insert fails. Tool
+  description rewritten to lead with name capture. Closes the
+  edit-symmetry gap surfaced during the SEV-1 sprint: previously the
+  user could AI-rename their org but not their own name.
+
+- **`pica_update_organisation_profile` now accepts `name`.** Customers can
+  rename their organisation via AI (e.g., fix signup typos, replace the
+  default "My Organization" placeholder). Updates `organisations.name`
+  directly; non-empty TRIM validation matches the DB-layer SEV-1 guard
+  shipped earlier on 2026-05-01. Tool description updated to mention the
+  typo-fix use case. Closes the placeholder-name lock-in trap surfaced
+  during the SEV-1 onboarding-stuck-state cleanup.
+
+## [2.45.0] - 2026-05-01
+
+### Added
+
+- **ADR-214 Phase 3a — 3 new workflow schema resources.**
+  - `pica://schemas/session-required` (studio session logging — `pica_sessions_create` primary; `pica_sessions_types` companion for session_type_id lookup; `pica_sessions_get` / `_list` for read).
+  - `pica://schemas/split-sheet-required` (publishing royalty splits on works — `pica_split_sheet_generate` primary; `pica_split_sheet_send` / `_get` / `_list` companions).
+  - `pica://schemas/recording-splits-required` (master ownership splits on recordings — `pica_recording_splits_create` primary with ADR-200 form-confirmation gate; `pica_recording_splits_verify` / `_list` companions).
+
+  Each derives required + recommended fields from live tool input schemas at build time; `recording-splits-required` embeds the `split_type` and `role` CHECK enums (4 + 8 values respectively) from a hand-edited `schema-mirror.json` entry verified against prod project `fwgcmjhlwevdnxgqmkmh`.
+
+- **WorkflowTag union expanded 12 → 15 values** (added `session-required`, `split-sheet-required`, `recording-splits-required`). 11 tools migrated from `"infrastructure"` to their P3a workflow tag (4 sessions + 4 split-sheet + 3 recording-splits).
+
+- **Agent-guide expanded 6 → 14 sections** for authenticated mode:
+  - 3 new write workflow sections (sessions, split-sheet, recording-splits) with canonical tool sequences and schema-URI footers.
+  - 1 new identifier-assign narrative section explaining the inline-update pattern (`pica_*_update` accepts identifiers as inline fields including satellite-routed person identifiers — `isni`, `musicbrainz_id`, `wikidata_id`, `discogs_artist_id`, `deezer_artist_id` route to `person_enrichment` automatically; the surface is uniform).
+  - 4 new read-workflow sections covering find-duplicates → merge, query → inspect → resolve gap-finding chain, lookup-person by industry identifier, and audit catalog completeness via dashboard tools.
+
+  Authenticated guide now ~12,750 B (lobby variant unchanged ~855 B).
+
+- **`schema-mirror.json` extended with `recording_splits` table** for `split_type` + `role` CHECK enum embedding. `sessions.status` and `split_sheets.status` documented inline in schema `summary` fields rather than `enum_tables` because they are not DB-CHECK-enforced.
+
+- **2 new MCP prompts.**
+  - `log-a-session` — guided studio session logging with optional `work_id` argument.
+  - `set-recording-splits` — guided master ownership split assignment with ADR-200 propose-and-confirm + verify flow; takes optional `recording_id`.
+
+- **`_meta.schemas` dispatcher emit on workflow-tagged tool results.** New `attachSchemaHints` private method on `ToolRegistry` mirrors the existing `attachSessionState` pattern verbatim — same merge semantics, null-safe handling, fail-open behavior. Every tool whose `workflows` field references one or more schema URIs auto-emits `_meta.schemas: ["pica://schemas/<workflow>-required", ...]` on successful results. 47 workflow-tagged tools across 13 files automatically tagged via the dispatcher hook (no per-executor edits). `ToolResult._meta` interface widened to `{ session_state?: SessionState; schemas?: string[]; [key: string]: unknown }`. Cross-transport survival verified — both HTTP (`app/api/mcp/route.ts`) and stdio (`mcp-server/src/server.ts`) preserve `_meta` end-to-end.
+
+- **Cost-model entries for ADR-217 + ADR-218 tools** (`pica_notifications_recent` → READ, `pica_notification_acknowledge` → WRITE, `pica_storage_configure_start` + `pica_storage_disconnect` → ADMIN). Unblocks ADR-180 lint cost-model coverage check; ADR-215 shadow-metering now records `billable_events` rows for these tools.
+
+### Changed
+
+- **11 existing prompts updated to reference ADR-214 schema URIs** where the workflow shape is implicated: `analyze-catalog`, `find-duplicates`, `enrich-metadata`, `verify-works`, `assess-catalog-health`, `audit-credits`, `new-catalog-setup`, `close-the-loop`, `register-my-works`, `prepare-for-sync`, `workspace-autopilot`. Agents invoking a refreshed prompt pick up the relevant `pica://schemas/<workflow>-required` (and `pica://docs/agent-guide` where orientation helps) on first read.
+
+- **`pica_merge_duplicates.entity_type` now accepts both forms.** Previously the enum was singular (`"work" | "person"`) while `pica_find_duplicates` was plural (`"works" | "people"`) — a real footgun documented in ADR-214 P3a Stage 1 R4. Tool now accepts all four (`works` / `people` / `work` / `person`); canonical plural form (`works` / `people`) matches the rest of the catalog tools. Internally coerces to plural for the success message and to singular for the SDK call. Backwards-compatible — no existing caller breaks. Success message no longer renders the broken `work(s)` / `person(s)` artifact when callers pass the plural form. The R4 confirm-branch (two-step ADR-200 confirmation flow) also uses canonical coercion with a try/catch fallback to "entities" so unknown entity_types don't break the confirm UX.
+
+### Fixed
+
+- **`pica_recordings_by_work` drift cleanup.** Removed tool was still referenced in:
+  - `mcp-server/src/prompts/index.ts` `verify-works` prompt body — swapped to `pica_recordings_query` with `work_id` filter (single-line drift fix).
+  - `mcp-server/src/tools/recovery-hints.ts` `next_tool` annotation — swapped to `pica_recordings_query`.
+  - `mcp-server/README.md` Recordings Management section — section refreshed to current 5 tools (`_query`, `_inspect`, `_create`, `_update`, `_delete`); count corrected 6 → 5. Larger README drift in works/people/etc. sections flagged as separate cleanup.
+  - `@withpica/mcp-utils` `recovery-hints.ts` DUPLICATE_ISRC `next_tool` — same swap (mcp-utils@1.15.1).
+
+- **Source ↔ dist invariant restored** for `prompts/index.{js,d.ts,*.map}` (PR #173 source landed without committed dist regen — develop's dist had been missing `log-a-session` + `set-recording-splits`) and `tools/recovery-hints.{js,*.map}` (source was correct; dist was stale). No semantic change beyond what was already on develop; clears phantom local-tsc errors per `feedback_root_tsc_stale_mcp_dist`.
+
+### Dependencies
+
+- `@withpica/mcp-utils` `^1.14.0` → `^1.15.1` (recovery-hints `next_tool` fix).
+
+## [2.44.0] - 2026-04-30
+
+### Added
+
+- **ADR-214 Phase 2 — 6 new workflow schema resources.**
+  - `pica://schemas/audio-upload-required` (3-step chain: presigned →
+    complete → analyze + poll)
+  - `pica://schemas/enrichment-resolve-required` (resolve fan-out →
+    proposals_list → proposal_apply / reject)
+  - `pica://schemas/agreement-required`
+  - `pica://schemas/multimedia-required`
+  - `pica://schemas/export-required`
+  - `pica://schemas/claim-required`
+
+  Each derives required + recommended fields from the live tool input
+  schemas at build time and embeds CHECK enums from `schema-mirror.json`.
+  Agent-guide expanded with 6 workflow sections (4 net-new, 2 rewrites
+  with schema-URI footers); intro bumps "five core" → "eleven core" and
+  "~227 tools" → "~231 tools".
+
+- **WorkflowTag union expanded to 12 values** (5 Phase 1 + 6 Phase 2 +
+  `infrastructure`). 28 tools migrated from `"infrastructure"` to their
+  Phase 2 workflow tag (4 audio-upload, 6 enrichment-resolve, 4
+  agreement, 4 multimedia, 5 export, 5 claim).
+- **`schema-mirror.json` extended with 6 new tables** for Phase 2
+  CHECK-constraint enum resolution (agreements, discovered_artists,
+  discovered_credits, discovered_custody, enrichment_proposals,
+  multimedia_items). Verified live against prod project
+  `fwgcmjhlwevdnxgqmkmh`.
+- **HTTP transport coverage** — `app/api/mcp/route.ts` `UI_RESOURCE_DEFS`
+  - `UI_RESOURCE_BODIES` extended with the 6 new schema URIs (matches
+    the Phase 1 pattern from PR #152). Per
+    `feedback_cross_transport_resource_coverage`.
+
+## [2.42.0] - 2026-04-30
+
+### Added
+
+- **ADR-218 Primitive B — `pica_notifications_recent` tool.** New read-only
+  MCP tool (`risk: "safe"`, `retry_safe: true`) returning the cross-transport
+  `discovery_events` feed for the calling org, ordered by `created_at` DESC
+  with optional `unread_only: boolean` filter (per-surface dedup against
+  `seen_in`). Default limit 20, max 100. Distinct from `pica_notifications_list`
+  which targets the person-scoped `pica.notifications` system; this reads the
+  org-wide ledger that web bell + telegram dispatcher also share.
+- **ADR-218 Primitive C — `pica_notification_acknowledge` tool.** New
+  mutating tool (`risk: "mutating"`, `retry_safe: true`) that appends `'mcp'`
+  to each event's `seen_in` array. Idempotent — re-acknowledging is a no-op.
+  Org-scoped server-side: out-of-org ids are silently skipped. Empty
+  `event_ids` returns a `VALIDATION_ERROR` without hitting the API.
+- \*\*Both tools registered in the existing `notifications` taxonomy bucket
+  - TOOL*METADATA (`category: "comms"`)\*\* + tagged `workflows: "infrastructure"`
+    per ADR-214 W4. Ride alongside the legacy `pica_notifications*_`and`pica*notify*_` families — the agent disambiguates from the descriptions.
+
+### Changed
+
+- **ADR-218 Primitive D — telegram dispatch dedup.** `telegramNotificationService.notifyEvent`
+  now consults `discovery_events` for an existing undismissed row matching
+  `(organisation_id, event_type, entity_id)` where `'mcp' = ANY(seen_in)`.
+  When found, suppresses the entire dispatch — closes the re-nag loop for
+  `until_resolved`-strategy alerts. Fresh `one_shot` events with no prior
+  row still fire normally. Lookup is fail-soft: any DB error logs a debug
+  and proceeds with dispatch (better an extra ping than a silently-dropped
+  alert).
+- **ADR-218 Primitive A — `_meta.session_state` envelope gains optional
+  `notifications` field.** `fetchSessionCounts` propagates the cross-transport
+  unread summary from the catalog-stats response into the envelope. Missing
+  field on older API servers leaves the envelope key off (no fabricated zero).
+
+### Bumped
+
+- `@withpica/mcp-sdk` peer to `^1.18.0` (`DiscoveriesResource.recent` +
+  `.acknowledge` methods + `NotificationsSummary` type on `CatalogStats`).
+- `@withpica/mcp-utils` peer to `^1.14.0` (optional `notifications` field on
+  `SessionStateCounts` + exported `NotificationsSummary` type).
+
+## [2.41.0] - 2026-04-30
+
+### Added
+
+- **ADR-210 P3 — `getAuthenticatedInstructions(slice)` + `getTrialEndingClause(slice)`
+  exports in `src/server-instructions.ts`.** New helpers that optionally append
+  a state-conditional trial-ending nudge to the authenticated handshake
+  instructions. The clause fires only when `billing_state === 'trial'` AND
+  `trial_days_remaining` is non-null AND `<= 3`; in all other cases the
+  function returns the unchanged base const. Pass `null` when no slice is
+  available — slice-less callers fail safe. Existing
+  `SERVER_INSTRUCTIONS_AUTHENTICATED` const is unchanged (parity with
+  `lib/mcp/server-instructions.ts` preserved).
+- **New `TrialNudgeSlice` interface export.** Minimal shape consumed by
+  the helper: `{ billing_state: string; trial_days_remaining: number | null }`.
+  Structurally compatible with the platform's `OrgBillingSlice` type so
+  callers can pass either.
+
+### Note on stdio behaviour
+
+The stdio binary in this release continues to call the equivalent of
+`getAuthenticatedInstructions(null)` at boot (returns the unchanged const) —
+trial state is not resolvable at boot without a `pica.catalogStats()` round
+trip. Stdio agents still see live `trial_days_remaining` via
+`_meta.session_state` on every write-tool result. A future phase may add
+boot-time slice resolution; this release ships the helper itself so the
+HTTP transport (`/api/mcp`) can use it immediately on a per-request basis.
+
+## [2.40.0] - 2026-04-30
+
+### Changed
+
+- **ADR-214 W4 — `workflows` field is now required on `ToolDefinition`.**
+  Flips the optional `workflows?: WorkflowTag | WorkflowTag[]` field
+  introduced in W1 to a required `workflows: WorkflowTag | WorkflowTag[]`.
+  TypeScript compilation now enforces that every new tool authored
+  declares its workflow membership at the source site — no escape
+  hatch except the explicit `"infrastructure"` opt-out. Drift
+  prevention mechanism #1 from ADR-214 §"Drift prevention" is now
+  fully load-bearing. `lint-required-schemas.ts` hardened: the
+  parallel-window warning for untagged tools becomes a hard error
+  (defence-in-depth in case a tool somehow reaches the registry
+  without a `workflows` field at runtime).
+
+### Added
+
+- **ADR-214 W2 — agent-guide + required-fields schema resources.**
+  Two new resource families on the catalog `mcp-server`:
+  - `pica://docs/agent-guide` — workflow narrative for agents. Visible
+    in both lobby and authenticated modes; content branches on
+    `lobbyMode`. Lobby variant (~865 bytes) covers the signup → magic
+    link flow + what unlocks. Authenticated variant (~4.3 KB) lists the
+    five core workflows (register a work, add a recording, add audio,
+    add recording credits, enrich metadata) with verbatim tool sequences
+    and 8 common gotchas — verified against the live tool registry on
+    2026-04-30.
+  - `pica://schemas/work-required`, `pica://schemas/recording-required`,
+    `pica://schemas/work-credits-required`,
+    `pica://schemas/recording-credits-required`,
+    `pica://schemas/person-required` — JSON contracts derived at build
+    time from each tool's `inputSchema` (in `ToolRegistry`) joined with
+    `schema-mirror.json` for live CHECK constraint enums. Authenticated
+    mode only.
+- **Build-time generator + schema mirror.**
+  - `mcp-server/scripts/build-required-schemas.ts` — runs as part of
+    `npm run prebuild` (chained after `bundle-apps.ts`); reads
+    `required-schemas.source.ts` + `ToolRegistry` + `schema-mirror.json`
+    and emits the deterministic `required-schemas.generated.ts`
+    (committed to git so PR diffs surface drift, per
+    `feedback_type_regen_cumulative_drift`).
+  - `mcp-server/src/resources/schema-mirror.json` — committed snapshot
+    of CHECK constraint enums for `works`, `recordings`, `work_credits`,
+    `recording_credits`, `audio_files`. Refresh via
+    `mcp-server/scripts/refresh-schema-mirror.ts` (humans only; CI never
+    auto-regenerates).
+- **Inverse-coverage CI lint (`scripts/lint-required-schemas.ts`).**
+  Walks `ToolRegistry` and `REQUIRED_SCHEMAS_SOURCE` from both
+  directions: every tool whose `workflows` field tags it for a workflow
+  must appear in the source file; every source reference must resolve
+  to a real tool. During the parallel-development window (W1 still in
+  flight), tools missing the `workflows` field emit a single summary
+  warning (per coordinator decision Stage 1 §R2). Once W4 makes the
+  field required, the warning becomes an error.
+- **Agent-guide drift lint (`scripts/lint-agent-guide.ts`).** Greps
+  every `pica_*` token in `agent-guide.ts` against `ToolRegistry` (in
+  both `discoveryMode` settings, so meta-tools like `pica_discover` are
+  resolvable). Catches stale references after tool renames.
+- **Meta-tests** for both lints (per `feedback_meta_test_load_bearing`):
+  3 / 3 regressions caught and reverted before ship — see
+  `docs/follow-ups/2026-04-30-adr214-w2-meta-test-outcomes.md`.
+
+### Changed
+
+- `mcp-server/package.json` — `prebuild` now chains
+  `bundle-apps.ts && build-required-schemas.ts`. New scripts
+  `lint:required-schemas` and `lint:agent-guide` added; both wired into
+  `prepublishOnly` after the existing checks.
+- `mcp-server/src/resources/index.ts` — registers 6 new URIs across
+  `listResources()` (1 in the lobby branch, 5 in the authenticated
+  branch) and `readResource()` (1 case for the agent-guide variant
+  branch, 5 cases for the schema URIs).
+
+### Dependencies
+
+- `pg` + `@types/pg` added as devDependencies (used only by
+  `refresh-schema-mirror.ts` for direct Postgres CHECK-constraint pulls
+  against staging).
+
+### Internal
+
+- **ADR-214 W1 — `WorkflowTag` type + optional `workflows` field on tool
+  definitions.** Adds a union type
+  (`"work-required" | "recording-required" | "work-credits-required"
+| "recording-credits-required" | "person-required" | "infrastructure"`)
+  and a `workflows?: WorkflowTag | WorkflowTag[]` field to
+  `ToolDefinition` at `mcp-server/src/tools/index.ts`. All 231 tools now
+  carry the field — 8 catalog-core tools (`pica_works_create`,
+  `pica_works_update`, `pica_recordings_create`,
+  `pica_recordings_update`, `pica_people_create`, `pica_people_update`,
+  `pica_credits_update`, `pica_recording_credits_update`) reference one
+  or more Phase 1 workflows; the remaining 223 carry
+  `"infrastructure"`. Field is optional in W1 to keep the rollout
+  additive; W4 (post-merge of W1 + W2 resource scaffolding) flips it to
+  required so every future tool is forced to declare its workflow at
+  compile time. No runtime behaviour change in this release.
+
+## [2.39.0] - 2026-04-30
+
+### Added
+
+- **ADR-211 Phase 1 — `pica_signup_start` unauthenticated tool.** New
+  agent-discoverable signup verb available without a connection key on
+  both stdio (lobby mode) and HTTP `/api/mcp` (anonymous mode). Mints
+  nothing locally — every invocation calls
+  `POST /api/public/onboarding/signup-start` so the
+  `ONBOARDING_TOKEN_SECRET` signing secret stays on the backend, never
+  in customer-distributed binaries. Returns a 15-minute JWT-bound
+  `/onboard/<token>` URL via `resource_link` (universal floor) +
+  capability-gated `elicitation/create url` (mode: "url"). Constructor
+  takes `{apiUrl, transport, clientId?}` — stdio binary stamps
+  `transport: "stdio"`, the HTTP carve-out stamps `transport: "http"`
+  and threads through any DCR `client_id` for OAuth resume.
+
+- **`SERVER_INSTRUCTIONS_UNAUTHENTICATED` lobby variant.** Short
+  ~600-char handshake text pointing the agent at the 3 lobby tools
+  (`pica_signup_start`, `pica_sign_in`, `pica_sign_out`) instead of the
+  full 200+ catalog surface. Selected at boot when `lobbyMode === true`
+  (stdio binary without `PICA_API_KEY`) and at handshake when
+  `/api/mcp` is invoked without a Bearer token. Catalog-tool guidance
+  omitted because no catalog tools are reachable in lobby mode.
+
+- **`SERVER_INSTRUCTIONS_AUTHENTICATED` alias** of the legacy
+  `SERVER_INSTRUCTIONS` export — the unaliased symbol stays exported
+  unchanged for backward compatibility.
+
+### Changed
+
+- **Lobby surface is now THREE tools** (was two): `pica_signup_start`
+  joins the existing `pica_sign_in` + `pica_sign_out` pair. Additive,
+  not replacement — Phase 1 evaluates consolidation in Phase 2 once
+  the `/onboard/<token>` page is live and the JWT-bound flow is the
+  preferred path. ADR-211 § Primitive A editorial amendment 2026-04-30
+  reflects this.
+
+### Notes
+
+- **`ONBOARDING_TOKEN_SECRET` env var required** on backend
+  environments (preview + prod already provisioned 2026-04-30). The
+  `lib/auth/scoped-jwt.ts` substrate gained an additive
+  `options.secretEnvVar` parameter so each scoped-JWT consumer
+  (upload-token, onboarding-token, future ADR-214 storage-config) can
+  rotate its signing secret independently. SUPABASE_JWT_SECRET still
+  serves as the local-dev fallback in both modes.
+
+- **No new exports in `@withpica/mcp-utils` or `@withpica/mcp-sdk`** —
+  Phase 1 consumes existing exports (`clientSupportsUrlElicitation`,
+  `CallerContext`) only. Per
+  `feedback_workspace_package_publish_discipline.md`: no bumps needed
+  upstream of this release.
+
+## [2.38.0] - 2026-04-30
+
+### Added
+
+- **ADR-208 Phase 3 Primitive D — `pica_release_show` rich-render tool.**
+  The catalog's first MCP tool returning `image` + `text` content blocks
+  in a single agent turn. Cover art ships as a base64 JPEG ≤512px;
+  markdown summary covers title, year, primary artists, label name, UPC,
+  catalog number, and tracklist with ISRCs and durations. Read-only
+  (`readOnlyHint: true`). Registered in
+  `mcp-server/src/tools/discovery.ts` `CATEGORIES.releases.tools` in
+  the same commit as the `ToolRegistry` registration per the layered-
+  discovery completeness rule.
+- **`_meta.ui.resourceUri = "ui://pica/release"`** — MCP Apps clients
+  (Claude Desktop, Cursor) render the iframe via the new resource at
+  `mcp-server/src/apps/release.ts`. Phase 3 ships the resource stub
+  (title + markdown + cover image binding); full interactive iframe
+  with track-list expand and inline streaming embeds is queued under
+  the ADR-200 Phase 1.x backlog.
+- **`structuredContent`** envelope — `{ title, markdown, cover_base64,
+cover_mime_type, resource_link_uri }`. Apps clients prefer this over
+  re-decoding the image content block; non-Apps clients ignore it.
+
+### Notes
+
+- **Universal floor is `image + text` only in Phase 3.** A `resource_link`
+  block is intentionally omitted because no release UI page exists in
+  the codebase yet (verified — neither `/portal/releases/[id]` nor
+  `/admin/releases/[id]`). Building one is queued under
+  `docs/follow-ups/2026-04-30-adr208-phase3-5-release-detail-page.md`
+  and ADR-208 § Primitive D was editorially amended on develop
+  (`30ceefc9d`) to reflect the deferral.
+- **"Key credits" deferred from the markdown body.** The existing
+  `releasesService.listTracks()` join surfaces work + recording artist
+  but not `work_credits`; adding the join widens Phase 3 scope. Will
+  land alongside ADR-213 when credit-attribution surfaces consume the
+  data cheaply.
+- **Sharp lives in the main Next.js app, not in this stdio binary.**
+  Cover-art bytes come from the new `/api/admin/releases/[id]/cover-art-thumbnail`
+  endpoint that does the resize + cache server-side, so the
+  customer-distributed `@withpica/mcp-server` install stays free of
+  sharp's ~50MB platform-specific native binaries.
+
+### Changed
+
+- **Bumps `@withpica/mcp-sdk` peer to ^1.17.0** to consume the new
+  `ReleasesResource.getCoverArtThumbnail()` method.
+  `@withpica/mcp-utils` stays at ^1.12.0 (T2.4's bump absorbed via the rebase).
+
+## [2.37.0] - 2026-04-30
+
+### Added
+
+- **ADR-210 Phase 2 — `pica_subscription_status` and `pica_subscription_manage`.**
+  Two new tools shipping the explicit billing read + action surface
+  that complements Phase 1's ambient `_meta.session_state.billing_slice`.
+  - `pica_subscription_status` (`readOnlyHint: true`) wraps the
+    existing `GET /api/admin/subscription` route and flattens it into
+    the 9-field shape ADR-210 § Phase 2 specifies (`billing_state`,
+    `trial_days_remaining`, `trial_ends_at`, `current_tier`,
+    `capacity_used`, `capacity_limit`, `capacity_pct`,
+    `recommended_tier`, `summary`). The `summary` line is a
+    server-side template the agent uses verbatim — predictable
+    wording, less variance across connectors.
+  - `pica_subscription_manage` (`readOnlyHint: false`) is a single-verb
+    dispatcher over the existing `POST /api/admin/subscription`
+    (subscribe / upgrade) and `POST /api/admin/subscription/portal`
+    (manage / cancel) routes. Returns `{url, expires_at, surface}`.
+    Subscribe / upgrade without `tier` returns a recoverable error
+    with `next_tool: pica_subscription_status` so the agent can
+    chain to read `recommended_tier` first rather than auto-pick.
+    Universal-floor `resource_link` content block ships on every
+    success response per ADR-200 Phase 1; `elicitation/create url`
+    fires only when `clientSupportsUrlElicitation(server)` (the
+    capability gate is mandatory because `elicitInput` with
+    `mode: "url"` throws synchronously against non-supporters per
+    `feedback_mcp_sdk_capability_gates_elicitation.md`).
+- **`subscription` category in `discovery.ts:CATEGORIES`** ("view your
+  billing state, manage your subscription, and pick a tier"). Lint
+  enforced by `scripts/lint-mcp-tools.ts` per
+  `feedback_mcp_taxonomy_completeness.md`.
+
+### Changed
+
+- **Bumps `@withpica/mcp-sdk` peer to ^1.16.0** to consume the new
+  `SubscriptionResource`. `@withpica/mcp-utils` stays at ^1.12.0
+  (T2.4's bump absorbed via the rebase).
+
+## [2.36.0] - 2026-04-30
+
+### Added
+
+- **ADR-213 Primitive A — `pica_recordings_create` post-create attribution hints.**
+  Every successful create call now appends up to three Important-severity
+  hints via the new `buildRecordingAttributionHints(recording)` helper
+  (`mcp-server/src/tools/recording-attribution-hints.ts`). Mirror of
+  `buildCustodyHints` for works:
+  - `recording_ownership_unset` — fires when `ownership_percentage IS NULL`.
+    Suggests `pica_recordings_update ownership_percentage:N`.
+  - `recording_no_credits` — always fires (we never know credits from a
+    single fresh row). Suggests the new `pica_recording_credits_update`.
+  - `recording_master_unclaimed` — fires when `ownership_percentage IS NULL`.
+    Alternative path for multi-party master claims via `pica_custody_claim`.
+    NULL-only triggers: `0` is "explicit zero", no hint. Negative-path
+    covered by jest at `recording-attribution-hints.test.ts` per
+    `feedback_meta_test_load_bearing.md`.
+- **ADR-213 Primitive B — `pica_recording_credits_update`.** First-party
+  recording-side write tool; closes the work/recording credit-write
+  asymmetry. Writes to `recording_credits` (NOT the trade-secret
+  enrichment-cascade-fed `credits` table — see `.claude/rules/ip-protection.md`).
+  Uses the 16-role `RECORDING_CREDIT_ROLES` enum (`MainArtist`,
+  `FeaturedArtist`, `Producer`, `Mixer`, `Engineer`, ... `Other`).
+  Songwriting credits (Writer, Composer, Lyricist, Arranger as a publishing
+  role) continue to route through `pica_credits_update` on the parent work.
+  Registered in `discovery.ts` `CATEGORIES.credits` in the same commit per
+  `feedback_mcp_taxonomy_completeness.md`. Listed under `write:catalog` scope
+  in `lib/services/mcp-scopes.ts`. `nextSteps` points at
+  `pica_recordings_inspect sections:["recording_credits"]` for ADR-198
+  round-trip verification.
+- **ADR-213 Primitive A.1 — `pica_recordings_inspect recording_credits`
+  section.** Additive (not replacement). The existing `credits` section
+  (work-side credits via parent work) keeps its current behaviour. New
+  `recording_credits` section reads first-party operator-authored credits
+  directly from the `recording_credits` table via the new
+  `pica.recordingCredits.list()` SDK method.
+- **`TOOL_METADATA` entry for `pica_recording_credits_update`** in
+  `mcp-server/src/tools/metadata.ts` (catalog/mutating/non-retry-safe).
+
+### Changed
+
+- **Bumps `@withpica/mcp-sdk` peer to ^1.15.0** and `@withpica/mcp-utils` to
+  ^1.12.0 to consume the new `RecordingCreditsResource` and the metadata
+  entry shipped alongside ADR-213.
+- **Tool count moves from 224 → 225** with the addition of
+  `pica_recording_credits_update`.
+
+## [2.35.0] - 2026-04-29
+
+### Added
+
+- **ADR-208 Phase 2 — `pica_upload` returns a JWT-bound `/upload/<token>` URL.**
+  The executor now calls `pica.uploads.createSession()` for server-side
+  mint of a 600s-TTL HS256 JWT scoped to the caller's org / user /
+  bucket-key / acceptFilter. Universal floor (`resource_link`) and
+  capability-gated `elicitation/create url` shapes unchanged — only the
+  URL flips from `${webBase}/workspace` to `${webBase}/upload/<jwt>`.
+  Tool description updated; obsolete Phase 1.5 forward-reference removed.
+
+### Changed
+
+- **`session_state.pending_uploads` now reads from
+  `organisations.pending_uploads_count`** (atomic +1 on JWT mint via
+  `/api/admin/uploads/sessions`, atomic -1 on JWT-path completion via
+  `/api/upload/[token]`). Phase 1's stub at `0` is gone. Atomic semantics
+  via the `inc_pending_uploads` SECURITY DEFINER RPC; `GREATEST(0, ...)`
+  clamp prevents negative drift. Sits alongside T1.2's billing fields on
+  the same `_meta.session_state` envelope — no shared edit to
+  `mcp-server-shared/mcp-utils/src/session-state.ts`.
+
+### Notes
+
+- Fail-soft: if `createSession()` throws (network blip, route 5xx), the
+  executor falls back to the legacy workspace URL and surfaces the error
+  in the `text_summary`. The card still works for MCP Apps clients via
+  `_meta.ui.resourceUri` regardless.
+
+### Bumped
+
+- `@withpica/mcp-sdk` dependency range bumped to `^1.14.0`
+  (`UploadsResource`, `CreateUploadSession*` types,
+  `CatalogStats.pending_uploads_count` now consumed).
+- `@withpica/mcp-utils` dependency range bumped to `^1.11.0`
+  (T1.2's billing-fields extension on `SessionStateCounts`).
+- `mcp-server/server.json` registry manifest version bumped to `2.35.0`
+  in lockstep with the npm package.
+
+## [2.34.0] - 2026-04-29
+
+### Added
+
+- **ADR-210 Phase 1 — billing slice on `_meta.session_state`.** The
+  `fetchSessionCounts` private in `ToolRegistry` now resolves the four
+  billing fields (`billing_state`, `trial_days_remaining`, `current_tier`,
+  `capacity_pct`) from `pica.catalogStats().billing_slice` alongside the
+  existing counts. `attachSessionState` flows them onto every successful
+  write-tool result through the same `_meta.session_state` envelope (no
+  new emission path — extends the existing one) so the agent sees ambient
+  billing posture between mutations without a `pica_subscription_status`
+  round-trip. Phase 2 will land that explicit read tool; Phase 1 ships
+  the substrate the tool reads from.
+- Same fail-soft posture as the existing fetcher: when `this.pica` is
+  missing (HTTP-discovery without bearer scope), or when the SDK response
+  is missing `billing_slice` (older server pre-Phase-1), the fetcher
+  emits a conservative `{ billing_state: "trial", trial_days_remaining:
+null, current_tier: null, capacity_pct: 0 }` rather than fabricating
+  "active" — the agent never sees misleading "active" billing for an
+  uninitialized context.
+
+### Bumped
+
+- `@withpica/mcp-sdk` dependency range bumped to `^1.13.0`
+  (`CatalogStats.billing_slice` field now consumed).
+- `@withpica/mcp-utils` dependency range bumped to `^1.11.0`
+  (`SessionStateCounts` shape extended with `BillingSlice` fields).
+- `mcp-server/server.json` registry manifest version bumped to `2.34.0`
+  in lockstep with the npm package.
+
+## [2.33.0] - 2026-04-29
+
+### Added
+
+- **ADR-208 Primitive B — `_meta.session_state` attached to write-tool results.**
+  The central `ToolRegistry.executeTool` wrapper now composes the six-key
+  session-state envelope (`works_count`, `recordings_count`,
+  `completeness_pct`, `mutations_this_session`, `since_last_briefing`,
+  `pending_uploads`) for every tool whose risk is `mutating` or
+  `destructive` (`readOnlyHint: false`), and attaches it under
+  `result._meta.session_state`. Read tools (`risk: safe`) skip this
+  entirely so the high-volume read path stays cheap; failed mutations
+  (`isError: true`) also skip because catalog state didn't change.
+  `pica_dashboard_briefing` running successfully resets the
+  `since_last_briefing` counter — handled in the wrapper, not the tool.
+  Cache key is org-scoped via `config.picaApiKey` (stdio) or
+  `callerContext.callerIdentity` (HTTP); two orgs sharing a worker
+  process never share state. Fail-open: any error in session-state
+  composition is swallowed and the result returns without `_meta.session_state`.
+  See `@withpica/mcp-utils@1.10.0` for the underlying `buildSessionState`
+  helper and the load-bearing cross-org isolation regression test.
+
+### Changed
+
+- Bump `@withpica/mcp-utils` dep range to `^1.10.0` to pick up the
+  `buildSessionState` / `incrementSessionMutations` /
+  `resetSinceLastBriefing` exports that compose Primitive B.
+
+## [2.32.0] - 2026-04-28
+
+### Changed
+
+- Bump `@withpica/mcp-utils` dep range to `^1.9.0`. The previously-pinned `^1.8.0`
+  resolved (via the npm registry) to a tarball that pre-dated the addition of
+  `clientSupportsUrlElicitation` and `elicitBulkConfirmation` to the source — Vercel
+  builds where the lockfile resolved from registry instead of the local workspace
+  link failed with `TS2305`. 1.9.0 republishes the same source state with both
+  exports present, so registry-pinned lockfiles now build cleanly without needing
+  the workspace-link override.
+
+## [2.31.0] - 2026-04-28
+
+### Added
+
+- **ADR-200 Phase 1 — `ToolExecutorContext` plumbed through the registry.**
+  `ToolExecutor` now takes an optional second arg `(args, ctx?)` carrying the
+  per-request `Server` reference. `server.ts` passes `{ server }` through to
+  `executeTool`; the discovery dispatcher (`pica_execute`) forwards it to its
+  delegate. Existing executors with the legacy `(args)` signature keep working
+  unchanged — only tools that need `server.elicitInput()` opt into the second
+  arg. Pre-existing destructive-confirmation gate (two-step token) is
+  preserved.
+- **`pica_upload` portable across non-MCP-Apps clients.** Response now ships
+  with a `resource_link` content block (universal MCP floor) alongside the
+  legacy text envelope and `_meta.ui.resourceUri` — Apps clients render the
+  iframe unchanged, ChatGPT / Gemini / Claude Code / curl-style clients see a
+  clickable link to the workspace upload page. Clients that advertised
+  `capabilities.elicitation.url` additionally receive a server-issued
+  `elicitation/create url` consent prompt; the call is gated on the new
+  `clientSupportsUrlElicitation` helper from `@withpica/mcp-utils@1.8.0` so
+  callers without the capability never see the SDK's synchronous
+  "Client does not support url elicitation" throw. `elicitationId` is a
+  per-call UUID. Universal floor remains usable when the user declines or the
+  elicitation times out — the resource_link in the response is the fallback.
+- **`pica_download` ships a `resource_link` for the signed file URL.** Same
+  universal-floor improvement on the download surface — text envelope still
+  carries the JSON shape ADR-152 cards expect, plus the new resource_link
+  exposes the URL/filename/mime to clients that render link blocks.
+- **ADR-200 Phase 1 — form-confirmation gate on the 4 customer-MCP Class D
+  bulk tools** (`pica_works_bulk_update`, `pica_people_bulk_update_roles`,
+  `pica_recording_splits_create`, `pica_collaborators_invite_bulk`). Each
+  now calls `elicitBulkConfirmation` from `@withpica/mcp-utils@1.8.0`
+  after the validation + dry_run paths but before persisting. The gate
+  fires only when the connected client advertises
+  `capabilities.elicitation`, and in that case the destructive write only
+  proceeds if the form returns `accept` with `confirm: true`. Universal
+  floor: clients without elicitation continue to execute as before
+  (existing destructive-token gate, where applicable, remains
+  authoritative). 11 new tests cover decline, accept-without-confirm,
+  no-caps fallback, and dry_run-skips-elicitation across the four tools.
+  `team_comms_send` (5th Class D tool) is gated in
+  `@withpica/team-mcp-server@1.3.0`.
+- **`ToolResult.content` widened to permit `resource_link` blocks.** Legacy
+  `Array<{ type, text }>` shape kept compatible via a structural union; tools
+  that only return text need no changes.
+
+### Changed
+
+- **Tool descriptions for `pica_upload` / `pica_download` updated** to point
+  at the ADR-200 fallback ladder rather than the prose "tell the user to use
+  the workspace dashboard" hint that ADR-152 originally shipped. Behaviour
+  for MCP Apps clients is unchanged.
+
+### Removed
+
+- **9 nested `withCreditGate(...)` wrappers unwrapped** across `tools/audio-files.ts` (2), `tools/exports.ts` (3), and `tools/enrichment.ts` (4). Each always ran inside a `withBillingGate(...)`; the inner wrapper was a no-op shim retained since ADR-162 disabled credit gating. Unwrapping leaves the subscription check as the sole gate on these tools, which matches the billing model.
+- **`tests/utils/credit-gate-mpp.test.ts` + `credit-gate-mpp-paths.test.ts` deleted.** Both suites exercised a disabled MPP + pay-per-credit path that no longer has any production call-sites. `tests/tools/metadata.test.ts` also drops its `credit-gated tools should have credits_required set` assertion — redundant now that `credits_required` is gone from the shared `@withpica/mcp-utils` type (companion entry in that package's CHANGELOG). `tests/tools/credits.test.ts` stale `describe("pica_credits_balance")` block (and associated `mockCreditsBalance` setup) removed — that tool was pulled from the surface 2026-04-22 but the tests were missed in that pass.
+- **`src/__mocks__/mppx-server.ts` + `mppx-mcp-sdk-server.ts` deleted** and the matching `moduleNameMapper` entries removed from `jest.config.js`. Both mocks existed only to stub out `mppx` for the now-deleted MPP unit tests. The `testPathIgnorePatterns` entry pointing at `credit-gate-mpp-paths.test.ts` is also removed (ghost reference to the deleted file).
+- **"credit-gated" prose stripped from tool descriptions** in `tools/app-tools.ts` (`pica_car_preview` description + carPreview reuse comment) and `tools/documents.ts` (`pica_documents_analyse` description). These strings were advertised in the tool description, telling agents a tool was "credit-gated (5 credits)" when it's actually subscription-gated at workspace level.
+- **`mppx` runtime dep still listed in `package.json`** — left in place to avoid lockfile churn; no `src/` consumer remains after this commit. Next publisher should drop it and rerun `npm install` to clean the lockfile.
+
+## [2.30.0] - 2026-04-27
+
+### Added
+
+- **`pica_audio_inspect` basic section surfaces 4 previously-invisible
+  columns** — `recording_id`, `stem_label`, `version_label`, and
+  `classification`. All four are real columns on `audio_files` written by
+  `pica_audio_complete_upload`. The 5th audit-flagged field
+  (`content_type`) is mapped to `audio_format` at write time and was
+  already surfaced. Closes a Phase 2 gap from the 2026-04-27 read-write
+  parity audit. SDK type `AudioFile` extended with the same three
+  optional fields (classification was already there).
+- **`pica_organisation_profile` includes `org_type`** — paired read tool's
+  underlying `/admin/settings/organisation-profile` SELECT now returns
+  the CHECK-enum value that `pica_update_organisation_profile` already
+  accepted (publisher / label / pro / sync_library / client / venue /
+  distributor / other). Same class as the settings/identity fan-out
+  fixed in 2.29.0 — write side accepted, read side truncated.
+- **`pica_physical_assets_inspect` adds a `links` section** — surfaces
+  the typed-edge rows that `pica_physical_assets_link_work` and
+  `pica_physical_assets_link_recording` write to `work_production_assets`
+  and `recording_production_assets`. Pre-fix the link rows were
+  write-only from the MCP surface even though both
+  `/admin/assets/[id]/{work,recording}-links` GET endpoints already
+  existed. SDK gains `assets.listWorkLinks(id)` and
+  `assets.listRecordingLinks(id)`.
+- **`dry_run` flag on three more Class D mutating tools** —
+  `pica_recording_splits_create`, `pica_collaborators_invite_bulk`,
+  and `team_comms_send`. Completes the Class D coverage started in the
+  ADR-199 5a part 1 commit (`a10006e5b`). Each tool early-returns
+  `{ dry_run: true, would_affect, sample / target_count }` after
+  validation and before the mutating SDK call, so agents can preview
+  bulk effects and external-comms dispatch before committing. For
+  `team_comms_send`, the preview echoes recipient and length-only
+  metadata; the message body is not surfaced to keep ops messaging
+  off the dry-run trace.
+
+### Fixed
+
+- **`pica_recordings_inspect` no longer hallucinates into the void on 404.**
+  ADR-198 verification 2026-04-26 found the inspect tool was returning 200
+  with `recording_error: "API request failed: 404 ..."` for every missing
+  entity / missing route handler. Agents read this as a successful empty
+  result and proceeded to call downstream sections (credits, audio) that
+  also 404'd silently — no Sentry alert, no audit row, no user-visible
+  error. Fix: basic-section catch now re-throws `EntityNotFoundError`
+  (new typed export from `@withpica/mcp-sdk` 1.12.0+), so 404 surfaces
+  as a hard `isError: true` envelope. Non-404 errors on the basic fetch
+  still get absorbed into `recording_error` (preserves the partial-result
+  pattern for transient failures).
+
+## [2.29.0] - 2026-04-25
+
+### Fixed
+
+- **94 previously-undiscoverable tools retrofitted into the layered-discovery
+  taxonomy.** Same bug class that bit four times in three weeks
+  (`pica_upload`/`pica_download` since ADR-152, `pica_submit_feedback` since
+  ADR-184, `pica_report_issue`/`pica_my_reported_issues` from ADR-196 Phase 3):
+  registered in `ToolRegistry` but absent from `CATEGORIES` in
+  `mcp-server/src/tools/discovery.ts`, so layered-discovery agents (default
+  for ChatGPT and Claude.ai connectors with `MCP_LAYERED_DISCOVERY=1`) could
+  not find them via `pica_discover`. The 2026-04-25 hardening that added
+  blocking `checkTaxonomyCompleteness` to `scripts/lint-mcp-tools.ts`
+  surfaced 94 grandfathered violators in the baseline. This release retrofits
+  every one. Fourteen new categories — `agreements`, `collaborators`,
+  `custody`, `physical_assets`, `recording_splits`, `royalties_statements`,
+  `share_links`, `split_sheets`, `licensing`, `notifications`, `messaging`,
+  `agent_identity`, `telegram`, `labels` — and the tools fold into existing
+  ones (`releases`, `analytics`, `enrichment`, `import`, `projects`,
+  `profile`) where they belong. `scripts/mcp-tool-lint-baseline.json
+→ missing_taxonomy` is now empty.
+- **`pica_upload` and `pica_download` newly reachable via `pica_discover`** —
+  the two generic harness cards (ADR-152) had been silently absent from the
+  `CATEGORIES` taxonomy since they shipped. `pica_upload` added to the
+  existing `uploads` category alongside the programmatic `pica_upload_file` +
+  `pica_upload_complete` pair. `pica_download` added to the `export` category
+  since it's the delivery side of any export-tool flow.
+
+### Changed
+
+- **`CATEGORIES` is now exported** from `mcp-server/src/tools/discovery.ts`
+  so `scripts/lint-mcp-tools.ts` can read it. Compile-time only; no
+  consumer change.
+
+## [2.28.1] - 2026-04-25
+
+### Fixed
+
+- **`pica_report_issue`, `pica_my_reported_issues`, and `pica_submit_feedback`
+  were unreachable via `pica_discover`** — the layered-discovery taxonomy
+  in `mcp-server/src/tools/discovery.ts` did not list them in any of its
+  26 categories, so agents using the layered flow (default for ChatGPT
+  and Claude.ai connectors that need to keep their context window
+  manageable) literally couldn't find these tools. Real-world failure
+  caught 2026-04-25: a Claude Desktop session dogfooding the issue-
+  reporting flow returned "no feedback or support tool exposed in the
+  PICA MCP" and suggested `pica_notes_create` as the closest match —
+  the exact failure mode `pica_report_issue` was designed to catch
+  (which it couldn't, because it wasn't discoverable). New `feedback`
+  category added to the discovery taxonomy listing all three tools.
+  `pica_submit_feedback` had been silently invisible since ADR-184
+  shipped — same bug class, same fix.
+
+### Changed
+
+- **`pica_report_issue` description tightened** to instruct the agent
+  on WHEN to call: PROACTIVELY without being asked when the agent itself
+  hits a workflow gap, AND on-demand when the user says "this is broken"
+  / "this didn't work". Previously the description was descriptive
+  ("file a structured issue when…") which left agents reading it as a
+  passive option rather than a recommended habit. Also adds a
+  cross-reference to `pica_my_reported_issues` for the resolution-poll
+  side of the closed loop.
+
+## [2.28.0] - 2026-04-24
+
+### Added
+
+- **ADR-196 Phase 4a — `pica_my_reported_issues` tool.** Org-scoped
+  customer-side polling tool that closes the loop on `pica_report_issue`.
+  Lets the agent answer "did anyone fix that thing I reported?" without
+  going through the operator surface. Returns the issue, current status,
+  resolution_note, and occurrence_count for each issue the calling org
+  has reported or been impacted by. Default sort most-recently-touched
+  first; optional `status` filter (open / triaged / investigating /
+  resolved / wont_fix). Tool metadata: `category=comms`, `risk=safe`,
+  `retry_safe=true`. Pairs with `@withpica/mcp-sdk@1.12.0` for the new
+  `OpsIssuesResource.listMine()` method.
+
+### Changed
+
+- **`mcp-server/src/config.ts` VERSION constant is now derived from
+  `package.json`** via `createRequire(import.meta.url)("../package.json")`,
+  not a hardcoded literal. Drift-proof — future bumps no longer require
+  manual sync between the two files. The version-sync lint in
+  `scripts/lint-mcp-tools.ts` now accepts both forms (literal still
+  blocks on drift; derived is always valid). Motivated by two
+  consecutive publishes (2.27.0 + 2.28.0) being blocked by the stale
+  literal — the trap is now permanently sealed.
+
+### Fixed
+
+- **`mcp-server/src/tools/discovery.ts` no longer references
+  `metadata.credits_required`** — the property was removed from
+  `ToolMetadata` in the chore/drop-mcp-credit-gating cleanup (per
+  ADR-162: PICA is subscription-only) but two stale references in
+  `discovery.ts` slipped through, blocking the publish until fixed.
+  No tool carries the field anymore so the conditional spread was
+  dead code; replaced with a comment recording the history. The
+  comment itself is removed in chore/drop-mcp-credit-gating
+  (this PR) — credit gating is gone for good.
+
+### Changed
+
+- **ADR-199 Week 1 — `withBillingGate` extended to every write-tool
+  surface.** Previously the gate only covered `audio-files.ts`,
+  `exports.ts`, and `enrichment.ts` (8 tools). Now wraps 38 write
+  executors across 9 tool families: `agreements` (4), `agreement-types`
+  (5 — `renderTemplate` deliberately ungated as it's a pure read),
+  `custody` (4), `people` (3), `works` (5), `recordings` (3), `credits`
+  (1), `assets` (7 — `assetExport` deliberately ungated to match
+  `pica_export_catalog_csv`), and `dashboard` claim/review tools (4).
+  Read tools (query / list / inspect / history / search / stats /
+  pulse / briefing) intentionally not wrapped. Behaviour change for
+  agents on hibernated workspaces: write tools that previously executed
+  now return the lobby error. Operation labels in the lobby message
+  use domain terms ("agreement creation", "physical asset link",
+  "custody claim", "discovery review", etc.). The gate itself reads
+  from `organisations.billing_state` via the new effective-state route
+  (see `[Unreleased]` in `@withpica/mcp-utils`); `is_internal=true`
+  organisations bypass the gate. Rollback path is the
+  `ADR199_READ_BILLING_FROM_ORG` env var on the Vercel app — flipping
+  to `false` reverts the read source to `user_profiles.billing_state`
+  without an MCP redeploy.
+- **ADR-199 Week 1 language sweep — agent-facing copy moves to domain
+  terms.** "Your organisation" / "this organisation" / "your org"
+  swept to "your catalog" (where the noun is the music data) or "your
+  account" (where no domain term fits) across `audit`, `collaborators`,
+  `custody`, `dashboard`, `directory`, `memory`, `metadata`,
+  `my-reported-issues`, `releases`, and `settings` tool descriptions.
+  Internal identifiers (`pica_organisation_profile`,
+  `pica_update_organisation_profile`, `org_type` parameter, the
+  `"organisation"` memory-visibility enum value) deliberately
+  preserved — those are wire-protocol or schema names, not copy.
+  Industry term "Performing rights organisation" preserved (it's a
+  PRO, not a withPICA org). Display names in `metadata.ts`
+  (`view organisation profile` / `update your organisation profile`)
+  swept to `view account profile` / `update your account profile`.
+
+## [2.27.0] - 2026-04-24
+
+### Added
+
+- **ADR-196 Phase 3 — `pica_report_issue` tool.** Lets an agent file a
+  structured issue when a workflow breaks in a way raw tool failures can't
+  capture (`workflow_gap` / `inconsistent_result` / `missing_step` /
+  `data_issue` / `ux_confusion`). Auto-dedupes via the v2 signature
+  (sha256 of `"v2|{kind}|{canonicalised_summary}"`), so two reports of
+  the same problem with different wording collapse into one
+  `ops_issues` row. Operators triage from the same record. Raw tool
+  errors continue to auto-populate `ops_issues` via the `mcp-audit.ts`
+  upsert path — agents should NOT call `pica_report_issue` for those
+  (it would create a duplicate). Tool metadata: `category=comms`,
+  `risk=mutating`, `retry_safe=true`. Pairs with
+  `@withpica/mcp-sdk@1.11.0` and `@withpica/mcp-utils@1.7.0` published
+  in the same cycle.
+
+### Fixed
+
+- **`config.ts` VERSION constant bumped to 2.27.0** to match the
+  `package.json` version. The `version-sync` lint in
+  `scripts/lint-mcp-tools.ts` blocked the initial 2.27.0 publish until
+  this was corrected — caught a pre-existing trap where the banner
+  version is hardcoded in source rather than derived from `package.json`
+  at build time. Future bumps must update both files; consider
+  auto-deriving in a follow-up.
+- **`pica_report_issue` tool — drop double-unwrap of SDK response.**
+  `OpsIssuesResource.reportIssue()` now returns the unwrapped payload
+  (mcp-sdk@1.11.0 tightened the return type), so the tool's previous
+  `result?.data || result` fallback was dead code that didn't
+  typecheck. Now `const data = result;` directly.
+
+## [2.26.0] - 2026-04-22
+
+Version leapfrogs 2.25.0 (which was published to npm without a matching commit / changelog entry in this repo, discovered during this publish cycle). 2.26.0 ships from a clean main at commit `a3c8ca870` with the full bundle below. Pairs with `@withpica/mcp-sdk@1.10.0` and `@withpica/mcp-utils@1.6.0`, both published the same day.
+
+### Removed
+
+- **Billing-credit tools removed from the MCP surface:** `pica_credits_balance` (credits.ts), `pica_credits_history` (settings.ts), `pica_credits_purchase` (purchases.ts tombstoned to an empty class). See `docs/MCP_REFINEMENT_LOG.md` entry B-001. withPICA is subscription-only at £9.99/mo; surfacing a credit-balance + credit-history + credit-purchase tool trio contradicted the billing model and misled agents (caught 2026-04-22 when an agent transcript opened with "998,894 credits — plenty. Running the export now."). The underlying SDK methods (`creditsBalance.*`, `settings.creditsHistory`) and `lib/services/credits/**` infra remain intact — only the MCP tool surface shrinks. `pica_credits_list` and `pica_credits_update` are **kept**: they're work_credits (songwriter roles + splits on a work), not billing credits.
+- **`CREDIT_INSUFFICIENT` recovery hints pointing at `pica_credits_balance`** removed from `recovery-hints.ts` for `pica_resolve_work`, `pica_export_song_registration`, `pica_export_catalog_asset_report`, `pica_audio_analyze`. Paired tests under `__tests__/tools/recovery-hints.test.ts` + `settings.test.ts` updated to assert the new shape.
+
+### Changed
+
+- **Credit-gating language stripped from tool descriptions** — `pica_audio_identify` ("Costs 3 pica credits on match…"), `pica_export_song_registration` ("Costs 1 pica credit."), `pica_export_industry_ready` (same), `pica_export_catalog_asset_report` ("Costs 5 pica credits…"), and the 3 `pica_resolve_*` tools in `enrichment.ts` ("Costs 1 pica credit per call."). The `withCreditGate` / `withBillingGate` runtime wrappers are **left in place** — only the agent-facing prompt-gating copy goes. Same B-001 refinement entry.
+- **Server instructions** (`src/server-instructions.ts`, mirrored in `lib/mcp/server-instructions.ts` via the parity test) open with a one-line disambiguation from `@picahq/mcp` (Pica AI / picaos.com) — a different product whose short name collides with ours. Helps agents that have both connectors installed (or users who pasted their withPICA key into the wrong config) recognise which server they're actually talking to. See the picaos name-collision memory rule.
+- **`pica_catalog_diligence` now returns structured JSON** instead of failing with a JSON-parse error on binary ZIP bytes. The fix lives in `@withpica/mcp-sdk`'s `AnalyticsResource.catalogDiligence()` — the SDK now requests `?format=json`. See the mcp-sdk CHANGELOG for detail. MCP refinement log: "Singleton — `pica_catalog_diligence` returns ZIP parsed as JSON".
+
+### Fixed
+
+- **ADR-174 Phase 2c — inverse phantom in `pica_works_update` (works slice).** Three jsonb compliance fields (`ai_disclosure`, `provenance_attestation`, `training_rights`) are satellite-routed to `work_licensing` via `WORK_SATELLITE_FIELDS` and accepted by both the HTTP route allow-list and the service layer, but were missing from `WORK_WRITE_PROPERTIES`. Agents following the `pica_works_update with ai_disclosure: ...` completion hint at works.ts:577 were hitting schema-level silent-drop (or strict-validator 400s). Added all three properties to the write schema with shapes copy-pasted from the parallel fields on `pica_recordings_update` (recordings.ts:193). Tool description updated to distinguish audio-trait satellite fields (still not exposed) from the three compliance satellite fields (now exposed). Full audit of the other 22 customer-MCP write tools yielded zero further inverse phantoms — see `docs/audits/2026-04-21-mcp-inverse-phantom-audit.md`.
+
+### Added
+
+- **ADR-189 Phase 4 slice 3: `pica_claim_artist` MCP tool.** INSTANT path for artist-claim on discovery-backed evidence. Wraps `artistClaimingService.processClaimDecision` to reuse the existing `work_claims.artist_claim_status` / `claimed_by_person_id` / `claim_confirmed_at` update path + `performer` work_credits insert. Refuses (409 `ADMIN_REVIEW_IN_PROGRESS`) when an open admin `artist_claims` row exists for the same (work, person) — returns `admin_review_id` in the body so the agent surface can route the user to resolve it. Rate-limited to 20/hour per user via the shared `claim_write` bucket. Wrapped in `withAgentActionStamp` when grant-authed — rollback captures pre-write `work_claims` row + tracks whether a new performer credit was inserted (deleted on compensation) or pre-existed (left alone). **Schema drift carryover:** the plan proposed capturing rollback state from 4 `works` columns, but live staging (`rtxcxazevrgcjnudvggf`) keeps the artist-claim lifecycle columns (`artist_claim_status`, `claimed_by_person_id`, `claim_confirmed_at`) on the `work_claims` satellite — only `primary_artist_id` lives on `works`. Service captures + restores from `work_claims` accordingly. The live `artist_claims.claim_status` CHECK constraint has no `under_review` state (only `pending | approved | rejected | withdrawn`), so the open-review gate checks `claim_status = 'pending'` only.
+
+### Removed
+
+- **ADR-154 F13: seven deprecated per-source enrich tools removed.** `pica_enrich_work_{mlc,musicbrainz,discogs,spotify,youtube}` and `pica_people_enrich_{isni,musicbrainz}` (tombstoned since ADR-179 Phase 1/2, 2026-04-17) are no longer registered — every call has returned a `-32070 TOOL_DEPRECATED` error for a full minor cycle, ending the one-minor deprecation window per ADR-179 Decision 2. Callers must use `pica_resolve_work(sources: [...])` or `pica_resolve_person(sources: [...])` instead; the `tools/list`, `metadata`, `recovery-hints`, and category-`discovery` surfaces shed the seven stale entries in this release. Downstream impact: clients that hardcoded the tool names now get `tools/list`-level absence rather than a deprecation envelope — fail-fast instead of fail-with-suggestion.
+
+### Changed
+
+- **ADR-154 F14: completion-hint sweep for the seven removed tools.** Updated every `→ then:` and hint-string reference that pointed at the F13 tombstones across `enrichment.ts`, `people.ts` (3 sites), `collaborators.ts`, `works.ts` (2 sites), `search.ts`, `server-instructions.ts`, `prompts/index.ts` (3 sites), and `resources/llms-primer.ts`. Agents discovering tools via descriptions will no longer be trained toward dead tool names. The ADR-179 "Replaces the five/two per-source tools" phrasing is gone from the resolver descriptions too — resolvers stand on their own now.
+- **ADR-180 Phase 3: full TOOL_METADATA coverage.** 29 tools retrofitted in `mcp-server/src/tools/metadata.ts` across eight family-scoped commits — resolve (3), cascade (3), enrichment proposals (4), collaborators (4), notify-user scheduling (3), physical-assets links (4), misc singletons (5), and the ADR-185 Part 1 agent-identity drift (3). `scripts/mcp-tool-lint-baseline.json` is deleted; MCP Tool Lint now runs in fully-strict mode. No behaviour change — tool discovery, audit categorisation, and risk-tier gating now classify the same 29 tools they couldn't classify before. `credits_required` deliberately omitted from new entries (credit gating is a no-op pass-through since ADR-162). Retry-safety follows ADR-180's `risk × retry_safe` table — e.g. `pica_enrichment_proposal_apply` is `retry_safe: false` (writes to entity columns), `_reject` is `retry_safe: true` (content-hash suppression is set-once). ADR-180 flipped from `Proposed` to `Accepted`.
+- **ADR-193 Surfaces 1+3: peer-connector coaching + URI source conventions (server-instructions addendum).** Handshake copy coaches agents to check peer MCPs (email / drive / notes / calendar / DAW) before asking users to paste or type data, and to cite findings via `pica_enrichment_propose` `sources[].url` using URI schemes — `gmail://` `gdrive://` `notion://` `file://` `telegram://` `calendar://` `daw://` `user://` `web://`. See `docs/mcp-source-uri-conventions.md` in the main repo for shapes. First concrete build for ADR-190 Principles 2 + 3 (Agent-Mediated Source Discovery). A latent HTTP-transport gap was fixed in the same develop commit (`63eef17f8`) — `/api/mcp/route.ts` was not wiring `SERVER_INSTRUCTIONS` into its Server constructor, so remote agentic clients (ChatGPT Apps, Claude Desktop remote, Cursor) saw zero coaching. The stdio transport in this package was always serving instructions correctly; only the remote transport was affected.
+
+### Added
+
+- **ADR-193 Surface 2: `gap_hints` envelope on 4 read tools.** `pica_works_inspect`, `pica_agreements_inspect`, `pica_people_inspect`, and `pica_enrichment_proposals_list` now emit an optional `gap_hints[]` field on `structuredContent` when a real gap is present. Each hint is capability-named (ADR-190 Principle 2 — `email_search` / `drive_search` / `filesystem_search` / `notes_search` / `calendar_search` / `web_search`, never vendor names), carries a concrete `query_shape`, and pre-fills the `then_call: "pica_enrichment_propose"` with the exact `then_args_shape` the agent should emit back (including URI-citation scaffolding from Surface 3). Gated by `MCP_GAP_HINTS_ENABLED=1` — off by default in prod. Empty array / omitted envelope when there's no real gap. Flat additive — the existing `CompletionHint` pipeline on `works_inspect` is untouched. Bundled: `enrich-metadata` prompt references the peer-connector pattern and points the agent at `gap_hints`.
+- **ADR-193 Surface 4: `pica_enrichment_propose` accepts `proposal_action: "create"`.** Closes the reserved-but-unwired create path from ADR-178 Phase 1. The tool schema now accepts `entity_type: "recording" | "agreement" | "person"` paired with `parent_entity_type` + `parent_entity_id` for create proposals. Apply-path branches on `rule_id === "agent_research"` and routes to `recordingsService.create` (parent required; `work_id` linkage), `agreementsService.create` (optional work parent, linked via `agreementWorksService.addWork` after create), or `peopleAdminService.create` (standalone — people have no parent FK). Recording creates seed `field_sources` verbatim from `proposal.sources[].url`, preserving URI schemes (gmail://, gdrive://, notion://, file://, telegram://, user://, web://) per ADR-193 AC 5. Agreements + people don't carry `field_sources` on the main table today; provenance URIs are captured in `resolution_note` until a follow-up migration adds the column. Work + publisher creation remain explicitly out of scope (dedup-critical — deferred to future ADR). Migration `20260422_01_adr193_proposal_parent_fields` adds nullable `parent_entity_type` + `parent_entity_id` columns with a CHECK pair + partial index for the review-queue scan. Legacy `artist_title_to_youtube` create rule is untouched (it continues to overload `entity_id` as the parent work id). 4 new service-layer tests green; total proposal-service suite 42/42.
+- **ADR-185 Part 1: three new session-auth-only tools.** `pica_create_agent_identity`, `pica_issue_agent_grant`, `pica_list_my_agent_grants`. Back a user-issued agent-identity + scoped-grant primitive — the substrate for Parts 2 (settings UI) and 3 (per-write provenance stamping). All three require `write:agent_identity` scope AND session-auth (raw API key / OAuth); the HTTP MCP dispatcher refuses `pica_grant_` callers with a structured `reason: "session_auth_required"` error before execution per AC 12. Subject is always the authenticated user — caller-supplied `user_id` is dropped per ADR-184 rule 2 / ADR-185 rule 1. Grant tokens use the format `pica_grant_<64 hex>` and are hashed at rest with HMAC-SHA256 + `API_KEY_HASH_PEPPER` (same scheme as api_keys per ADR-185 line 193 + ADR-167 D-5).
+- **ADR-185 Part 2: two new session-auth-only tools.** `pica_revoke_agent_grant` (DELETE `/admin/agent-grants/:id`, idempotent, 404 masks ownership failures) and `pica_get_agent_activity` (GET `/admin/agent-activity`, paginated, optionally filtered by identity or grant). Both appended to `SESSION_AUTH_ONLY_TOOLS` in the HTTP MCP dispatcher and to the `write:agent_identity` scope bucket. Together with the Part 1 trio this completes the five-tool agent-identity surface the ADR Scope requires. Revocation takes effect on the next request (AC: within 60s — `resolveGrantToken` checks `revoked_at` on every call, no cache layer).
+- **ADR-185 Part 3 passes 1-5: agent-action provenance stamping wraps 27 write-tool families.** Part 3 layers two complementary wrappers over existing write tools so every per-grant write records a row in `mcp_agent_actions` for audit + revoke-replay. `withAgentActionStamp` (compensation-after): handler runs, stamps; on stamp failure, compensation undoes the write via captured prior state — used for creates and updates (soft-delete families get meaningful delete compensation — flip `is_deleted` back). `withAgentActionStampFirst` (stamp-first, pass 4): stamp commits BEFORE the destructive op; stamp-ok + handler-fail logs a "ghost stamp" at error level — used for hard-delete families where compensation is impossible. Both wrappers are no-ops when the caller is not an agent grant (session-auth / raw API key writes are unaffected). Families covered across the five passes: works/recordings/people/agreements/releases/notes creates; notes_delete; sessions_create; share_links_create; projects_create; multimedia_create; recording_splits_create; works_update; recordings_update; people_update; agreements_update; projects_update; notes_update; releases_update; people_delete; publishers_create; the six hard-delete families (works/recordings/agreements/projects/sessions/releases) via the stamp-first variant; and pass 5's `pica_projects_attach_works` (project_works insert wrapped, GET + POST migrated from `requireAuth` + `getUserProfile` to `withOrgContext` for consistency). `pica_sessions_update` remains deferred — action-branching route (start/complete/cancel + participant add/remove + regular update) needs a dedicated design slice before wrapping.
+- **New tool** `pica_submit_feedback`: agent-native feedback submission. Routes bug_report→devops, feature_request→ceo, question→comms, other→category-mapped. Requires `write:feedback` scope. Subject is always the authenticated user per ADR-184 rule 2. (ADR-184 slice 8 — landed on develop 2026-04-19 post-2.23.0 publish.)
+- **ADR-189 Phase 3: two new identity-capture tools.** `pica_update_my_identity` (stage_name / IPI / ISNI / IPN / PRO) and `pica_update_organisation_profile` (org_type / display_name / tagline / ipi_number). Both admin-scoped, both `retry_safe: true` (idempotent upserts — re-applying the same IPI leaves the row in the same state). Subject derived from auth (no `user_id` / `organisation_id` parameters — ADR-184 rule 2). After the identity write, `pica_update_my_identity` re-runs cross-org discovery and returns the count of newly-visible credits / custody / artist-link rows so the agent can surface "found N more — claim them?" in the same conversation turn. Rate-limited at 20 writes/hour/user via `checkActionRateLimit` (R1 mitigation). Admin routes (`POST /api/admin/my-identity`, `POST /api/admin/organisation-profile`) wrap in `withAgentActionStamp` when the caller presents an agent grant (ADR-185 Part 3) — UPDATE compensation captures pre-write state via read-before-write and PATCHes the row back on stamp failure, or deletes a lazy-created person row.
+- **ADR-189 Phase 4 Task 1: `pica_claim_credit`.** New activation-loop tool that drains a `discovered_credits` row into a `work_credits` row in the calling org, giving the user `view` access to the linked work. Check-and-set on `discovered_credits.status` prevents double-claims in concurrent sessions. Rate-limited to 20/hour per user via `checkActionRateLimit`. Returns `is_first_claim: true` on first-ever claim by the user (derived from `agent_action_log` stamp count). Wraps in `withAgentActionStamp` for grant callers — compensating transaction calls `revertClaimCredit` (flips discovery back to `pending` + deletes the `work_credits` row) if the stamp INSERT fails. Error taxonomy: `DISCOVERY_NOT_FOUND` (404), `DISCOVERY_ALREADY_RESOLVED` (409), `EVIDENCE_REVOKED` (410), `RATE_LIMITED` (429 + `Retry-After`). `pica_claim_credit` added to `ADMIN_ONLY_TOOLS` in `mcp-scopes.ts`; metadata entry `category: "discovery", risk: "mutating", retry_safe: false`. Route: `POST /api/admin/discoveries/[id]/claim-credit`. SDK method: `pica.discoveries.claimCredit(id)`.
+- **ADR-189 Phase 4 Task 2: `pica_claim_custody` + +72h auto-approve worker.** Drains a `discovered_custody` row into a pending `custody_claims` row (status=`pending`, `chain`=custody_type, `custody_source`=`claimed`, provenance in `evidence.source`=`"auto-discovered-via-email"`). Schedules a silent-consent auto-approve by inserting a `scheduled_notifications` row (`source=pica_claim_custody`, `deliver_at`=+72h, message=`custody_auto_approve:<uuid>`). Does NOT mutate `works.{composition,master}_custodian_org_id` immediately — the 1-minute cron fires `scheduledNotificationsService.drainDue()` which now dispatches `source=pica_claim_custody` rows to a new `handleCustodyAutoApprove` branch that runs the **Delta 1 stale-promotion guard**: UPDATE `works` custodian columns ONLY IF the snapshot captured at claim time (`expected_previous_custodian_org_id` + `expected_custody_source` + `custody_side` — migration `20260421_01_custody_claims_expected_previous`) still matches; otherwise flip the claim to `superseded` (new status) and leave the catalog untouched. Error taxonomy identical to `pica_claim_credit`. `pica_claim_custody` was already in `ADMIN_ONLY_TOOLS` since Phase 4 Task 0; this ships the actual wiring. Route: `POST /api/admin/discoveries/[id]/claim-custody`. SDK method: `pica.discoveries.claimCustody(id)`. Stamp compensation via `revertClaimCustody` flips discovery back to pending, cancels the scheduled_notification, deletes the custody_claims row.
+
+## [2.24.0] - 2026-04-21
+
+### Fixed
+
+- **`pica_integrations_status` no longer tells users to "connect Spotify".** Two real-user failures on Claude Desktop (2026-04-21) traced back to the tool lumping platform-level Spotify/YouTube (PICA has its own credentials; no per-user OAuth exists or has ever existed) into the same "Available to connect" list as genuine user-OAuth peer connectors (Google/Notion/Airtable/Telegram). Failure modes observed: (1) user pasted a Spotify track URL → agent replied "head to your Pica dashboard and add Spotify as an integration"; (2) user asked "what songs do I have in pica" with a catalog holding 1 work → agent replied "you currently have no connections set up in Pica — so there are no songs or any other data accessible." Reshape: the tool now returns `peerConnectors` (the 4 actual OAuth services) separately from `platformReads` (Spotify, YouTube, MusicBrainz, MLC, ISNI, Discogs, with the tool name for each). Summary leads with "PICA catalog is ALWAYS accessible via pica_works_query, pica_people_query, pica_dashboard_briefing, pica_search_all — no setup required." The dead `connectedProviders.includes("spotify")` check that could never evaluate true was removed.
+- **Server instructions: catalog-is-always-accessible guidance.** Handshake now explicitly states (a) the catalog is always accessible via the read tools with zero setup, (b) `pica_integrations_status` showing "0 connected" refers to optional peer connectors, NOT the catalog — call `pica_works_query` to check, (c) Spotify/YouTube URLs go through `pica_import_streaming_link` / `pica_import_youtube_link` directly; no per-user Spotify/YouTube OAuth exists to set up, do not tell the user to "connect Spotify in your dashboard". Replaces earlier copy that left the agent free to hallucinate a dashboard-integration flow. `lib/mcp/server-instructions.ts` parity copy updated in lockstep; the HTTP transport at `/api/mcp` picks up the new text on next handshake without requiring a redeploy of this package. Under the 2000-char token budget at 1833 chars.
+
+## [2.23.0] - 2026-04-19
+
+### Added
+
+- **ADR-181 Phase 1: `pica_audit_list` ported from `@withpica/mcp-server-settings`
+  (ADR-154 F6).** Closes the one trailing-gap tool from the source-merge audit —
+  every other tool the three sub-servers exposed was already registered by
+  `mcp-server`'s superset. Registered in `lib/services/mcp-scopes.ts`
+  `ADMIN_ONLY_TOOLS` alongside the team / org-profile admin operations; the
+  `mcp_audit_log` read is org-scoped and matches the existing admin posture
+  for `pica_organisation_profile` / `pica_team_list`. Landed in `54ae935d9`
+  via PR #50.
+- **ADR-181 Phase 1: bundle-size CI gate per Decision 2.** New
+  `scripts/check-mcp-bundle.ts` walks `mcp-server/dist/`, sums byte size
+  (excluding source maps), and fails if total > 210 MB (70% × Vercel's
+  300 MB serverless-function cap). Runs on every push / PR that touches
+  `mcp-server/**`, `mcp-server-shared/**`, the script, or the workflow
+  itself (`.github/workflows/mcp-bundle-size.yml`). `package.json`
+  `prepublishOnly` invokes it locally so a bloated bundle can't ship out
+  of a developer machine. Current measurement on this branch:
+  0.79 MB / 210 MB limit (0.38% of cap). Landed in `558315069` via PR #50.
+
+## [2.22.0] - 2026-04-18
+
+### Added
+
+- **ADR-174 Phase 2 item 7 follow-up: `pica_projects_attach_works` (stdio).**
+  Closes the `work_ids` FIELD_NOT_WIRED gap on `pica_projects_create` /
+  `_update`. Pre-slice the MCP tools advertised `work_ids` but the admin
+  route silently dropped it — the route redirect message already pointed
+  agents at `POST /api/admin/projects/[id]/works`, but no MCP tool
+  exposed that path. The new tool accepts
+  `{ project_id, works: [{ work_id, project_day?, notes? }...] }` and
+  attaches each item via `ProjectsResource.attachWork` with per-item
+  result reporting (`attached[]`, `skipped[]` for already-linked,
+  `failed[]` for other errors). Registered in `lib/services/mcp-scopes.ts`
+  under `write:catalog`.
+
+### Changed
+
+- **ADR-174 Phase 2 item 22: `pica_publishers_create` reshaped.** Pre-slice
+  the schema exposed only `{ name, ipi }` (2 fields) and the SDK's
+  `PublishersResource.create` hit a 404 — the admin route did not exist.
+  The companion slice 1 commit added `POST /api/admin/publishers`;
+  this slice reshapes the tool to match. All 8 audit-row-22
+  Add-candidates surfaced (`legal_name`, `country`, `isni`,
+  `publisher_type`, `wikidata_id`, `parent_publisher_id`,
+  `founded_date`, `headquarters`) plus the explicit `ipi → ipi_number`
+  rename. `parent_publisher_id` description steers agents at
+  `pica_publishers_query` to resolve the parent UUID. Required fields:
+  `name`, `ipi_number`. The route is idempotent on `ipi_number` — a
+  duplicate IPI returns the existing row with `already_existed: true`
+  instead of failing.
+
+- **ADR-174 Phase 2 items 14+15: `pica_agreements_create` / `_update`
+  reshaped to consume `AGREEMENTS_WRITE_PROPERTIES` from
+  `@withpica/mcp-utils`.** Tool schemas now advertise all 13
+  Add-candidate columns from audit rows 14+15. Tool descriptions steer
+  agents toward `counterparty_org_id` (ADR-176 first-class-party) over
+  free-text `other_party_name` — use `pica_search_all` to resolve an
+  org name to an ID. `_update` description calls out that
+  counterparty_org_id changes require the linked-org check at the
+  route layer (orgLinkingService.areLinked). No tool signature change
+  otherwise; existing fields preserved.
+
+### Route-side companion (non-package, same slice)
+
+- `app/api/admin/agreements/route.ts` POST and
+  `app/api/admin/agreements/[id]/route.ts` PATCH — phantom/unknown key
+  rejection via `AGREEMENT_POST_ALLOWED_FIELDS` /
+  `AGREEMENT_PATCH_ALLOWED_FIELDS` /
+  `AGREEMENT_WRITE_PHANTOM_REDIRECTS` in
+  `lib/services/agreements-write-constants.ts`. Pre-slice both routes
+  spread `body` straight into the Supabase insert/update — effectively
+  a wide-open write surface. Also surfaces and fixes pre-existing dark
+  code in the PATCH test file (3 tests were sending `name` and `type`
+  — phantom field names that silently dropped against `title` and
+  `agreement_type`).
+
+- `app/api/admin/publishers/route.ts` POST (NEW) — publishers had no
+  admin route at all pre-slice, so `pica_publishers_create` and the
+  SDK's `PublishersResource.create` 404'd at runtime. Slice 1
+  (0ba4d400d) adds the route with phantom/unknown-field rejection via
+  `PUBLISHERS_POST_ALLOWED_FIELDS` / `PUBLISHERS_WRITE_PHANTOM_REDIRECTS`
+  in `lib/services/publishers-write-constants.ts`, idempotent
+  deduplication by `ipi_number`, FK pre-validation on
+  `parent_publisher_id`, and server-stamped provenance.
+
+- **ADR-174 Phase 2 item 21: `pica_multimedia_create` reshaped.** Added
+  15 real-column fields that were invisible to agents pre-ADR-174:
+  `credits`, `duration_seconds`, `collection_id`, `display_order`,
+  `is_featured`, `is_published`, `venue`, `event_name`,
+  `performance_date`, `setlist_position`, `sync_side`, and the external
+  identifier set (`spotify_url`, `spotify_track_uri`, `spotify_track_id`,
+  `youtube_url`, `youtube_video_id`, `soundcloud_url`, `thumbnail_url`).
+  Description now points agents at `POST /api/admin/multimedia/upload`
+  for file uploads and `pica_multimedia_link_youtube` for the YouTube
+  enrichment flow — the generic create surface is for external-URL
+  linking and performance-context metadata.
+
+### Route-side companion (non-package, same slice)
+
+- `app/api/admin/multimedia/route.ts` POST — phantom/unknown key guard
+  via `MULTIMEDIA_POST_ALLOWED_FIELDS` /
+  `MULTIMEDIA_POST_PHANTOM_REDIRECTS` in
+  `lib/services/multimedia-write-constants.ts`. Redirects upload-flow
+  columns (s3*key, file_name, …) to `/api/admin/multimedia/upload`,
+  enrichment columns (youtube_view_count, spotify_popularity) to their
+  respective cascades, and scanner columns (virus_scan*\*) to the
+  scanner flow. Also closes a latent privilege-escalation path: pre-slice
+  the route overwrote `body.user_id` with the authenticated session's
+  id, but a caller could still _attempt_ to pass `user_id` (silently
+  overwritten). The guard now 400s on `user_id` / `organisation_id`
+  injection attempts with a clear PHANTOM_FIELD message.
+
+- **ADR-174 Phase 2 item 13: `pica_sessions_create` reshaped.** Dropped
+  `additionalProperties: true` per Decision 2. Added 6 previously-missing
+  real columns from audit row 13 as explicit Zod properties:
+  `description`, `timezone`, `is_all_day`, `location_url`, `recording_id`,
+  `status` (enum: scheduled / in_progress / completed / cancelled), plus
+  the `metadata` jsonb bag and the `participants` relational array
+  (already handled by the service but undocumented in the tool surface).
+  `recurrence_rule` deferred — the service's `CreateSessionParams` type
+  needs to accept it first (tracked in the route-guard PHANTOM_REDIRECT
+  entry).
+
+### Route-side companion (non-package, same slice)
+
+- `app/api/admin/sessions/route.ts` POST now reads `body.status` and
+  `body.metadata` (pre-slice silently dropped) and 400s on phantom /
+  unknown keys via `SESSION_POST_ALLOWED_FIELDS` /
+  `SESSION_POST_PHANTOM_REDIRECTS` in
+  `lib/services/sessions-write-constants.ts`.
+
+- **ADR-174 Phase 2 item 20: `pica_share_links_create` reshaped to
+  consume `SHARE_LINKS_WRITE_PROPERTIES` from `@withpica/mcp-utils`.**
+  Tool schema now advertises all 13 add-candidate columns from audit
+  row 20 that were previously invisible to agents (access_type,
+  allowed_person_ids, allow_comments, allow_view_collaborators,
+  allow_view_financials, notify_on_access, watermark_audio,
+  sent_to_emails, playlist_name, allow_streaming, include_all_files,
+  included_file_ids, description). Executor widened to pass every
+  caller-provided property through to the SDK / admin route — the
+  route-layer allow-list (slice 1) rejects anything outside the
+  contract. `password` remains the canonical plain-text input; the
+  route hashes to `password_hash`.
+
+- **ADR-174 Phase 2 items 16+17: `pica_agreement_types_create` / `_update`
+  reshaped to consume `AGREEMENT_TYPES_WRITE_PROPERTIES` from
+  `@withpica/mcp-utils`.** Dropped the inlined property map in favour of
+  the shared module that documents per-branch applicability. Phantom
+  fields `title`, `description`, `points_percentage`, `recoupment_terms`,
+  `rights_assigned` removed from the schema (agents sending them now fail
+  fast at the admin route guard with a `PHANTOM_FIELD` redirect pointing
+  at the canonical column or resolution path). Tool descriptions updated
+  to truthfully list the required fields per branch (template needs
+  `name` + `category` + `templateText`; producer needs `producer_id` +
+  `royalty_points` + `deliverables` + `work_id`|`recording_id`;
+  work_for_hire needs `contractor_id` + `contractor_role` + `fee_amount`
+  - `services_description` + `work_id`|`recording_id`). Tool description
+    for `_update` now calls out that PATCH on producer_agreements and
+    work_for_hire_agreements is action-only — the generic update path has
+    no live field-update surface on those two branches until a follow-up
+    slice promotes the action-based PATCH handlers to accept field
+    updates.
+
+### Added
+
+- **ADR-179 Phase 1: `pica_resolve_work` (stdio).** Outcome-shaped
+  resolver that fans a work out across every eligible enrichment source
+  in one call. Replaces the five `pica_enrich_work_*` tools' role at
+  the agent layer. Returns `applied[]` / `proposals[]` / `errors[]` /
+  `recovery_hints[]`. `isError` is set only when every source that ran
+  errored — partial failure is a non-error receipt. Credit + billing
+  gates wire through the `external_resolver_call` action key.
+- **ADR-179 Phase 2: `pica_resolve_person` (stdio).** Person-side
+  resolver mirroring `pica_resolve_work`. Sources are narrower —
+  `isni` | `musicbrainz` — covering the identity-graph cascade rules
+  (ISNI→Wikidata and MBID→Wikidata crosswalks plus their downstream
+  awards / biography enrichment). Same output shape, same isError
+  semantics, same credit-gate action key as the work resolver.
+  Registered in `lib/services/mcp-scopes.ts` under `write:people` and
+  listed in the layered-discovery `enrichment` category so
+  `pica_discover` surfaces it above the deprecated
+  `pica_people_enrich_*` pair.
+
+### Deprecated
+
+- **`pica_enrich_work_mlc`, `pica_enrich_work_musicbrainz`,
+  `pica_enrich_work_discogs`, `pica_enrich_work_spotify`,
+  `pica_enrich_work_youtube`.** All five now return
+  `TOOL_DEPRECATED` (jsonrpc code -32070) with a suggested-call
+  payload pointing at `pica_resolve_work` with the correct `sources`
+  narrowing. Tool definitions stay registered so `tools/list` and
+  `pica_tool_details` can still surface them with a migration hint for
+  one minor version — removal scheduled for the next minor after
+  ADR-179 Phase 4's publish.
+- **`pica_people_enrich_isni`, `pica_people_enrich_musicbrainz`.**
+  Both now return `TOOL_DEPRECATED` (jsonrpc code -32070) with a
+  suggested-call payload pointing at
+  `pica_resolve_person(sources: ['isni' | 'musicbrainz'])`. Tool
+  definitions stay registered until the next minor; same one-minor-
+  version deprecation window as the work-side five.
+
+### Changed
+
+- `pica_tool_details` responses for the five deprecated work tools
+  now carry a `TOOL_DEPRECATED` entry in `recovery_hints` as the first
+  item. Existing `NO_MATCH` / `MISSING_INPUT` hints are kept behind
+  it — they are dead code today but stay in the registry until tool
+  removal so downstream consumers don't see a mid-version
+  disappearance.
+- Same treatment applied to the two deprecated person tools:
+  `pica_people_enrich_isni` and `pica_people_enrich_musicbrainz` each
+  get a `TOOL_DEPRECATED` recovery hint prepended to their existing
+  `NO_MATCH` entry.
+
+## [2.22.0] — 2026-04-16
+
+### Changed
+
+- **ADR-174 Phase 2 item 10 (recording_splits): reshape
+  `pica_recording_splits_create`.** Adopts the shared
+  `RECORDING_SPLITS_WRITE_PROPERTIES` from `@withpica/mcp-utils@1.4.0`,
+  dropping `additionalProperties: true` per Decision 2. All 9 audit-
+  Keep fields now enumerated as explicit Zod properties — no phantom
+  additions, no renames. Description-level hint on `role` replaced
+  with a proper `enum` array matching the route's validRoles allow-
+  list. Schema is now byte-identical to `@withpica/mcp-server-business`
+  (both consume the shared module) — pre-slice they were independent
+  byte-divergent-risk copies.
+
+### Route-side companion (non-package, same slice)
+
+- `app/api/admin/recordings/[id]/splits/route.ts` POST — UNKNOWN_FIELD
+  guard runs before the required-field check so misspelled keys fail
+  fast with the field name. See the slice commit.
+
+## [2.21.0] — 2026-04-16
+
+### Fixed
+
+- **ADR-174 Phase 2 item 24 (team): `pica_team_update_role` now actually
+  updates role.** Pre-ADR-174 the tool was named `_update_role` but its
+  Zod schema only accepted `permissions` — the `role` field was missing
+  entirely. The admin PATCH route at `/api/admin/team/[id]` hard-
+  destructured `{ permissions }` and silently dropped every other
+  field, so even if an agent hand-crafted a call with `role` the DB
+  write would not happen. Audit row 24 flagged this as "Add `role`, or
+  rename the tool." Fixed by adding `role: string` to the MCP Zod
+  schema, widening the route to build the update object from whichever
+  of `role` / `permissions` are provided, and making the old
+  "permissions required" check accept "at least one of role or
+  permissions." `id` stays required; `role` and `permissions` are now
+  both optional but at least one must be set.
+
+### Route-side companion (non-package, same slice)
+
+- `app/api/admin/team/[id]/route.ts` PATCH — phantom/unknown key
+  rejection via `TEAM_MEMBERSHIP_PATCH_ALLOWED_FIELDS` (allow-list of
+  `permissions` + `role`), error message updated from "permissions
+  required" to "at least one of permissions or role is required", and
+  "failed to update permissions" to "failed to update team membership"
+  (now-generic — it updates role too).
+
+## [2.20.0] — 2026-04-16
+
+### Changed
+
+- **ADR-174 Phase 2 item 7 (projects): reshape `pica_projects_create` /
+  `pica_projects_update` Zod schemas.** Exposed 9 Add-candidate fields
+  from audit row 18 that were already plumbed end-to-end through the
+  route and service but invisible to agents via tool discovery:
+  `start_date`, `end_date`, `location_name`, `location_address`,
+  `location_url`, `virtual_url`, `is_open`, `max_participants`, `status`
+  (enum: draft / scheduled / active / completed / cancelled). Also
+  surfaced the route-level `generate_invite_code` flag and the
+  freeform `metadata` jsonb object. Dropped `work_ids` from both
+  schemas — the pre-ADR-174 tool advertised `work_ids` but the admin
+  POST / PATCH routes never routed it to the `project_works` junction
+  (see commit `edf890a24` for the route-side FIELD_NOT_WIRED rejection
+  and redirect message pointing at
+  `POST /api/admin/projects/[id]/works`). The `project_type`
+  description replaces the pre-ADR-174 "album, ep, compilation, single,
+  mixtape" hint (none of which are valid backend values) with the
+  actual convention: writing_camp, recording_session, production,
+  mixing, mastering, retreat, other.
+
+### Route-side companion (non-package, same slice)
+
+- `app/api/admin/projects/route.ts` POST and
+  `app/api/admin/projects/[id]/route.ts` PATCH — phantom/unknown key
+  rejection with `FIELD_NOT_WIRED` redirect for `work_ids`. See commit
+  `edf890a24`.
+
+## [2.19.0] — 2026-04-16
+
+### Added
+
+- **ADR-178: `pica_enrichment_propose` stdio tool.** New agentic write
+  tool that files enrichment proposals sourced from open-web research
+  (Audiomack, Songdata, MusicBrainz page, label portals, artist bios,
+  etc.) rather than from PICA's structured cascade. Every proposed
+  field must cite at least one source URL — `sources[].fields` arrays
+  form the trust moat, and the server rejects uncited claims with
+  `code: MISSING_SOURCE`. Source type routes the proposal as
+  `source = 'agent_research'`, `rule_id = 'agent_research'` on the
+  existing `enrichment_proposals` table (no new queue, no new review
+  tools — reuses `pica_enrichment_proposals_list` / `_apply` /
+  `_reject` from `2.10.0`).
+
+  Tool description carries ADR-178 Decision 3 language verbatim: when
+  the user is in-session, the agent asks for approval directly and
+  calls `pica_enrichment_proposal_apply` after confirmation — the
+  dashboard card is the receipt, not the workflow. This shapes agent
+  behaviour in-context without needing a new code path for "in-
+  session approval".
+
+  Wrapped in `withBillingGate` and (via
+  `@withpica/mcp-utils@1.3.0`) `withCreditGate` under the new
+  `enrichment_propose` action key. Credit gating is telemetric only
+  while ADR-162 keeps the subscription gate on; the wrap is already
+  in place so re-enabling billing doesn't need a tool-surface change.
+
+### Fixed
+
+- **ADR-178 slice 1b regression caught in smoke test:** agent-research
+  proposals whose `proposed_fields` cite columns that don't exist on
+  the target table (tempo_bpm, musical_key, producers — the Heinzmann
+  transcript's fields, not columns on `works`) used to 500 with a
+  Postgres "column does not exist" error because the service built a
+  column-scoped `SELECT` from the proposed keys. Fix snapshots the
+  full live row and builds `current_fields` from the intersection of
+  proposed keys and actual columns. Unknown keys now land as pending
+  proposals with an empty baseline instead of crashing the request.
+  Apply path for unknown-column fields is a separate open question on
+  the ADR (see Open Question 5).
+
+## [2.18.0] — 2026-04-16
+
+### Changed
+
+- **ADR-174 Phase 2 item 6: reshape `pica_credits_update` Zod schema.**
+  Dropped phantom `publisher_name` and `publisher_ipi` properties —
+  `work_credits` has no columns for either. Agents now resolve a
+  publisher name or IPI to a UUID via `pica_publishers_query` (or
+  create one via `pica_publishers_create`) and pass the result as
+  `publisher_id`. Added three audit "Add candidate" columns to the
+  per-credit-object shape: `is_primary` (boolean), `notes` (string),
+  `attestation_status` (enum: pending / attested / disputed /
+  declined). `attested_at` / `attested_by` remain service-managed.
+  Description refresh calls out `credit_type` as the canonical column
+  name stored behind the `role` alias and `writer_split_percentage`
+  behind `splits`. No required-field change — `person_id`, `role`,
+  `splits` stay required.
+
+### Route-side companion (non-package, same slice)
+
+- `app/api/admin/works/[id]/credits/route.ts` POST — phantom/unknown
+  key rejection on each `credits[i]` element with field name + index
+  in the error payload, plus a mirror-fill step that normalises
+  `role` ↔ `credit_type` and `splits` ↔ `writer_split_percentage` so
+  callers sending either spelling flow through. See commit
+  `dbfb098ae` for the server-side guard.
+
+### Not covered by this slice
+
+- `work_collaborators` (publishing-side POST at
+  `app/api/admin/works/[id]/collaborators/route.ts`) was not in the
+  ADR-174 audit — the MCP tool's `updateCollaborators` SDK hop hits
+  that route for writer/composer/lyricist/arranger roles today and
+  inherits a separate column set. Tracked as a follow-up slice.
+
+## [2.17.0] — 2026-04-16
+
+### Changed
+
+- **ADR-174 Phase 2 item 5: reshape `pica_physical_assets_create` and
+  `pica_physical_assets_update` Zod schemas.** Adopted the shared
+  `PHYSICAL_ASSETS_WRITE_PROPERTIES` from `@withpica/mcp-utils@1.2.0`,
+  dropped `additionalProperties: true` on both tools, and moved 11
+  phantom top-level fields (`current_valuation`, `valuation_currency`,
+  `valuation_source`, `valuation_date`, `valuation_notes`,
+  `reverb_listing_url`, `ebay_item_url`, `insured`,
+  `insurance_provider`, `insurance_policy_number`, `insurance_coverage`)
+  off the top-level surface. Agents set these via
+  `external_references: { current_valuation: 1500, insurer: "ACME", ... }`
+  per the ADR-174 Open Decision 1 (2026-04-14) resolution. Two fields
+  were renamed at the jsonb layer: `insurance_provider → insurer`,
+  `insurance_coverage → insured_value`. `asset_type`, `condition`,
+  `acquisition_method`, `license_type`, and `status` gained proper
+  `enum` arrays matching the underlying `physical_assets_*_check` CHECK
+  constraints — pre-reshape they were loose strings with the enum
+  hinted in the description (so callers could pass `studio_equipment`
+  at the MCP layer and get a 500 from the CHECK constraint at the DB
+  layer).
+- **No description lie.** Both tool descriptions now explicitly name
+  `external_references` as the home for valuation/insurance/DSP URL
+  details rather than the pre-ADR-174 "tracks … valuation, photos,
+  insurance, and status" claim that the schema couldn't honour.
+
+### Route-side companion (non-package, same slice)
+
+- `app/api/admin/assets/route.ts` POST and
+  `app/api/admin/assets/[id]/route.ts` PATCH — phantom/unknown key
+  rejection with redirect messages (400 + `PHANTOM_FIELD` /
+  `UNKNOWN_FIELD` error codes). See commit `ced46b889` for the
+  server-side guard.
+
+## [2.16.0] — 2026-04-15
+
+### Added
+
+- **ADR-173: five release-track tools.** Closes the gap flagged by two
+  independent external MCP reviewers on 2026-04-14 ("release layer looks
+  shallow"). New tools on the stdio transport:
+  - `pica_releases_attach_track` — attach a recording and/or work at a
+    specific `(disc_number, track_number)`. Idempotent on position.
+    At least one of `recording_id` / `work_id` is required.
+  - `pica_releases_list_tracks` — list tracks in `(disc, track)` order
+    with inlined title/artist/ISRC/duration from the linked recording
+    and work.
+  - `pica_releases_detach_track` — soft-confirmation detach by position
+    (preview without `confirm:true`, delete with).
+  - `pica_releases_reorder_tracks` — transactional positional reorder
+    via the `reorder_release_tracks_atomic` Postgres RPC. Rejects
+    duplicate positions in the payload before any DB write.
+  - `pica_releases_attach_recording_with_work` — compound workflow that
+    auto-pulls the recording's linked work onto the new track row.
+
+### Changed
+
+- **`pica_works_inspect` and `pica_recordings_inspect` gain a `releases`
+  section.** Lazy (only fetched when requested). Returns every release
+  the entity appears on with its track position. Answers "which albums
+  is this master on?" in one call — previously unanswerable via MCP.
+
+### Fixed
+
+- **`pica_releases_list_tracks` 500 on every call.** Pre-merge E2E
+  caught two latent bugs in the `listTracks` service query: a missing
+  FK `release_tracks.recording_id → recordings(id)` (PostgREST could
+  not resolve the `recording:recordings(...)` embed) and a
+  `duration_seconds` column reference where the live column is
+  `duration_ms`. Fixed in migration
+  `20260415_01_adr173_fix_release_tracks_recording_fk.sql` +
+  a rename in `lib/services/releases.ts`. The migration also NULLs 85
+  orphan `recording_id` values on production left behind by the
+  2026-04-04 soundslikefez duplicate-works cleanup.
+
+### Note on version number
+
+This release would have been `2.15.0` per the original ADR-173
+implementation record, but `2.15.0` was taken on `develop` by the
+ADR-174 Phase 2 item 4 slice while the ADR-173 fix commits were in
+flight. Bumped to `2.16.0` to keep the published package timeline
+linear.
+
+## [2.15.0] — 2026-04-15
+
+### Changed
+
+- **ADR-174 Phase 2 item 4: `pica_people_create` / `pica_people_update`
+  schema reconciliation.** Introduced `PEOPLE_WRITE_PROPERTIES` as the
+  canonical source of truth for the people write surface — every
+  property maps to a real column on either `public.people` or
+  `public.person_enrichment`. `additionalProperties: true` is off;
+  unknown keys 400 at the HTTP layer (see develop commit
+  `fbea9e2a3`).
+- **Satellite-routing made explicit.** Eleven fields remain in the
+  schema but their descriptions now name `person_enrichment` as the
+  write target: external identifiers (`isni`, `musicbrainz_id`,
+  `wikidata_id`, `discogs_artist_id`, `deezer_artist_id`) and
+  biographical data (`date_of_birth`, `gender`, `nationality`,
+  `birth_place`, `instruments`, `career_start_year`). The service
+  fans these out through `syncPersonEnrichmentSatellite`. Correction
+  to the original audit (row 7) landed in ADR-174's Corrections
+  block: six of these fields were classified as "Remove — no column
+  on people", which missed the satellite hop. They are not phantom
+  writes, and subsequent slices must audit satellite write paths
+  before classifying any field as phantom.
+- **Twelve add-candidates surfaced** (audit row 7 "Missing writable
+  columns"): `middle_name`, `person_type`, `company`, `position`,
+  `territory`, `social_media`, `emails`, `pro_name`,
+  `pro_member_number`, `mcps_member_number`, `relationship_strength`,
+  `email_preferences`. All verified against `public.people` columns
+  2026-04-15 (project `fwgcmjhlwevdnxgqmkmh`).
+- **Deprecated duplicates rejected.** `type` (deprecated dup of
+  `person_type`) and `role` (deprecated singular of `roles`) are
+  now 400 PHANTOM_FIELD with a redirect message naming the canonical
+  column. Both DB columns still exist as unused dead space —
+  removing them is out of scope and scheduled for ADR-165-style
+  cleanup.
+- **Description lies removed.** The audit (row 8) flagged
+  `pica_people_update` description as "Additional fields are also
+  accepted" with no enumeration. That sentence is gone from both
+  `create` and `update` descriptions.
+
+### Breaking
+
+- Callers that were passing the deprecated `type` / `role`
+  duplicates now get a 400 with a redirect hint — previously the
+  keys were silently dropped by the ORM. Same failure-mode calculus
+  as the works / recordings slices — the writes were already
+  failing, now they fail visibly.
+- Callers that were passing arbitrary unlisted keys now get a 400 —
+  previously `additionalProperties: true` let them through and the
+  ORM dropped them silently. Zero rows observed in `people.metadata`
+  jsonb for any of the pre-existing phantom keys (verified during
+  ADR-174 Phase 1 2026-04-14).
+
+## [2.14.0] — 2026-04-14
+
+### Changed
+
+- **ADR-174 Phase 2: `pica_recordings_create` / `pica_recordings_update`
+  schema reconciliation.** Introduced `RECORDING_WRITE_PROPERTIES` as
+  the canonical source of truth for the recordings write surface —
+  every property maps to a real column on `public.recordings`. Added
+  thirteen fields the DB exposes that the tool was hiding:
+  `duration_ms`, `preview_url`, `album_art_url`, `spotify_url`,
+  `spotify_track_uri`, `spotify_track_id`, `youtube_video_id`,
+  `youtube_url`, `apple_music_url`, `deezer_track_id`,
+  `mlc_recording_id`, `mlc_song_code`, `isrc_prefix`. The
+  `version_type` field is now enum-restricted to the ADR-166 values
+  (`master`, `alternate_master`, `music_video`, `lyric_video`,
+  `live_performance`, `acoustic`, `remix`, `cover`, `alternate`),
+  matching the `recordings_version_type_check` DB constraint.
+- **`pica_recordings_create` default `version_type` changed from
+  `"original"` to `"master"`.** Pre-fix the executor defaulted to
+  `"original"`, which is not a valid version_type — every call without
+  an explicit type tripped the recording-type CHECK constraint and
+  surfaced as a 500 from the service. `"master"` is the DB-level
+  default and the canonical ADR-166 value.
+- **Title rename made explicit.** `recording_title` is the canonical
+  column on `public.recordings`. The tool keeps `title` as an input
+  alias for ergonomics; the schema now declares both fields with the
+  rename called out in their descriptions, instead of relying on
+  `additionalProperties: true` to hide the translation.
+- Tool descriptions now steer album metadata (`album_name`,
+  `album_release_date`, `upc`, `track_number`) to
+  `pica_releases_create/update`, ISWCs to `pica_works_create/update`,
+  and label metadata to `pica_releases_*.label_organization_id` via
+  `pica_labels_query`. `duration_seconds` is explicitly named as the
+  works convention; `recordings` carries `duration_ms`.
+
+### Removed
+
+- **ADR-174 Phase 2: seven phantom fields rejected on
+  `pica_recordings_create` / `pica_recordings_update`.** The Zod schema
+  no longer accepts them and `additionalProperties: true` is gone:
+  `album_name`, `album_release_date`, `upc`, `track_number`, `label`,
+  `duration_seconds`, `iswc` — none of these corresponded to columns on
+  `recordings`. The HTTP route at `POST/PATCH /api/admin/recordings[/id]`
+  now 400s on any of these keys with a redirect message naming the
+  correct tool (commit `cffa6f947`).
+
+## [2.13.1] — 2026-04-14
+
+### Changed
+
+- **ADR-174 Phase 2: `pica_works_bulk_update.updates` schema gated on
+  `WORK_WRITE_PROPERTIES`.** The bulk tool was the last write-path
+  surface that still accepted any key — `updates: { type: "object" }`
+  with no property list (audit row 25). Now validates against the same
+  canonical schema as `pica_works_update`: phantom keys (label, upc,
+  album_name, …) and arbitrary unlisted keys fail fast with a
+  descriptive `VALIDATION_ERROR` before the SDK is called. One bad key
+  invalidates the whole batch — no partial writes.
+
+## [2.13.0] — 2026-04-14
+
+### Changed
+
+- **ADR-174 Phase 2: `pica_works_create` / `pica_works_update` schema
+  reconciliation.** Introduced `WORK_WRITE_PROPERTIES` as the canonical
+  source of truth for the works write surface — every property maps to
+  a real column on `public.works`. Added five fields the DB exposes
+  that the tool was hiding: `tempo`, `key`, `display_artist`,
+  `published`, `tunecode`. Tool descriptions now steer album/release
+  metadata (`album_name`, `album_art_url`, `track_number`, `upc`,
+  `spotify_url`) to `pica_releases_create/update` and label metadata to
+  `pica_releases_*.label_organization_id` via `pica_labels_query`.
+
+### Removed
+
+- **ADR-174 Phase 2: seven phantom fields removed from
+  `pica_works_create` / `pica_works_update`.** `label`, `spotify_url`,
+  `album_name`, `album_release_date`, `album_art_url`, `track_number`,
+  `upc` — none of these corresponded to columns on `works`. The HTTP
+  route at `POST/PATCH /api/admin/works[/id]` now 400s on any of these
+  keys with a redirect message naming the correct tool (commit
+  `9d68b16b1`). Previously they routed silently into the
+  `work_album_metadata` / `work_spotify_data` satellites that ADR-165
+  marked as dead — a write succeeded but no reader could find the
+  value.
+- **ADR-174 Phase 2: `additionalProperties: true` removed from both
+  works write schemas.** The tool no longer silently accepts arbitrary
+  keys; unknown keys surface as validation errors. Description lies
+  about `available_for_licensing`, `vocal_type`, `energy`,
+  `danceability` also removed — those fields live on satellite tables
+  and are not exposed through MCP.
+
+## [2.12.0] — 2026-04-14
+
+### Added
+
+- **ADR-174 Phase 2: `pica_labels_query` tool** — read-only resolution of
+  label names to `organisations.id`. Returns label organisations
+  (`org_type='label'`) whose name or display_name matches the substring
+  query, for use as `releases.label_organization_id` via
+  `pica_releases_create` / `pica_releases_update`. `query` and `limit`
+  both optional; limit defaults to 50, max 100. Category: catalog.
+  Annotations: `readOnlyHint: true`.
+
+### Changed
+
+- **ADR-174 Phase 2: `pica_releases_create` / `pica_releases_update`
+  schema reconciliation.** Input schemas now expose the nine ADR-174
+  Decision 3 fields that `releases` actually stores:
+  `label_organization_id`, `distributor_organization_id`,
+  `pre_release_date`, `artwork_url`, `spotify_album_uri`, `spotify_url`,
+  `apple_music_url`, `other_urls`, `notes`. Tool descriptions now
+  direct agents to call `pica_labels_query` (new) or `pica_search_all`
+  to resolve a label/distributor name to an organisation ID before
+  writing.
+
+### Removed
+
+- **ADR-174 Phase 2: freetext `label` removed from
+  `pica_releases_create` / `pica_releases_update`.** The field never
+  corresponded to a real column on `releases` — the DB models labels
+  via `label_organization_id` FK. Agents must now resolve a label name
+  to an organisation ID (via `pica_labels_query`) instead of passing a
+  string. Pre-fix behaviour: tool schema accepted `label`, service
+  propagated it to the DB, the DB rejected it as `42703 column does not
+exist`, every call 500'd. No working integrations could have relied
+  on this — the change is strictly a fix, not a break.
+
+## [2.11.0] — 2026-04-13
+
+### Changed
+
+- **ADR-171: Prompts replaced with workflow-level skills.**
+  11 prompts → 10 skills, each with decision trees, domain knowledge,
+  enrichment source priority, and the shared preamble (tone, prerequisite
+  check, summary pattern). Deployed as upgraded prompts; will convert to
+  MCP skills format when the spec extension ships.
+
+  New skills: `workspace-autopilot`, `establish-identity`,
+  `catalog-your-music`, `upload-and-analyse`, `close-the-loop`,
+  `manage-collaborators`, `establish-ownership`, `production-assets`,
+  `stay-connected`, `export-and-report`.
+
+  Retired prompts: `analyze-catalog`, `find-duplicates`,
+  `enrich-metadata`, `verify-works`, `assess-catalog-health`,
+  `audit-credits`, `new-catalog-setup`, `register-my-works`,
+  `prepare-for-sync`. Functionality folded into new skills —
+  see design spec for mapping.
+  - `workspace-autopilot` now routes through the full journey sequence
+    (identity → catalog → audio → gaps → collaborators → ownership →
+    notifications → exports) instead of the old 5-condition router.
+  - `close-the-loop` absorbs 7 former prompts and adds the enrichment
+    cascade decision tree (MLC first if IPI, MusicBrainz second, Spotify
+    third) and inline duplicate detection.
+  - `export-and-report` absorbs `analyze-catalog`, `register-my-works`,
+    and `prepare-for-sync` into a single export/report skill with CAR,
+    CWR, CSV, provenance, sync readiness, and carbon footprint paths.
+
+## [2.10.0] — 2026-04-11
+
+### Added
+
+- **ADR-163: Tier B enrichment proposal review tools.**
+  - `pica_enrichment_proposals_list` — list pending proposals
+    awaiting review. Filters: `entity_type`, `entity_id`,
+    `rule_id`, `source`, `limit` (1..100, default 20), `offset`.
+    Only `status='pending'` rows are returned. Backed by
+    `GET /api/admin/enrichment-proposals`.
+  - `pica_enrichment_proposal_apply` — apply a pending proposal.
+    For update proposals, runs drift detection first: if the
+    entity has changed since the proposal was created, returns
+    `{ status: 'drift_detected', conflicts }` without writing.
+    Agents surface conflicts to the user before retrying with
+    `force=true`. For create proposals (`artist_title_to_youtube`),
+    a uniqueness check runs instead and cannot be forced. Backed
+    by `POST /api/admin/enrichment-proposals/:id/apply`.
+  - `pica_enrichment_proposal_reject` — reject a pending proposal
+    with an optional `resolution_note`. Content-hash suppression
+    (ADR-163) permanently blocks re-proposal of identical content
+    — no cooldown, no timer. Backed by
+    `POST /api/admin/enrichment-proposals/:id/reject`.
+
+- **ADR-166: YouTube import as a recording-version source.**
+  - `pica_import_youtube_link` MCP tool wraps the Phase 3 orchestrator.
+    Takes a YouTube URL, returns a preview (items + classification +
+    work match), then `confirm: true` executes the import as a new
+    recording on an existing or newly-created work. Supports
+    `selectedVideoIds`, `targetWorkId`, and `overrideVersionType`
+    for fine-grained agent control. Landed in `78da58344`
+    (feat(adr-166): phase 4 — pica_import_youtube_link MCP tool + SDK
+    methods).
+
+### Changed
+
+- `pica_cascade_health` outcome bucket list extended to include
+  the ADR-163 Phase 1 `proposed` and `suppressed` outcomes. Tool
+  description now reads `wrote / no_match / already_enriched /
+error / proposed / suppressed`. Counters populate automatically
+  from `cascadeOutcomeCounter` — no schema change required for
+  existing `/api/admin/cascade-health` or
+  `/api/internal/cascade-health` consumers.
+
+- Several mcp-server source files got minor reformatting from ADR-165's
+  flattener strip (removing `work_spotify_data` + `work_album_metadata`
+  fields from the Work shape) and ADR-166's cascade rule rewrites.
+  These are consumer-invisible at the MCP tool surface — the tools
+  still accept the same inputs and return the same outputs — but the
+  underlying `PicaClient.works` reads + writes now route through the
+  ADR-165 overlay. See the ADR-165 and ADR-166 implementation records
+  for details.
+
+### Fixed
+
+- `pica_run_person_cascade` tool description had a dangling
+  `→ then: pica_people_inspect` chain with no parenthetical reason hint,
+  which the `composability-chains.test.ts` linter caught as a content
+  bug. Description updated to `→ then: pica_people_inspect (see what
+the cascade wrote)`. Fixed in `3a2843636` (test(mcp-server): fix 10
+  pre-existing test failures across 8 suites).
+
+### Notes
+
+- Backwards-compatible minor bump. Three new tools, one widened
+  description, no removals or signature changes.
+- Depends on `@withpica/mcp-sdk@^1.4.0` for the new
+  `EnrichmentResource.listEnrichmentProposals` /
+  `applyEnrichmentProposal` / `rejectEnrichmentProposal` methods.
+- Source additions landed across ADR-163 Phase 3d (`ff9cf265a`) and
+  Phase 6 (`ff97faa56`).
+- Registry: https://www.npmjs.com/package/@withpica/mcp-server/v/2.10.0
+- Published alongside `@withpica/mcp-sdk@1.4.0` and
+  `@withpica/mcp-server-business@1.3.0` in ADR-163 Phase 6.
+
+## [2.9.0] — 2026-04-11
+
+### Added
+
+- **ADR-164 audit follow-up: three new cascade MCP tools**
+  - `pica_run_work_cascade(work_id)` — manually re-evaluate a work
+    against every ADR-164 cascade rule and fire those whose
+    preconditions are satisfied. Idempotent. Fire-and-forget. Backed by
+    `POST /api/admin/works/:id/cascade-run`.
+  - `pica_run_person_cascade(person_id)` — same for people. Fires
+    `ipi_to_mlc_works` (MLC writer/publisher splits),
+    `mbid_to_wikidata_crosswalk`, `isni_to_wikidata_crosswalk`,
+    `wikidata_to_awards`, `wikidata_to_biography`, and
+    `google_contact_suggest`. Backed by
+    `POST /api/admin/people/:id/cascade-run`.
+  - `pica_cascade_health` — snapshot of in-process cascade counters
+    (ADR-164 Decision 5). Org-auth twin of the operator-only
+    `/api/internal/cascade-health` endpoint. Returns per-rule failure
+    counts bucketed by reason + outcome totals. Process-global, not
+    persistent across serverless cold starts — treat as a spot-check.
+
+### Notes
+
+- Source additions landed in `38901f281` (ADR-164 audit follow-ups).
+  Version bump + rebuilt dist + publish tagged in `edfbcb07b`.
+- Minor bump per semver — new tools, no removed or renamed surface.
+- Registry URL:
+  https://www.npmjs.com/package/@withpica/mcp-server/v/2.9.0
+- Tarball verified post-publish by pulling
+  `withpica-mcp-server-2.9.0.tgz` from the registry and grepping for
+  all three new tool names in `package/dist/tools/enrichment.js`.
+
+## [2.8.0] — 2026-04-10
+
+### Changed
+
+- **ADR-162: subscription-based billing, credit gating disabled.**
+  `withCreditGate` is now a pass-through — all tools are free for
+  active subscribers. The MPP (Micropayment Protocol) machinery is
+  retained in `@withpica/mcp-utils` for a future pay-per-credit
+  re-enable but is dormant. Version bump carried in `7c4f5d24a`
+  (`chore(adr-162): version bumps for npm publish`).
+
+## [2.7.0] — 2026-04-08
+
+### Added
+
+- **ADR-158c custody tool release.** Six `pica_custody_*` tools go
+  live: claim, accept, decline, dispute, incoming list, history.
+  Version bump in `91dd1c275` (`chore(adr-158c): version bumps for
+custody tool release (Phase 6b)`).
+
+## [2.6.2] — pre-2026-04-08
+
+### Fixed
+
+- Stale version constant in the boot banner — the banner was still
+  reporting an older version after an earlier bump. Fixed in
+  `980dabc02` (`fix(mcp-server): correct stale version constant in
+boot banner (2.6.2)`).
+
+## [2.6.1] — pre-2026-04-08
+
+### Fixed
+
+- MCP server now emits `tools/list_changed` + `resources/list_changed`
+  notifications after sign-in and sign-out, so clients refresh the
+  tool list without a reconnect. Fixed in `f1ba2a211`.
+
+## [2.6.0] — 2026-04-07
+
+### Changed
+
+- **ADR-155 launch — publish 6 packages.** Catalog server rebaselined
+  from the broken `3.0.0` publish (deprecated + unpublished from npm
+  because `file:` deps had been baked into the tarball, leaving every
+  fresh installer dead) to `2.6.0`. Five new sibling packages
+  (`@withpica/mcp-sdk`, `@withpica/mcp-utils`,
+  `@withpica/mcp-server-business`, `-enrichment`, `-settings`)
+  published at `1.0.0` alongside with real semver deps so `npm
+install` actually resolves on user machines.
+- `connect.withpica.com` leads with the no-api-key lobby-mode flow.
+  Landed in `e235aed40` (`feat(mcp): ADR-155 launch — publish 6
+packages, lobby-mode connect copy`).
+
+## Pre-2.6.0 — pre-changelog era
+
+Earlier versions (`2.0.0` through `2.5.x`) covered the pre-ADR-155
+monolithic MCP server. Version history for that era is reconstructable
+via `git log --follow -- mcp-server/package.json`. Notable milestones:
+
+- `2.5.x` — MCP Apps prebuild script + ext-apps devDependency added
+- `2.4.x` — build/publish polish, `.vercel/` excluded from tarball
+- `~2.0.0` — ADR-149 agentic hardening (write tiers, ProposedAction,
+  confirmation, audit, annotations)
+
+[Unreleased]: https://github.com/withpica/pica/compare/edfbcb07b...HEAD
+[2.9.0]: https://github.com/withpica/pica/compare/7c4f5d24a...edfbcb07b
+[2.8.0]: https://github.com/withpica/pica/compare/91dd1c275...7c4f5d24a
+[2.7.0]: https://github.com/withpica/pica/compare/980dabc02...91dd1c275
+[2.6.2]: https://github.com/withpica/pica/compare/f1ba2a211...980dabc02
+[2.6.1]: https://github.com/withpica/pica/compare/e235aed40...f1ba2a211
+[2.6.0]: https://github.com/withpica/pica/commit/e235aed40