@withpica/mcp-server 1.3.0

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. ~232 tools are available. fourteen 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- see `pica://schemas/audio-upload-required`.\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   `pica_enrichment_proposal_reject` \u2014 dismiss with content-hash suppression.\n- see `pica://schemas/enrichment-resolve-required`.\n\n### create an agreement\n1. `pica_agreements_create` \u2014 title + agreement_type + other_party_name\n   required. prefer counterparty_org_id (FK) over free-text other_party_name.\n2. `pica_agreements_link_work` \u2014 attach works (optional royalty_split per work).\n3. `pica_agreement_templates_render` \u2014 template-driven alternative.\n- see `pica://schemas/agreement-required`.\n\n### add multimedia\n- `pica_multimedia_create` \u2014 title + content_type required.\n- `pica_multimedia_link_youtube` \u2014 YouTube videos (auto-enriched).\n- `pica_multimedia_import_url` \u2014 external image / video URL (downloads\n  into PICA storage).\n- `pica_multimedia_link_work` \u2014 attach to a work (relationship_type required).\n- see `pica://schemas/multimedia-required`.\n\n### log a studio session\n1. (optional) `pica_sessions_types` \u2014 pre-flight to discover valid\n   `session_type_id` values for this org. Lookup table; org-scoped.\n2. `pica_sessions_create` \u2014 title + start_time + end_time (ISO 8601).\n   session_type_id, location, work_id, recording_id, participants are\n   all optional inline fields.\n3. `pica_sessions_get` / `pica_sessions_list` \u2014 read-back / browse.\n- the `status` enum (scheduled / in_progress / completed / cancelled) is\n  documented but NOT enforced by a DB CHECK \u2014 values may evolve.\n- see `pica://schemas/session-required`.\n\n### generate a split sheet (publishing royalties on a work)\n1. **pre-condition:** writer credits on the work must already total 100%\n   via `pica_credits_update`. `pica_split_sheet_generate` returns 400\n   otherwise.\n2. `pica_split_sheet_generate` \u2014 work_id only; snapshots current splits.\n3. `pica_split_sheet_send` \u2014 notify each credited writer for signature\n   via in-app + Telegram + email. Non-PICA-user writers get a\n   collaboration invite email instead. Per-writer soft-fails.\n4. `pica_split_sheet_get` / `pica_split_sheet_list` \u2014 read-back.\n- see `pica://schemas/split-sheet-required`.\n\n### assign master ownership splits (recording rights)\n- DISTINCT from publishing splits above. Recording splits live on\n  `recording_splits`, not `work_credits`. Drives master royalty payouts\n  + downstream credit gating.\n1. `pica_recording_splits_create` \u2014 recording_id + split_type\n   (master / mechanical / performance / sync) + percentage required.\n   role / person_id / territory / start_date / end_date optional.\n   Use `dry_run: true` for a no-op preview before committing.\n   ADR-200 form-confirmation gate fires on connectors that support\n   `elicitation/url`.\n2. `pica_recording_splits_verify` \u2014 explicitly mark a split as agreed.\n3. `pica_recording_splits_list` \u2014 list all splits on a recording.\n- see `pica://schemas/recording-splits-required`.\n\n### assign an industry identifier (iswc / isrc / isni / ipi / etc.)\n**there is no standalone identifier-assign tool.** every identifier is\nan inline field on the entity's update tool. don't search for a\ngeneric identifier-assign verb \u2014 set the field on `pica_works_update`\n/ `pica_recordings_update` / `pica_people_update` directly.\n\n- **work identifiers** \u2192 `pica_works_update`: `iswc`, `isrc`,\n  `tunecode`, `prs_work_id`, `spotify_track_uri`.\n- **recording identifiers** \u2192 `pica_recordings_update`: `isrc`,\n  `isrc_source`, `musicbrainz_recording_id`, `mlc_recording_id`,\n  `mlc_song_code`, `spotify_track_uri`, `spotify_track_id`,\n  `youtube_video_id`, `youtube_url`, `apple_music_url`,\n  `deezer_track_id`, `ppl_recording_id`.\n- **person identifiers** \u2192 `pica_people_update`: `cae_ipi_number`,\n  `ipn_number`, `prs_number`, `ppl_number`, `mcps_member_number`,\n  `pro_name` + `pro_member_number`, plus the satellite-routed\n  identifiers below.\n\n**satellite-routed person identifiers (set them inline anyway):**\n`isni`, `musicbrainz_id`, `wikidata_id`, `discogs_artist_id`,\n`deezer_artist_id` are stored on the `person_enrichment` satellite\ntable under the hood, NOT on `people`. **don't think about that.**\nset them as inline fields on `pica_people_update` exactly like the\nnon-satellite identifiers above; the service fans out automatically.\nthe surface is uniform \u2014 satellites are an implementation detail.\n\nfield-name notes \u2014 these names are surface-precise; the route's\nallow-list rejects the abbreviated forms:\n- `cae_ipi_number` (NOT `cae_ipi`)\n- `ipn_number` (NOT `ipn`)\n- `pro_member_number` (the generic non-PRO/PPL/MCPS variant) is paired\n  with `pro_name` to specify which PRO.\n\n**examples:**\n- `pica_works_update { id: \"<uuid>\", iswc: \"T-123.456.789-0\" }`\n- `pica_people_update { id: \"<uuid>\", cae_ipi_number: \"00000000001\",\n  isni: \"0000000123456789\" }`\n\n### export the catalog\n- one of: `pica_export_catalog_csv` (broadest, ungated) /\n  `pica_export_song_registration` (CWR for PRO/CMO) /\n  `pica_export_industry_ready` (publisher / label / sync) /\n  `pica_export_catalog_asset_report` (CAR \u2014 finance / insurance / diligence) /\n  `pica_export_ai_consent` (AI-consent matrix).\n- see `pica://schemas/export-required` for which export matches which destination.\n\n### claim a discovery\n1. `pica_discoveries_query` \u2014 list pending; row carries\n   `type: 'credit' | 'custody' | 'artist'`.\n2. typed claim: `pica_claim_credit` / `pica_claim_custody` /\n   `pica_claim_artist`. or `pica_discoveries_review` for generic accept/reject.\n- see `pica://schemas/claim-required`.\n\n## reading the catalog\n\nwrite-flows above assume you already know what to write. these read-\npatterns help you find the right entity / gap / duplicate first.\n\n### find duplicates and merge them\n1. `pica_find_duplicates` \u2014 `entity_type: \"works\" | \"people\"`. returns\n   groups + suggested winners.\n2. `pica_merge_duplicates` \u2014 `entity_type` accepts both forms; the\n   canonical plural (`\"works\" | \"people\"`) matches `pica_find_duplicates`\n   and is preferred. legacy singular (`\"work\" | \"person\"`) still works\n   for backwards compatibility. max 25 loser_ids per call. requires\n   admin scope.\n- if you need to merge but don't have admin scope, ping a workspace\n  owner \u2014 there is no agent-side workaround.\n\n### audit catalog completeness\n1. `pica_dashboard_briefing` \u2014 high-level state: counts of\n   needs_attention works, recent activity, unresolved discoveries.\n   start here, not at `*_query`.\n2. `pica_dashboard_pulse` \u2014 trend / velocity companion.\n3. drill into specifics from the briefing's pointers \u2014 usually a\n   `pica_*_query` filtered by health, then `pica_*_inspect` per row.\n\n### find gaps and fill them\n1. `pica_works_query { health_filter: \"needs_attention\" | \"low_completeness\" }`\n   \u2014 under-used. surfaces works missing credits / iswc / metadata.\n   parallel filters exist on `pica_recordings_query` /\n   `pica_people_query` (`pica_people_query` is full-text only \u2014 no\n   typed health_filter yet).\n2. `pica_works_inspect { id, sections: [\"health\", \"completeness\", \"enrichment\"] }`\n   \u2014 request only the sections you need. sections=[] (omit) returns\n   everything which is noisy.\n3. if the gap is identifier-shaped (missing ISWC / ISRC / ISNI /\n   MusicBrainz id) \u2014 `pica_resolve_work` / `_recording` / `_person`\n   fans the cascade. tier B fuzzy matches queue as proposals \u2014 drain\n   via `pica_enrichment_proposals_list` \u2192 `_apply` / `_reject`.\n\n### look up a person by industry identifier\n- `pica_people_query` accepts a free-text `query` field that matches\n  name, email, OR identifier (IPI / ISNI / etc.). there is NO typed\n  filter (`pica_people_query { isni: \"...\" }` does not work) \u2014 use\n  the `query` string.\n- if no match, fall back to `pica_search_all` for a cross-entity scan.\n- if still no match, the person isn't in the catalog yet \u2014\n  `pica_people_create` (set the identifier inline; see the\n  identifier-assign section above) \u2192 `pica_resolve_person` to fan\n  enrichment across ISNI + MusicBrainz.\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.** every identifier (ISWC,\n  ISRC, ISNI, CAE/IPI, MusicBrainz id, etc.) is an inline field on the\n  entity's update tool \u2014 see the \"assign an industry identifier\"\n  section above for the surface-precise field names.\n- **two write surfaces for collaborators.** `pica_credits_update` is\n  canonical for work splits; `pica_recording_credits_update` is the\n  recording-side variant with a different role enum (MainArtist /\n  FeaturedArtist / Producer / etc.). don't cross them.\n- **people identifiers \u2014 treat as one inline surface.** `pica_people_update`\n  accepts every identifier as an inline field; some route to the\n  `person_enrichment` satellite under the hood (see the identifier\n  section above) \u2014 the surface stays uniform.\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.** writes are org-scoped; iswc\n  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- `pica://schemas/audio-upload-required` \u2014 3-step audio chain.\n- `pica://schemas/enrichment-resolve-required` \u2014 resolve \u2192 proposals chain.\n- `pica://schemas/agreement-required` \u2014 backs `pica_agreements_create`.\n- `pica://schemas/multimedia-required` \u2014 backs `pica_multimedia_create`.\n- `pica://schemas/export-required` \u2014 five export destinations.\n- `pica://schemas/claim-required` \u2014 three discovery claim verbs.\n- `pica://schemas/session-required` \u2014 backs `pica_sessions_create`.\n- `pica://schemas/split-sheet-required` \u2014 backs `pica_split_sheet_generate` (publishing splits on works).\n- `pica://schemas/recording-splits-required` \u2014 backs `pica_recording_splits_create` (master ownership splits on recordings).\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~232 tools across catalog (works, recordings, people, credits, sessions,\nsplits), enrichment, exports, agreements, multimedia, analytics, and\naudio. fourteen required-fields schema resources at\n`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,88ZAqPrC,CAAC;AAEF,eAAO,MAAM,iBAAiB,k6BAuB7B,CAAC"}

package/dist/resources/agent-guide.js

@@ -0,0 +1,284 @@
+// 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. ~232 tools are available. fourteen 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.
+- see \`pica://schemas/audio-upload-required\`.
+
+### 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.
+   \`pica_enrichment_proposal_reject\` — dismiss with content-hash suppression.
+- see \`pica://schemas/enrichment-resolve-required\`.
+
+### create an agreement
+1. \`pica_agreements_create\` — title + agreement_type + other_party_name
+   required. prefer counterparty_org_id (FK) over free-text other_party_name.
+2. \`pica_agreements_link_work\` — attach works (optional royalty_split per work).
+3. \`pica_agreement_templates_render\` — template-driven alternative.
+- see \`pica://schemas/agreement-required\`.
+
+### add multimedia
+- \`pica_multimedia_create\` — title + content_type required.
+- \`pica_multimedia_link_youtube\` — YouTube videos (auto-enriched).
+- \`pica_multimedia_import_url\` — external image / video URL (downloads
+  into PICA storage).
+- \`pica_multimedia_link_work\` — attach to a work (relationship_type required).
+- see \`pica://schemas/multimedia-required\`.
+
+### log a studio session
+1. (optional) \`pica_sessions_types\` — pre-flight to discover valid
+   \`session_type_id\` values for this org. Lookup table; org-scoped.
+2. \`pica_sessions_create\` — title + start_time + end_time (ISO 8601).
+   session_type_id, location, work_id, recording_id, participants are
+   all optional inline fields.
+3. \`pica_sessions_get\` / \`pica_sessions_list\` — read-back / browse.
+- the \`status\` enum (scheduled / in_progress / completed / cancelled) is
+  documented but NOT enforced by a DB CHECK — values may evolve.
+- see \`pica://schemas/session-required\`.
+
+### generate a split sheet (publishing royalties on a work)
+1. **pre-condition:** writer credits on the work must already total 100%
+   via \`pica_credits_update\`. \`pica_split_sheet_generate\` returns 400
+   otherwise.
+2. \`pica_split_sheet_generate\` — work_id only; snapshots current splits.
+3. \`pica_split_sheet_send\` — notify each credited writer for signature
+   via in-app + Telegram + email. Non-PICA-user writers get a
+   collaboration invite email instead. Per-writer soft-fails.
+4. \`pica_split_sheet_get\` / \`pica_split_sheet_list\` — read-back.
+- see \`pica://schemas/split-sheet-required\`.
+
+### assign master ownership splits (recording rights)
+- DISTINCT from publishing splits above. Recording splits live on
+  \`recording_splits\`, not \`work_credits\`. Drives master royalty payouts
+  + downstream credit gating.
+1. \`pica_recording_splits_create\` — recording_id + split_type
+   (master / mechanical / performance / sync) + percentage required.
+   role / person_id / territory / start_date / end_date optional.
+   Use \`dry_run: true\` for a no-op preview before committing.
+   ADR-200 form-confirmation gate fires on connectors that support
+   \`elicitation/url\`.
+2. \`pica_recording_splits_verify\` — explicitly mark a split as agreed.
+3. \`pica_recording_splits_list\` — list all splits on a recording.
+- see \`pica://schemas/recording-splits-required\`.
+
+### assign an industry identifier (iswc / isrc / isni / ipi / etc.)
+**there is no standalone identifier-assign tool.** every identifier is
+an inline field on the entity's update tool. don't search for a
+generic identifier-assign verb — set the field on \`pica_works_update\`
+/ \`pica_recordings_update\` / \`pica_people_update\` directly.
+
+- **work identifiers** → \`pica_works_update\`: \`iswc\`, \`isrc\`,
+  \`tunecode\`, \`prs_work_id\`, \`spotify_track_uri\`.
+- **recording identifiers** → \`pica_recordings_update\`: \`isrc\`,
+  \`isrc_source\`, \`musicbrainz_recording_id\`, \`mlc_recording_id\`,
+  \`mlc_song_code\`, \`spotify_track_uri\`, \`spotify_track_id\`,
+  \`youtube_video_id\`, \`youtube_url\`, \`apple_music_url\`,
+  \`deezer_track_id\`, \`ppl_recording_id\`.
+- **person identifiers** → \`pica_people_update\`: \`cae_ipi_number\`,
+  \`ipn_number\`, \`prs_number\`, \`ppl_number\`, \`mcps_member_number\`,
+  \`pro_name\` + \`pro_member_number\`, plus the satellite-routed
+  identifiers below.
+
+**satellite-routed person identifiers (set them inline anyway):**
+\`isni\`, \`musicbrainz_id\`, \`wikidata_id\`, \`discogs_artist_id\`,
+\`deezer_artist_id\` are stored on the \`person_enrichment\` satellite
+table under the hood, NOT on \`people\`. **don't think about that.**
+set them as inline fields on \`pica_people_update\` exactly like the
+non-satellite identifiers above; the service fans out automatically.
+the surface is uniform — satellites are an implementation detail.
+
+field-name notes — these names are surface-precise; the route's
+allow-list rejects the abbreviated forms:
+- \`cae_ipi_number\` (NOT \`cae_ipi\`)
+- \`ipn_number\` (NOT \`ipn\`)
+- \`pro_member_number\` (the generic non-PRO/PPL/MCPS variant) is paired
+  with \`pro_name\` to specify which PRO.
+
+**examples:**
+- \`pica_works_update { id: "<uuid>", iswc: "T-123.456.789-0" }\`
+- \`pica_people_update { id: "<uuid>", cae_ipi_number: "00000000001",
+  isni: "0000000123456789" }\`
+
+### export the catalog
+- one of: \`pica_export_catalog_csv\` (broadest, ungated) /
+  \`pica_export_song_registration\` (CWR for PRO/CMO) /
+  \`pica_export_industry_ready\` (publisher / label / sync) /
+  \`pica_export_catalog_asset_report\` (CAR — finance / insurance / diligence) /
+  \`pica_export_ai_consent\` (AI-consent matrix).
+- see \`pica://schemas/export-required\` for which export matches which destination.
+
+### claim a discovery
+1. \`pica_discoveries_query\` — list pending; row carries
+   \`type: 'credit' | 'custody' | 'artist'\`.
+2. typed claim: \`pica_claim_credit\` / \`pica_claim_custody\` /
+   \`pica_claim_artist\`. or \`pica_discoveries_review\` for generic accept/reject.
+- see \`pica://schemas/claim-required\`.
+
+## reading the catalog
+
+write-flows above assume you already know what to write. these read-
+patterns help you find the right entity / gap / duplicate first.
+
+### find duplicates and merge them
+1. \`pica_find_duplicates\` — \`entity_type: "works" | "people"\`. returns
+   groups + suggested winners.
+2. \`pica_merge_duplicates\` — \`entity_type\` accepts both forms; the
+   canonical plural (\`"works" | "people"\`) matches \`pica_find_duplicates\`
+   and is preferred. legacy singular (\`"work" | "person"\`) still works
+   for backwards compatibility. max 25 loser_ids per call. requires
+   admin scope.
+- if you need to merge but don't have admin scope, ping a workspace
+  owner — there is no agent-side workaround.
+
+### audit catalog completeness
+1. \`pica_dashboard_briefing\` — high-level state: counts of
+   needs_attention works, recent activity, unresolved discoveries.
+   start here, not at \`*_query\`.
+2. \`pica_dashboard_pulse\` — trend / velocity companion.
+3. drill into specifics from the briefing's pointers — usually a
+   \`pica_*_query\` filtered by health, then \`pica_*_inspect\` per row.
+
+### find gaps and fill them
+1. \`pica_works_query { health_filter: "needs_attention" | "low_completeness" }\`
+   — under-used. surfaces works missing credits / iswc / metadata.
+   parallel filters exist on \`pica_recordings_query\` /
+   \`pica_people_query\` (\`pica_people_query\` is full-text only — no
+   typed health_filter yet).
+2. \`pica_works_inspect { id, sections: ["health", "completeness", "enrichment"] }\`
+   — request only the sections you need. sections=[] (omit) returns
+   everything which is noisy.
+3. if the gap is identifier-shaped (missing ISWC / ISRC / ISNI /
+   MusicBrainz id) — \`pica_resolve_work\` / \`_recording\` / \`_person\`
+   fans the cascade. tier B fuzzy matches queue as proposals — drain
+   via \`pica_enrichment_proposals_list\` → \`_apply\` / \`_reject\`.
+
+### look up a person by industry identifier
+- \`pica_people_query\` accepts a free-text \`query\` field that matches
+  name, email, OR identifier (IPI / ISNI / etc.). there is NO typed
+  filter (\`pica_people_query { isni: "..." }\` does not work) — use
+  the \`query\` string.
+- if no match, fall back to \`pica_search_all\` for a cross-entity scan.
+- if still no match, the person isn't in the catalog yet —
+  \`pica_people_create\` (set the identifier inline; see the
+  identifier-assign section above) → \`pica_resolve_person\` to fan
+  enrichment across ISNI + MusicBrainz.
+
+## 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.** every identifier (ISWC,
+  ISRC, ISNI, CAE/IPI, MusicBrainz id, etc.) is an inline field on the
+  entity's update tool — see the "assign an industry identifier"
+  section above for the surface-precise field names.
+- **two write surfaces for collaborators.** \`pica_credits_update\` is
+  canonical for work splits; \`pica_recording_credits_update\` is the
+  recording-side variant with a different role enum (MainArtist /
+  FeaturedArtist / Producer / etc.). don't cross them.
+- **people identifiers — treat as one inline surface.** \`pica_people_update\`
+  accepts every identifier as an inline field; some route to the
+  \`person_enrichment\` satellite under the hood (see the identifier
+  section above) — the surface stays uniform.
+- **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.** writes are org-scoped; 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\`.
+- \`pica://schemas/audio-upload-required\` — 3-step audio chain.
+- \`pica://schemas/enrichment-resolve-required\` — resolve → proposals chain.
+- \`pica://schemas/agreement-required\` — backs \`pica_agreements_create\`.
+- \`pica://schemas/multimedia-required\` — backs \`pica_multimedia_create\`.
+- \`pica://schemas/export-required\` — five export destinations.
+- \`pica://schemas/claim-required\` — three discovery claim verbs.
+- \`pica://schemas/session-required\` — backs \`pica_sessions_create\`.
+- \`pica://schemas/split-sheet-required\` — backs \`pica_split_sheet_generate\` (publishing splits on works).
+- \`pica://schemas/recording-splits-required\` — backs \`pica_recording_splits_create\` (master ownership splits on recordings).
+
+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
+~232 tools across catalog (works, recordings, people, credits, sessions,
+splits), enrichment, exports, agreements, multimedia, analytics, and
+audio. fourteen 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqPxC,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;CAuBhC,CAAC"}

package/dist/resources/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Resource Registry for MCP Server
+ * Manages read-only data resources that AI assistants can access
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ServerConfig } from "../config.js";
+export interface ResourceDefinition {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}
+export interface ResourceContent {
+    contents: Array<{
+        uri: string;
+        mimeType: string;
+        text: string;
+    }>;
+}
+export type ResourceResult = any;
+export declare class ResourceRegistry {
+    private pica;
+    private config?;
+    constructor(pica: PicaClient | null, config?: ServerConfig);
+    /**
+     * List all available resources
+     */
+    listResources(): ResourceDefinition[];
+    /**
+     * Read a resource by URI
+     */
+    readResource(uri: string): Promise<any>;
+    /**
+     * Get OpenAPI specification resource
+     */
+    private getOpenAPISpec;
+    /**
+     * Get works list resource
+     */
+    private getWorksList;
+    /**
+     * Get people list resource
+     */
+    private getPeopleList;
+    /**
+     * Get recordings list resource
+     */
+    private getRecordingsList;
+    /**
+     * Get catalog statistics resource
+     */
+    private getCatalogStats;
+    /**
+     * Get catalog health (PICA Score) resource
+     */
+    private getCatalogHealth;
+    /**
+     * Get workspace context resource — aggregated orientation for agents
+     */
+    private getWorkspaceContext;
+    /**
+     * Get recent events resource — webhook deliveries
+     */
+    private getRecentEvents;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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;AAU/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;IA8MrC;;OAEG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAyJ7C;;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"}