@jaypie/mcp 0.8.25 → 0.8.28

package/dist/suites/docs/index.js

@@ -1,5 +1,5 @@
 import { fabricService } from '@jaypie/fabric';
-import { createMarkdownStore, normalizeAlias, isValidAlias } from '@jaypie/tildeskill';
+import { createMarkdownStore, createLayeredStore, normalizeAlias, isValidAlias } from '@jaypie/tildeskill';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -9,7 +9,7 @@ import { gt } from 'semver';
 /**
  * Docs Suite - Documentation services (skill, version, release_notes)
  */
-const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.25#e9d2d378"
+const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.28#dbd0faa2"
     ;
 const __filename$1 = fileURLToPath(import.meta.url);
 const __dirname$1 = path.dirname(__filename$1);
@@ -17,10 +17,34 @@ const __dirname$1 = path.dirname(__filename$1);
 // Environment variables allow overriding paths when bundled (e.g., esbuild Lambda)
 const RELEASE_NOTES_PATH = process.env.MCP_RELEASE_NOTES_PATH ||
     path.join(__dirname$1, "..", "..", "..", "release-notes");
-const SKILLS_PATH = process.env.MCP_SKILLS_PATH ||
+// Bundled Jaypie skills ship inside the @jaypie/mcp package. MCP_BUILTIN_SKILLS_PATH
+// lets bundlers (esbuild, Lambda) relocate them without disabling the built-in layer.
+const BUILTIN_SKILLS_PATH = process.env.MCP_BUILTIN_SKILLS_PATH ||
     path.join(__dirname$1, "..", "..", "..", "skills");
-// Create skill store using tildeskill
-const skillStore = createMarkdownStore({ path: SKILLS_PATH });
+const LOCAL_SKILLS_NAMESPACE = "local";
+const JAYPIE_SKILLS_NAMESPACE = "jaypie";
+const LAYER_SEPARATOR = ":";
+// Skill layers resolved in order: a client's MCP_SKILLS_PATH layers on top of
+// the built-in Jaypie skill pack so `skill("aws")` prefers the client's copy
+// while still exposing bundled Jaypie docs under the `jaypie:` namespace.
+const skillLayers = [];
+const skillLayerPaths = new Map();
+if (process.env.MCP_SKILLS_PATH) {
+    skillLayers.push({
+        namespace: LOCAL_SKILLS_NAMESPACE,
+        store: createMarkdownStore({ path: process.env.MCP_SKILLS_PATH }),
+    });
+    skillLayerPaths.set(LOCAL_SKILLS_NAMESPACE, process.env.MCP_SKILLS_PATH);
+}
+skillLayers.push({
+    namespace: JAYPIE_SKILLS_NAMESPACE,
+    store: createMarkdownStore({ path: BUILTIN_SKILLS_PATH }),
+});
+skillLayerPaths.set(JAYPIE_SKILLS_NAMESPACE, BUILTIN_SKILLS_PATH);
+const skillStore = createLayeredStore({
+    layers: skillLayers,
+    separator: LAYER_SEPARATOR,
+});
 async function parseReleaseNoteFile(filePath) {
     try {
         const content = await fs.readFile(filePath, "utf-8");
@@ -98,27 +122,6 @@ function filterReleaseNotesSince(notes, sinceVersion) {
 // =============================================================================
 // SKILL SERVICE
 // =============================================================================
-/**
- * Generate alternative spellings for plural/singular matching
- */
-function getAlternativeSpellings(alias) {
-    const alternatives = [];
-    if (alias.endsWith("es")) {
-        // "indexes" -> try "indexe" and "index"
-        alternatives.push(alias.slice(0, -1)); // Remove "s" -> "indexe"
-        alternatives.push(alias.slice(0, -2)); // Remove "es" -> "index"
-    }
-    else if (alias.endsWith("s")) {
-        // "skills" -> try "skill"
-        alternatives.push(alias.slice(0, -1)); // Remove "s" -> "skill"
-    }
-    else {
-        // "fish" -> try "fishs" and "fishes"
-        alternatives.push(alias + "s");
-        alternatives.push(alias + "es");
-    }
-    return alternatives;
-}
 /**
  * Add alias to frontmatter indicating the canonical skill name
  */
@@ -153,33 +156,32 @@ const skillService = fabricService({
         }
         if (alias === "index") {
             const allSkills = await skillStore.list();
-            const skills = allSkills.filter((s) => s.alias !== "index");
+            // Index entries from every layer hide per-layer "index" records.
+            const skills = allSkills.filter((s) => s.alias !== "index" && !s.alias.endsWith(`${LAYER_SEPARATOR}index`));
             const skillList = skills.map(formatSkillListItem).join("\n");
             return `# Index of Skills\n\n${skillList}`;
         }
-        // Try exact match first
-        let skill = await skillStore.get(alias);
-        let matchedAlias = alias;
-        // If no exact match, try alternative spellings (plural/singular)
-        if (!skill) {
-            const alternatives = getAlternativeSpellings(alias);
-            for (const alt of alternatives) {
-                skill = await skillStore.get(alt);
-                if (skill) {
-                    matchedAlias = alt;
-                    break;
-                }
-            }
-        }
+        const skill = await skillStore.find(alias);
         if (!skill) {
             throw new Error(`Skill "${alias}" not found. Use skill("index") to list available skills.`);
         }
-        // Return raw file content for non-index skills (preserve frontmatter)
-        const skillPath = path.join(SKILLS_PATH, `${matchedAlias}.md`);
+        // Split the namespaced alias the layered store returned (e.g., "local:aws")
+        // so we can read the raw markdown file from the correct layer directory.
+        const separatorIdx = skill.alias.indexOf(LAYER_SEPARATOR);
+        const layerNamespace = separatorIdx === -1 ? "" : skill.alias.slice(0, separatorIdx);
+        const innerAlias = separatorIdx === -1 ? skill.alias : skill.alias.slice(separatorIdx + 1);
+        const layerPath = skillLayerPaths.get(layerNamespace);
+        if (!layerPath) {
+            // Defensive: layered store returned a layer we don't know the path for.
+            return skill.content;
+        }
+        const skillPath = path.join(layerPath, `${innerAlias}.md`);
         let content = await fs.readFile(skillPath, "utf-8");
-        // If we matched via alternative spelling, add alias to indicate canonical name
-        if (matchedAlias !== alias) {
-            content = addAliasToFrontmatter(content, matchedAlias);
+        // Detect plural/singular fallback so we can annotate the canonical alias.
+        const inputSeparatorIdx = alias.indexOf(LAYER_SEPARATOR);
+        const inputInnerAlias = inputSeparatorIdx === -1 ? alias : alias.slice(inputSeparatorIdx + 1);
+        if (innerAlias !== inputInnerAlias) {
+            content = addAliasToFrontmatter(content, skill.alias);
         }
         return content;
     },

package/dist/suites/docs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/suites/docs/index.ts"],"sourcesContent":["/**\n * Docs Suite - Documentation services (skill, version, release_notes)\n */\nimport { fabricService } from \"@jaypie/fabric\";\nimport {\n  createMarkdownStore,\n  isValidAlias,\n  normalizeAlias,\n  type SkillRecord,\n} from \"@jaypie/tildeskill\";\nimport * as fs from \"node:fs/promises\";\nimport * as path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport matter from \"gray-matter\";\nimport { gt } from \"semver\";\n\n// Build-time constants\ndeclare const __BUILD_VERSION_STRING__: string;\nconst BUILD_VERSION_STRING =\n  typeof __BUILD_VERSION_STRING__ !== \"undefined\"\n    ? __BUILD_VERSION_STRING__\n    : \"@jaypie/mcp@0.0.0\";\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n// From dist/suites/docs/, go up 3 levels to package root where skills/ and release-notes/ live\n// Environment variables allow overriding paths when bundled (e.g., esbuild Lambda)\nconst RELEASE_NOTES_PATH =\n  process.env.MCP_RELEASE_NOTES_PATH ||\n  path.join(__dirname, \"..\", \"..\", \"..\", \"release-notes\");\nconst SKILLS_PATH =\n  process.env.MCP_SKILLS_PATH ||\n  path.join(__dirname, \"..\", \"..\", \"..\", \"skills\");\n\n// Create skill store using tildeskill\nconst skillStore = createMarkdownStore({ path: SKILLS_PATH });\n\n// =============================================================================\n// HELPER FUNCTIONS\n// =============================================================================\n\ninterface ReleaseNoteFrontMatter {\n  date?: string;\n  summary?: string;\n  version?: string;\n}\n\nasync function parseReleaseNoteFile(filePath: string): Promise<{\n  date?: string;\n  filename: string;\n  summary?: string;\n  version?: string;\n}> {\n  try {\n    const content = await fs.readFile(filePath, \"utf-8\");\n    const filename = path.basename(filePath, \".md\");\n\n    if (content.startsWith(\"---\")) {\n      const parsed = matter(content);\n      const frontMatter = parsed.data as ReleaseNoteFrontMatter;\n      return {\n        date: frontMatter.date,\n        filename,\n        summary: frontMatter.summary,\n        version: frontMatter.version || filename,\n      };\n    }\n\n    return { filename, version: filename };\n  } catch {\n    return { filename: path.basename(filePath, \".md\") };\n  }\n}\n\nfunction formatReleaseNoteListItem(note: {\n  date?: string;\n  filename: string;\n  packageName: string;\n  summary?: string;\n  version?: string;\n}): string {\n  const { date, packageName, summary, version } = note;\n  const parts = [`* ${packageName}@${version}`];\n\n  if (date) {\n    parts.push(`(${date})`);\n  }\n\n  if (summary) {\n    parts.push(`- ${summary}`);\n  }\n\n  return parts.join(\" \");\n}\n\nfunction formatSkillListItem(skill: SkillRecord): string {\n  const { alias, description } = skill;\n  if (description) {\n    return `* ${alias} - ${description}`;\n  }\n  return `* ${alias}`;\n}\n\nasync function getPackageReleaseNotes(packageName: string): Promise<\n  Array<{\n    date?: string;\n    filename: string;\n    packageName: string;\n    summary?: string;\n    version?: string;\n  }>\n> {\n  const packageDir = path.join(RELEASE_NOTES_PATH, packageName);\n  try {\n    const files = await fs.readdir(packageDir);\n    const mdFiles = files.filter((file) => file.endsWith(\".md\"));\n\n    const notes = await Promise.all(\n      mdFiles.map(async (file) => {\n        const parsed = await parseReleaseNoteFile(path.join(packageDir, file));\n        return { ...parsed, packageName };\n      }),\n    );\n\n    return notes.sort((a, b) => {\n      if (!a.version || !b.version) return 0;\n      try {\n        return gt(a.version, b.version) ? -1 : 1;\n      } catch {\n        return b.version.localeCompare(a.version);\n      }\n    });\n  } catch {\n    return [];\n  }\n}\n\nfunction filterReleaseNotesSince(\n  notes: Array<{\n    date?: string;\n    filename: string;\n    packageName: string;\n    summary?: string;\n    version?: string;\n  }>,\n  sinceVersion: string,\n): Array<{\n  date?: string;\n  filename: string;\n  packageName: string;\n  summary?: string;\n  version?: string;\n}> {\n  return notes.filter((note) => {\n    if (!note.version) return false;\n    try {\n      return gt(note.version, sinceVersion);\n    } catch {\n      return false;\n    }\n  });\n}\n\n// =============================================================================\n// SKILL SERVICE\n// =============================================================================\n\n/**\n * Generate alternative spellings for plural/singular matching\n */\nfunction getAlternativeSpellings(alias: string): string[] {\n  const alternatives: string[] = [];\n\n  if (alias.endsWith(\"es\")) {\n    // \"indexes\" -> try \"indexe\" and \"index\"\n    alternatives.push(alias.slice(0, -1)); // Remove \"s\" -> \"indexe\"\n    alternatives.push(alias.slice(0, -2)); // Remove \"es\" -> \"index\"\n  } else if (alias.endsWith(\"s\")) {\n    // \"skills\" -> try \"skill\"\n    alternatives.push(alias.slice(0, -1)); // Remove \"s\" -> \"skill\"\n  } else {\n    // \"fish\" -> try \"fishs\" and \"fishes\"\n    alternatives.push(alias + \"s\");\n    alternatives.push(alias + \"es\");\n  }\n\n  return alternatives;\n}\n\n/**\n * Add alias to frontmatter indicating the canonical skill name\n */\nfunction addAliasToFrontmatter(content: string, matchedAlias: string): string {\n  if (content.startsWith(\"---\")) {\n    // Find the end of frontmatter\n    const endIndex = content.indexOf(\"---\", 3);\n    if (endIndex !== -1) {\n      // Insert alias before the closing ---\n      const beforeClose = content.slice(0, endIndex);\n      const afterClose = content.slice(endIndex);\n      return `${beforeClose}alias: ${matchedAlias}\\n${afterClose}`;\n    }\n  }\n  // No frontmatter exists, create one\n  return `---\\nalias: ${matchedAlias}\\n---\\n\\n${content}`;\n}\n\nexport const skillService = fabricService({\n  alias: \"skill\",\n  description:\n    \"Access Jaypie development documentation. Pass a skill alias (e.g., 'aws', 'tests', 'errors') to get that documentation. Pass 'index' or no argument to list all available skills.\",\n  input: {\n    alias: {\n      description:\n        \"Skill alias (e.g., 'aws', 'tests'). Omit or use 'index' to list all skills.\",\n      required: false,\n      type: String,\n    },\n  },\n  service: async ({ alias: inputAlias }: { alias?: string }) => {\n    const alias = normalizeAlias(inputAlias || \"index\");\n\n    if (!isValidAlias(alias)) {\n      throw new Error(\n        `Invalid skill alias \"${alias}\". Use alphanumeric characters, hyphens, and underscores only.`,\n      );\n    }\n\n    if (alias === \"index\") {\n      const allSkills = await skillStore.list();\n      const skills = allSkills.filter(\n        (s: { alias: string }) => s.alias !== \"index\",\n      );\n      const skillList = skills.map(formatSkillListItem).join(\"\\n\");\n\n      return `# Index of Skills\\n\\n${skillList}`;\n    }\n\n    // Try exact match first\n    let skill = await skillStore.get(alias);\n    let matchedAlias = alias;\n\n    // If no exact match, try alternative spellings (plural/singular)\n    if (!skill) {\n      const alternatives = getAlternativeSpellings(alias);\n      for (const alt of alternatives) {\n        skill = await skillStore.get(alt);\n        if (skill) {\n          matchedAlias = alt;\n          break;\n        }\n      }\n    }\n\n    if (!skill) {\n      throw new Error(\n        `Skill \"${alias}\" not found. Use skill(\"index\") to list available skills.`,\n      );\n    }\n\n    // Return raw file content for non-index skills (preserve frontmatter)\n    const skillPath = path.join(SKILLS_PATH, `${matchedAlias}.md`);\n    let content = await fs.readFile(skillPath, \"utf-8\");\n\n    // If we matched via alternative spelling, add alias to indicate canonical name\n    if (matchedAlias !== alias) {\n      content = addAliasToFrontmatter(content, matchedAlias);\n    }\n\n    return content;\n  },\n});\n\n// =============================================================================\n// VERSION SERVICE\n// =============================================================================\n\nexport const versionService = fabricService({\n  alias: \"version\",\n  description: `Prints the current version and hash, \\`${BUILD_VERSION_STRING}\\``,\n  input: {},\n  service: async () => BUILD_VERSION_STRING,\n});\n\n// =============================================================================\n// RELEASE NOTES SERVICE\n// =============================================================================\n\nasync function getReleaseNotesHelp(): Promise<string> {\n  return fs.readFile(path.join(__dirname, \"release-notes\", \"help.md\"), \"utf-8\");\n}\n\ninterface ReleaseNotesInput {\n  package?: string;\n  since_version?: string;\n  version?: string;\n}\n\nexport const releaseNotesService = fabricService({\n  alias: \"release_notes\",\n  description:\n    \"Browse Jaypie package release notes. Commands: list, read. Call with no args for help.\",\n  input: {\n    command: {\n      description: \"Command to execute (omit for help)\",\n      required: false,\n      type: String,\n    },\n    input: {\n      description: \"Command parameters\",\n      required: false,\n      type: Object,\n    },\n  },\n  service: async ({\n    command,\n    input: params,\n  }: {\n    command?: string;\n    input?: ReleaseNotesInput;\n  }) => {\n    if (!command || command === \"help\") {\n      return getReleaseNotesHelp();\n    }\n\n    const p = params || {};\n\n    switch (command) {\n      case \"list\": {\n        const entries = await fs.readdir(RELEASE_NOTES_PATH, {\n          withFileTypes: true,\n        });\n        const packageDirs = entries\n          .filter((entry) => entry.isDirectory())\n          .map((entry) => entry.name);\n        const packagesToList = p.package\n          ? packageDirs.filter((pkg) => pkg === p.package)\n          : packageDirs;\n\n        if (packagesToList.length === 0 && p.package) {\n          return `No release notes found for package \"${p.package}\".`;\n        }\n\n        const allNotes = await Promise.all(\n          packagesToList.map((pkg) => getPackageReleaseNotes(pkg)),\n        );\n        let flatNotes = allNotes.flat();\n\n        if (p.since_version) {\n          flatNotes = filterReleaseNotesSince(flatNotes, p.since_version);\n        }\n\n        if (flatNotes.length === 0) {\n          const filterDesc = p.since_version\n            ? ` newer than ${p.since_version}`\n            : \"\";\n          return `No release notes found${filterDesc}.`;\n        }\n\n        return flatNotes.map(formatReleaseNoteListItem).join(\"\\n\");\n      }\n\n      case \"read\": {\n        if (!p.package) throw new Error(\"package is required\");\n        if (!p.version) throw new Error(\"version is required\");\n        const filePath = path.join(\n          RELEASE_NOTES_PATH,\n          p.package,\n          `${p.version}.md`,\n        );\n        return fs.readFile(filePath, \"utf-8\");\n      }\n\n      default:\n        throw new Error(\n          `Unknown command: ${command}. Use release_notes() for help.`,\n        );\n    }\n  },\n});\n"],"names":["__filename","__dirname"],"mappings":";;;;;;;;AAAA;;AAEG;AAgBH,MAAM,oBAAoB,GAEpB;IACmB;AAEzB,MAAMA,YAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;AACjD,MAAMC,WAAS,GAAG,IAAI,CAAC,OAAO,CAACD,YAAU,CAAC;AAC1C;AACA;AACA,MAAM,kBAAkB,GACtB,OAAO,CAAC,GAAG,CAAC,sBAAsB;AAClC,IAAA,IAAI,CAAC,IAAI,CAACC,WAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,CAAC;AACzD,MAAM,WAAW,GACf,OAAO,CAAC,GAAG,CAAC,eAAe;AAC3B,IAAA,IAAI,CAAC,IAAI,CAACA,WAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC;AAElD;AACA,MAAM,UAAU,GAAG,mBAAmB,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;AAY7D,eAAe,oBAAoB,CAAC,QAAgB,EAAA;AAMlD,IAAA,IAAI;QACF,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;AAE/C,QAAA,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE;AAC7B,YAAA,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;AAC9B,YAAA,MAAM,WAAW,GAAG,MAAM,CAAC,IAA8B;YACzD,OAAO;gBACL,IAAI,EAAE,WAAW,CAAC,IAAI;gBACtB,QAAQ;gBACR,OAAO,EAAE,WAAW,CAAC,OAAO;AAC5B,gBAAA,OAAO,EAAE,WAAW,CAAC,OAAO,IAAI,QAAQ;aACzC;QACH;AAEA,QAAA,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE;IACxC;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE;IACrD;AACF;AAEA,SAAS,yBAAyB,CAAC,IAMlC,EAAA;IACC,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI;IACpD,MAAM,KAAK,GAAG,CAAC,CAAA,EAAA,EAAK,WAAW,CAAA,CAAA,EAAI,OAAO,CAAA,CAAE,CAAC;IAE7C,IAAI,IAAI,EAAE;AACR,QAAA,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAA,CAAA,CAAG,CAAC;IACzB;IAEA,IAAI,OAAO,EAAE;AACX,QAAA,KAAK,CAAC,IAAI,CAAC,KAAK,OAAO,CAAA,CAAE,CAAC;IAC5B;AAEA,IAAA,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;AACxB;AAEA,SAAS,mBAAmB,CAAC,KAAkB,EAAA;AAC7C,IAAA,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,KAAK;IACpC,IAAI,WAAW,EAAE;AACf,QAAA,OAAO,CAAA,EAAA,EAAK,KAAK,CAAA,GAAA,EAAM,WAAW,EAAE;IACtC;IACA,OAAO,CAAA,EAAA,EAAK,KAAK,CAAA,CAAE;AACrB;AAEA,eAAe,sBAAsB,CAAC,WAAmB,EAAA;IASvD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC;AAC7D,IAAA,IAAI;QACF,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC;AAC1C,QAAA,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAE5D,QAAA,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAC7B,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,KAAI;AACzB,YAAA,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;AACtE,YAAA,OAAO,EAAE,GAAG,MAAM,EAAE,WAAW,EAAE;QACnC,CAAC,CAAC,CACH;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KAAI;YACzB,IAAI,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO;AAAE,gBAAA,OAAO,CAAC;AACtC,YAAA,IAAI;AACF,gBAAA,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC;YAC1C;AAAE,YAAA,MAAM;gBACN,OAAO,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC;YAC3C;AACF,QAAA,CAAC,CAAC;IACJ;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,EAAE;IACX;AACF;AAEA,SAAS,uBAAuB,CAC9B,KAME,EACF,YAAoB,EAAA;AAQpB,IAAA,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,KAAI;QAC3B,IAAI,CAAC,IAAI,CAAC,OAAO;AAAE,YAAA,OAAO,KAAK;AAC/B,QAAA,IAAI;YACF,OAAO,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC;QACvC;AAAE,QAAA,MAAM;AACN,YAAA,OAAO,KAAK;QACd;AACF,IAAA,CAAC,CAAC;AACJ;AAEA;AACA;AACA;AAEA;;AAEG;AACH,SAAS,uBAAuB,CAAC,KAAa,EAAA;IAC5C,MAAM,YAAY,GAAa,EAAE;AAEjC,IAAA,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE;;AAExB,QAAA,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AACtC,QAAA,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IACxC;AAAO,SAAA,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE;;AAE9B,QAAA,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IACxC;SAAO;;AAEL,QAAA,YAAY,CAAC,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC;AAC9B,QAAA,YAAY,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACjC;AAEA,IAAA,OAAO,YAAY;AACrB;AAEA;;AAEG;AACH,SAAS,qBAAqB,CAAC,OAAe,EAAE,YAAoB,EAAA;AAClE,IAAA,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE;;QAE7B,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;AAC1C,QAAA,IAAI,QAAQ,KAAK,EAAE,EAAE;;YAEnB,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC;YAC9C,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC;AAC1C,YAAA,OAAO,GAAG,WAAW,CAAA,OAAA,EAAU,YAAY,CAAA,EAAA,EAAK,UAAU,EAAE;QAC9D;IACF;;AAEA,IAAA,OAAO,CAAA,YAAA,EAAe,YAAY,CAAA,SAAA,EAAY,OAAO,EAAE;AACzD;AAEO,MAAM,YAAY,GAAG,aAAa,CAAC;AACxC,IAAA,KAAK,EAAE,OAAO;AACd,IAAA,WAAW,EACT,mLAAmL;AACrL,IAAA,KAAK,EAAE;AACL,QAAA,KAAK,EAAE;AACL,YAAA,WAAW,EACT,6EAA6E;AAC/E,YAAA,QAAQ,EAAE,KAAK;AACf,YAAA,IAAI,EAAE,MAAM;AACb,SAAA;AACF,KAAA;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAsB,KAAI;QAC3D,MAAM,KAAK,GAAG,cAAc,CAAC,UAAU,IAAI,OAAO,CAAC;AAEnD,QAAA,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE;AACxB,YAAA,MAAM,IAAI,KAAK,CACb,wBAAwB,KAAK,CAAA,8DAAA,CAAgE,CAC9F;QACH;AAEA,QAAA,IAAI,KAAK,KAAK,OAAO,EAAE;AACrB,YAAA,MAAM,SAAS,GAAG,MAAM,UAAU,CAAC,IAAI,EAAE;AACzC,YAAA,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAC7B,CAAC,CAAoB,KAAK,CAAC,CAAC,KAAK,KAAK,OAAO,CAC9C;AACD,YAAA,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YAE5D,OAAO,CAAA,qBAAA,EAAwB,SAAS,CAAA,CAAE;QAC5C;;QAGA,IAAI,KAAK,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC;QACvC,IAAI,YAAY,GAAG,KAAK;;QAGxB,IAAI,CAAC,KAAK,EAAE;AACV,YAAA,MAAM,YAAY,GAAG,uBAAuB,CAAC,KAAK,CAAC;AACnD,YAAA,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE;gBAC9B,KAAK,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;gBACjC,IAAI,KAAK,EAAE;oBACT,YAAY,GAAG,GAAG;oBAClB;gBACF;YACF;QACF;QAEA,IAAI,CAAC,KAAK,EAAE;AACV,YAAA,MAAM,IAAI,KAAK,CACb,UAAU,KAAK,CAAA,yDAAA,CAA2D,CAC3E;QACH;;AAGA,QAAA,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAA,EAAG,YAAY,CAAA,GAAA,CAAK,CAAC;QAC9D,IAAI,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;;AAGnD,QAAA,IAAI,YAAY,KAAK,KAAK,EAAE;AAC1B,YAAA,OAAO,GAAG,qBAAqB,CAAC,OAAO,EAAE,YAAY,CAAC;QACxD;AAEA,QAAA,OAAO,OAAO;IAChB,CAAC;AACF,CAAA;AAED;AACA;AACA;AAEO,MAAM,cAAc,GAAG,aAAa,CAAC;AAC1C,IAAA,KAAK,EAAE,SAAS;IAChB,WAAW,EAAE,CAAA,uCAAA,EAA0C,oBAAoB,CAAA,EAAA,CAAI;AAC/E,IAAA,KAAK,EAAE,EAAE;AACT,IAAA,OAAO,EAAE,YAAY,oBAAoB;AAC1C,CAAA;AAED;AACA;AACA;AAEA,eAAe,mBAAmB,GAAA;AAChC,IAAA,OAAO,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAACA,WAAS,EAAE,eAAe,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC;AAC/E;AAQO,MAAM,mBAAmB,GAAG,aAAa,CAAC;AAC/C,IAAA,KAAK,EAAE,eAAe;AACtB,IAAA,WAAW,EACT,wFAAwF;AAC1F,IAAA,KAAK,EAAE;AACL,QAAA,OAAO,EAAE;AACP,YAAA,WAAW,EAAE,oCAAoC;AACjD,YAAA,QAAQ,EAAE,KAAK;AACf,YAAA,IAAI,EAAE,MAAM;AACb,SAAA;AACD,QAAA,KAAK,EAAE;AACL,YAAA,WAAW,EAAE,oBAAoB;AACjC,YAAA,QAAQ,EAAE,KAAK;AACf,YAAA,IAAI,EAAE,MAAM;AACb,SAAA;AACF,KAAA;IACD,OAAO,EAAE,OAAO,EACd,OAAO,EACP,KAAK,EAAE,MAAM,GAId,KAAI;AACH,QAAA,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,MAAM,EAAE;YAClC,OAAO,mBAAmB,EAAE;QAC9B;AAEA,QAAA,MAAM,CAAC,GAAG,MAAM,IAAI,EAAE;QAEtB,QAAQ,OAAO;YACb,KAAK,MAAM,EAAE;gBACX,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,kBAAkB,EAAE;AACnD,oBAAA,aAAa,EAAE,IAAI;AACpB,iBAAA,CAAC;gBACF,MAAM,WAAW,GAAG;qBACjB,MAAM,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,WAAW,EAAE;qBACrC,GAAG,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,IAAI,CAAC;AAC7B,gBAAA,MAAM,cAAc,GAAG,CAAC,CAAC;AACvB,sBAAE,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,KAAK,GAAG,KAAK,CAAC,CAAC,OAAO;sBAC7C,WAAW;gBAEf,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE;AAC5C,oBAAA,OAAO,CAAA,oCAAA,EAAuC,CAAC,CAAC,OAAO,IAAI;gBAC7D;gBAEA,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAChC,cAAc,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,sBAAsB,CAAC,GAAG,CAAC,CAAC,CACzD;AACD,gBAAA,IAAI,SAAS,GAAG,QAAQ,CAAC,IAAI,EAAE;AAE/B,gBAAA,IAAI,CAAC,CAAC,aAAa,EAAE;oBACnB,SAAS,GAAG,uBAAuB,CAAC,SAAS,EAAE,CAAC,CAAC,aAAa,CAAC;gBACjE;AAEA,gBAAA,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE;AAC1B,oBAAA,MAAM,UAAU,GAAG,CAAC,CAAC;AACnB,0BAAE,CAAA,YAAA,EAAe,CAAC,CAAC,aAAa,CAAA;0BAC9B,EAAE;oBACN,OAAO,CAAA,sBAAA,EAAyB,UAAU,CAAA,CAAA,CAAG;gBAC/C;gBAEA,OAAO,SAAS,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YAC5D;YAEA,KAAK,MAAM,EAAE;gBACX,IAAI,CAAC,CAAC,CAAC,OAAO;AAAE,oBAAA,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC;gBACtD,IAAI,CAAC,CAAC,CAAC,OAAO;AAAE,oBAAA,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC;AACtD,gBAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CACxB,kBAAkB,EAClB,CAAC,CAAC,OAAO,EACT,CAAA,EAAG,CAAC,CAAC,OAAO,CAAA,GAAA,CAAK,CAClB;gBACD,OAAO,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;YACvC;AAEA,YAAA;AACE,gBAAA,MAAM,IAAI,KAAK,CACb,oBAAoB,OAAO,CAAA,+BAAA,CAAiC,CAC7D;;IAEP,CAAC;AACF,CAAA;;;;"}
+{"version":3,"file":"index.js","sources":["../../../src/suites/docs/index.ts"],"sourcesContent":["/**\n * Docs Suite - Documentation services (skill, version, release_notes)\n */\nimport { fabricService } from \"@jaypie/fabric\";\nimport {\n  createLayeredStore,\n  createMarkdownStore,\n  isValidAlias,\n  type LayeredStoreLayer,\n  normalizeAlias,\n  type SkillRecord,\n} from \"@jaypie/tildeskill\";\nimport * as fs from \"node:fs/promises\";\nimport * as path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport matter from \"gray-matter\";\nimport { gt } from \"semver\";\n\n// Build-time constants\ndeclare const __BUILD_VERSION_STRING__: string;\nconst BUILD_VERSION_STRING =\n  typeof __BUILD_VERSION_STRING__ !== \"undefined\"\n    ? __BUILD_VERSION_STRING__\n    : \"@jaypie/mcp@0.0.0\";\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n// From dist/suites/docs/, go up 3 levels to package root where skills/ and release-notes/ live\n// Environment variables allow overriding paths when bundled (e.g., esbuild Lambda)\nconst RELEASE_NOTES_PATH =\n  process.env.MCP_RELEASE_NOTES_PATH ||\n  path.join(__dirname, \"..\", \"..\", \"..\", \"release-notes\");\n\n// Bundled Jaypie skills ship inside the @jaypie/mcp package. MCP_BUILTIN_SKILLS_PATH\n// lets bundlers (esbuild, Lambda) relocate them without disabling the built-in layer.\nconst BUILTIN_SKILLS_PATH =\n  process.env.MCP_BUILTIN_SKILLS_PATH ||\n  path.join(__dirname, \"..\", \"..\", \"..\", \"skills\");\n\nconst LOCAL_SKILLS_NAMESPACE = \"local\";\nconst JAYPIE_SKILLS_NAMESPACE = \"jaypie\";\nconst LAYER_SEPARATOR = \":\";\n\n// Skill layers resolved in order: a client's MCP_SKILLS_PATH layers on top of\n// the built-in Jaypie skill pack so `skill(\"aws\")` prefers the client's copy\n// while still exposing bundled Jaypie docs under the `jaypie:` namespace.\nconst skillLayers: LayeredStoreLayer[] = [];\nconst skillLayerPaths = new Map<string, string>();\n\nif (process.env.MCP_SKILLS_PATH) {\n  skillLayers.push({\n    namespace: LOCAL_SKILLS_NAMESPACE,\n    store: createMarkdownStore({ path: process.env.MCP_SKILLS_PATH }),\n  });\n  skillLayerPaths.set(LOCAL_SKILLS_NAMESPACE, process.env.MCP_SKILLS_PATH);\n}\n\nskillLayers.push({\n  namespace: JAYPIE_SKILLS_NAMESPACE,\n  store: createMarkdownStore({ path: BUILTIN_SKILLS_PATH }),\n});\nskillLayerPaths.set(JAYPIE_SKILLS_NAMESPACE, BUILTIN_SKILLS_PATH);\n\nconst skillStore = createLayeredStore({\n  layers: skillLayers,\n  separator: LAYER_SEPARATOR,\n});\n\n// =============================================================================\n// HELPER FUNCTIONS\n// =============================================================================\n\ninterface ReleaseNoteFrontMatter {\n  date?: string;\n  summary?: string;\n  version?: string;\n}\n\nasync function parseReleaseNoteFile(filePath: string): Promise<{\n  date?: string;\n  filename: string;\n  summary?: string;\n  version?: string;\n}> {\n  try {\n    const content = await fs.readFile(filePath, \"utf-8\");\n    const filename = path.basename(filePath, \".md\");\n\n    if (content.startsWith(\"---\")) {\n      const parsed = matter(content);\n      const frontMatter = parsed.data as ReleaseNoteFrontMatter;\n      return {\n        date: frontMatter.date,\n        filename,\n        summary: frontMatter.summary,\n        version: frontMatter.version || filename,\n      };\n    }\n\n    return { filename, version: filename };\n  } catch {\n    return { filename: path.basename(filePath, \".md\") };\n  }\n}\n\nfunction formatReleaseNoteListItem(note: {\n  date?: string;\n  filename: string;\n  packageName: string;\n  summary?: string;\n  version?: string;\n}): string {\n  const { date, packageName, summary, version } = note;\n  const parts = [`* ${packageName}@${version}`];\n\n  if (date) {\n    parts.push(`(${date})`);\n  }\n\n  if (summary) {\n    parts.push(`- ${summary}`);\n  }\n\n  return parts.join(\" \");\n}\n\nfunction formatSkillListItem(skill: SkillRecord): string {\n  const { alias, description } = skill;\n  if (description) {\n    return `* ${alias} - ${description}`;\n  }\n  return `* ${alias}`;\n}\n\nasync function getPackageReleaseNotes(packageName: string): Promise<\n  Array<{\n    date?: string;\n    filename: string;\n    packageName: string;\n    summary?: string;\n    version?: string;\n  }>\n> {\n  const packageDir = path.join(RELEASE_NOTES_PATH, packageName);\n  try {\n    const files = await fs.readdir(packageDir);\n    const mdFiles = files.filter((file) => file.endsWith(\".md\"));\n\n    const notes = await Promise.all(\n      mdFiles.map(async (file) => {\n        const parsed = await parseReleaseNoteFile(path.join(packageDir, file));\n        return { ...parsed, packageName };\n      }),\n    );\n\n    return notes.sort((a, b) => {\n      if (!a.version || !b.version) return 0;\n      try {\n        return gt(a.version, b.version) ? -1 : 1;\n      } catch {\n        return b.version.localeCompare(a.version);\n      }\n    });\n  } catch {\n    return [];\n  }\n}\n\nfunction filterReleaseNotesSince(\n  notes: Array<{\n    date?: string;\n    filename: string;\n    packageName: string;\n    summary?: string;\n    version?: string;\n  }>,\n  sinceVersion: string,\n): Array<{\n  date?: string;\n  filename: string;\n  packageName: string;\n  summary?: string;\n  version?: string;\n}> {\n  return notes.filter((note) => {\n    if (!note.version) return false;\n    try {\n      return gt(note.version, sinceVersion);\n    } catch {\n      return false;\n    }\n  });\n}\n\n// =============================================================================\n// SKILL SERVICE\n// =============================================================================\n\n/**\n * Add alias to frontmatter indicating the canonical skill name\n */\nfunction addAliasToFrontmatter(content: string, matchedAlias: string): string {\n  if (content.startsWith(\"---\")) {\n    // Find the end of frontmatter\n    const endIndex = content.indexOf(\"---\", 3);\n    if (endIndex !== -1) {\n      // Insert alias before the closing ---\n      const beforeClose = content.slice(0, endIndex);\n      const afterClose = content.slice(endIndex);\n      return `${beforeClose}alias: ${matchedAlias}\\n${afterClose}`;\n    }\n  }\n  // No frontmatter exists, create one\n  return `---\\nalias: ${matchedAlias}\\n---\\n\\n${content}`;\n}\n\nexport const skillService = fabricService({\n  alias: \"skill\",\n  description:\n    \"Access Jaypie development documentation. Pass a skill alias (e.g., 'aws', 'tests', 'errors') to get that documentation. Pass 'index' or no argument to list all available skills.\",\n  input: {\n    alias: {\n      description:\n        \"Skill alias (e.g., 'aws', 'tests'). Omit or use 'index' to list all skills.\",\n      required: false,\n      type: String,\n    },\n  },\n  service: async ({ alias: inputAlias }: { alias?: string }) => {\n    const alias = normalizeAlias(inputAlias || \"index\");\n\n    if (!isValidAlias(alias)) {\n      throw new Error(\n        `Invalid skill alias \"${alias}\". Use alphanumeric characters, hyphens, and underscores only.`,\n      );\n    }\n\n    if (alias === \"index\") {\n      const allSkills = await skillStore.list();\n      // Index entries from every layer hide per-layer \"index\" records.\n      const skills = allSkills.filter(\n        (s: { alias: string }) =>\n          s.alias !== \"index\" && !s.alias.endsWith(`${LAYER_SEPARATOR}index`),\n      );\n      const skillList = skills.map(formatSkillListItem).join(\"\\n\");\n\n      return `# Index of Skills\\n\\n${skillList}`;\n    }\n\n    const skill = await skillStore.find(alias);\n\n    if (!skill) {\n      throw new Error(\n        `Skill \"${alias}\" not found. Use skill(\"index\") to list available skills.`,\n      );\n    }\n\n    // Split the namespaced alias the layered store returned (e.g., \"local:aws\")\n    // so we can read the raw markdown file from the correct layer directory.\n    const separatorIdx = skill.alias.indexOf(LAYER_SEPARATOR);\n    const layerNamespace =\n      separatorIdx === -1 ? \"\" : skill.alias.slice(0, separatorIdx);\n    const innerAlias =\n      separatorIdx === -1 ? skill.alias : skill.alias.slice(separatorIdx + 1);\n    const layerPath = skillLayerPaths.get(layerNamespace);\n    if (!layerPath) {\n      // Defensive: layered store returned a layer we don't know the path for.\n      return skill.content;\n    }\n\n    const skillPath = path.join(layerPath, `${innerAlias}.md`);\n    let content = await fs.readFile(skillPath, \"utf-8\");\n\n    // Detect plural/singular fallback so we can annotate the canonical alias.\n    const inputSeparatorIdx = alias.indexOf(LAYER_SEPARATOR);\n    const inputInnerAlias =\n      inputSeparatorIdx === -1 ? alias : alias.slice(inputSeparatorIdx + 1);\n    if (innerAlias !== inputInnerAlias) {\n      content = addAliasToFrontmatter(content, skill.alias);\n    }\n\n    return content;\n  },\n});\n\n// =============================================================================\n// VERSION SERVICE\n// =============================================================================\n\nexport const versionService = fabricService({\n  alias: \"version\",\n  description: `Prints the current version and hash, \\`${BUILD_VERSION_STRING}\\``,\n  input: {},\n  service: async () => BUILD_VERSION_STRING,\n});\n\n// =============================================================================\n// RELEASE NOTES SERVICE\n// =============================================================================\n\nasync function getReleaseNotesHelp(): Promise<string> {\n  return fs.readFile(path.join(__dirname, \"release-notes\", \"help.md\"), \"utf-8\");\n}\n\ninterface ReleaseNotesInput {\n  package?: string;\n  since_version?: string;\n  version?: string;\n}\n\nexport const releaseNotesService = fabricService({\n  alias: \"release_notes\",\n  description:\n    \"Browse Jaypie package release notes. Commands: list, read. Call with no args for help.\",\n  input: {\n    command: {\n      description: \"Command to execute (omit for help)\",\n      required: false,\n      type: String,\n    },\n    input: {\n      description: \"Command parameters\",\n      required: false,\n      type: Object,\n    },\n  },\n  service: async ({\n    command,\n    input: params,\n  }: {\n    command?: string;\n    input?: ReleaseNotesInput;\n  }) => {\n    if (!command || command === \"help\") {\n      return getReleaseNotesHelp();\n    }\n\n    const p = params || {};\n\n    switch (command) {\n      case \"list\": {\n        const entries = await fs.readdir(RELEASE_NOTES_PATH, {\n          withFileTypes: true,\n        });\n        const packageDirs = entries\n          .filter((entry) => entry.isDirectory())\n          .map((entry) => entry.name);\n        const packagesToList = p.package\n          ? packageDirs.filter((pkg) => pkg === p.package)\n          : packageDirs;\n\n        if (packagesToList.length === 0 && p.package) {\n          return `No release notes found for package \"${p.package}\".`;\n        }\n\n        const allNotes = await Promise.all(\n          packagesToList.map((pkg) => getPackageReleaseNotes(pkg)),\n        );\n        let flatNotes = allNotes.flat();\n\n        if (p.since_version) {\n          flatNotes = filterReleaseNotesSince(flatNotes, p.since_version);\n        }\n\n        if (flatNotes.length === 0) {\n          const filterDesc = p.since_version\n            ? ` newer than ${p.since_version}`\n            : \"\";\n          return `No release notes found${filterDesc}.`;\n        }\n\n        return flatNotes.map(formatReleaseNoteListItem).join(\"\\n\");\n      }\n\n      case \"read\": {\n        if (!p.package) throw new Error(\"package is required\");\n        if (!p.version) throw new Error(\"version is required\");\n        const filePath = path.join(\n          RELEASE_NOTES_PATH,\n          p.package,\n          `${p.version}.md`,\n        );\n        return fs.readFile(filePath, \"utf-8\");\n      }\n\n      default:\n        throw new Error(\n          `Unknown command: ${command}. Use release_notes() for help.`,\n        );\n    }\n  },\n});\n"],"names":["__filename","__dirname"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/mcp",
-  "version": "0.8.25",
+  "version": "0.8.28",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",
@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "@jaypie/fabric": "^0.2.4",
-    "@jaypie/tildeskill": "^0.2.0",
+    "@jaypie/tildeskill": "^0.3.0",
     "@modelcontextprotocol/sdk": "^1.17.0",
     "commander": "^14.0.0",
     "gray-matter": "^4.0.3",

package/release-notes/dynamodb/0.5.0.md

@@ -0,0 +1,69 @@
+---
+version: "0.5.0"
+date: "2026-04-11"
+summary: "Breaking: model-keyed GSIs, pk=id, updatedAt as sort key, auto-bump timestamps"
+---
+
+# @jaypie/dynamodb 0.5.0
+
+**Tables must be recreated.** This is a pre-1.0 breaking change that restructures the primary key, GSI schema, and timestamp management.
+
+## Breaking Changes
+
+### Primary Key
+
+- **Old**: pk=`model`, sk=`id`
+- **New**: pk=`id` only (no sort key)
+
+Entity operations `getEntity`, `deleteEntity`, `archiveEntity`, and `destroyEntity` now take `{ id }` instead of `{ id, model }`.
+
+### GSI Schema
+
+GSIs are now model-keyed with composite sort keys instead of scope-keyed with `sequence`:
+
+| Old GSI | Old pk pattern | New GSI | New pk pattern |
+|---------|---------------|---------|---------------|
+| indexScope | `{scope}#{model}` | indexModel | `{model}` |
+| indexAlias | `{scope}#{model}#{alias}` | indexModelAlias | `{model}#{alias}` |
+| indexCategory | `{scope}#{model}#{category}` | indexModelCategory | `{model}#{category}` |
+| indexType | `{scope}#{model}#{type}` | indexModelType | `{model}#{type}` |
+| indexXid | `{scope}#{model}#{xid}` | indexModelXid | `{model}#{xid}` |
+
+All GSIs now use a composite sort key: `{scope}#{updatedAt}` (stored as `{indexName}Sk`). Queries use `begins_with` on the sk composite to filter by scope.
+
+### Removed
+
+- **`sequence` field** -- ordering is now by `updatedAt` in the composite sk
+- **Key builder functions**: `buildIndexScope`, `buildIndexAlias`, `buildIndexCategory`, `buildIndexType`, `buildIndexXid` -- use `buildCompositeKey` instead
+- **Index name constants**: `INDEX_ALIAS`, `INDEX_CATEGORY`, `INDEX_SCOPE`, `INDEX_TYPE`, `INDEX_XID`
+- **Implicit `DEFAULT_INDEXES` fallback** -- models must be registered with `registerModel()` and `fabricIndex()` before querying
+
+### Changed Signatures
+
+| Function | Old | New |
+|----------|-----|-----|
+| `getEntity` | `{ id, model }` | `{ id }` |
+| `deleteEntity` | `{ id, model }` | `{ id }` |
+| `archiveEntity` | `{ id, model }` | `{ id }` |
+| `destroyEntity` | `{ id, model }` | `{ id }` |
+| `queryByScope` | `{ model, scope }` (scope required) | `{ model, scope? }` (scope optional) |
+| `queryByAlias` | `{ alias, model, scope }` (scope required) | `{ alias, model, scope? }` (scope optional) |
+| `queryByCategory` | `{ model, scope, category }` | `{ model, category, scope? }` -- throws `ConfigurationError` if model hasn't registered `fabricIndex("category")` |
+| `queryByType` | `{ model, scope, type }` | `{ model, type, scope? }` -- throws `ConfigurationError` if model hasn't registered `fabricIndex("type")` |
+
+### Timestamp Management
+
+`indexEntity` now manages `updatedAt` and `createdAt` automatically on every write:
+- `updatedAt` is bumped to `new Date().toISOString()` on every call
+- `createdAt` is backfilled to the same timestamp if not already set
+- Callers should no longer set these fields manually
+
+## Migration
+
+1. Register model indexes using `fabricIndex()` from `@jaypie/fabric`
+2. Recreate DynamoDB tables (primary key and GSI shapes have changed)
+3. Remove `sequence` from entity creation code
+4. Remove `model` parameter from `getEntity`, `deleteEntity`, `archiveEntity`, `destroyEntity` calls
+5. Remove manual `createdAt`/`updatedAt` assignment
+6. Replace old key builder functions with `buildCompositeKey`
+7. Optionally make `scope` omitted in query calls to query across all scopes

package/release-notes/fabric/0.3.0.md

@@ -0,0 +1,41 @@
+---
+version: "0.3.0"
+date: "2026-04-11"
+summary: "Breaking: fabricIndex factory, remove DEFAULT_INDEXES, drop sequence, composite sk support"
+---
+
+# @jaypie/fabric 0.3.0
+
+## Breaking Changes
+
+- **Removed `DEFAULT_INDEXES`** export and the implicit fallback in `getModelIndexes()`. Models must now be registered with `registerModel()` before indexing or querying. Calling `getModelIndexes()` on an unregistered model throws `ConfigurationError`.
+- **Removed `sequence` field** from `FabricModel` and `IndexableModel`. Sort ordering is now by `updatedAt` via composite sort keys.
+- **Removed `DEFAULT_SORT_KEY`** constant (was `"sequence"`).
+
+## New Features
+
+- **`fabricIndex(field?)`** factory function for building canonical Jaypie GSI definitions:
+  - `fabricIndex()` produces `indexModel` with pk=`["model"]`, sk=`["scope", "updatedAt"]`
+  - `fabricIndex("alias")` produces `indexModelAlias` with pk=`["model", "alias"]`, sk=`["scope", "updatedAt"]`, sparse
+  - Works for any field: `fabricIndex("category")`, `fabricIndex("xid")`, `fabricIndex("customField")`
+- **`getGsiAttributeNames(index)`** returns `{ pk, sk }` attribute names for an index definition. Single source of truth for GSI provisioning and query attribute references.
+- **Composite sk support in `populateIndexKeys`**: when `sk.length > 1`, writes a composite sk attribute named `{indexName}Sk` (e.g., `indexModelSk = "scope#updatedAt"`). When `sk.length === 1`, the single field is used directly as the GSI sort key (no extra attribute written).
+
+## Migration
+
+Replace `DEFAULT_INDEXES` usage with explicit `fabricIndex()` calls:
+
+```typescript
+import { fabricIndex, registerModel } from "@jaypie/fabric";
+
+registerModel({
+  model: "record",
+  indexes: [
+    fabricIndex(),           // indexModel
+    fabricIndex("alias"),    // indexModelAlias
+    fabricIndex("category"), // indexModelCategory
+  ],
+});
+```
+
+Remove any references to `sequence` from entity creation or update code. Ordering is now by `updatedAt`, which is managed automatically by `indexEntity`.

package/release-notes/mcp/0.8.26.md

@@ -0,0 +1,10 @@
+---
+version: 0.8.26
+date: 2026-04-11
+summary: Delegate skill plural/singular resolution to @jaypie/tildeskill find()
+---
+
+## Changes
+
+- Skill service now calls `skillStore.find(alias)` from `@jaypie/tildeskill@0.2.1` instead of duplicating the plural/singular fallback loop
+- No behavior change for callers; `skill("indexes")`, `skill("skills")`, etc. still resolve to their canonical files

package/release-notes/mcp/0.8.27.md

@@ -0,0 +1,17 @@
+---
+version: 0.8.27
+date: 2026-04-11
+summary: Layer MCP_SKILLS_PATH over the bundled Jaypie skill pack via createLayeredStore
+---
+
+## Changes
+
+- The skill service now uses `createLayeredStore` from `@jaypie/tildeskill@0.3.0`, composing two layers:
+  - `local` — populated from `MCP_SKILLS_PATH` when set.
+  - `jaypie` — always present; sources the bundled `packages/mcp/skills/` directory.
+- `skill("aws")` still resolves to the first layer that has it, so a client's local copy wins over the bundled version. Use `skill("jaypie:aws")` or `skill("local:aws")` to target a specific layer. `skill("index")` now emits namespace-prefixed entries (`local:foo`, `jaypie:bar`).
+- New env var `MCP_BUILTIN_SKILLS_PATH` overrides the bundled skills directory for esbuild/Lambda bundling without disabling the layered composition.
+
+## Breaking behavior change
+
+Previously `MCP_SKILLS_PATH` **replaced** the bundled skill directory. It now **augments** it as the top `local:` layer. To keep the old "relocate bundled skills" pattern working for Lambda bundlers, set `MCP_BUILTIN_SKILLS_PATH` instead.

package/release-notes/testkit/1.2.29.md

@@ -0,0 +1,9 @@
+---
+version: 1.2.29
+date: 2026-04-11
+summary: Mock new tildeskill exports (find, getAlternativeSpellings)
+---
+
+## Changes
+
+- Add mocks for `SkillStore.find` and the newly exported `getAlternativeSpellings` from `@jaypie/tildeskill@0.2.1`

package/release-notes/testkit/1.2.30.md

@@ -0,0 +1,10 @@
+---
+version: 1.2.30
+date: 2026-04-11
+summary: Mock createLayeredStore and update getByNickname mock to return an array
+---
+
+## Changes
+
+- Added a mock `createLayeredStore` export that returns the standard mock `SkillStore` shape.
+- `SkillStore.getByNickname` mock now resolves to `[]` instead of `null` to match the `Promise<SkillRecord[]>` signature introduced in `@jaypie/tildeskill@0.3.0`.

package/release-notes/tildeskill/0.2.1.md

@@ -0,0 +1,11 @@
+---
+version: 0.2.1
+date: 2026-04-11
+summary: Add SkillStore.find with plural/singular fallback and export getAlternativeSpellings
+---
+
+## Changes
+
+- Add `SkillStore.find(alias)` that tries an exact lookup then alternative plural/singular spellings, returning the matched record (check `record.alias` to detect a fallback match)
+- Export `getAlternativeSpellings(alias)` core utility for callers that want the candidate list directly
+- Implemented on both `createMarkdownStore` and `createMemoryStore`

package/release-notes/tildeskill/0.3.0.md

@@ -0,0 +1,23 @@
+---
+version: 0.3.0
+date: 2026-04-11
+summary: Layered skill stores with namespace prefixes; getByNickname now returns all matches
+---
+
+## Changes
+
+- **New `createLayeredStore`** — compose ordered child stores with namespace prefixes (e.g., `local`, `jaypie`). `get`/`find` walk layers top-to-bottom and return the first match with its alias namespaced (`local:aws`). Namespace-qualified inputs (`jaypie:aws`) route directly to that layer. `list`/`search` aggregate every layer. `put` requires a namespace-qualified alias and delegates to the matching layer.
+- **New types** `LayeredStoreLayer` and `LayeredStoreOptions` exported from the package root.
+- **`SkillStore.getByNickname` now returns `Promise<SkillRecord[]>`** (breaking signature change). Returns every record whose `nicknames` list contains the query instead of only the first. A layered store aggregates matches across every layer so a nickname like `sparticus` can resolve to several skills at once.
+- **`isValidAlias` accepts `:`** so callers can validate namespace-qualified inputs destined for a layered store. Path traversal guards (`..`, `/`, `\\`) are unchanged.
+
+## Breaking changes
+
+- `getByNickname` return type changed from `SkillRecord | null` to `SkillRecord[]`. Update callers:
+
+  ```diff
+  - const skill = await store.getByNickname("amazon");
+  - if (skill) console.log(skill.alias);
+  + const matches = await store.getByNickname("amazon");
+  + matches.forEach((m) => console.log(m.alias));
+  ```

package/skills/dynamodb.md

@@ -7,34 +7,24 @@ related: apikey, aws, cdk, models, vocabulary
 
 Jaypie provides `@jaypie/dynamodb` for single-table DynamoDB with entity operations, GSI-based queries, hierarchical scoping, and soft delete. Access through the main `jaypie` package or directly.
 
-## Key Naming Conventions
+## Key Design
 
-Jaypie uses two key naming patterns. Understanding when to use each avoids confusion.
+### Primary Key: `id` Only
 
-### Jaypie Default: `model` / `id`
-
-`JaypieDynamoDb` creates tables with `model` (partition key) and `id` (sort key) by default. This is the **recommended convention for new Jaypie tables** and the convention used by `@jaypie/dynamodb`:
+`JaypieDynamoDb` creates tables with `id` as the sole partition key (no sort key). `model` and `scope` are regular attributes used in GSI partition keys:
 
 ```typescript
 const table = new JaypieDynamoDb(this, "myApp");
-// Creates table with: model (HASH), id (RANGE)
+// Creates table with: id (HASH) — no sort key
 ```
 
 Items look like:
 
 ```typescript
-{ model: "user", id: "u_abc123", name: "John", email: "john@example.com" }
-{ model: "apikey", id: "a1b2c3d4...", ownerId: "u_abc123" }
+{ id: "u_abc123", model: "user", name: "John", scope: "@" }
+{ id: "a1b2c3d4", model: "apikey", scope: "user#u_abc123" }
 ```
 
-### Generic DynamoDB: `pk` / `sk`
-
-The `pk` / `sk` pattern is the standard DynamoDB convention used in broader DynamoDB literature. Jaypie uses it in local development scripts and educational examples. It's functionally equivalent — just different attribute names.
-
-### Entity Prefixing (Value Pattern)
-
-Entity prefixes like `USER#123` are a **value-level pattern** (how you structure the data stored in keys), not an attribute naming convention. You can use entity prefixes with either `model`/`id` or `pk`/`sk` attribute names.
-
 ## @jaypie/dynamodb Package
 
 The runtime package provides entity operations, GSI-based queries, key builders, and client management.
@@ -99,30 +89,26 @@ All entities follow this shape:
 ```typescript
 interface StorableEntity {
   // Primary Key
-  model: string;              // Partition key (e.g., "record", "message")
-  id: string;                 // Sort key (UUID)
+  id: string;                 // Partition key (UUID)
 
   // Required
-  name: string;
+  model: string;              // Entity model name (e.g., "record", "message")
   scope: string;              // APEX ("@") or "{parent.model}#{parent.id}"
-  sequence: number;           // Date.now() for chronological ordering
 
-  // Optional (trigger GSI index population when present)
+  // Optional identity
+  name?: string;
   alias?: string;             // Human-friendly slug
   category?: string;          // Category for filtering
   type?: string;              // Type for filtering
   xid?: string;               // External ID for cross-system lookup
 
-  // GSI Keys (auto-populated by putEntity/updateEntity)
-  indexAlias?: string;
-  indexCategory?: string;
-  indexScope?: string;
-  indexType?: string;
-  indexXid?: string;
+  // GSI Keys (auto-populated by indexEntity on every write)
+  // indexModel, indexModelAlias, indexModelCategory, etc.
+  // indexModelSk, indexModelAliasSk, etc. (composite sort keys)
 
-  // Timestamps (ISO 8601)
-  createdAt: string;
-  updatedAt: string;
+  // Timestamps (ISO 8601) — managed by indexEntity
+  createdAt?: string;         // Backfilled on first write
+  updatedAt?: string;         // Bumped on every write
   archivedAt?: string;
   deletedAt?: string;
 
@@ -137,50 +123,46 @@ interface StorableEntity {
 ```typescript
 import { APEX, putEntity, getEntity, updateEntity, deleteEntity, archiveEntity, destroyEntity } from "@jaypie/dynamodb";
 
-const now = new Date().toISOString();
-
-// Create entity — auto-populates GSI keys
+// Create entity — indexEntity auto-populates GSI keys, createdAt, updatedAt
 const record = await putEntity({
   entity: {
     model: "record",
     id: crypto.randomUUID(),
     name: "Daily Log",
     scope: APEX,
-    sequence: Date.now(),
     alias: "2026-01-07",
     category: "memory",
-    createdAt: now,
-    updatedAt: now,
   },
 });
-// indexScope: "@#record" (auto-populated)
-// indexAlias: "@#record#2026-01-07" (auto-populated)
-// indexCategory: "@#record#memory" (auto-populated)
+// indexModel: "record" (auto-populated)
+// indexModelAlias: "record#2026-01-07" (auto-populated)
+// indexModelCategory: "record#memory" (auto-populated)
+// indexModelSk: "@#2026-01-07T..." (auto-populated)
 
-// Get by primary key
-const item = await getEntity({ id: "abc-123", model: "record" });
+// Get by primary key (id only)
+const item = await getEntity({ id: "abc-123" });
 
 // Update — sets updatedAt, re-indexes
 await updateEntity({ entity: { ...item, name: "Updated Name" } });
 
-// Soft delete — sets deletedAt, re-indexes with #deleted suffix
-await deleteEntity({ id: "abc-123", model: "record" });
+// Soft delete — sets deletedAt, re-indexes with #deleted suffix on pk
+await deleteEntity({ id: "abc-123" });
 
-// Archive — sets archivedAt, re-indexes with #archived suffix
-await archiveEntity({ id: "abc-123", model: "record" });
+// Archive — sets archivedAt, re-indexes with #archived suffix on pk
+await archiveEntity({ id: "abc-123" });
 
 // Hard delete — permanently removes
-await destroyEntity({ id: "abc-123", model: "record" });
+await destroyEntity({ id: "abc-123" });
 ```
 
 | Function | Description |
 |----------|-------------|
-| `putEntity({ entity })` | Create or replace (auto-indexes GSI keys) |
-| `getEntity({ id, model })` | Get by primary key |
+| `putEntity({ entity })` | Create or replace (auto-indexes GSI keys, auto-timestamps) |
+| `getEntity({ id })` | Get by primary key (id only) |
 | `updateEntity({ entity })` | Update (sets `updatedAt`, re-indexes) |
-| `deleteEntity({ id, model })` | Soft delete (`deletedAt`, `#deleted` suffix) |
-| `archiveEntity({ id, model })` | Archive (`archivedAt`, `#archived` suffix) |
-| `destroyEntity({ id, model })` | Hard delete (permanent) |
+| `deleteEntity({ id })` | Soft delete (`deletedAt`, `#deleted` suffix on GSI pk) |
+| `archiveEntity({ id })` | Archive (`archivedAt`, `#archived` suffix on GSI pk) |
+| `destroyEntity({ id })` | Hard delete (permanent) |
 
 ### Scope and Hierarchy
 
@@ -209,31 +191,48 @@ const { items: chats } = await queryByScope({ model: "chat", scope: APEX });
 
 ### GSI Schema
 
-Jaypie defines five GSI patterns, but **do not create all five upfront**. Start with zero GSIs and add only what your access patterns require. The most common first GSI is `indexScope` for hierarchical queries.
+GSIs are defined using `fabricIndex()` from `@jaypie/fabric`. **Do not create all GSIs upfront** — start with zero and add only what your access patterns require. The most common first GSI is `indexModel` for listing entities by model.
 
 **Important:** DynamoDB allows only **one GSI to be added per deployment**. If you need multiple GSIs, add them sequentially across separate deploys. For production tables, the AWS CLI is often better suited for adding GSIs than CDK (which may try to replace the table).
 
-All GSIs use `sequence` (Number) as the sort key for chronological ordering.
+All GSIs use a composite sort key of `scope#updatedAt` (stored as `{indexName}Sk`). Queries use `begins_with` on the sk to filter by scope; omitting scope lists across all scopes.
+
+| GSI Name | Partition Key Pattern | Sort Key | Purpose | Add When |
+|----------|----------------------|----------|---------|----------|
+| `indexModel` | `{model}` | `indexModelSk` = `{scope}#{updatedAt}` | List entities by model | You need to list/query by model |
+| `indexModelAlias` | `{model}#{alias}` (sparse) | `indexModelAliasSk` = `{scope}#{updatedAt}` | Human-friendly slug lookup | You need slug-based lookups |
+| `indexModelCategory` | `{model}#{category}` (sparse) | `indexModelCategorySk` = `{scope}#{updatedAt}` | Category filtering | You need to filter by category |
+| `indexModelType` | `{model}#{type}` (sparse) | `indexModelTypeSk` = `{scope}#{updatedAt}` | Type filtering | You need to filter by type |
+| `indexModelXid` | `{model}#{xid}` (sparse) | `indexModelXidSk` = `{scope}#{updatedAt}` | External ID lookup | You need cross-system ID lookups |
 
-| GSI Name | Partition Key Pattern | Purpose | Add When |
-|----------|----------------------|---------|----------|
-| `indexScope` | `{scope}#{model}` | List entities by parent | You need hierarchical queries |
-| `indexAlias` | `{scope}#{model}#{alias}` | Human-friendly slug lookup | You need slug-based lookups |
-| `indexCategory` | `{scope}#{model}#{category}` | Category filtering | You need to filter by category |
-| `indexType` | `{scope}#{model}#{type}` | Type filtering | You need to filter by type (note: vocabulary discourages `type` in favor of `category`; `indexType` is retained as a legacy GSI pattern) |
-| `indexXid` | `{scope}#{model}#{xid}` | External ID lookup | You need cross-system ID lookups |
+```typescript
+import { fabricIndex, registerModel } from "@jaypie/fabric";
+
+// Register model indexes (must happen before any queries)
+registerModel({
+  model: "record",
+  indexes: [
+    fabricIndex(),           // indexModel: pk=["model"], sk=["scope","updatedAt"]
+    fabricIndex("alias"),    // indexModelAlias: pk=["model","alias"], sparse
+    fabricIndex("category"), // indexModelCategory: pk=["model","category"], sparse
+  ],
+});
+```
 
 ### Query Functions
 
-All queries return `{ items, lastEvaluatedKey }` and support pagination:
+All queries return `{ items, lastEvaluatedKey }` and support pagination. `scope` is always optional — when omitted, queries span all scopes. `queryByCategory` and `queryByType` throw `ConfigurationError` if the model has not registered the corresponding `fabricIndex()`.
 
 ```typescript
 import { APEX, queryByScope, queryByAlias, queryByCategory, queryByType, queryByXid } from "@jaypie/dynamodb";
 
-// List by parent scope (most common)
+// List by model (scope optional)
 const { items } = await queryByScope({ model: "record", scope: APEX });
 
-// Filter by category
+// List across all scopes
+const { items: allRecords } = await queryByScope({ model: "record" });
+
+// Filter by category (requires fabricIndex("category") registered)
 const { items: memories } = await queryByCategory({
   model: "record", scope: APEX, category: "memory",
 });
@@ -241,7 +240,7 @@ const { items: memories } = await queryByCategory({
 // Lookup by alias (returns single or null)
 const item = await queryByAlias({ model: "record", scope: APEX, alias: "2026-01-07" });
 
-// Filter by type
+// Filter by type (requires fabricIndex("type") registered)
 const { items: drafts } = await queryByType({
   model: "record", scope: APEX, type: "draft",
 });
@@ -306,14 +305,13 @@ const json = await exportEntitiesToJson("vocabulary", APEX);
 
 ### Key Builders
 
-Build composite GSI keys manually when needed:
+Build composite keys manually when needed:
 
 ```typescript
-import { buildIndexScope, buildIndexAlias, buildIndexCategory, calculateScope } from "@jaypie/dynamodb";
+import { buildCompositeKey, calculateScope } from "@jaypie/dynamodb";
 
-buildIndexScope(APEX, "record");                    // "@#record"
-buildIndexAlias(APEX, "record", "daily-log");       // "@#record#daily-log"
-buildIndexCategory(APEX, "record", "memory");       // "@#record#memory"
+buildCompositeKey({ model: "record" }, ["model"]);                    // "record"
+buildCompositeKey({ model: "record", alias: "daily-log" }, ["model", "alias"]); // "record#daily-log"
 calculateScope({ model: "chat", id: "abc-123" });   // "chat#abc-123"
 ```
 
@@ -323,8 +321,8 @@ calculateScope({ model: "chat", id: "abc-123" });   // "chat#abc-123"
 
 | Setting | Default | Source |
 |---------|---------|--------|
-| Partition key | `model` (String) | Jaypie construct |
-| Sort key | `id` (String) | Jaypie construct |
+| Partition key | `id` (String) | Jaypie construct |
+| Sort key | None | Jaypie construct |
 | Billing mode | PAY_PER_REQUEST | Jaypie construct |
 | Removal policy | DESTROY (non-production), RETAIN (production) | Jaypie construct |
 | Point-in-time recovery | Enabled | Jaypie construct |
@@ -332,14 +330,16 @@ calculateScope({ model: "chat", id: "abc-123" });   // "chat#abc-123"
 
 ```typescript
 import { JaypieDynamoDb } from "@jaypie/constructs";
+import { fabricIndex } from "@jaypie/fabric";
 
-// Recommended: start with no indexes (uses model/id keys)
+// Recommended: start with no indexes
 const table = new JaypieDynamoDb(this, "myApp");
 
 // Add indexes when driven by real access patterns
 const table = new JaypieDynamoDb(this, "myApp", {
   indexes: [
-    { pk: ["scope", "model"], sk: ["sequence"] },
+    fabricIndex(),           // indexModel
+    fabricIndex("alias"),    // indexModelAlias (sparse)
   ],
 });
 ```
@@ -356,7 +356,7 @@ Use docker-compose for local DynamoDB. The `@jaypie/dynamodb` MCP tool can gener
 {
   "scripts": {
     "dynamo:init": "docker compose up -d && npm run dynamo:create-table",
-    "dynamo:create-table": "AWS_ACCESS_KEY_ID=local AWS_SECRET_ACCESS_KEY=local aws dynamodb create-table --table-name jaypie-local --attribute-definitions AttributeName=pk,AttributeType=S AttributeName=sk,AttributeType=S --key-schema AttributeName=pk,KeyType=HASH AttributeName=sk,KeyType=RANGE --billing-mode PAY_PER_REQUEST --endpoint-url http://127.0.0.1:9060 2>/dev/null || true",
+    "dynamo:create-table": "AWS_ACCESS_KEY_ID=local AWS_SECRET_ACCESS_KEY=local aws dynamodb create-table --table-name jaypie-local --attribute-definitions AttributeName=id,AttributeType=S --key-schema AttributeName=id,KeyType=HASH --billing-mode PAY_PER_REQUEST --endpoint-url http://127.0.0.1:9060 2>/dev/null || true",
     "dynamo:remove": "docker compose down -v",
     "dynamo:start": "docker compose up -d",
     "dynamo:stop": "docker compose down"
@@ -420,21 +420,24 @@ describe("OrderService", () => {
 });
 ```
 
-## Migration: class to category (v0.4.0)
-
-Version 0.4.0 renamed `class` → `category` and `indexClass` → `indexCategory`.
-
-**If your table was created with an older version:**
-
-1. **Local dev**: Delete and recreate the table using MCP `createTable`
-2. **Production**: See `packages/dynamodb/CLAUDE.md` for migration script
-
-| Old | New |
-|-----|-----|
-| `class` | `category` |
-| `indexClass` | `indexCategory` |
-| `INDEX_CLASS` | `INDEX_CATEGORY` |
-| `queryByClass()` | `queryByCategory()` |
+## Migration: v0.4.x to v0.5.0
+
+Version 0.5.0 is a breaking change. **Tables must be recreated** (pre-1.0 breaking change).
+
+| Old (0.4.x) | New (0.5.0) |
+|-------------|-------------|
+| Primary key: pk=`model`, sk=`id` | Primary key: pk=`id` only |
+| GSI sort key: `sequence` (number) | GSI sort key: composite `scope#updatedAt` |
+| GSI pk: `{scope}#{model}#{field}` | GSI pk: `{model}#{field}` |
+| GSI names: indexScope, indexAlias, indexCategory, indexType, indexXid | GSI names: indexModel, indexModelAlias, indexModelCategory, indexModelType, indexModelXid |
+| `sequence` field on entity | Removed — ordering by `updatedAt` |
+| `getEntity({ id, model })` | `getEntity({ id })` |
+| `deleteEntity({ id, model })` | `deleteEntity({ id })` |
+| `archiveEntity({ id, model })` | `archiveEntity({ id })` |
+| `destroyEntity({ id, model })` | `destroyEntity({ id })` |
+| `buildIndexScope`, `buildIndexAlias`, etc. | Removed; use `buildCompositeKey` |
+| `DEFAULT_INDEXES` implicit fallback | Must `registerModel()` with `fabricIndex()` before querying |
+| Callers set `createdAt`/`updatedAt` | `indexEntity` manages both automatically |
 
 ## See Also
 

package/skills/tildeskill.md

@@ -10,12 +10,15 @@ Skill/vocabulary management with pluggable storage backends for AI assistants an
 ## Overview
 
 This package provides a storage abstraction for skill/vocabulary documents with markdown frontmatter support. It enables:
+
 - Loading skills from markdown files with YAML frontmatter
 - In-memory storage for testing
+- Layered composition of multiple stores with namespace prefixes
 - Consistent alias normalization and validation
 - Filtering by namespace and tags
 - Searching across alias, name, description, content, and tags
 - Include expansion for composable skills
+- Plural/singular fallback lookup via `find()` and `getAlternativeSpellings()`
 
 ## Installation
 
@@ -27,24 +30,25 @@ npm install @jaypie/tildeskill
 
 ```typescript
 interface SkillRecord {
-  alias: string;              // Lookup key (normalized lowercase)
-  content: string;            // Markdown body
-  description?: string;       // Brief description from frontmatter
-  includes?: string[];        // Auto-expand these skill aliases on lookup
-  name?: string;              // Display title for the skill
-  nicknames?: string[];       // Alternate lookup keys for getByNickname
-  related?: string[];         // Related skill aliases
-  tags?: string[];            // Categorization tags
+  alias: string; // Lookup key (normalized lowercase)
+  content: string; // Markdown body
+  description?: string; // Brief description from frontmatter
+  includes?: string[]; // Auto-expand these skill aliases on lookup
+  name?: string; // Display title for the skill
+  nicknames?: string[]; // Alternate lookup keys for getByNickname
+  related?: string[]; // Related skill aliases
+  tags?: string[]; // Categorization tags
 }
 
 interface ListFilter {
-  namespace?: string;         // Namespace prefix matching (e.g., "kit:*")
-  tag?: string;               // Filter by tag
+  namespace?: string; // Namespace prefix matching (e.g., "kit:*")
+  tag?: string; // Filter by tag
 }
 
 interface SkillStore {
+  find(alias: string): Promise<SkillRecord | null>;
   get(alias: string): Promise<SkillRecord | null>;
-  getByNickname(nickname: string): Promise<SkillRecord | null>;
+  getByNickname(nickname: string): Promise<SkillRecord[]>;
   list(filter?: ListFilter): Promise<SkillRecord[]>;
   put(record: SkillRecord): Promise<SkillRecord>;
   search(term: string): Promise<SkillRecord[]>;
@@ -68,7 +72,7 @@ if (skill) {
 
 // List all skills
 const skills = await store.list();
-skills.forEach(s => console.log(`${s.alias}: ${s.description}`));
+skills.forEach((s) => console.log(`${s.alias}: ${s.description}`));
 ```
 
 ### Memory Store (Testing)
@@ -77,7 +81,7 @@ skills.forEach(s => console.log(`${s.alias}: ${s.description}`));
 import { createMemoryStore } from "@jaypie/tildeskill";
 
 const store = createMemoryStore([
-  { alias: "test", content: "# Test\n\nContent", description: "Test skill" }
+  { alias: "test", content: "# Test\n\nContent", description: "Test skill" },
 ]);
 
 const skill = await store.get("test");
@@ -110,25 +114,72 @@ const cloudSkills = await store.list({ tag: "cloud" });
 // Search across alias, name, description, content, and tags
 const results = await store.search("lambda");
 
-// Lookup by nickname
-const skill = await store.getByNickname("amazon");
+// Lookup by nickname — returns every matching record, so a name like
+// "sparticus" can resolve to multiple skills across layers.
+const matches = await store.getByNickname("amazon");
+```
+
+## Layered Stores
+
+```typescript
+import { createLayeredStore, createMarkdownStore } from "@jaypie/tildeskill";
+
+// Compose multiple stores with namespace prefixes. Earlier layers win
+// for single-result lookups; aggregate methods merge every layer.
+const layered = createLayeredStore({
+  layers: [
+    { namespace: "local", store: createMarkdownStore({ path: "./my-skills" }) },
+    {
+      namespace: "jaypie",
+      store: createMarkdownStore({ path: "./jaypie-skills" }),
+    },
+  ],
+});
+
+await layered.get("aws"); // → { alias: "local:aws", ... }
+await layered.get("jaypie:aws"); // → { alias: "jaypie:aws", ... }
+await layered.find("skills"); // per-layer plural fallback
+await layered.list(); // prefixed aliases from every layer
+await layered.put({ alias: "local:new", content: "# New" }); // must be qualified
+```
+
+The MCP server itself uses `createLayeredStore` to place `MCP_SKILLS_PATH`
+(the client's local library, namespace `local`) over the bundled Jaypie
+skills (namespace `jaypie`). Set `MCP_BUILTIN_SKILLS_PATH` if a bundler
+needs to relocate the Jaypie base layer.
+
+## Plural/Singular Fallback
+
+```typescript
+// find() tries exact match then plural/singular alternatives
+const skill = await store.find("skills"); // resolves skill.md
+// skill.alias is the canonical filename; compare to the input to detect fallback
+
+import { getAlternativeSpellings } from "@jaypie/tildeskill";
+getAlternativeSpellings("skills"); // ["skill"]
+getAlternativeSpellings("indexes"); // ["indexe", "index"]
+getAlternativeSpellings("fish"); // ["fishs", "fishes"]
 ```
 
 ## Validation Utilities
 
 ```typescript
-import { isValidAlias, validateAlias, normalizeAlias } from "@jaypie/tildeskill";
+import {
+  isValidAlias,
+  validateAlias,
+  normalizeAlias,
+} from "@jaypie/tildeskill";
 
 // Check validity
-isValidAlias("my-skill");     // true
-isValidAlias("../../etc");    // false (path traversal)
+isValidAlias("my-skill"); // true
+isValidAlias("../../etc"); // false (path traversal)
 
 // Normalize to lowercase
-normalizeAlias("MY-Skill");   // "my-skill"
+normalizeAlias("MY-Skill"); // "my-skill"
 
 // Validate and normalize (throws on invalid)
-validateAlias("valid");       // returns "valid"
-validateAlias("../bad");      // throws BadRequestError
+validateAlias("valid"); // returns "valid"
+validateAlias("../bad"); // throws BadRequestError
 ```
 
 ## Skill File Format
@@ -144,7 +195,6 @@ nicknames: alt-name, another-alias
 related: alias1, alias2, alias3
 tags: category1, category2
 ---
-
 # Skill Title
 
 Markdown content...

package/skills/vocabulary.md

@@ -49,7 +49,7 @@ Arguably composition, identity, instance, and relation would form a more complet
 - name: most common way to clearly reference the entity
 - related: array of id strings, complex "{model}#{id}" strings, or `{ id, model }` objects
 - scope: organizes entities, usually a reference to a parent entity
-- sequence: computed scalar, usually `Date.now()` for chronological ordering
+- sequence: deprecated; ordering now uses `updatedAt` via GSI composite sort key
 - state: mutable data the entity tracks
 - status: canceled, complete, error, pending, processing, queued, sending
 - updatedAt: timestamp
@@ -66,7 +66,7 @@ Arguably composition, identity, instance, and relation would form a more complet
 - key => alias; make api or secret keys explicit in name
 - ou => scope
 - output => state
-- type => category, tags; reserved (exception: `indexType` GSI exists in DynamoDB as a legacy pattern; prefer `category` for new work)
+- type => category, tags; reserved (exception: `indexModelType` GSI exists in DynamoDB as a legacy pattern; prefer `category` for new work)
 
 Avoid words defined elsewhere (services, terminology)