@withpica/mcp-server-directory 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,39 +1,56 @@
 # Changelog
 
-All notable changes to `@withpica/mcp-server-directory` will be documented in this file.
+All notable changes to `@withpica/mcp-server-directory` are documented here.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-> **Rule of the road:** every version bump to this package MUST land with a
-> matching entry here in the same commit. See the project's "npm publish
-> discipline" memory entry for the enforcement rationale.
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to semantic versioning where the major number is incremented
+for breaking tool-surface changes.
 
 ## [Unreleased]
 
-## [1.1.0] — 2026-04-13
+## [1.1.0] - 2026-04-21
 
-### Changed
+Shipped as minor rather than major despite the `*_full` tool removal:
+the removed names had near-zero external adoption (they shipped recently
+and weren't advertised externally), and staying on the 1.x line keeps
+`^1.0.0` consumers on the upgrade path rather than stranding them on
+the broken cascade. Clients that cached the `*_full` names will see a
+tool-not-found error and need to refresh their tool list.
 
-- **ADR-171: Prompts replaced with workflow-level skills.**
-  3 prompts → 2 skills, each with decision trees, domain knowledge,
-  and the shared preamble (tone, discovery principle, read-only note).
+### Breaking
 
-  New skills: `discover-music`, `research-creator`.
+- **Removed `directory_lookup_person_full` and `directory_lookup_work_full`.**
+  Both tools hit the same upstream endpoints as their non-`_full` counterparts
+  with only a formatting difference — there was no capability delta. The
+  `_full` variants are now the canonical names (`directory_lookup_person`
+  and `directory_lookup_work`); the thin variants have been deleted. Clients
+  that cached the `_full` names need to update their tool list; the
+  replacements return a superset of the prior data, so no output is lost.
 
-  Retired prompts: `find-music`, `directory-autopilot`.
-  `find-music` → `discover-music` (adds equal discovery principle,
-  reference track search, similarity exploration).
-  `directory-autopilot` routing folded into `research-creator`
-  (identifier resolution, browsing, creator lookup all in one skill).
-  `research-creator` gains collaborator network, similarity search,
-  rights landscape, and identifier routing from the old autopilot.
+### Added
 
-## [1.0.0] — 2026-04-06
+- **`directory_chain` tool** — one-call rights-chain lookup. Accepts a
+  free-text query, a direct ISWC/ISRC `identifier`, or audio-only filters
+  (BPM / key / energy / mood). Returns the already-public `ChainResult`
+  shape: work + writers + publishers (names + roles only, no IPIs or
+  splits) + linked recording + audio characteristics. Wraps the existing
+  public `/api/public/directory/chain` endpoint — no new backing API work.
+- `directory_list_people` now accepts `letter` (A–Z, `#`) for alphabetical
+  browsing. The backend has supported this for months; only the MCP tool
+  was missing the parameter.
+- `directory_list_works` now accepts `letter`, `sort` (`title` | `recent`),
+  and `isrc` — all previously backend-only.
 
-### Added
+### Changed
 
-- Initial release of the PICA Public Directory MCP Server
-- 12 read-only tools for searching works, recordings, people, and identifiers
-- 3 prompts: `find-music`, `research-creator`, `directory-autopilot`
-- Deterministic eval harness for prompt routing validation
+- **`directory_lookup_person` now matches its description.** Previously the
+  tool advertised ISNI / IPI / MusicBrainz ID support but the backing query
+  only matched `global_creator_id` — any non-UUID identifier silently 404'd.
+  The query now cascades through `global_creator_id` → `isni` →
+  `cae_ipi_number` → `musicbrainz_id`, first hit wins.
+- `directory_search` description rewritten to drop the false "ranked" claim.
+  The backing endpoint is a fan-out (`listWorks` + `listPeople`,
+  half-limit each), not cross-type ranking. Callers should prefer typed
+  list tools when they know the entity type.
+- `directory_lookup_isrc` description rewritten to frame it honestly as a
+  pinned filter preset on `list_works` rather than a distinct lookup.

package/dist/prompts/index.d.ts

@@ -1,8 +1,6 @@
 /**
- * Skill Registry for Directory MCP Server
- * Workflow-level skills for music discovery and creator research.
- * Deployed as upgraded prompts; will convert to MCP skills format
- * when the spec extension ships (ADR-171).
+ * Prompt Registry for Directory MCP Server
+ * Guided workflows for music discovery, sync licensing, and rights research
  */
 export interface PromptDefinition {
     name: string;
@@ -27,7 +25,8 @@ export interface PromptResult {
 export declare class PromptRegistry {
     listPrompts(): PromptDefinition[];
     getPrompt(name: string, args?: Record<string, any>): Promise<PromptResult>;
-    private getDiscoverMusicSkill;
-    private getResearchCreatorSkill;
+    private getFindMusicPrompt;
+    private getResearchCreatorPrompt;
+    private getDirectoryAutopilotPrompt;
 }
 //# 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;;;;;GAKG;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;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAkBD,qBAAa,cAAc;IACzB,WAAW,IAAI,gBAAgB,EAAE;IA8B3B,SAAS,CACb,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACzB,OAAO,CAAC,YAAY,CAAC;IAWxB,OAAO,CAAC,qBAAqB;IAiF7B,OAAO,CAAC,uBAAuB;CA2EhC"}
+{"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;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,cAAc;IACzB,WAAW,IAAI,gBAAgB,EAAE;IAoC3B,SAAS,CACb,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACzB,OAAO,CAAC,YAAY,CAAC;IAaxB,OAAO,CAAC,kBAAkB;IA6C1B,OAAO,CAAC,wBAAwB;IAwChC,OAAO,CAAC,2BAA2B;CAqCpC"}

package/dist/prompts/index.js

@@ -1,25 +1,10 @@
 // Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
-const SHARED_PREAMBLE = `You are guiding a music seeker through the PICA public directory — a discovery layer over verified music catalogs.
-
-Tone: knowledgeable friend. You know what's available and how to find it. Straightforward, never salesy.
-
-Discovery principle: every creator's work has equal discoverability. Catalog quality determines visibility, not fame or follower count. Results are sorted by musical fit, not popularity. An unknown songwriter with analysed audio ranks the same as a major artist.
-
-Before starting this workflow:
-1. Read the llms://primer resource to understand what's available in the directory
-2. This is a read-only public directory — you can search and look up, but you can't create or modify anything
-3. Only works from organisations that opted into the directory are visible
-
-After completing this workflow:
-- Summarise what you found in one short paragraph
-- Suggest the natural next step
-- If they say no, that's fine. Don't ask twice.`;
 export class PromptRegistry {
     listPrompts() {
         return [
             {
-                name: "discover-music",
-                description: "Find music for a sync brief, playlist, or project — search by mood, BPM, key, energy, or description. Equal discovery: results sorted by musical fit, not popularity",
+                name: "find-music",
+                description: "Find music for a sync brief, playlist, or project — search by mood, BPM, key, energy, or description",
                 arguments: [
                     {
                         name: "brief",
@@ -30,7 +15,7 @@ export class PromptRegistry {
             },
             {
                 name: "research-creator",
-                description: "Research a songwriter, composer, or performer — full catalog, identifiers, collaborator network, rights landscape, and similarity search",
+                description: "Research a songwriter, composer, or performer — see their works, identifiers, collaborators, and verification status",
                 arguments: [
                     {
                         name: "name_or_id",
@@ -39,166 +24,138 @@ export class PromptRegistry {
                     },
                 ],
             },
+            {
+                name: "directory-autopilot",
+                description: "Not sure where to start? Describe what you need and get routed to the right workflow — sync search, rights research, or identifier lookup",
+                arguments: [],
+            },
         ];
     }
     async getPrompt(name, args) {
         switch (name) {
-            case "discover-music":
-                return this.getDiscoverMusicSkill(args?.brief);
+            case "find-music":
+                return this.getFindMusicPrompt(args?.brief);
             case "research-creator":
-                return this.getResearchCreatorSkill(args?.name_or_id);
+                return this.getResearchCreatorPrompt(args?.name_or_id);
+            case "directory-autopilot":
+                return this.getDirectoryAutopilotPrompt();
             default:
                 throw new Error(`Prompt not found: ${name}`);
         }
     }
-    getDiscoverMusicSkill(brief) {
+    getFindMusicPrompt(brief) {
         const briefInstruction = brief
             ? `The user is looking for: "${brief}". Translate this into audio search parameters.`
-            : `Ask what they're looking for — a mood, a scene, a vibe, or specific audio characteristics (BPM, key, energy).`;
+            : `Ask me what I'm looking for — a mood, a scene, a vibe, or specific audio characteristics (BPM, key, energy).`;
         return {
             messages: [
                 {
                     role: "user",
                     content: {
                         type: "text",
-                        text: `${SHARED_PREAMBLE}
+                        text: `Help me find music in the PICA public directory for a sync brief or project.
 
---- SKILL: discover-music ---
+${briefInstruction}
 
-Help find music by what it sounds like, not who made it. Equal discovery — every well-catalogued work has the same chance.
+Workflow:
+1. Translate the brief into search parameters for directory_search_recordings:
+   - Mood descriptions → energy, danceability, key_mode, mood filters
+   - "Upbeat" → min_energy: 0.6, min_danceability: 0.5
+   - "Dark/moody" → max_energy: 0.4, key_mode: minor
+   - "Chill" → max_energy: 0.4, max_bpm: 100
+   - Specific requests → use BPM, key, duration filters directly
 
-${briefInstruction}
+2. Run directory_search_recordings with the parameters.
+
+3. For each promising result, use directory_lookup_work to get:
+   - Who wrote it (credits with IPI numbers)
+   - Whether credits are attested (verified ownership)
+   - DSP links (Spotify, Apple Music — so the user can listen)
+   - Registration score (higher = cleaner rights chain)
 
-Sync brief / mood-based search:
-  → Extract parameters from natural language:
-    mood, BPM range, key, energy, instrumentation, vocal/instrumental, duration constraints
-  → Translate mood descriptions to search parameters for directory_search_recordings:
-    - "Upbeat" → min_energy: 0.6, min_danceability: 0.5
-    - "Dark/moody" → max_energy: 0.4, key_mode: minor
-    - "Chill" → max_energy: 0.4, max_bpm: 100
-    - Specific requests → use BPM, key, duration filters directly
-  → Run directory_search_recordings with the parameters
-  → Present results by musical fit, not popularity:
-    "here are [N] tracks that match. sorted by how closely they fit your brief, not by who made them."
-  → Per result: title, creator, BPM, key, mood tags, duration.
-     No follower counts. No stream numbers.
-
-For each promising result, use directory_lookup_work_full to get:
-  - Who wrote it (credits with IPI numbers)
-  - Whether credits are attested (verified ownership)
-  - DSP links (Spotify, Apple Music — so the user can listen)
-  - Registration score (higher = cleaner rights chain)
-
-Present as a shortlist with:
-  - Title, artist, BPM, key, energy
-  - Credits summary (who to contact for licensing)
-  - Any flags (unattested credits, low registration score, missing ISRC)
-
-Reference track search:
-  → "got a reference track? tell me what you like about it."
-  → Parse what they value: tempo, mood, instrumentation, vocal style
-  → Search by those parameters
-
-Similarity exploration:
-  → "want to find music similar to [track] by someone you've never heard of?"
-  → Search by the sound, not the name — this is where the discovery principle lives
-
-If they like one:
-  → "want to hear more from this creator, or find similar tracks?"
-  → Similar → search with same parameters
-  → More from creator → pivot to research-creator skill
-
-Rights check:
-  → For any track: "want to check the rights situation?"
-  → Show ownership, publisher, contact path via directory_lookup_work_full
-  → If enquiry → guide through submission
+4. Present results as a shortlist with:
+   - Title, artist, BPM, key, energy
+   - Credits summary (who to contact for licensing)
+   - Any flags (unattested credits, low registration score, missing ISRC)
 
 If no results match, suggest broadening the search (wider BPM range, drop key filter, etc.).
 
-If the catalog is small, say so: "the directory currently has [N] works — it's growing. here's what matches from what's available."
+Important: This is a public directory — only works from organisations that opted in are visible. If the catalog is small, say so.`,
+                    },
+                },
+            ],
+        };
+    }
+    getResearchCreatorPrompt(nameOrId) {
+        const searchInstruction = nameOrId
+            ? `Look up: "${nameOrId}". Try directory_lookup_person first (it accepts name, IPI, ISNI, or MusicBrainz ID). If that doesn't match, use directory_list_people with a text search.`
+            : `Ask me for the creator's name, IPI number, ISNI, or MusicBrainz ID.`;
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Help me research a music creator in the PICA public directory.
 
-Domain knowledge:
-- Results sorted by audio-parameter match, not streams or followers
-- Reference track searching works by extracting musical qualities, not artist similarity
-- Rights information is always available — the directory doesn't hide who owns what
-- Sync supervisors think in briefs (mood + tempo + energy + duration), not artist names
-- Similarity search by audio surfaces genuinely similar music the seeker might never have found
+${searchInstruction}
 
-Tools: directory_search_recordings, directory_search, directory_lookup_work, directory_lookup_work_full, directory_lookup_person, directory_lookup_person_full`,
+Once you find the person, use directory_lookup_person to get their complete profile:
+- Identifiers (IPI, ISNI, MusicBrainz) — essential for rights verification
+- All credited works with roles (writer, composer, performer, producer)
+- Collaborator network — who they work with
+- Verification score — how complete their profile is
+
+Then for their most notable works (up to 5), use directory_lookup_work to get:
+- Full credits and splits (are they the sole writer or one of many?)
+- Recordings with ISRCs
+- Audio analysis (BPM, key, energy)
+- DSP links and registration status
+
+Present a summary:
+- Creator profile (name, identifiers, role patterns)
+- Catalog overview (how many works, typical roles, common collaborators)
+- Notable works with credit details
+- Any gaps (missing identifiers, unattested credits, low scores)
+
+This is useful for: rights research, due diligence before licensing, publisher evaluation, or understanding a catalog before acquisition.`,
                     },
                 },
             ],
         };
     }
-    getResearchCreatorSkill(nameOrId) {
-        const searchInstruction = nameOrId
-            ? `Look up: "${nameOrId}". Try directory_lookup_person_full first (it accepts name, IPI, ISNI, or MusicBrainz ID). If that doesn't match, use directory_list_people with a text search.`
-            : `Ask for the creator's name, IPI number, ISNI, or MusicBrainz ID.`;
+    getDirectoryAutopilotPrompt() {
         return {
             messages: [
                 {
                     role: "user",
                     content: {
                         type: "text",
-                        text: `${SHARED_PREAMBLE}
+                        text: `You've connected to the PICA public music directory. Help me find what I need.
 
---- SKILL: research-creator ---
+First, read the llms://primer resource to understand what's available.
 
-Deep-dive on a specific creator. Full catalog, identifiers, collaborator network, rights landscape.
+Then ask me what I'm looking for. Based on my answer, route to the right workflow:
 
-Also handles routing that was previously in directory-autopilot:
-- If the user has a specific identifier to resolve (ISRC, ISWC, IPI, ISNI):
-  → ISRC (e.g. USABC1234567) → directory_lookup_isrc → then directory_lookup_work_full
-  → ISWC (e.g. T-123.456.789-0) → directory_lookup_work_full
-  → IPI or ISNI → directory_lookup_person_full
-  → MusicBrainz ID → directory_lookup_person_full
-- If the user wants to browse → use directory_search with a broad query, or directory_list_works / directory_list_people
+If I'm looking for MUSIC FOR A PROJECT (sync brief, playlist, mood search):
+→ Use the find-music workflow. Translate my description into audio search parameters and search recordings by BPM, key, energy, mood. Then look up full details on promising matches.
 
-"who do you want to learn about?"
+If I'm looking for INFORMATION ABOUT A CREATOR (songwriter, composer, performer):
+→ Use the research-creator workflow. Look up their profile, works, identifiers, and collaborators.
 
-${searchInstruction}
+If I have a SPECIFIC IDENTIFIER to resolve (ISRC, ISWC, IPI, ISNI):
+→ Route directly to the right lookup tool:
+  - ISRC (e.g. USABC1234567) → directory_lookup_isrc → then directory_lookup_work
+  - ISWC (e.g. T-123.456.789-0) → directory_lookup_work
+  - IPI or ISNI → directory_lookup_person
+  - MusicBrainz ID → directory_lookup_person
+
+If I want to BROWSE what's in the directory:
+→ Use directory_search with a broad query, or directory_list_works / directory_list_people to paginate.
+
+Tell me which workflow you chose and why, in one sentence. Offer alternatives.
 
-Lookup by name, IPI, ISNI, or ISRC:
-  → Find the person using directory_lookup_person_full
-  → If multiple matches: present with distinguishing works/roles
-
-Creator profile:
-  → Full catalog: all works, roles, co-writers
-  → Identifiers: IPI, ISNI, MusicBrainz, IPN
-  → Collaborator network: "frequently works with [names]"
-  → Genre/mood footprint: based on analysed audio across catalog
-
-For their most notable works (up to 5), use directory_lookup_work_full to get:
-  - Full credits and splits (are they the sole writer or one of many?)
-  - Recordings with ISRCs
-  - Audio analysis (BPM, key, energy)
-  - DSP links and registration status
-
-Cross-reference:
-  → "want to verify their identifiers against ISNI or MusicBrainz?"
-  → Flag discrepancies
-
-Similarity exploration:
-  → "want to find other creators with a similar sound?"
-  → Use directory_search_recordings by audio characteristics of their catalog
-  → Equal discovery: results by sound, not fame
-
-Rights landscape:
-  → "want to know who controls their catalog?"
-  → Publishers, agreements, licensing paths
-
-After research:
-  → Summary: creator profile, catalog overview, notable works, gaps
-  → "want to submit a licensing enquiry, or explore more creators?"
-
-Domain knowledge:
-- Creator research often starts from one work and expands via collaborator network — adjacent talent discovery
-- Identifier verification across sources catches discrepancies that matter for rights
-- Similarity search by audio surfaces genuinely similar music through non-traditional channels
-- The collaborator network is how you discover creators no algorithm would surface
-- This is useful for: rights research, due diligence before licensing, publisher evaluation, or catalog acquisition
-
-Tools: directory_lookup_person_full, directory_lookup_work_full, directory_search_recordings, directory_search, directory_lookup_isrc, directory_list_works, directory_list_people`,
+Important: This is a read-only public directory. I can search and look up, but I can't create or modify anything. Only works from organisations that opted into the directory are visible.`,
                     },
                 },
             ],

package/dist/prompts/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAgC7D,MAAM,eAAe,GAAG;;;;;;;;;;;;;;gDAcwB,CAAC;AAEjD,MAAM,OAAO,cAAc;IACzB,WAAW;QACT,OAAO;YACL;gBACE,IAAI,EAAE,gBAAgB;gBACtB,WAAW,EACT,sKAAsK;gBACxK,SAAS,EAAE;oBACT;wBACE,IAAI,EAAE,OAAO;wBACb,WAAW,EACT,+EAA+E;wBACjF,QAAQ,EAAE,KAAK;qBAChB;iBACF;aACF;YACD;gBACE,IAAI,EAAE,kBAAkB;gBACxB,WAAW,EACT,0IAA0I;gBAC5I,SAAS,EAAE;oBACT;wBACE,IAAI,EAAE,YAAY;wBAClB,WAAW,EAAE,mDAAmD;wBAChE,QAAQ,EAAE,KAAK;qBAChB;iBACF;aACF;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,SAAS,CACb,IAAY,EACZ,IAA0B;QAE1B,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,gBAAgB;gBACnB,OAAO,IAAI,CAAC,qBAAqB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACjD,KAAK,kBAAkB;gBACrB,OAAO,IAAI,CAAC,uBAAuB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YACxD;gBACE,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,EAAE,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAEO,qBAAqB,CAAC,KAAc;QAC1C,MAAM,gBAAgB,GAAG,KAAK;YAC5B,CAAC,CAAC,6BAA6B,KAAK,iDAAiD;YACrF,CAAC,CAAC,+GAA+G,CAAC;QAEpH,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE;wBACP,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,GAAG,eAAe;;;;;;EAMlC,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+JAyD6I;qBACpJ;iBACF;aACF;SACF,CAAC;IACJ,CAAC;IAEO,uBAAuB,CAAC,QAAiB;QAC/C,MAAM,iBAAiB,GAAG,QAAQ;YAChC,CAAC,CAAC,aAAa,QAAQ,iKAAiK;YACxL,CAAC,CAAC,kEAAkE,CAAC;QAEvE,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE;wBACP,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,GAAG,eAAe;;;;;;;;;;;;;;;;EAgBlC,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mLA0CgK;qBACxK;iBACF;aACF;SACF,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AA8B7D,MAAM,OAAO,cAAc;IACzB,WAAW;QACT,OAAO;YACL;gBACE,IAAI,EAAE,YAAY;gBAClB,WAAW,EACT,sGAAsG;gBACxG,SAAS,EAAE;oBACT;wBACE,IAAI,EAAE,OAAO;wBACb,WAAW,EACT,+EAA+E;wBACjF,QAAQ,EAAE,KAAK;qBAChB;iBACF;aACF;YACD;gBACE,IAAI,EAAE,kBAAkB;gBACxB,WAAW,EACT,sHAAsH;gBACxH,SAAS,EAAE;oBACT;wBACE,IAAI,EAAE,YAAY;wBAClB,WAAW,EAAE,mDAAmD;wBAChE,QAAQ,EAAE,KAAK;qBAChB;iBACF;aACF;YACD;gBACE,IAAI,EAAE,qBAAqB;gBAC3B,WAAW,EACT,2IAA2I;gBAC7I,SAAS,EAAE,EAAE;aACd;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,SAAS,CACb,IAAY,EACZ,IAA0B;QAE1B,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,YAAY;gBACf,OAAO,IAAI,CAAC,kBAAkB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC9C,KAAK,kBAAkB;gBACrB,OAAO,IAAI,CAAC,wBAAwB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YACzD,KAAK,qBAAqB;gBACxB,OAAO,IAAI,CAAC,2BAA2B,EAAE,CAAC;YAC5C;gBACE,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,EAAE,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAEO,kBAAkB,CAAC,KAAc;QACvC,MAAM,gBAAgB,GAAG,KAAK;YAC5B,CAAC,CAAC,6BAA6B,KAAK,iDAAiD;YACrF,CAAC,CAAC,8GAA8G,CAAC;QAEnH,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE;wBACP,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE;;EAEhB,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;kIAyBgH;qBACvH;iBACF;aACF;SACF,CAAC;IACJ,CAAC;IAEO,wBAAwB,CAAC,QAAiB;QAChD,MAAM,iBAAiB,GAAG,QAAQ;YAChC,CAAC,CAAC,aAAa,QAAQ,4JAA4J;YACnL,CAAC,CAAC,qEAAqE,CAAC;QAE1E,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE;wBACP,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE;;EAEhB,iBAAiB;;;;;;;;;;;;;;;;;;;;0IAoBuH;qBAC/H;iBACF;aACF;SACF,CAAC;IACJ,CAAC;IAEO,2BAA2B;QACjC,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE;wBACP,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;2LAwByK;qBAChL;iBACF;aACF;SACF,CAAC;IACJ,CAAC;CACF"}

package/dist/prompts/public-question-atlas.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Public Question Atlas — ADR-229 Decision 1.
+ *
+ * Source-of-truth registry mapping natural public-discovery questions to
+ * the canonical directory-MCP tool resolution. Sister of:
+ *   - `mcp-server/src/prompts/creator-question-atlas.ts` (ADR-226, customer)
+ *   - `team-mcp-server/src/prompts/operator-question-atlas.ts` (ADR-228, operator)
+ *
+ * Read by:
+ *
+ *   - lint Rule 11F (extended in ADR-229) — validates every `directory_*`
+ *     tool's `Use when the user asks` block cites questions resolving
+ *     here, rejects creator/operator atlas cross-pollination, asserts
+ *     mutual exclusivity of `clean_empty_state` and `fallback_when_empty`,
+ *     and asserts `disambiguation` shape integrity
+ *   - `scripts/intent-resolution-eval.ts --surface=directory` (ADR-229 PR-3)
+ *   - the Phase 4 description rewrites — `Use when the user asks` blocks
+ *     pull question + synonym strings from here
+ *
+ * The `AtlasEntry` type is inline-duplicated rather than imported from a
+ * shared package, mirroring ADR-228's choice (Open Question 3 default —
+ * extract to `packages/mcp-atlas-types/` only if a fourth MCP surface
+ * lands or the type drift becomes painful).
+ *
+ * Two shape extensions vs the creator and operator atlases (per ADR-229
+ * Decision 4):
+ *
+ *   1. `clean_empty_state?: { message; suggest_query_shape }` — public-
+ *      surface analog of `fallback_when_empty`. The directory has no
+ *      internal action to nudge toward (the empty state IS the final
+ *      answer for the anonymous user); this field carries the prescribed
+ *      empty-state copy plus a query-shape hint for the calling LLM.
+ *
+ *   2. `disambiguation?: { ambiguous_terms[]; resolver_tool; resolver_intent }` —
+ *      first-class concern on the public surface (creator/operator MCPs
+ *      have a calling-context that narrows the search; the public
+ *      directory hits "Bowie", "Sade", "Madonna", "Lover Boy" constantly
+ *      and must declare an explicit resolver step).
+ *
+ * `clean_empty_state` and `fallback_when_empty` are mutually exclusive on
+ * a single entry — Rule 11F enforces this at lint time.
+ *
+ * The public atlas omits `natural_domain` (creator-side binds to
+ * `discovery.ts` CATEGORIES; the directory MCP has no equivalent
+ * taxonomy — the discovery surface is search and lookup, not category-
+ * faceted browse). It also omits `available_when` (the operator atlas's
+ * forward-compat hook for unshipped sections; the directory has no
+ * deferred-section concept).
+ */
+export interface AtlasFallback {
+    message: string;
+    next_tool: string;
+}
+export interface AtlasCleanEmptyState {
+    /**
+     * Atlas-prescribed copy for the empty-state response. The calling LLM
+     * may render in its own voice; the suggested-query-shape hint is the
+     * load-bearing part.
+     */
+    message: string;
+    /**
+     * Free-text hint for how to refine the query, interpreted by the LLM
+     * as guidance (not rendered verbatim). Example:
+     * `"title + writer | title + year | ISWC if known"`.
+     */
+    suggest_query_shape: string;
+}
+export interface AtlasDisambiguation {
+    /**
+     * Names known to be ambiguous in the music-metadata domain (multiple
+     * persons, artist projects, or works with the same string). v1 ships
+     * a static list; v2 (deferred per ADR-229 § Risks #3) could resolve
+     * dynamically against the index's name-collision frequency.
+     */
+    ambiguous_terms: string[];
+    /**
+     * The directory tool the agent should call FIRST to surface candidate
+     * entities for the user to disambiguate before committing to the
+     * lookup tool in `resolves_to`.
+     */
+    resolver_tool: string;
+    /**
+     * Free-text guidance for the LLM on how to run the resolver step.
+     * Example: `"Call directory_lookup_person first to surface candidates;
+     * ask which one before calling directory_list_works."`
+     */
+    resolver_intent: string;
+}
+export type AtlasResolution = {
+    kind: "tool";
+    name: string;
+    default_args?: Record<string, unknown>;
+} | {
+    kind: "prompt";
+    name: string;
+};
+export interface AtlasEntry {
+    question: string;
+    synonyms: string[];
+    resolves_to: AtlasResolution;
+    /** Mutually exclusive with `clean_empty_state` (lint-enforced). */
+    fallback_when_empty?: AtlasFallback;
+    /** ADR-229 Decision 4 — public-surface empty-state contract. */
+    clean_empty_state?: AtlasCleanEmptyState;
+    /** ADR-229 Decision 4 — public-surface name-collision contract. */
+    disambiguation?: AtlasDisambiguation;
+}
+/**
+ * Names known-ambiguous in the music-metadata domain — multiple persons
+ * sharing a stage name, or artist project names that collide with
+ * person names. Seed list per ADR-229 § Open Q2 (case-insensitive — the
+ * lint and the resolver normalise on lowercase).
+ *
+ * Grow this list as Phase 5 eval data surfaces real collisions the
+ * static seed misses. Do not prune without eval evidence — the cost of
+ * missing a real collision (wrong-tool routing on a public-facing
+ * surface) is higher than the cost of an extra resolver call.
+ */
+export declare const AMBIGUOUS_NAMES: string[];
+export declare const PUBLIC_ATLAS: AtlasEntry[];
+//# sourceMappingURL=public-question-atlas.d.ts.map

package/dist/prompts/public-question-atlas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-question-atlas.d.ts","sourceRoot":"","sources":["../../src/prompts/public-question-atlas.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,eAAe,CAAC;IAC7B,mEAAmE;IACnE,mBAAmB,CAAC,EAAE,aAAa,CAAC;IACpC,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,oBAAoB,CAAC;IACzC,mEAAmE;IACnE,cAAc,CAAC,EAAE,mBAAmB,CAAC;CACtC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,EAWnC,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,UAAU,EAqZpC,CAAC"}