@withpica/mcp-server 2.35.0 → 2.40.0

package/CHANGELOG.md

@@ -11,6 +11,294 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
@@ -69,7 +357,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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
+null, current_tier: null, capacity_pct: 0 }` rather than fabricating
   "active" — the agent never sees misleading "active" billing for an
   uninitialized context.
 

package/dist/apps/release.d.ts

@@ -0,0 +1,2 @@
+export declare const RELEASE_HTML: string;
+//# sourceMappingURL=release.d.ts.map

package/dist/apps/release.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release.d.ts","sourceRoot":"","sources":["../../src/apps/release.ts"],"names":[],"mappings":"AAwEA,eAAO,MAAM,YAAY,QAIxB,CAAC"}

package/dist/apps/release.js

@@ -0,0 +1,69 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+/**
+ * pica_release_show MCP App card — Phase 3 stub render.
+ *
+ * Renders three fields from `structuredContent`: title, markdown summary,
+ * cover image. No interactive affordances yet — full track-list expand,
+ * inline streaming embeds, and per-track agent links are queued under
+ * the ADR-200 Phase 1.x backlog.
+ *
+ * MCP Apps clients (Claude Desktop, Cursor) iframe this. Every other
+ * client ignores `_meta.ui` and renders the universal floor (image +
+ * text content blocks) per the 2025-11-25 image primitive.
+ *
+ * DOM API only — never innerHTML.
+ */
+import { buildAppHtml } from "./shared.js";
+const RELEASE_BODY = `
+<div class="stack gap-6">
+  <div id="rel-cover-wrap" style="display: none; text-align: center;">
+    <img id="rel-cover" alt="release cover art"
+         style="max-width: 320px; max-height: 320px; border-radius: 12px; border: 1px solid var(--card-border);" />
+  </div>
+
+  <header>
+    <h1 class="heading heading-lg" id="rel-title">release</h1>
+  </header>
+
+  <article id="rel-summary" class="card-flat" style="padding: 16px 20px;">
+    <div id="rel-markdown" class="text-primary" style="white-space: pre-wrap; font-size: 14px; line-height: 1.6;"></div>
+  </article>
+</div>
+
+<style>
+#rel-cover { display: block; margin: 0 auto; }
+#rel-markdown { font-family: inherit; }
+#rel-summary { background: rgba(255,255,255,0.03); }
+</style>
+`;
+const RELEASE_JS = `
+var relState = { title: null, markdown: null, cover_base64: null, cover_mime_type: null };
+
+function relRender() {
+  var titleEl = document.getElementById("rel-title");
+  if (titleEl && relState.title) titleEl.textContent = relState.title;
+
+  var mdEl = document.getElementById("rel-markdown");
+  if (mdEl && relState.markdown) mdEl.textContent = relState.markdown;
+
+  if (relState.cover_base64 && relState.cover_mime_type) {
+    var coverEl = document.getElementById("rel-cover");
+    var wrapEl = document.getElementById("rel-cover-wrap");
+    if (coverEl && wrapEl) {
+      coverEl.src = "data:" + relState.cover_mime_type + ";base64," + relState.cover_base64;
+      wrapEl.style.display = "block";
+    }
+  }
+}
+
+window.onPicaToolResult = function (data) {
+  if (!data) return;
+  if (data.title) relState.title = data.title;
+  if (data.markdown) relState.markdown = data.markdown;
+  if (data.cover_base64) relState.cover_base64 = data.cover_base64;
+  if (data.cover_mime_type) relState.cover_mime_type = data.cover_mime_type;
+  relRender();
+};
+`;
+export const RELEASE_HTML = buildAppHtml("pica — release", RELEASE_BODY, RELEASE_JS);
+//# sourceMappingURL=release.js.map

package/dist/apps/release.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"release.js","sourceRoot":"","sources":["../../src/apps/release.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;CAqBpB,CAAC;AAEF,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BlB,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAG,YAAY,CACtC,gBAAgB,EAChB,YAAY,EACZ,UAAU,CACX,CAAC"}

package/dist/resources/agent-guide.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ADR-214 — workflow narrative for agents.
+ *
+ * Two markdown constants. ResourceRegistry serves AGENT_GUIDE_LOBBY when
+ * config.lobbyMode || !pica, AGENT_GUIDE_AUTHENTICATED otherwise.
+ *
+ * Tool sequences are verbatim from ADR-214 Decision section "Top
+ * workflows" — audit-verified 2026-04-30 against the live ToolRegistry.
+ *
+ * Edits to this file are linted by scripts/lint-agent-guide.ts: every
+ * `pica_*` token must resolve to a real tool in ToolRegistry.
+ */
+export declare const AGENT_GUIDE_AUTHENTICATED = "# pica \u2014 agent guide\n\npica manages a music catalog: works (compositions), recordings (masters),\npeople (writers, performers, publishers), credits, agreements, exports.\nmulti-tenant per organisation; every write is org-scoped automatically.\n\nyou are signed in. ~227 tools are available. five core workflows below\ncover most of the surface; for anything not listed, fall back to\n`pica_discover` (mode: list_categories \u2192 list_tools) \u2192 `pica_tool_details`.\n\n## top workflows\n\n### register a new work\n1. `pica_works_create` \u2014 title required; iswc settable inline.\n2. `pica_credits_update` \u2014 batch; attach writer/composer credits.\n   writer_split_percentage values must sum to 100 across all writer rows.\n   see `pica://schemas/work-required` and `pica://schemas/work-credits-required`.\n\n### add a recording to an existing work\n- `pica_recordings_create` \u2014 title + artist_name + version_type required\n  (version_type defaults to `master`). isrc and duration_ms are inline.\n- see `pica://schemas/recording-required`.\n\n### add audio to a recording\n1. `pica_audio_presigned_upload` \u2014 returns a signed url + token.\n2. uploader (browser, curl, sdk) PUTs the file to that url.\n3. `pica_audio_complete_upload` \u2014 registers the upload in the catalog.\n4. (optional) `pica_audio_analyze` \u2014 async; extracts bpm, key, mood, and\n   transcribes lyrics via whisper.\n5. `pica_audio_inspect` (sections: [\"analysis\", \"status\"]) \u2014 poll for\n   analysis results when you called step 4.\n\n### add recording credits\n- `pica_recording_credits_update` \u2014 batch. role enum is DISTINCT from\n  work credits (MainArtist / FeaturedArtist / Producer / Engineer / etc.).\n- person_id is OPTIONAL \u2014 credits can carry just credited_name when the\n  person isn't in the catalog yet.\n- see `pica://schemas/recording-credits-required`.\n\n### enrich existing metadata\n1. `pica_resolve_work` / `pica_resolve_person` / `pica_resolve_recording` \u2014\n   tier A identifier matches apply directly; tier B fuzzy matches queue\n   as proposals.\n2. `pica_enrichment_proposals_list` \u2014 view pending proposals.\n3. `pica_enrichment_proposal_apply` \u2014 commit a proposal you've reviewed.\n\n## common gotchas\n\n- **duration units differ.** `works.duration_seconds` (integer seconds);\n  `recordings.duration_ms` (integer milliseconds);\n  `audio_files.duration_seconds` (seconds again).\n- **no standalone identifier-assign tool.** iswc on works, isrc on\n  recordings, ipi/pro/ppl/mcps numbers on people \u2014 all inline at create\n  or update. there is no separate identifier tool family; don't search\n  for one.\n- **two write surfaces for work collaborators.** `pica_credits_update`\n  is canonical (writer/publisher splits + attestation). `work_collaborators`\n  is a simpler legacy surface still used by some flows.\n- **recording credits are a separate surface** with a different role\n  enum. use `pica_recording_credits_update`, not `pica_credits_update`.\n- **people identifier sprawl.** inline columns: `cae_ipi_number`,\n  `ipn_number`, `prs_number`, `ppl_number`, `pro_member_number`,\n  `mcps_member_number`. satellite (settable through the same create/update\n  call): `isni`, `musicbrainz_id`, `wikidata_id`, `discogs_artist_id`,\n  `imdb_id`, `viaf_id`, `deezer_artist_id`. treat as one inline surface.\n- **audio analysis is async + explicit.** `pica_audio_complete_upload`\n  does NOT auto-trigger analysis. call `pica_audio_analyze` and poll.\n- **lyrics from analysis don't auto-write back to `works.lyrics`.**\n  whisper transcripts land on the analysis row; copy is a separate step.\n- **org scoping + duplicate prevention.** every write is scoped to the\n  caller's organisation. iswc and isrc duplicates are blocked at write.\n\n## schema resources (pre-flight before each workflow)\n\n- `pica://schemas/work-required` \u2014 backs `pica_works_create`.\n- `pica://schemas/recording-required` \u2014 backs `pica_recordings_create`.\n- `pica://schemas/work-credits-required` \u2014 backs `pica_credits_update`.\n- `pica://schemas/recording-credits-required` \u2014 backs `pica_recording_credits_update`.\n- `pica://schemas/person-required` \u2014 backs `pica_people_create`.\n\neach schema returns a json contract: required fields, recommended fields,\nCHECK enum values, companion-call orchestration, and an example payload.\n";
+export declare const AGENT_GUIDE_LOBBY = "# pica \u2014 sign in to begin\n\nyou are in lobby mode. three tools are available; the rest unlock after\nsign-in.\n\n## lobby tools\n- `pica_signup_start` \u2014 create a new organisation and get a magic link\n  for first-time setup.\n- `pica_sign_in` \u2014 request a magic link for an existing user.\n- `pica_sign_out` \u2014 drop session.\n\n## to sign in\n1. ask the user for an email address.\n2. call `pica_signup_start` (new user) or `pica_sign_in` (returning).\n3. user clicks the magic link. on the next request, the catalog tool\n   surface unlocks automatically \u2014 no config to refresh.\n\n## what unlocks after sign-in\n~227 tools across catalog (works, recordings, people, credits),\nenrichment, exports, agreements, multimedia, analytics, and audio. five\nrequired-fields schema resources at `pica://schemas/<workflow>-required`.\nthe full agent-guide replaces this lobby content.\n";
+//# sourceMappingURL=agent-guide.d.ts.map

package/dist/resources/agent-guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-guide.d.ts","sourceRoot":"","sources":["../../src/resources/agent-guide.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,yBAAyB,2zIAkFrC,CAAC;AAEF,eAAO,MAAM,iBAAiB,24BAsB7B,CAAC"}

package/dist/resources/agent-guide.js

@@ -0,0 +1,120 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+/**
+ * ADR-214 — workflow narrative for agents.
+ *
+ * Two markdown constants. ResourceRegistry serves AGENT_GUIDE_LOBBY when
+ * config.lobbyMode || !pica, AGENT_GUIDE_AUTHENTICATED otherwise.
+ *
+ * Tool sequences are verbatim from ADR-214 Decision section "Top
+ * workflows" — audit-verified 2026-04-30 against the live ToolRegistry.
+ *
+ * Edits to this file are linted by scripts/lint-agent-guide.ts: every
+ * `pica_*` token must resolve to a real tool in ToolRegistry.
+ */
+export const AGENT_GUIDE_AUTHENTICATED = `# pica — agent guide
+
+pica manages a music catalog: works (compositions), recordings (masters),
+people (writers, performers, publishers), credits, agreements, exports.
+multi-tenant per organisation; every write is org-scoped automatically.
+
+you are signed in. ~227 tools are available. five core workflows below
+cover most of the surface; for anything not listed, fall back to
+\`pica_discover\` (mode: list_categories → list_tools) → \`pica_tool_details\`.
+
+## top workflows
+
+### register a new work
+1. \`pica_works_create\` — title required; iswc settable inline.
+2. \`pica_credits_update\` — batch; attach writer/composer credits.
+   writer_split_percentage values must sum to 100 across all writer rows.
+   see \`pica://schemas/work-required\` and \`pica://schemas/work-credits-required\`.
+
+### add a recording to an existing work
+- \`pica_recordings_create\` — title + artist_name + version_type required
+  (version_type defaults to \`master\`). isrc and duration_ms are inline.
+- see \`pica://schemas/recording-required\`.
+
+### add audio to a recording
+1. \`pica_audio_presigned_upload\` — returns a signed url + token.
+2. uploader (browser, curl, sdk) PUTs the file to that url.
+3. \`pica_audio_complete_upload\` — registers the upload in the catalog.
+4. (optional) \`pica_audio_analyze\` — async; extracts bpm, key, mood, and
+   transcribes lyrics via whisper.
+5. \`pica_audio_inspect\` (sections: ["analysis", "status"]) — poll for
+   analysis results when you called step 4.
+
+### add recording credits
+- \`pica_recording_credits_update\` — batch. role enum is DISTINCT from
+  work credits (MainArtist / FeaturedArtist / Producer / Engineer / etc.).
+- person_id is OPTIONAL — credits can carry just credited_name when the
+  person isn't in the catalog yet.
+- see \`pica://schemas/recording-credits-required\`.
+
+### enrich existing metadata
+1. \`pica_resolve_work\` / \`pica_resolve_person\` / \`pica_resolve_recording\` —
+   tier A identifier matches apply directly; tier B fuzzy matches queue
+   as proposals.
+2. \`pica_enrichment_proposals_list\` — view pending proposals.
+3. \`pica_enrichment_proposal_apply\` — commit a proposal you've reviewed.
+
+## common gotchas
+
+- **duration units differ.** \`works.duration_seconds\` (integer seconds);
+  \`recordings.duration_ms\` (integer milliseconds);
+  \`audio_files.duration_seconds\` (seconds again).
+- **no standalone identifier-assign tool.** iswc on works, isrc on
+  recordings, ipi/pro/ppl/mcps numbers on people — all inline at create
+  or update. there is no separate identifier tool family; don't search
+  for one.
+- **two write surfaces for work collaborators.** \`pica_credits_update\`
+  is canonical (writer/publisher splits + attestation). \`work_collaborators\`
+  is a simpler legacy surface still used by some flows.
+- **recording credits are a separate surface** with a different role
+  enum. use \`pica_recording_credits_update\`, not \`pica_credits_update\`.
+- **people identifier sprawl.** inline columns: \`cae_ipi_number\`,
+  \`ipn_number\`, \`prs_number\`, \`ppl_number\`, \`pro_member_number\`,
+  \`mcps_member_number\`. satellite (settable through the same create/update
+  call): \`isni\`, \`musicbrainz_id\`, \`wikidata_id\`, \`discogs_artist_id\`,
+  \`imdb_id\`, \`viaf_id\`, \`deezer_artist_id\`. treat as one inline surface.
+- **audio analysis is async + explicit.** \`pica_audio_complete_upload\`
+  does NOT auto-trigger analysis. call \`pica_audio_analyze\` and poll.
+- **lyrics from analysis don't auto-write back to \`works.lyrics\`.**
+  whisper transcripts land on the analysis row; copy is a separate step.
+- **org scoping + duplicate prevention.** every write is scoped to the
+  caller's organisation. iswc and isrc duplicates are blocked at write.
+
+## schema resources (pre-flight before each workflow)
+
+- \`pica://schemas/work-required\` — backs \`pica_works_create\`.
+- \`pica://schemas/recording-required\` — backs \`pica_recordings_create\`.
+- \`pica://schemas/work-credits-required\` — backs \`pica_credits_update\`.
+- \`pica://schemas/recording-credits-required\` — backs \`pica_recording_credits_update\`.
+- \`pica://schemas/person-required\` — backs \`pica_people_create\`.
+
+each schema returns a json contract: required fields, recommended fields,
+CHECK enum values, companion-call orchestration, and an example payload.
+`;
+export const AGENT_GUIDE_LOBBY = `# pica — sign in to begin
+
+you are in lobby mode. three tools are available; the rest unlock after
+sign-in.
+
+## lobby tools
+- \`pica_signup_start\` — create a new organisation and get a magic link
+  for first-time setup.
+- \`pica_sign_in\` — request a magic link for an existing user.
+- \`pica_sign_out\` — drop session.
+
+## to sign in
+1. ask the user for an email address.
+2. call \`pica_signup_start\` (new user) or \`pica_sign_in\` (returning).
+3. user clicks the magic link. on the next request, the catalog tool
+   surface unlocks automatically — no config to refresh.
+
+## what unlocks after sign-in
+~227 tools across catalog (works, recordings, people, credits),
+enrichment, exports, agreements, multimedia, analytics, and audio. five
+required-fields schema resources at \`pica://schemas/<workflow>-required\`.
+the full agent-guide replaces this lobby content.
+`;
+//# sourceMappingURL=agent-guide.js.map

package/dist/resources/agent-guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-guide.js","sourceRoot":"","sources":["../../src/resources/agent-guide.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkFxC,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;CAsBhC,CAAC"}

package/dist/resources/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAO/C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAK5C,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,KAAK,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;CACJ;AAED,MAAM,MAAM,cAAc,GAAG,GAAG,CAAC;AAEjC,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,IAAI,CAAoB;IAChC,OAAO,CAAC,MAAM,CAAC,CAAe;gBAElB,IAAI,EAAE,UAAU,GAAG,IAAI,EAAE,MAAM,CAAC,EAAE,YAAY;IAK1D;;OAEG;IACH,aAAa,IAAI,kBAAkB,EAAE;IA8FrC;;OAEG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IA8G7C;;OAEG;IACH,OAAO,CAAC,cAAc;IA6BtB;;OAEG;YACW,YAAY;IA4B1B;;OAEG;YACW,aAAa;IA4B3B;;OAEG;YACW,iBAAiB;IA2B/B;;OAEG;YACW,eAAe;IAoD7B;;OAEG;YACW,gBAAgB;IAc9B;;OAEG;YACW,mBAAmB;IAcjC;;OAEG;YACW,eAAe;CAa9B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAY/C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAM5C,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,KAAK,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;CACJ;AAED,MAAM,MAAM,cAAc,GAAG,GAAG,CAAC;AAEjC,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,IAAI,CAAoB;IAChC,OAAO,CAAC,MAAM,CAAC,CAAe;gBAElB,IAAI,EAAE,UAAU,GAAG,IAAI,EAAE,MAAM,CAAC,EAAE,YAAY;IAK1D;;OAEG;IACH,aAAa,IAAI,kBAAkB,EAAE;IA+IrC;;OAEG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IA4J7C;;OAEG;IACH,OAAO,CAAC,cAAc;IA6BtB;;OAEG;YACW,YAAY;IA4B1B;;OAEG;YACW,aAAa;IA4B3B;;OAEG;YACW,iBAAiB;IA2B/B;;OAEG;YACW,eAAe;IAoD7B;;OAEG;YACW,gBAAgB;IAc9B;;OAEG;YACW,mBAAmB;IAcjC;;OAEG;YACW,eAAe;CAa9B"}

package/dist/resources/index.js

@@ -3,8 +3,11 @@ import { ResourceError } from "@withpica/mcp-utils";
 import { readFileSync } from "fs";
 import { join } from "path";
 import { WITHPICA_PRIMER } from "./llms-primer.js";
+import { AGENT_GUIDE_AUTHENTICATED, AGENT_GUIDE_LOBBY, } from "./agent-guide.js";
+import { REQUIRED_SCHEMAS } from "./required-schemas.generated.js";
 import { UPLOAD_HTML } from "../apps/upload.js";
 import { DOWNLOAD_HTML } from "../apps/download.js";
+import { RELEASE_HTML } from "../apps/release.js";
 import { PICA_STORAGE_CONNECT_DOMAINS } from "../apps/shared.js";
 export class ResourceRegistry {
     pica;
@@ -24,6 +27,12 @@ export class ResourceRegistry {
                 description: "Getting started guide — how to sign in and what you can do",
                 mimeType: "text/markdown",
             },
+            {
+                uri: "pica://docs/agent-guide",
+                name: "Agent Guide — How to Use PICA",
+                description: "Workflow-by-workflow guide for agents — what tools to call in what order, common gotchas, pointers to schema resources. Lobby mode returns a sign-in-focused variant; authenticated mode returns the full workflow map.",
+                mimeType: "text/markdown",
+            },
         ];
         if (this.config?.lobbyMode || !this.pica) {
             return resources;
@@ -83,6 +92,36 @@ export class ResourceRegistry {
             name: "Download File",
             description: "File download card — shows file metadata and a download button",
             mimeType: "text/html;profile=mcp-app",
+        }, {
+            uri: "ui://pica/release",
+            name: "Release Card",
+            description: "Release rich-render card — cover art + markdown summary (ADR-208 Phase 3 Primitive D, Phase 3 stub)",
+            mimeType: "text/html;profile=mcp-app",
+        }, {
+            uri: "pica://schemas/work-required",
+            name: "Required Fields — Register a Work",
+            description: "Required + recommended fields, CHECK enums, and companion-call orchestration for pica_works_create. Read before calling the work-create workflow.",
+            mimeType: "application/json",
+        }, {
+            uri: "pica://schemas/recording-required",
+            name: "Required Fields — Register a Recording",
+            description: "Required + recommended fields, CHECK enums, and companion-call orchestration for pica_recordings_create.",
+            mimeType: "application/json",
+        }, {
+            uri: "pica://schemas/work-credits-required",
+            name: "Required Fields — Attach Work Credits",
+            description: "Per-row required fields and CHECK enums for pica_credits_update (writer/composer/publisher splits, sum to 100).",
+            mimeType: "application/json",
+        }, {
+            uri: "pica://schemas/recording-credits-required",
+            name: "Required Fields — Attach Recording Credits",
+            description: "Per-row required fields and the role enum for pica_recording_credits_update (MainArtist / FeaturedArtist / Producer / Engineer / etc.).",
+            mimeType: "application/json",
+        }, {
+            uri: "pica://schemas/person-required",
+            name: "Required Fields — Register a Person",
+            description: "Required + recommended fields for pica_people_create (writers, performers, publishers; identifiers settable inline).",
+            mimeType: "application/json",
         });
         return resources;
     }
@@ -112,6 +151,18 @@ export class ResourceRegistry {
                         },
                     ],
                 };
+            case "pica://docs/agent-guide": {
+                const lobby = this.config?.lobbyMode || !this.pica;
+                return {
+                    contents: [
+                        {
+                            uri: "pica://docs/agent-guide",
+                            mimeType: "text/markdown",
+                            text: lobby ? AGENT_GUIDE_LOBBY : AGENT_GUIDE_AUTHENTICATED,
+                        },
+                    ],
+                };
+            }
             default:
                 break;
         }
@@ -179,6 +230,35 @@ export class ResourceRegistry {
                         },
                     ],
                 };
+            case "ui://pica/release":
+                return {
+                    contents: [
+                        {
+                            uri: "ui://pica/release",
+                            mimeType: "text/html;profile=mcp-app",
+                            text: RELEASE_HTML,
+                        },
+                    ],
+                };
+            case "pica://schemas/work-required":
+            case "pica://schemas/recording-required":
+            case "pica://schemas/work-credits-required":
+            case "pica://schemas/recording-credits-required":
+            case "pica://schemas/person-required": {
+                const key = uri.replace("pica://schemas/", "");
+                const body = REQUIRED_SCHEMAS[key];
+                if (!body)
+                    throw new ResourceError(`Schema not found: ${uri}`);
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: "application/json",
+                            text: JSON.stringify(body, null, 2),
+                        },
+                    ],
+                };
+            }
             default:
                 throw new ResourceError(`Resource not found: ${uri}`);
         }