@withpica/mcp-server 2.44.0 → 2.45.0

package/CHANGELOG.md

@@ -11,6 +11,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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

package/README.md

@@ -39,14 +39,13 @@ The Model Context Protocol (MCP) is an open standard that enables AI assistants
 - `pica_people_enrich_isni` - Enrich from ISNI
 - `pica_people_enrich_musicbrainz` - Enrich from MusicBrainz
 
-**Recordings Management (6 tools)**
+**Recordings Management (5 tools)**
 
-- `pica_recordings_list` - List recordings
-- `pica_recordings_get` - Get recording details
+- `pica_recordings_query` - List/search recordings; filter by `work_id` (replaces removed `pica_recordings_by_work`)
+- `pica_recordings_inspect` - Get recording details (sections-based)
 - `pica_recordings_create` - Create new recording
 - `pica_recordings_update` - Update recording
 - `pica_recordings_delete` - Delete recording
-- `pica_recordings_by_work` - Get recordings of a work
 
 **Search & Analytics (2 tools)**
 

package/dist/prompts/index.d.ts

@@ -74,5 +74,13 @@ export declare class PromptRegistry {
      * Prepare for sync — get catalog sync-ready
      */
     private getPrepareForSyncPrompt;
+    /**
+     * Log a session — guided studio session capture
+     */
+    private getLogASessionPrompt;
+    /**
+     * Set recording splits — guided master ownership split assignment with verify gate
+     */
+    private getSetRecordingSplitsPrompt;
 }
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB;;OAEG;IACH,WAAW,IAAI,gBAAgB,EAAE;IA6EjC;;OAEG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC;IAwCvE;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA8B/B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA+B/B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAkC/B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAgC5B;;OAEG;IACH,OAAO,CAAC,4BAA4B;IA+BpC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkC7B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAsChC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAuC7B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAmChC;;OAEG;IACH,OAAO,CAAC,2BAA2B;IA+CnC;;OAEG;IACH,OAAO,CAAC,uBAAuB;CAoChC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB;;OAEG;IACH,WAAW,IAAI,gBAAgB,EAAE;IAuGjC;;OAEG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC;IA8CvE;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAgC/B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA+B/B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAqC/B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAgC5B;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAiCpC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAoC7B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAyChC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA0C7B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAqChC;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAiDnC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAuC/B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAsC5B;;OAEG;IACH,OAAO,CAAC,2BAA2B;CA6CpC"}

package/dist/prompts/index.js

@@ -66,6 +66,28 @@ export class PromptRegistry {
                 description: "Assess the workspace state and route to the right workflow — use this when you first connect or don't know where to start",
                 arguments: [],
             },
+            {
+                name: "log-a-session",
+                description: "Log a studio session — guided capture of who was there, what work was being made, and what happened",
+                arguments: [
+                    {
+                        name: "work_id",
+                        description: "Optional work this session was for — pass to skip the discovery question",
+                        required: false,
+                    },
+                ],
+            },
+            {
+                name: "set-recording-splits",
+                description: "Set master ownership splits on a recording — guided propose-and-confirm flow with verify gate",
+                arguments: [
+                    {
+                        name: "recording_id",
+                        description: "Optional recording to set splits on — pass to skip the discovery question",
+                        required: false,
+                    },
+                ],
+            },
         ];
     }
     /**
@@ -95,6 +117,10 @@ export class PromptRegistry {
                 return this.getPrepareForSyncPrompt();
             case "workspace-autopilot":
                 return this.getWorkspaceAutopilotPrompt();
+            case "log-a-session":
+                return this.getLogASessionPrompt(args?.work_id);
+            case "set-recording-splits":
+                return this.getSetRecordingSplitsPrompt(args?.recording_id);
             default:
                 throw new Error(`Prompt not found: ${name}`);
         }
@@ -111,6 +137,8 @@ export class PromptRegistry {
                         type: "text",
                         text: `Please analyze my music catalog and provide a comprehensive report.
 
+If you're unsure where to start, read pica://docs/agent-guide for the workflow taxonomy.
+
 Use the following tools to gather data:
 1. pica_catalog_stats - Get overall statistics
 2. pica_works_query - Review works data
@@ -176,6 +204,9 @@ Be thorough but conservative - only flag items that have a strong likelihood of
                         type: "text",
                         text: `Please identify works and people that could benefit from metadata enrichment.
 
+Pre-flight: read pica://schemas/enrichment-resolve-required for the canonical resolve/propose shape (target_type, target_id, sources).
+If you're unsure where to start, read pica://docs/agent-guide for the workflow taxonomy.
+
 Use these tools:
 1. pica_works_query - Get all works
 2. pica_people_query - Get all people
@@ -214,7 +245,7 @@ ADR-193 — before asking the user to paste facts, check your other connected MC
 
 Use these tools:
 1. pica_works_query with verified: false - Get unverified works
-2. pica_recordings_by_work - Check if works have recordings
+2. pica_recordings_query with work_id - Check if works have recordings
 3. pica_people_query - Check for associated people/credits
 
 For each unverified work, assess:
@@ -246,6 +277,8 @@ Provide specific recommendations for each category, including what's needed to m
                         type: "text",
                         text: `Please assess the health of my music catalog using the PICA Score.
 
+If you're unsure where to start, read pica://docs/agent-guide for the workflow taxonomy.
+
 Use these tools:
 1. pica_works_inspect({ sections: ["score"] }) - Get the PICA Score with pillar breakdown
 2. pica_catalog_stats - Get raw catalog statistics for additional context
@@ -279,6 +312,8 @@ Provide:
                         type: "text",
                         text: `Please audit the credits across my music catalog to find gaps and issues.
 
+Pre-flight: if you propose adding a missing credit, read pica://schemas/work-credits-required for the canonical credit shape (role, splits totaling 100%).
+
 Use these tools:
 1. pica_works_query - Get all works
 2. pica_credits_list - Check credits for each work (sample at least 20 works, prioritizing recent ones)
@@ -315,6 +350,9 @@ Report:
                         type: "text",
                         text: `I just connected to PICA. Help me get started with my music catalog.
 
+Pre-flight: read pica://schemas/work-required, pica://schemas/work-credits-required, and pica://schemas/audio-upload-required for the canonical create-work, add-credit, and upload-audio shapes.
+If you're unsure where to start, read pica://docs/agent-guide for the workflow taxonomy.
+
 First, read the workspace://context resource to understand my current catalog state (is it empty or do I already have works?).
 
 If the catalog is empty, welcome me and explain that I can get my music into PICA however I like:
@@ -358,6 +396,9 @@ Important: I can always log in at withpica.com to see, verify, and manage everyt
                         type: "text",
                         text: `Help me close the loop on a work — find what's missing and offer to fix each gap.
 
+Pre-flight: per gap class, read the relevant schema before writing — pica://schemas/work-credits-required (credits/splits), pica://schemas/audio-upload-required (master audio), pica://schemas/enrichment-resolve-required (ISWC/ISRC via cascade).
+If you're unsure where to start, read pica://docs/agent-guide for the workflow taxonomy.
+
 ${workInstruction}
 
 For the work, check every aspect of completeness:
@@ -395,6 +436,8 @@ Keep it conversational — don't list all gaps at once. Start with the most impo
                         type: "text",
                         text: `Help me check which of my works are registered and which still need registration.
 
+Pre-flight: read pica://schemas/enrichment-resolve-required (for resolving missing ISWCs via the cascade) and pica://schemas/export-required (for the CWR export shape) before writing.
+
 Steps:
 1. pica_works_query — list works, then use pica_works_inspect with sections: ["registration"] to check registration status across PROs (PRS, MCPS, PPL, MLC)
 2. For works that aren't registered, use pica_works_inspect with sections: ["registration", "completeness"] on a sample to understand what's blocking registration
@@ -432,6 +475,8 @@ Focus on practical next steps, not just reporting.`,
                         type: "text",
                         text: `You've just connected to a PICA workspace. Assess its current state and guide me to the most valuable next action.
 
+If you're unsure where to start, read pica://docs/agent-guide for the workflow taxonomy.
+
 Step 1 — Orient:
 Read the workspace://context resource to get a snapshot of the catalog: org info, catalog size, health score, and top priorities.
 
@@ -481,6 +526,8 @@ Important: Don't run all workflows at once. Pick the single most valuable action
                         type: "text",
                         text: `Help me get my catalog ready for sync licensing — make sure my works are discoverable and attractive to music supervisors.
 
+Pre-flight: if you propose enriching from Spotify/MusicBrainz to fill genre/mood/identifier gaps, read pica://schemas/enrichment-resolve-required for the canonical resolve shape.
+
 Steps:
 1. pica_catalog_stats — get an overview of the catalog
 2. pica_works_query — sample works to check what's missing for sync readiness
@@ -508,5 +555,91 @@ The goal is making works findable by mood, BPM, key, and energy — that's what
             ],
         };
     }
+    /**
+     * Log a session — guided studio session capture
+     */
+    getLogASessionPrompt(workId) {
+        const workInstruction = workId
+            ? `Log this session against work ${workId}.`
+            : `Ask me which work this session was for. If I'm not sure or it doesn't have one yet, that's fine — work_id is optional.`;
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Help me log a studio session.
+
+Pre-flight: read pica://schemas/session-required for the canonical session shape (title, start_time, end_time required; session_type_id from pica_sessions_types; participants; optional work_id/recording_id).
+
+${workInstruction}
+
+Walk me through it conversationally — don't dump a form. Capture each piece in turn:
+
+1. What was the session for? — title and a short description (e.g. "vocal recording for track 3")
+2. What kind of session? — call pica_sessions_types and let me pick (recording, mixing, mastering, writing, production, rehearsal). Pass the chosen type's UUID as session_type_id.
+3. When was it? — start_time and end_time as ISO 8601. If I give you "yesterday afternoon", confirm a specific time. Default timezone Europe/London unless I say otherwise. If it was a full-day affair, set is_all_day: true.
+4. Where? — studio name in location, or a virtual link in location_url for remote sessions.
+5. Who was there? — collect participants as { personId?, userId?, role? }. If I name someone you don't recognise, offer to look them up via pica_people_query first; if they're not on PICA yet, offer pica_collaborators_invite to bring them in.
+6. What happened? — capture as notes. This is the bit I'll thank you for later.
+
+Then call pica_sessions_create with the captured fields. Confirm what was logged and offer the natural next step:
+- "Want me to attach a multimedia file from this session?" (pica_multimedia_create)
+- "Want me to set master ownership splits for any new recording from this session?" (pica_recording_splits_create)
+- "Want me to log another session?"
+
+If I skip something, that's fine — only title, start_time, and end_time are strictly required. Don't badger me for the rest.`,
+                    },
+                },
+            ],
+        };
+    }
+    /**
+     * Set recording splits — guided master ownership split assignment with verify gate
+     */
+    getSetRecordingSplitsPrompt(recordingId) {
+        const recordingInstruction = recordingId
+            ? `Work on recording ${recordingId}.`
+            : `Ask me which recording to set splits on. If I'm not sure of the ID, use pica_recordings_query to list recent ones and let me pick.`;
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Help me set master ownership splits on a recording — these are master-side royalty shares (distinct from writer splits, which are credits on a work).
+
+Pre-flight: read pica://schemas/recording-splits-required for the canonical split shape (recording_id, person_id, split_percentage, split_type). Splits must total 100%.
+
+${recordingInstruction}
+
+Walk me through it carefully — splits flow into payments, so we want to get this right:
+
+1. Show current state — call pica_recording_splits_list for the recording. If splits already exist, summarise them (who owns what %, total). Ask whether I want to add to them, replace them, or just verify what's there.
+
+2. Capture the proposed splits — for each split:
+   - Who owns this share? (person_id from pica_people_query, or offer pica_collaborators_invite if they're not on PICA yet)
+   - What percentage? (must total 100% across all splits)
+   - What kind? (split_type — typical values: artist, producer, label, featured)
+
+3. Pre-commit dry-run — call pica_recording_splits_create with dry_run: true for each proposed split (per ADR-199). Show me the would-affect preview so I can confirm before persisting. Sum the percentages out loud. If they don't total 100%, stop and ask me to adjust.
+
+4. Confirm explicitly — say something like "I'm about to set [N] splits totalling 100% on this recording. Reply 'yes' to commit, or tell me what to change." Wait for my confirmation. Don't write without it.
+
+5. Commit — call pica_recording_splits_create (dry_run omitted) for each split. Report each one back as it lands.
+
+6. Verify — for each newly-created split, call pica_recording_splits_verify with the split_id to mark it agreed-upon. Report the verified state.
+
+7. Offer the natural next step:
+   - "Want me to generate a split sheet PDF for signing?" (pica_split_sheet_generate)
+   - "Want me to send the split sheet to the parties?" (pica_split_sheet_send)
+   - "Want me to set splits on another recording?"
+
+If at any point the totals are off or I waver, stop and re-confirm. Splits are not the place to be ambitious — accuracy beats throughput.`,
+                    },
+                },
+            ],
+        };
+    }
 }
 //# sourceMappingURL=index.js.map

package/dist/prompts/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"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"}

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

@@ -10,6 +10,6 @@
  * 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. ~231 tools are available. eleven 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### 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## 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, isrc, ipi/pro/etc.\n  are all inline on the entity create/update \u2014 no separate tool family.\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.** see\n  `pica://schemas/person-required` for the full set (ipi / ipn / prs / ppl /\n  pro / mcps / isni / musicbrainz / wikidata / discogs / imdb / viaf / deezer).\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\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~231 tools across catalog (works, recordings, people, credits),\nenrichment, exports, agreements, multimedia, analytics, and audio.\neleven required-fields schema resources at `pica://schemas/<workflow>-required`.\nthe full agent-guide replaces this lobby content.\n";
+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

@@ -1 +1 @@
-{"version":3,"file":"agent-guide.d.ts","sourceRoot":"","sources":["../../src/resources/agent-guide.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,yBAAyB,2lMAoHrC,CAAC;AAEF,eAAO,MAAM,iBAAiB,64BAsB7B,CAAC"}
+{"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

@@ -17,7 +17,7 @@ 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. ~231 tools are available. eleven core workflows below
+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\`.
 
@@ -75,6 +75,80 @@ cover most of the surface; for anything not listed, fall back to
 - \`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) /
@@ -90,20 +164,72 @@ cover most of the surface; for anything not listed, fall back to
    \`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.** iswc, isrc, ipi/pro/etc.
-  are all inline on the entity create/update — no separate tool family.
+- **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.** see
-  \`pica://schemas/person-required\` for the full set (ipi / ipn / prs / ppl /
-  pro / mcps / isni / musicbrainz / wikidata / discogs / imdb / viaf / deezer).
+- **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\`.**
@@ -124,6 +250,9 @@ cover most of the surface; for anything not listed, fall back to
 - \`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.
@@ -146,9 +275,10 @@ sign-in.
    surface unlocks automatically — no config to refresh.
 
 ## what unlocks after sign-in
-~231 tools across catalog (works, recordings, people, credits),
-enrichment, exports, agreements, multimedia, analytics, and audio.
-eleven required-fields schema resources at \`pica://schemas/<workflow>-required\`.
+~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

@@ -1 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoHxC,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;CAsBhC,CAAC"}
+{"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.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;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;IAyLrC;;OAEG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAsJ7C;;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;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"}