@jaypie/mcp 0.8.158 → 0.8.159

package/README.md

@@ -44,6 +44,17 @@ cpSync(assets.skills, join("dist", MCP_ASSET_DIRECTORY.SKILLS), { recursive: tru
 
 `MCP_BUILTIN_SKILLS_PATH` and `MCP_RELEASE_NOTES_PATH` point at other locations.
 
+`getMcpBuildInfo` returns the version and commit of the build that packed the markdown:
+
+```typescript
+import { getMcpBuildInfo } from "@jaypie/mcp/assets";
+
+const { commit, version, versionString } = getMcpBuildInfo();
+// { commit: "460f95c3", version: "0.8.159", versionString: "@jaypie/mcp@0.8.159#460f95c3" }
+```
+
+`commit` is empty when `PROJECT_COMMIT` was unset at build time. Unbuilt source returns version `0.0.0`.
+
 ### Filtering Tools
 
 `createMcpServer`, `mcpExpressHandler`, and `mcpHttpHandler` accept `services`, an allowlist of tool names:

package/dist/assets.d.ts

@@ -8,6 +8,14 @@ interface McpAssetPaths {
     /** Absolute path of the Jaypie skills directory read by `skill` */
     skills: string;
 }
+interface McpBuildInfo {
+    /** First 8 characters of `PROJECT_COMMIT` at build time; empty when unset */
+    commit: string;
+    /** `package.json` version at build time */
+    version: string;
+    /** `@jaypie/mcp@<version>#<commit>`, the string `version` answers */
+    versionString: string;
+}
 /**
  * Absolute paths of the markdown directories `skill` and `release_notes` read
  * at runtime
@@ -29,6 +37,21 @@ interface McpAssetPaths {
  * ```
  */
 declare function getMcpAssetPaths(): McpAssetPaths;
+/**
+ * Version and commit of the `@jaypie/mcp` build, compiled in at build time
+ *
+ * A consumer syncing `skills/` and `release-notes/` reads the build that
+ * packed them from the same package. Unbuilt source (tests, `tsx`) returns
+ * version `0.0.0` and an empty commit.
+ *
+ * @example
+ * ```typescript
+ * import { getMcpBuildInfo } from "@jaypie/mcp/assets";
+ *
+ * const { commit, version, versionString } = getMcpBuildInfo();
+ * ```
+ */
+declare function getMcpBuildInfo(): McpBuildInfo;
 
-export { MCP_ASSET_DIRECTORY, getMcpAssetPaths };
-export type { McpAssetPaths };
+export { MCP_ASSET_DIRECTORY, getMcpAssetPaths, getMcpBuildInfo };
+export type { McpAssetPaths, McpBuildInfo };

package/dist/assets.js

@@ -1,11 +1,8 @@
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-// Locate the markdown that ships inside @jaypie/mcp, for build scripts that bundle it
-//
-//
-// Constants
-//
+// Locate the markdown that ships inside @jaypie/mcp, and the build that packed it,
+// for build scripts that bundle it
 const MCP_ASSET_DIRECTORY = {
     RELEASE_NOTES: "release-notes",
     SKILLS: "skills",
@@ -42,6 +39,30 @@ function getMcpAssetPaths() {
         skills: path.join(packageRoot, MCP_ASSET_DIRECTORY.SKILLS),
     };
 }
+/**
+ * Version and commit of the `@jaypie/mcp` build, compiled in at build time
+ *
+ * A consumer syncing `skills/` and `release-notes/` reads the build that
+ * packed them from the same package. Unbuilt source (tests, `tsx`) returns
+ * version `0.0.0` and an empty commit.
+ *
+ * @example
+ * ```typescript
+ * import { getMcpBuildInfo } from "@jaypie/mcp/assets";
+ *
+ * const { commit, version, versionString } = getMcpBuildInfo();
+ * ```
+ */
+function getMcpBuildInfo() {
+    return {
+        commit: "4e7a07fe"
+            ,
+        version: "0.8.159"
+            ,
+        versionString: "@jaypie/mcp@0.8.159#4e7a07fe"
+            ,
+    };
+}
 
-export { MCP_ASSET_DIRECTORY, getMcpAssetPaths };
+export { MCP_ASSET_DIRECTORY, getMcpAssetPaths, getMcpBuildInfo };
 //# sourceMappingURL=assets.js.map

package/dist/assets.js.map

@@ -1 +1 @@
-{"version":3,"file":"assets.js","sources":["../src/assets.ts"],"sourcesContent":["// Locate the markdown that ships inside @jaypie/mcp, for build scripts that bundle it\n\nimport * as path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\n//\n//\n// Constants\n//\n\nexport const MCP_ASSET_DIRECTORY = {\n  RELEASE_NOTES: \"release-notes\",\n  SKILLS: \"skills\",\n} as const;\n\n//\n//\n// Types\n//\n\nexport interface McpAssetPaths {\n  /** Absolute path of the release notes directory read by `release_notes` */\n  releaseNotes: string;\n  /** Absolute path of the Jaypie skills directory read by `skill` */\n  skills: string;\n}\n\n//\n//\n// Main\n//\n\n/**\n * Absolute paths of the markdown directories `skill` and `release_notes` read\n * at runtime\n *\n * A bundler (esbuild) inlines the code but not the markdown. Copy each\n * directory beside the bundle under its own name (`skills/`,\n * `release-notes/`) and the docs suite finds it without configuration. Call\n * this from a build script, never from bundled code.\n *\n * @example\n * ```typescript\n * import { cpSync } from \"node:fs\";\n * import { join } from \"node:path\";\n * import { getMcpAssetPaths, MCP_ASSET_DIRECTORY } from \"@jaypie/mcp/assets\";\n *\n * const assets = getMcpAssetPaths();\n * cpSync(assets.skills, join(\"dist\", MCP_ASSET_DIRECTORY.SKILLS), { recursive: true });\n * cpSync(assets.releaseNotes, join(\"dist\", MCP_ASSET_DIRECTORY.RELEASE_NOTES), { recursive: true });\n * ```\n */\nexport function getMcpAssetPaths(): McpAssetPaths {\n  // src/assets.ts and dist/assets.js both sit one level below the package root\n  const packageRoot = path.join(\n    path.dirname(fileURLToPath(import.meta.url)),\n    \"..\",\n  );\n  return {\n    releaseNotes: path.join(packageRoot, MCP_ASSET_DIRECTORY.RELEASE_NOTES),\n    skills: path.join(packageRoot, MCP_ASSET_DIRECTORY.SKILLS),\n  };\n}\n"],"names":[],"mappings":";;;AAAA;AAKA;AACA;AACA;AACA;AAEO,MAAM,mBAAmB,GAAG;AACjC,IAAA,aAAa,EAAE,eAAe;AAC9B,IAAA,MAAM,EAAE,QAAQ;;AAelB;AACA;AACA;AACA;AAEA;;;;;;;;;;;;;;;;;;;AAmBG;SACa,gBAAgB,GAAA;;IAE9B,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAC3B,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAC5C,IAAI,CACL;IACD,OAAO;QACL,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,mBAAmB,CAAC,aAAa,CAAC;QACvE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,mBAAmB,CAAC,MAAM,CAAC;KAC3D;AACH;;;;"}
+{"version":3,"file":"assets.js","sources":["../src/assets.ts"],"sourcesContent":["// Locate the markdown that ships inside @jaypie/mcp, and the build that packed it,\n// for build scripts that bundle it\n\nimport * as path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\n//\n//\n// Build-time constants (replaced by @rollup/plugin-replace)\n//\n\ndeclare const __BUILD_COMMIT__: string;\ndeclare const __BUILD_VERSION__: string;\ndeclare const __BUILD_VERSION_STRING__: string;\n\n//\n//\n// Constants\n//\n\nconst UNBUILT_COMMIT = \"\";\nconst UNBUILT_VERSION = \"0.0.0\";\nconst UNBUILT_VERSION_STRING = `@jaypie/mcp@${UNBUILT_VERSION}`;\n\nexport const MCP_ASSET_DIRECTORY = {\n  RELEASE_NOTES: \"release-notes\",\n  SKILLS: \"skills\",\n} as const;\n\n//\n//\n// Types\n//\n\nexport interface McpAssetPaths {\n  /** Absolute path of the release notes directory read by `release_notes` */\n  releaseNotes: string;\n  /** Absolute path of the Jaypie skills directory read by `skill` */\n  skills: string;\n}\n\nexport interface McpBuildInfo {\n  /** First 8 characters of `PROJECT_COMMIT` at build time; empty when unset */\n  commit: string;\n  /** `package.json` version at build time */\n  version: string;\n  /** `@jaypie/mcp@<version>#<commit>`, the string `version` answers */\n  versionString: string;\n}\n\n//\n//\n// Main\n//\n\n/**\n * Absolute paths of the markdown directories `skill` and `release_notes` read\n * at runtime\n *\n * A bundler (esbuild) inlines the code but not the markdown. Copy each\n * directory beside the bundle under its own name (`skills/`,\n * `release-notes/`) and the docs suite finds it without configuration. Call\n * this from a build script, never from bundled code.\n *\n * @example\n * ```typescript\n * import { cpSync } from \"node:fs\";\n * import { join } from \"node:path\";\n * import { getMcpAssetPaths, MCP_ASSET_DIRECTORY } from \"@jaypie/mcp/assets\";\n *\n * const assets = getMcpAssetPaths();\n * cpSync(assets.skills, join(\"dist\", MCP_ASSET_DIRECTORY.SKILLS), { recursive: true });\n * cpSync(assets.releaseNotes, join(\"dist\", MCP_ASSET_DIRECTORY.RELEASE_NOTES), { recursive: true });\n * ```\n */\nexport function getMcpAssetPaths(): McpAssetPaths {\n  // src/assets.ts and dist/assets.js both sit one level below the package root\n  const packageRoot = path.join(\n    path.dirname(fileURLToPath(import.meta.url)),\n    \"..\",\n  );\n  return {\n    releaseNotes: path.join(packageRoot, MCP_ASSET_DIRECTORY.RELEASE_NOTES),\n    skills: path.join(packageRoot, MCP_ASSET_DIRECTORY.SKILLS),\n  };\n}\n\n/**\n * Version and commit of the `@jaypie/mcp` build, compiled in at build time\n *\n * A consumer syncing `skills/` and `release-notes/` reads the build that\n * packed them from the same package. Unbuilt source (tests, `tsx`) returns\n * version `0.0.0` and an empty commit.\n *\n * @example\n * ```typescript\n * import { getMcpBuildInfo } from \"@jaypie/mcp/assets\";\n *\n * const { commit, version, versionString } = getMcpBuildInfo();\n * ```\n */\nexport function getMcpBuildInfo(): McpBuildInfo {\n  return {\n    commit:\n      typeof __BUILD_COMMIT__ !== \"undefined\"\n        ? __BUILD_COMMIT__\n        : UNBUILT_COMMIT,\n    version:\n      typeof __BUILD_VERSION__ !== \"undefined\"\n        ? __BUILD_VERSION__\n        : UNBUILT_VERSION,\n    versionString:\n      typeof __BUILD_VERSION_STRING__ !== \"undefined\"\n        ? __BUILD_VERSION_STRING__\n        : UNBUILT_VERSION_STRING,\n  };\n}\n"],"names":[],"mappings":";;;AAAA;AACA;AAuBO,MAAM,mBAAmB,GAAG;AACjC,IAAA,aAAa,EAAE,eAAe;AAC9B,IAAA,MAAM,EAAE,QAAQ;;AAwBlB;AACA;AACA;AACA;AAEA;;;;;;;;;;;;;;;;;;;AAmBG;SACa,gBAAgB,GAAA;;IAE9B,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAC3B,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAC5C,IAAI,CACL;IACD,OAAO;QACL,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,mBAAmB,CAAC,aAAa,CAAC;QACvE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,mBAAmB,CAAC,MAAM,CAAC;KAC3D;AACH;AAEA;;;;;;;;;;;;;AAaG;SACa,eAAe,GAAA;IAC7B,OAAO;AACL,QAAA,MAAM,EAEA;AACF,YAAgB;AACpB,QAAA,OAAO,EAED;AACF,YAAiB;AACrB,QAAA,aAAa,EAEP;AACF,YAAwB;KAC7B;AACH;;;;"}

package/dist/suites/docs/help.d.ts

@@ -1 +1 @@
-export declare const RELEASE_NOTES_HELP = "# Release Notes\n\nBrowse Jaypie package release notes.\n\n## Commands\n\n| Command | Description | Required Parameters |\n|---------|-------------|---------------------|\n| `list` | List available release notes | - |\n| `read` | Read a specific release note | `package`, `version` |\n\n## Options for `list`\n\n| Option | Description |\n|--------|-------------|\n| `package` | Filter by package name (e.g., \"mcp\", \"jaypie\") |\n| `since_version` | Only versions newer than this (e.g., \"1.0.0\") |\n\n## Examples\n\n```\nrelease_notes(\"list\")\nrelease_notes(\"list\", { package: \"mcp\" })\nrelease_notes(\"list\", { package: \"jaypie\", since_version: \"2.0.0\" })\nrelease_notes(\"read\", { package: \"mcp\", version: \"0.4.2\" })\n```\n\n## Available Packages\n\nRelease notes are available for all Jaypie packages including:\n- `jaypie` - Main package\n- `mcp` - MCP server\n- `fabric` - Service handlers and adapters\n- `llm` - LLM provider interface\n- And more...\n\nUse `release_notes(\"list\")` to see all available packages and versions.\n";
+export declare const RELEASE_NOTES_HELP = "# Release Notes\n\nBrowse Jaypie package release notes.\n\n## Commands\n\n| Command | Description | Required Parameters |\n|---------|-------------|---------------------|\n| `list` | List available release notes | - |\n| `read` | Read a specific release note | `package`, `version` |\n\n## Options for `list`\n\n| Option | Description |\n|--------|-------------|\n| `cursor` | Opaque cursor from a previous page's `Next page` footer |\n| `limit` | Notes per page (default 50, maximum 200) |\n| `package` | Filter by package name (e.g., \"mcp\", \"jaypie\") |\n| `since_version` | Only versions newer than this (e.g., \"1.0.0\") |\n\n## Pagination\n\n`list` sorts by package ascending, then version descending, and returns one\npage. When more notes exist, the last line is a footer:\n\n```\nNext page: release_notes(\"list\", { cursor: \"...\" })\n```\n\nThe cursor carries `package`, `since_version`, and `limit`, so the footer call\nalone continues the same listing. Pass `limit` with a cursor to change the page\nsize. Passing a `package` or `since_version` that differs from the cursor is an\nerror.\n\n## Examples\n\n```\nrelease_notes(\"list\")\nrelease_notes(\"list\", { limit: 20 })\nrelease_notes(\"list\", { package: \"mcp\" })\nrelease_notes(\"list\", { package: \"jaypie\", since_version: \"2.0.0\" })\nrelease_notes(\"read\", { package: \"mcp\", version: \"0.4.2\" })\n```\n\n## Available Packages\n\nRelease notes are available for all Jaypie packages including:\n- `jaypie` - Main package\n- `mcp` - MCP server\n- `fabric` - Service handlers and adapters\n- `llm` - LLM provider interface\n- And more...\n\nUse `release_notes(\"list\")` to see all available packages and versions.\n";

package/dist/suites/docs/help.js

@@ -14,13 +14,30 @@ Browse Jaypie package release notes.
 
 | Option | Description |
 |--------|-------------|
+| \`cursor\` | Opaque cursor from a previous page's \`Next page\` footer |
+| \`limit\` | Notes per page (default 50, maximum 200) |
 | \`package\` | Filter by package name (e.g., "mcp", "jaypie") |
 | \`since_version\` | Only versions newer than this (e.g., "1.0.0") |
 
+## Pagination
+
+\`list\` sorts by package ascending, then version descending, and returns one
+page. When more notes exist, the last line is a footer:
+
+\`\`\`
+Next page: release_notes("list", { cursor: "..." })
+\`\`\`
+
+The cursor carries \`package\`, \`since_version\`, and \`limit\`, so the footer call
+alone continues the same listing. Pass \`limit\` with a cursor to change the page
+size. Passing a \`package\` or \`since_version\` that differs from the cursor is an
+error.
+
 ## Examples
 
 \`\`\`
 release_notes("list")
+release_notes("list", { limit: 20 })
 release_notes("list", { package: "mcp" })
 release_notes("list", { package: "jaypie", since_version: "2.0.0" })
 release_notes("read", { package: "mcp", version: "0.4.2" })

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

@@ -1 +1 @@
-{"version":3,"file":"help.js","sources":["../../../src/suites/docs/help.ts"],"sourcesContent":["// Inlined so bundled builds (esbuild, Lambda) need no shipped file\n\nexport const RELEASE_NOTES_HELP = `# Release Notes\n\nBrowse Jaypie package release notes.\n\n## Commands\n\n| Command | Description | Required Parameters |\n|---------|-------------|---------------------|\n| \\`list\\` | List available release notes | - |\n| \\`read\\` | Read a specific release note | \\`package\\`, \\`version\\` |\n\n## Options for \\`list\\`\n\n| Option | Description |\n|--------|-------------|\n| \\`package\\` | Filter by package name (e.g., \"mcp\", \"jaypie\") |\n| \\`since_version\\` | Only versions newer than this (e.g., \"1.0.0\") |\n\n## Examples\n\n\\`\\`\\`\nrelease_notes(\"list\")\nrelease_notes(\"list\", { package: \"mcp\" })\nrelease_notes(\"list\", { package: \"jaypie\", since_version: \"2.0.0\" })\nrelease_notes(\"read\", { package: \"mcp\", version: \"0.4.2\" })\n\\`\\`\\`\n\n## Available Packages\n\nRelease notes are available for all Jaypie packages including:\n- \\`jaypie\\` - Main package\n- \\`mcp\\` - MCP server\n- \\`fabric\\` - Service handlers and adapters\n- \\`llm\\` - LLM provider interface\n- And more...\n\nUse \\`release_notes(\"list\")\\` to see all available packages and versions.\n`;\n"],"names":[],"mappings":"AAAA;AAEO,MAAM,kBAAkB,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"help.js","sources":["../../../src/suites/docs/help.ts"],"sourcesContent":["// Inlined so bundled builds (esbuild, Lambda) need no shipped file\n\nexport const RELEASE_NOTES_HELP = `# Release Notes\n\nBrowse Jaypie package release notes.\n\n## Commands\n\n| Command | Description | Required Parameters |\n|---------|-------------|---------------------|\n| \\`list\\` | List available release notes | - |\n| \\`read\\` | Read a specific release note | \\`package\\`, \\`version\\` |\n\n## Options for \\`list\\`\n\n| Option | Description |\n|--------|-------------|\n| \\`cursor\\` | Opaque cursor from a previous page's \\`Next page\\` footer |\n| \\`limit\\` | Notes per page (default 50, maximum 200) |\n| \\`package\\` | Filter by package name (e.g., \"mcp\", \"jaypie\") |\n| \\`since_version\\` | Only versions newer than this (e.g., \"1.0.0\") |\n\n## Pagination\n\n\\`list\\` sorts by package ascending, then version descending, and returns one\npage. When more notes exist, the last line is a footer:\n\n\\`\\`\\`\nNext page: release_notes(\"list\", { cursor: \"...\" })\n\\`\\`\\`\n\nThe cursor carries \\`package\\`, \\`since_version\\`, and \\`limit\\`, so the footer call\nalone continues the same listing. Pass \\`limit\\` with a cursor to change the page\nsize. Passing a \\`package\\` or \\`since_version\\` that differs from the cursor is an\nerror.\n\n## Examples\n\n\\`\\`\\`\nrelease_notes(\"list\")\nrelease_notes(\"list\", { limit: 20 })\nrelease_notes(\"list\", { package: \"mcp\" })\nrelease_notes(\"list\", { package: \"jaypie\", since_version: \"2.0.0\" })\nrelease_notes(\"read\", { package: \"mcp\", version: \"0.4.2\" })\n\\`\\`\\`\n\n## Available Packages\n\nRelease notes are available for all Jaypie packages including:\n- \\`jaypie\\` - Main package\n- \\`mcp\\` - MCP server\n- \\`fabric\\` - Service handlers and adapters\n- \\`llm\\` - LLM provider interface\n- And more...\n\nUse \\`release_notes(\"list\")\\` to see all available packages and versions.\n`;\n"],"names":[],"mappings":"AAAA;AAEO,MAAM,kBAAkB,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/suites/docs/index.d.ts

@@ -3,6 +3,8 @@ export declare const skillService: import("@jaypie/fabric").Service<{
 }, string, string>;
 export declare const versionService: import("@jaypie/fabric").Service<Record<string, unknown>, string, string>;
 interface ReleaseNotesInput {
+    cursor?: string;
+    limit?: number | string;
     package?: string;
     since_version?: string;
     version?: string;

package/dist/suites/docs/index.js

@@ -6,15 +6,15 @@ import { existsSync, readdirSync } from 'node:fs';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { gt } from 'semver';
-import { getMcpAssetPaths, MCP_ASSET_DIRECTORY } from '../../assets.js';
+import { gt, valid, rcompare } from 'semver';
+import { getMcpAssetPaths, MCP_ASSET_DIRECTORY, getMcpBuildInfo } from '../../assets.js';
 import { RELEASE_NOTES_HELP } from './help.js';
 
 /**
  * Docs Suite - Documentation services (skill, version, release_notes)
  */
-const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.158#55ed6fbc"
-    ;
+// Build-time constants
+const BUILD_VERSION_STRING = getMcpBuildInfo().versionString;
 // =============================================================================
 // ASSET PATHS
 // =============================================================================
@@ -117,6 +117,102 @@ const skillStore = createLayeredStore({
     layers: skillLayers,
     separator: LAYER_SEPARATOR,
 });
+// =============================================================================
+// HELPER FUNCTIONS
+// =============================================================================
+const CURSOR_ENCODING = "base64url";
+const INVALID_CURSOR_MESSAGE = 'Invalid cursor. Call release_notes("list") to start over.';
+const RELEASE_NOTES_LIST_LIMIT = {
+    DEFAULT: 50,
+    MAXIMUM: 200,
+};
+function compareText({ a, b }) {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
+/**
+ * Package ascending, then semver descending. Valid semver sorts before
+ * anything else, and filename breaks every remaining tie so the order is total.
+ */
+function compareReleaseNotes({ a, b, }) {
+    const byPackage = compareText({ a: a.packageName, b: b.packageName });
+    if (byPackage !== 0)
+        return byPackage;
+    const aVersion = a.version && valid(a.version);
+    const bVersion = b.version && valid(b.version);
+    if (aVersion && bVersion) {
+        const byVersion = rcompare(aVersion, bVersion);
+        if (byVersion !== 0)
+            return byVersion;
+    }
+    else if (aVersion) {
+        return -1;
+    }
+    else if (bVersion) {
+        return 1;
+    }
+    return compareText({ a: b.filename, b: a.filename });
+}
+function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function isOptionalString(value) {
+    return value === undefined || typeof value === "string";
+}
+function encodeListCursor(cursor) {
+    const ordered = {
+        limit: cursor.limit,
+        offset: cursor.offset,
+        package: cursor.package,
+        since_version: cursor.since_version,
+    };
+    return Buffer.from(JSON.stringify(ordered)).toString(CURSOR_ENCODING);
+}
+function decodeListCursor(cursor) {
+    if (typeof cursor !== "string" || cursor.length === 0) {
+        throw new BadRequestError(INVALID_CURSOR_MESSAGE);
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(Buffer.from(cursor, CURSOR_ENCODING).toString("utf-8"));
+    }
+    catch {
+        throw new BadRequestError(INVALID_CURSOR_MESSAGE);
+    }
+    if (typeof decoded !== "object" || decoded === null) {
+        throw new BadRequestError(INVALID_CURSOR_MESSAGE);
+    }
+    const candidate = decoded;
+    const isValid = typeof candidate.offset === "number" &&
+        Number.isInteger(candidate.offset) &&
+        candidate.offset >= 0 &&
+        (candidate.limit === undefined ||
+            (isPositiveInteger(candidate.limit) &&
+                candidate.limit <= RELEASE_NOTES_LIST_LIMIT.MAXIMUM)) &&
+        isOptionalString(candidate.package) &&
+        isOptionalString(candidate.since_version);
+    if (!isValid) {
+        throw new BadRequestError(INVALID_CURSOR_MESSAGE);
+    }
+    return candidate;
+}
+/**
+ * Accept a number or numeric string, reject anything below one, and clamp to
+ * the maximum
+ */
+function resolveListLimit(value) {
+    if (value === undefined || value === null || value === "") {
+        return RELEASE_NOTES_LIST_LIMIT.DEFAULT;
+    }
+    const limit = typeof value === "string" ? Number(value) : value;
+    if (!isPositiveInteger(limit)) {
+        throw new BadRequestError("limit must be a positive integer");
+    }
+    return Math.min(limit, RELEASE_NOTES_LIST_LIMIT.MAXIMUM);
+}
 async function parseReleaseNoteFile(filePath) {
     try {
         const content = await fs.readFile(filePath, "utf-8");
@@ -151,21 +247,11 @@ async function getPackageReleaseNotes(packageName) {
     const packageDir = path.join(RELEASE_NOTES_PATH, packageName);
     try {
         const files = await fs.readdir(packageDir);
-        const mdFiles = files.filter((file) => file.endsWith(".md"));
-        const notes = await Promise.all(mdFiles.map(async (file) => {
+        const mdFiles = files.filter((file) => file.endsWith(MARKDOWN_EXTENSION));
+        return await Promise.all(mdFiles.map(async (file) => {
             const parsed = await parseReleaseNoteFile(path.join(packageDir, file));
             return { ...parsed, packageName };
         }));
-        return notes.sort((a, b) => {
-            if (!a.version || !b.version)
-                return 0;
-            try {
-                return gt(a.version, b.version) ? -1 : 1;
-            }
-            catch {
-                return b.version.localeCompare(a.version);
-            }
-        });
     }
     catch {
         return [];
@@ -198,7 +284,7 @@ const versionService = fabricService({
 });
 const releaseNotesService = fabricService({
     alias: "release_notes",
-    description: "Browse Jaypie package release notes. Commands: list, read. Call with no args for help.",
+    description: "Browse Jaypie package release notes. Commands: list (paginated), read. Call with no args for help.",
     input: {
         command: {
             description: "Command to execute (omit for help)",
@@ -206,7 +292,7 @@ const releaseNotesService = fabricService({
             type: String,
         },
         input: {
-            description: "Command parameters",
+            description: `Command parameters. list: package, since_version, limit (default ${RELEASE_NOTES_LIST_LIMIT.DEFAULT}, maximum ${RELEASE_NOTES_LIST_LIMIT.MAXIMUM}), cursor (from the "Next page" footer). read: package, version (both required).`,
             required: false,
             type: Object,
         },
@@ -219,30 +305,60 @@ const releaseNotesService = fabricService({
         const p = params || {};
         switch (command) {
             case "list": {
+                const cursor = p.cursor === undefined ? undefined : decodeListCursor(p.cursor);
+                if (cursor) {
+                    if (p.package !== undefined && p.package !== cursor.package) {
+                        throw new BadRequestError("package does not match the cursor. Omit package or start over without a cursor.");
+                    }
+                    if (p.since_version !== undefined &&
+                        p.since_version !== cursor.since_version) {
+                        throw new BadRequestError("since_version does not match the cursor. Omit since_version or start over without a cursor.");
+                    }
+                }
+                const limit = resolveListLimit(p.limit ?? cursor?.limit);
+                const offset = cursor?.offset ?? 0;
+                const packageFilter = cursor ? cursor.package : p.package;
+                const sinceVersion = cursor ? cursor.since_version : p.since_version;
                 const entries = await fs.readdir(RELEASE_NOTES_PATH, {
                     withFileTypes: true,
                 });
                 const packageDirs = entries
                     .filter((entry) => entry.isDirectory())
                     .map((entry) => entry.name);
-                const packagesToList = p.package
-                    ? packageDirs.filter((pkg) => pkg === p.package)
+                const packagesToList = packageFilter
+                    ? packageDirs.filter((pkg) => pkg === packageFilter)
                     : packageDirs;
-                if (packagesToList.length === 0 && p.package) {
-                    return `No release notes found for package "${p.package}".`;
+                if (packagesToList.length === 0 && packageFilter) {
+                    return `No release notes found for package "${packageFilter}".`;
                 }
                 const allNotes = await Promise.all(packagesToList.map((pkg) => getPackageReleaseNotes(pkg)));
                 let flatNotes = allNotes.flat();
-                if (p.since_version) {
-                    flatNotes = filterReleaseNotesSince(flatNotes, p.since_version);
+                if (sinceVersion) {
+                    flatNotes = filterReleaseNotesSince(flatNotes, sinceVersion);
                 }
                 if (flatNotes.length === 0) {
-                    const filterDesc = p.since_version
-                        ? ` newer than ${p.since_version}`
-                        : "";
+                    const filterDesc = sinceVersion ? ` newer than ${sinceVersion}` : "";
                     return `No release notes found${filterDesc}.`;
                 }
-                return flatNotes.map(formatReleaseNoteListItem).join("\n");
+                if (offset >= flatNotes.length) {
+                    throw new BadRequestError(INVALID_CURSOR_MESSAGE);
+                }
+                flatNotes.sort((a, b) => compareReleaseNotes({ a, b }));
+                const nextOffset = offset + limit;
+                const page = flatNotes
+                    .slice(offset, nextOffset)
+                    .map(formatReleaseNoteListItem)
+                    .join("\n");
+                if (nextOffset >= flatNotes.length) {
+                    return page;
+                }
+                const nextCursor = encodeListCursor({
+                    limit,
+                    offset: nextOffset,
+                    package: packageFilter,
+                    since_version: sinceVersion,
+                });
+                return `${page}\n\nNext page: release_notes("list", { cursor: "${nextCursor}" })`;
             }
             case "read": {
                 if (!p.package)

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 { BadRequestError } from \"@jaypie/errors\";\nimport { fabricService } from \"@jaypie/fabric\";\nimport { parseFrontmatter } from \"@jaypie/kit\";\nimport {\n  createLayeredStore,\n  createMarkdownStore,\n  createSkillService,\n  type LayeredStoreLayer,\n} from \"@jaypie/tildeskill\";\nimport { existsSync, readdirSync, type Dirent } from \"node:fs\";\nimport * as fs from \"node:fs/promises\";\nimport * as path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { gt } from \"semver\";\n\nimport { getMcpAssetPaths, MCP_ASSET_DIRECTORY } from \"../../assets.js\";\nimport { RELEASE_NOTES_HELP } from \"./help.js\";\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\n// =============================================================================\n// ASSET PATHS\n// =============================================================================\n\nconst ENV_BUILTIN_SKILLS_PATH = \"MCP_BUILTIN_SKILLS_PATH\";\nconst ENV_RELEASE_NOTES_PATH = \"MCP_RELEASE_NOTES_PATH\";\nconst MARKDOWN_EXTENSION = \".md\";\nconst WARNING_PREFIX = \"[@jaypie/mcp]\";\n\n// A bundler (esbuild) collapses every module into one file, so this module's\n// directory is the bundle directory rather than dist/suites/docs/\nconst MODULE_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));\nconst PACKAGE_ASSET_PATHS = getMcpAssetPaths();\n\n/**\n * An explicit environment path wins outright. Otherwise the package copy wins,\n * then a copy beside the bundle. Returns the package path when neither exists.\n */\nfunction resolveAssetDirectory({\n  bundled,\n  envPath,\n  packaged,\n}: {\n  bundled: string;\n  envPath?: string;\n  packaged: string;\n}): string {\n  if (envPath) return envPath;\n  return (\n    [packaged, bundled].find((candidate) => existsSync(candidate)) ?? packaged\n  );\n}\n\nfunction hasEntries({\n  directory,\n  isEntry,\n}: {\n  directory: string;\n  isEntry: (entry: Dirent) => boolean;\n}): boolean {\n  try {\n    return readdirSync(directory, { withFileTypes: true }).some(isEntry);\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Warn once, on first use, when an asset directory is missing or empty. Waiting\n * for first use keeps servers that never call the service quiet.\n */\nfunction createAssetCheck({\n  directory,\n  envName,\n  isEntry,\n  name,\n}: {\n  directory: string;\n  envName: string;\n  isEntry: (entry: Dirent) => boolean;\n  name: string;\n}): () => void {\n  let checked = false;\n  return () => {\n    if (checked) return;\n    checked = true;\n    if (hasEntries({ directory, isEntry })) return;\n    // stderr keeps the stdio transport's stdout clean and still reaches CloudWatch\n    // eslint-disable-next-line no-console\n    console.warn(\n      `${WARNING_PREFIX} No ${name} found in \"${directory}\". Copy the ${name} directory from getMcpAssetPaths() in @jaypie/mcp/assets beside the bundle or set ${envName}.`,\n    );\n  };\n}\n\n/** Run `check` before any property of `target` is read */\nfunction withAssetCheck<T extends object>({\n  check,\n  target,\n}: {\n  check: () => void;\n  target: T;\n}): T {\n  return new Proxy(target, {\n    get(object, property, receiver) {\n      check();\n      return Reflect.get(object, property, receiver);\n    },\n  });\n}\n\nconst RELEASE_NOTES_PATH = resolveAssetDirectory({\n  bundled: path.join(MODULE_DIRECTORY, MCP_ASSET_DIRECTORY.RELEASE_NOTES),\n  envPath: process.env[ENV_RELEASE_NOTES_PATH],\n  packaged: PACKAGE_ASSET_PATHS.releaseNotes,\n});\n\n// Bundled Jaypie skills ship inside the @jaypie/mcp package. MCP_BUILTIN_SKILLS_PATH\n// relocates them without disabling the built-in layer.\nconst BUILTIN_SKILLS_PATH = resolveAssetDirectory({\n  bundled: path.join(MODULE_DIRECTORY, MCP_ASSET_DIRECTORY.SKILLS),\n  envPath: process.env[ENV_BUILTIN_SKILLS_PATH],\n  packaged: PACKAGE_ASSET_PATHS.skills,\n});\n\nconst checkReleaseNoteAssets = createAssetCheck({\n  directory: RELEASE_NOTES_PATH,\n  envName: ENV_RELEASE_NOTES_PATH,\n  isEntry: (entry) => entry.isDirectory(),\n  name: MCP_ASSET_DIRECTORY.RELEASE_NOTES,\n});\n\nconst checkSkillAssets = createAssetCheck({\n  directory: BUILTIN_SKILLS_PATH,\n  envName: ENV_BUILTIN_SKILLS_PATH,\n  isEntry: (entry) => entry.isFile() && entry.name.endsWith(MARKDOWN_EXTENSION),\n  name: MCP_ASSET_DIRECTORY.SKILLS,\n});\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[] = [];\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}\n\nskillLayers.push({\n  namespace: JAYPIE_SKILLS_NAMESPACE,\n  store: withAssetCheck({\n    check: checkSkillAssets,\n    target: createMarkdownStore({ path: BUILTIN_SKILLS_PATH }),\n  }),\n});\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 frontMatter =\n        parseFrontmatter<ReleaseNoteFrontMatter>(content).data;\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\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\nexport const skillService = createSkillService(skillStore);\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\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 RELEASE_NOTES_HELP;\n    }\n\n    checkReleaseNoteAssets();\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 BadRequestError(\"package is required\");\n        if (!p.version) throw new BadRequestError(\"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 BadRequestError(\n          `Unknown command: ${command}. Use release_notes() for help.`,\n        );\n    }\n  },\n});\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sources":["../../../src/suites/docs/index.ts"],"sourcesContent":["/**\n * Docs Suite - Documentation services (skill, version, release_notes)\n */\nimport { BadRequestError } from \"@jaypie/errors\";\nimport { fabricService } from \"@jaypie/fabric\";\nimport { parseFrontmatter } from \"@jaypie/kit\";\nimport {\n  createLayeredStore,\n  createMarkdownStore,\n  createSkillService,\n  type LayeredStoreLayer,\n} from \"@jaypie/tildeskill\";\nimport { existsSync, readdirSync, type Dirent } from \"node:fs\";\nimport * as fs from \"node:fs/promises\";\nimport * as path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { gt, rcompare, valid } from \"semver\";\n\nimport {\n  getMcpAssetPaths,\n  getMcpBuildInfo,\n  MCP_ASSET_DIRECTORY,\n} from \"../../assets.js\";\nimport { RELEASE_NOTES_HELP } from \"./help.js\";\n\n// Build-time constants\nconst BUILD_VERSION_STRING = getMcpBuildInfo().versionString;\n\n// =============================================================================\n// ASSET PATHS\n// =============================================================================\n\nconst ENV_BUILTIN_SKILLS_PATH = \"MCP_BUILTIN_SKILLS_PATH\";\nconst ENV_RELEASE_NOTES_PATH = \"MCP_RELEASE_NOTES_PATH\";\nconst MARKDOWN_EXTENSION = \".md\";\nconst WARNING_PREFIX = \"[@jaypie/mcp]\";\n\n// A bundler (esbuild) collapses every module into one file, so this module's\n// directory is the bundle directory rather than dist/suites/docs/\nconst MODULE_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));\nconst PACKAGE_ASSET_PATHS = getMcpAssetPaths();\n\n/**\n * An explicit environment path wins outright. Otherwise the package copy wins,\n * then a copy beside the bundle. Returns the package path when neither exists.\n */\nfunction resolveAssetDirectory({\n  bundled,\n  envPath,\n  packaged,\n}: {\n  bundled: string;\n  envPath?: string;\n  packaged: string;\n}): string {\n  if (envPath) return envPath;\n  return (\n    [packaged, bundled].find((candidate) => existsSync(candidate)) ?? packaged\n  );\n}\n\nfunction hasEntries({\n  directory,\n  isEntry,\n}: {\n  directory: string;\n  isEntry: (entry: Dirent) => boolean;\n}): boolean {\n  try {\n    return readdirSync(directory, { withFileTypes: true }).some(isEntry);\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Warn once, on first use, when an asset directory is missing or empty. Waiting\n * for first use keeps servers that never call the service quiet.\n */\nfunction createAssetCheck({\n  directory,\n  envName,\n  isEntry,\n  name,\n}: {\n  directory: string;\n  envName: string;\n  isEntry: (entry: Dirent) => boolean;\n  name: string;\n}): () => void {\n  let checked = false;\n  return () => {\n    if (checked) return;\n    checked = true;\n    if (hasEntries({ directory, isEntry })) return;\n    // stderr keeps the stdio transport's stdout clean and still reaches CloudWatch\n    // eslint-disable-next-line no-console\n    console.warn(\n      `${WARNING_PREFIX} No ${name} found in \"${directory}\". Copy the ${name} directory from getMcpAssetPaths() in @jaypie/mcp/assets beside the bundle or set ${envName}.`,\n    );\n  };\n}\n\n/** Run `check` before any property of `target` is read */\nfunction withAssetCheck<T extends object>({\n  check,\n  target,\n}: {\n  check: () => void;\n  target: T;\n}): T {\n  return new Proxy(target, {\n    get(object, property, receiver) {\n      check();\n      return Reflect.get(object, property, receiver);\n    },\n  });\n}\n\nconst RELEASE_NOTES_PATH = resolveAssetDirectory({\n  bundled: path.join(MODULE_DIRECTORY, MCP_ASSET_DIRECTORY.RELEASE_NOTES),\n  envPath: process.env[ENV_RELEASE_NOTES_PATH],\n  packaged: PACKAGE_ASSET_PATHS.releaseNotes,\n});\n\n// Bundled Jaypie skills ship inside the @jaypie/mcp package. MCP_BUILTIN_SKILLS_PATH\n// relocates them without disabling the built-in layer.\nconst BUILTIN_SKILLS_PATH = resolveAssetDirectory({\n  bundled: path.join(MODULE_DIRECTORY, MCP_ASSET_DIRECTORY.SKILLS),\n  envPath: process.env[ENV_BUILTIN_SKILLS_PATH],\n  packaged: PACKAGE_ASSET_PATHS.skills,\n});\n\nconst checkReleaseNoteAssets = createAssetCheck({\n  directory: RELEASE_NOTES_PATH,\n  envName: ENV_RELEASE_NOTES_PATH,\n  isEntry: (entry) => entry.isDirectory(),\n  name: MCP_ASSET_DIRECTORY.RELEASE_NOTES,\n});\n\nconst checkSkillAssets = createAssetCheck({\n  directory: BUILTIN_SKILLS_PATH,\n  envName: ENV_BUILTIN_SKILLS_PATH,\n  isEntry: (entry) => entry.isFile() && entry.name.endsWith(MARKDOWN_EXTENSION),\n  name: MCP_ASSET_DIRECTORY.SKILLS,\n});\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[] = [];\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}\n\nskillLayers.push({\n  namespace: JAYPIE_SKILLS_NAMESPACE,\n  store: withAssetCheck({\n    check: checkSkillAssets,\n    target: createMarkdownStore({ path: BUILTIN_SKILLS_PATH }),\n  }),\n});\n\nconst skillStore = createLayeredStore({\n  layers: skillLayers,\n  separator: LAYER_SEPARATOR,\n});\n\n// =============================================================================\n// HELPER FUNCTIONS\n// =============================================================================\n\nconst CURSOR_ENCODING = \"base64url\";\nconst INVALID_CURSOR_MESSAGE =\n  'Invalid cursor. Call release_notes(\"list\") to start over.';\nconst RELEASE_NOTES_LIST_LIMIT = {\n  DEFAULT: 50,\n  MAXIMUM: 200,\n} as const;\n\ninterface ReleaseNoteFrontMatter {\n  date?: string;\n  summary?: string;\n  version?: string;\n}\n\ninterface ReleaseNoteListItem {\n  date?: string;\n  filename: string;\n  packageName: string;\n  summary?: string;\n  version?: string;\n}\n\n/** Decoded form of the opaque `list` cursor */\ninterface ReleaseNotesListCursor {\n  limit?: number;\n  offset: number;\n  package?: string;\n  since_version?: string;\n}\n\nfunction compareText({ a, b }: { a: string; b: string }): number {\n  if (a < b) return -1;\n  if (a > b) return 1;\n  return 0;\n}\n\n/**\n * Package ascending, then semver descending. Valid semver sorts before\n * anything else, and filename breaks every remaining tie so the order is total.\n */\nfunction compareReleaseNotes({\n  a,\n  b,\n}: {\n  a: ReleaseNoteListItem;\n  b: ReleaseNoteListItem;\n}): number {\n  const byPackage = compareText({ a: a.packageName, b: b.packageName });\n  if (byPackage !== 0) return byPackage;\n\n  const aVersion = a.version && valid(a.version);\n  const bVersion = b.version && valid(b.version);\n  if (aVersion && bVersion) {\n    const byVersion = rcompare(aVersion, bVersion);\n    if (byVersion !== 0) return byVersion;\n  } else if (aVersion) {\n    return -1;\n  } else if (bVersion) {\n    return 1;\n  }\n\n  return compareText({ a: b.filename, b: a.filename });\n}\n\nfunction isPositiveInteger(value: unknown): value is number {\n  return typeof value === \"number\" && Number.isInteger(value) && value > 0;\n}\n\nfunction isOptionalString(value: unknown): boolean {\n  return value === undefined || typeof value === \"string\";\n}\n\nfunction encodeListCursor(cursor: ReleaseNotesListCursor): string {\n  const ordered: ReleaseNotesListCursor = {\n    limit: cursor.limit,\n    offset: cursor.offset,\n    package: cursor.package,\n    since_version: cursor.since_version,\n  };\n  return Buffer.from(JSON.stringify(ordered)).toString(CURSOR_ENCODING);\n}\n\nfunction decodeListCursor(cursor: unknown): ReleaseNotesListCursor {\n  if (typeof cursor !== \"string\" || cursor.length === 0) {\n    throw new BadRequestError(INVALID_CURSOR_MESSAGE);\n  }\n\n  let decoded: unknown;\n  try {\n    decoded = JSON.parse(\n      Buffer.from(cursor, CURSOR_ENCODING).toString(\"utf-8\"),\n    );\n  } catch {\n    throw new BadRequestError(INVALID_CURSOR_MESSAGE);\n  }\n\n  if (typeof decoded !== \"object\" || decoded === null) {\n    throw new BadRequestError(INVALID_CURSOR_MESSAGE);\n  }\n\n  const candidate = decoded as Record<string, unknown>;\n  const isValid =\n    typeof candidate.offset === \"number\" &&\n    Number.isInteger(candidate.offset) &&\n    candidate.offset >= 0 &&\n    (candidate.limit === undefined ||\n      (isPositiveInteger(candidate.limit) &&\n        candidate.limit <= RELEASE_NOTES_LIST_LIMIT.MAXIMUM)) &&\n    isOptionalString(candidate.package) &&\n    isOptionalString(candidate.since_version);\n\n  if (!isValid) {\n    throw new BadRequestError(INVALID_CURSOR_MESSAGE);\n  }\n\n  return candidate as unknown as ReleaseNotesListCursor;\n}\n\n/**\n * Accept a number or numeric string, reject anything below one, and clamp to\n * the maximum\n */\nfunction resolveListLimit(value: unknown): number {\n  if (value === undefined || value === null || value === \"\") {\n    return RELEASE_NOTES_LIST_LIMIT.DEFAULT;\n  }\n  const limit = typeof value === \"string\" ? Number(value) : value;\n  if (!isPositiveInteger(limit)) {\n    throw new BadRequestError(\"limit must be a positive integer\");\n  }\n  return Math.min(limit, RELEASE_NOTES_LIST_LIMIT.MAXIMUM);\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 frontMatter =\n        parseFrontmatter<ReleaseNoteFrontMatter>(content).data;\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\nasync function getPackageReleaseNotes(\n  packageName: string,\n): Promise<ReleaseNoteListItem[]> {\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(MARKDOWN_EXTENSION));\n\n    return await Promise.all(\n      mdFiles.map(async (file) => {\n        const parsed = await parseReleaseNoteFile(path.join(packageDir, file));\n        return { ...parsed, packageName };\n      }),\n    );\n  } catch {\n    return [];\n  }\n}\n\nfunction filterReleaseNotesSince(\n  notes: ReleaseNoteListItem[],\n  sinceVersion: string,\n): ReleaseNoteListItem[] {\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\nexport const skillService = createSkillService(skillStore);\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\ninterface ReleaseNotesInput {\n  cursor?: string;\n  limit?: number | string;\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 (paginated), 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. list: package, since_version, limit (default ${RELEASE_NOTES_LIST_LIMIT.DEFAULT}, maximum ${RELEASE_NOTES_LIST_LIMIT.MAXIMUM}), cursor (from the \"Next page\" footer). read: package, version (both required).`,\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 RELEASE_NOTES_HELP;\n    }\n\n    checkReleaseNoteAssets();\n    const p = params || {};\n\n    switch (command) {\n      case \"list\": {\n        const cursor =\n          p.cursor === undefined ? undefined : decodeListCursor(p.cursor);\n        if (cursor) {\n          if (p.package !== undefined && p.package !== cursor.package) {\n            throw new BadRequestError(\n              \"package does not match the cursor. Omit package or start over without a cursor.\",\n            );\n          }\n          if (\n            p.since_version !== undefined &&\n            p.since_version !== cursor.since_version\n          ) {\n            throw new BadRequestError(\n              \"since_version does not match the cursor. Omit since_version or start over without a cursor.\",\n            );\n          }\n        }\n\n        const limit = resolveListLimit(p.limit ?? cursor?.limit);\n        const offset = cursor?.offset ?? 0;\n        const packageFilter = cursor ? cursor.package : p.package;\n        const sinceVersion = cursor ? cursor.since_version : p.since_version;\n\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 = packageFilter\n          ? packageDirs.filter((pkg) => pkg === packageFilter)\n          : packageDirs;\n\n        if (packagesToList.length === 0 && packageFilter) {\n          return `No release notes found for package \"${packageFilter}\".`;\n        }\n\n        const allNotes = await Promise.all(\n          packagesToList.map((pkg) => getPackageReleaseNotes(pkg)),\n        );\n        let flatNotes = allNotes.flat();\n\n        if (sinceVersion) {\n          flatNotes = filterReleaseNotesSince(flatNotes, sinceVersion);\n        }\n\n        if (flatNotes.length === 0) {\n          const filterDesc = sinceVersion ? ` newer than ${sinceVersion}` : \"\";\n          return `No release notes found${filterDesc}.`;\n        }\n\n        if (offset >= flatNotes.length) {\n          throw new BadRequestError(INVALID_CURSOR_MESSAGE);\n        }\n\n        flatNotes.sort((a, b) => compareReleaseNotes({ a, b }));\n        const nextOffset = offset + limit;\n        const page = flatNotes\n          .slice(offset, nextOffset)\n          .map(formatReleaseNoteListItem)\n          .join(\"\\n\");\n\n        if (nextOffset >= flatNotes.length) {\n          return page;\n        }\n\n        const nextCursor = encodeListCursor({\n          limit,\n          offset: nextOffset,\n          package: packageFilter,\n          since_version: sinceVersion,\n        });\n        return `${page}\\n\\nNext page: release_notes(\"list\", { cursor: \"${nextCursor}\" })`;\n      }\n\n      case \"read\": {\n        if (!p.package) throw new BadRequestError(\"package is required\");\n        if (!p.version) throw new BadRequestError(\"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 BadRequestError(\n          `Unknown command: ${command}. Use release_notes() for help.`,\n        );\n    }\n  },\n});\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/mcp",
-  "version": "0.8.158",
+  "version": "0.8.159",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",

package/release-notes/constructs/1.2.87.md

@@ -0,0 +1,19 @@
+---
+version: 1.2.87
+date: 2026-09-14
+summary: JaypieStack warns at synth on an unset or non-hex PROJECT_NONCE
+---
+
+## Changes
+
+- **`JaypieStack`** warns at synth (`@jaypie/constructs:projectNonceFormat`)
+  when `CDK_DEFAULT_ACCOUNT` is set and `PROJECT_NONCE` is unset or does not
+  match `^[0-9a-f]{6,}$`. A word or branch-name nonce lands in immutable stack
+  names and global S3 bucket names, where it repeats across projects and
+  accounts (#554).
+
+## Upgrade
+
+- A stack deployed with a non-hex nonce keeps warning. Stack and bucket names
+  cannot be renamed: acknowledge `@jaypie/constructs:projectNonceFormat`, or
+  deploy a new install with a hex nonce and tear down the old one.

package/release-notes/mcp/0.8.159.md

@@ -0,0 +1,50 @@
+---
+version: 0.8.159
+date: 2026-09-14
+summary: PROJECT_NONCE is a required 8-hex environment variable in every skill
+---
+
+## Changes
+
+- **`cicd-actions`** makes `project-nonce` `required: true` in
+  `setup-environment` and fails with `::error::` when it is empty. The branch
+  name and `prod` fallbacks are removed (#554).
+- **`cicd-environments`** moves `PROJECT_NONCE` to Required Variables (8
+  lowercase hex, unique per environment, `openssl rand -hex 4`) and adds it to
+  the sandbox and production examples.
+- **`cicd-deploy`** passes `project-nonce: ${{ vars.PROJECT_NONCE }}` in both
+  deploy jobs, replaces hand-rolled `api-${env}-${nonce}` naming with the
+  `JaypieStack` generated name, and adds One Install per Environment.
+- **`variables`**, **`cdk`**, **`jaypie`**, **`recipe-api-server`**, and
+  **`debugging`** use hex nonces in place of `dev`, `staging`, and `prod`.
+- **`cdk`** documents the `@jaypie/constructs:projectNonceFormat` synth
+  warning.
+- **`github`** notes that `setup-environment` fails on an empty
+  `project-nonce` instead of falling back.
+- **`@jaypie/mcp/assets`** exports `getMcpBuildInfo()`, which returns
+  `{ commit, version, versionString }` from the same build-time replacements the
+  `version` tool reports. A consumer syncing `skills/` and `release-notes/`
+  reads the build from the same package. The **`mcp`** skill documents it
+  (#555).
+- **`tildeskill`** documents that layered `find` checks every layer for an
+  exact alias before plural/singular fallback (#558).
+- **`tildeskill`** documents `createDynamoDbStore` from
+  `@jaypie/tildeskill/dynamodb`, `syncSkills`, and `delete` semantics for every
+  store. **`dynamodb`** notes that skills use `indexModelCategory` and that
+  `registerSkillModel()` declares it (#557).
+- **`tildeskill`** documents that `createSkillService` throws `BadRequestError`
+  for an invalid alias and `NotFoundError` for a missing skill.
+- **`release_notes("list")`** paginates. `limit` defaults to 50 and caps at
+  200. Notes sort by package ascending, then version descending. A
+  `Next page: release_notes("list", { cursor: "..." })` footer appears only
+  when more notes exist, and its opaque cursor carries `package`,
+  `since_version`, and `limit`. Invalid cursors and filters that conflict with
+  the cursor return a bad request. The unfiltered first page drops from about
+  61K to about 5.7K characters. The **`mcp`** and **`releasenotes`** skills
+  document it (#556).
+
+## Upgrade
+
+- Projects built from the previous `cicd-actions` template may have deployed
+  branch-name nonces. Set `PROJECT_NONCE` on each GitHub environment. The new
+  value creates a new install, so tear down the old stacks and buckets.

package/release-notes/testkit/1.2.74.md

@@ -0,0 +1,12 @@
+---
+version: 1.2.74
+date: 2026-09-14
+summary: Tildeskill mocks cover the DynamoDB store, syncSkills, and SkillStore delete
+---
+
+## Changes
+
+- Mock stores implement `delete`, resolving `false` (#557).
+- New tildeskill mocks: `createDynamoDbStore`, `hashSkill`,
+  `registerSkillModel`, `syncSkills` (resolves empty lists), and the
+  `SKILL_MODEL`, `SKILL_MODEL_NAME`, and `SKILL_NAMESPACE` constants (#557).

package/release-notes/tildeskill/0.3.5.md

@@ -0,0 +1,34 @@
+---
+version: 0.3.5
+date: 2026-09-14
+summary: DynamoDB skill store, syncSkills, and SkillStore delete; layered find prefers an exact alias in any layer
+---
+
+## Changes
+
+- `createLayeredStore().find` checks every layer for an exact alias before it
+  tries plural/singular fallback in any layer. With `studio:test` and
+  `jaypie:tests`, `find("tests")` returns `jaypie:tests` in place of
+  `studio:test`, so a local skill cannot shadow an existing Jaypie skill under
+  a different spelling (#558).
+- `createSkillService` resolves through `find`, so `skill("tests")` follows the
+  same order. Namespace-qualified aliases still search only their own layer.
+- `createDynamoDbStore({ category })` from the new `@jaypie/tildeskill/dynamodb`
+  subpath serves skills from `@jaypie/dynamodb` as `skill` entities with
+  deterministic ids (`uuidv5("<category>:<alias>", SKILL_NAMESPACE)`) and
+  `metadata.hash`. `@jaypie/dynamodb` is an optional peer dependency that the
+  main entry never imports. The store loads it with a dynamic import on first
+  use, so a CJS consumer shares the host's initialized client (#557).
+- `syncSkills({ from, to })` puts added and changed records, leaves unchanged
+  records alone, deletes records missing from `from`, and returns
+  `{ added, removed, unchanged, updated }`. An empty `from` with a non-empty
+  `to` throws `ConfigurationError` unless `allowEmptySource: true` (#557).
+- `SkillStore` gains `delete(alias)`. Memory removes the record, markdown
+  removes the file, layered requires a namespace-qualified alias, and DynamoDB
+  soft deletes (#557).
+- New main exports: `hashSkill`, `registerSkillModel`, `SKILL_MODEL`,
+  `SKILL_MODEL_NAME`, `syncSkills`, and the `DynamoDbStoreOptions`,
+  `SyncSkillsOptions`, and `SyncSkillsResult` types.
+- `createSkillService` throws `BadRequestError` for an invalid alias and
+  `NotFoundError` for a missing skill in place of a vanilla `Error`. Messages
+  are unchanged.

package/skills/cdk.md

@@ -153,6 +153,8 @@ Props extend `StackProps` with one addition:
 
 If you see `undefined` or `unknown` in a generated stack name or tag, an env var is missing — fix the environment rather than overriding `stackName`.
 
+`JaypieStack` warns at synth (`@jaypie/constructs:projectNonceFormat`) when `CDK_DEFAULT_ACCOUNT` is set and `PROJECT_NONCE` is unset or is not lowercase hex of six or more characters. The warning fires before the first deploy makes a word or branch-name nonce permanent.
+
 #### `JaypieAppStack` / `JaypieInfrastructureStack`
 
 Thin convenience subclasses that pre-fill `key`:
@@ -206,12 +208,14 @@ See `skill("variables")` for the role of `PROJECT_ENV` and `PROJECT_NONCE`.
 
 ```bash
 # Deploy to sandbox
-PROJECT_ENV=sandbox PROJECT_NONCE=dev cdk deploy
+PROJECT_ENV=sandbox PROJECT_NONCE=3f9c21ab cdk deploy
 
 # Deploy to production
-PROJECT_ENV=production PROJECT_NONCE=prod cdk deploy
+PROJECT_ENV=production PROJECT_NONCE=ba342b91 cdk deploy
 ```
 
+Deploys run in CI (see `skill("cicd-deploy")`). Each environment carries its own `PROJECT_NONCE`, 8 lowercase hex characters generated once with `openssl rand -hex 4`. See `skill("github")` for provisioning.
+
 ## Lambda with DynamoDB Tables
 
 Pass tables to `JaypieLambda` for automatic permissions and environment wiring:

package/skills/cicd-actions.md

@@ -49,9 +49,8 @@ inputs:
     description: 'Sponsor segment of the generated stack name'
     required: true
   project-nonce:
-    description: 'Unique resource identifier'
-    required: false
-    default: ''
+    description: '8 lowercase hex characters, unique per environment'
+    required: true
   log-level:
     description: 'Log level (trace, debug, info, warn, error)'
     required: false
@@ -92,14 +91,11 @@ runs:
         echo "PROJECT_KEY=${{ inputs.project-key }}" >> $GITHUB_ENV
         echo "PROJECT_SPONSOR=${{ inputs.project-sponsor }}" >> $GITHUB_ENV
 
-        # Resolve PROJECT_NONCE (default: branch name or 'prod')
+        # Resolve PROJECT_NONCE (required, no fallback)
         NONCE="${{ inputs.project-nonce }}"
         if [ -z "$NONCE" ]; then
-          if [ "$PROJECT_ENV" = "production" ]; then
-            NONCE="prod"
-          else
-            NONCE="${GITHUB_REF_NAME//\//-}"
-          fi
+          echo "::error::project-nonce is empty. Set PROJECT_NONCE on the GitHub environment (openssl rand -hex 4)"
+          exit 1
         fi
         echo "project-nonce=${NONCE}" >> $GITHUB_OUTPUT
         echo "PROJECT_NONCE=${NONCE}" >> $GITHUB_ENV
@@ -131,6 +127,8 @@ runs:
 
 `project-sponsor` is `required: true` on purpose. `PROJECT_SPONSOR` is the first segment of the generated stack name (`cdk-{PROJECT_SPONSOR}-{PROJECT_KEY}-{PROJECT_ENV}-{PROJECT_NONCE}`), and an optional input with an empty default deploys `cdk-undefined-...` silently. A stack name is immutable, so correcting it later means a stack replacement. See `skill("cdk")` for stack naming and `skill("variables")` for the full variable reference.
 
+`project-nonce` is `required: true` with no fallback, and the step exits with `::error::` when it is empty because GitHub does not enforce `required` on composite action inputs. `PROJECT_NONCE` is 8 lowercase hex characters, generated once per environment (`openssl rand -hex 4`) and stored as a GitHub environment variable (see `skill("cicd-environments")`). It lands in globally unique names (S3 buckets), SSM parameter paths, and immutable stack names. A branch name or word such as `prod` repeats across projects and accounts, and changing the nonce later means a new install beside the old one.
+
 ## configure-aws/action.yml
 
 Configures AWS credentials via OIDC.

package/skills/cicd-deploy.md

@@ -75,6 +75,7 @@ jobs:
           project-key: my-project
           project-sponsor: ${{ vars.PROJECT_SPONSOR }}
           project-env: sandbox
+          project-nonce: ${{ vars.PROJECT_NONCE }}
 
       - uses: ./.github/actions/configure-aws
         with:
@@ -163,6 +164,7 @@ jobs:
           project-key: my-project
           project-sponsor: ${{ vars.PROJECT_SPONSOR }}
           project-env: production
+          project-nonce: ${{ vars.PROJECT_NONCE }}
 
       - uses: ./.github/actions/configure-aws
         with:
@@ -271,27 +273,28 @@ Requirements:
 
 See `skill("cicd-actions")` for the `web-deploy` action body and `skill("web")` for the construct.
 
-## Environment-Specific Stack Naming
+## Stack Naming
 
-Use consistent stack naming with environment and nonce:
+`JaypieStack` names every stack `cdk-{PROJECT_SPONSOR}-{PROJECT_KEY}-{PROJECT_ENV}-{PROJECT_NONCE}[-{key}]` and resolves the account and region (see `skill("cdk")`). Do not compose stack names in `app.ts`:
 
 ```typescript
 // workspaces/cdk/src/app.ts
-const env = process.env.PROJECT_ENV || "sandbox";
-const nonce = process.env.PROJECT_NONCE || "dev";
-
-new ApiStack(app, `api-${env}-${nonce}`, {
-  env: {
-    account: process.env.CDK_DEFAULT_ACCOUNT,
-    region: process.env.CDK_DEFAULT_REGION,
-  },
-});
+import { App } from "aws-cdk-lib";
+import { JaypieAppStack } from "@jaypie/constructs";
+
+const app = new App();
+new JaypieAppStack(app, "AppStack");
 ```
 
-This produces stack names like:
-- `api-sandbox-feat-new-feature`
-- `api-sandbox-main`
-- `api-production-prod`
+With `PROJECT_NONCE` set per environment (see `skill("cicd-environments")`), this produces:
+- `cdk-finlaysonstudio-my-project-sandbox-3f9c21ab-app`
+- `cdk-finlaysonstudio-my-project-production-ba342b91-app`
+
+The `cdk-deploy` globs `*-sandbox-*` and `*-production-*` match these names.
+
+### One Install per Environment
+
+The nonce belongs to the environment, so every branch that deploys to sandbox updates the same stacks. A project serving fixed hostnames (`api.sandbox.example.com`) holds one install per environment, because CloudFront aliases and Route53 records collide. Override `project-nonce` with a new hex value only for an intentional clean install beside an existing one. Stack and bucket names cannot be renamed, so recovering from a wrong nonce means that new install and a teardown of the old one.
 
 ## Deployment Flow
 

package/skills/cicd-environments.md

@@ -12,6 +12,9 @@ GitHub Environments provide deployment-specific variables for Jaypie CDK workflo
 | Variable | Description |
 |----------|-------------|
 | `AWS_ROLE_ARN` | OIDC role ARN for assuming AWS credentials |
+| `PROJECT_NONCE` | 8 lowercase hex characters, unique per environment |
+
+Generate `PROJECT_NONCE` once per environment with `openssl rand -hex 4`. It scopes stack names, S3 bucket names, and SSM paths, so a new value deploys a new install and strands the old one. `setup-environment` fails when it is missing (see `skill("cicd-actions")`).
 
 ## Optional Variables
 
@@ -21,7 +24,6 @@ GitHub Environments provide deployment-specific variables for Jaypie CDK workflo
 | `LOG_LEVEL` | `trace` (sandbox) / `info` (production) | Application log level |
 | `PROJECT_CHAOS` | `full` (sandbox) / `none` (production) | Chaos engineering mode |
 | `PROJECT_ENV` | Environment name | Environment identifier |
-| `PROJECT_NONCE` | Branch name or `prod` | Unique identifier for resources |
 
 ## Environment Setup
 
@@ -43,6 +45,7 @@ GitHub Environments provide deployment-specific variables for Jaypie CDK workflo
 AWS_ROLE_ARN      = arn:aws:iam::123456789012:role/GitHubActions-Sandbox
 AWS_REGION        = us-east-1
 PROJECT_ENV       = sandbox
+PROJECT_NONCE     = 3f9c21ab
 LOG_LEVEL         = trace
 PROJECT_CHAOS     = full
 ```
@@ -53,6 +56,7 @@ PROJECT_CHAOS     = full
 AWS_ROLE_ARN      = arn:aws:iam::123456789012:role/GitHubActions-Production
 AWS_REGION        = us-east-1
 PROJECT_ENV       = production
+PROJECT_NONCE     = ba342b91
 LOG_LEVEL         = info
 PROJECT_CHAOS     = none
 ```

package/skills/debugging.md

@@ -39,11 +39,15 @@ If you see `undefined` in a CDK stack name, a required variable is missing:
 // BAD: undefined if PROJECT_NONCE not set
 const stackName = `api-${process.env.PROJECT_NONCE}`;
 
-// GOOD: Provide default
+// BAD: a word default repeats across projects and accounts
 const nonce = process.env.PROJECT_NONCE || "dev";
-const stackName = `api-${nonce}`;
+
+// GOOD: JaypieStack names the stack from PROJECT_* variables
+new JaypieAppStack(app, "AppStack");
 ```
 
+Set the missing variable on the GitHub environment rather than adding a default (see `skill("cicd-environments")`).
+
 ### "unknown" in Logs
 
 `unknown` indicates a value was expected but fell back to a default:

package/skills/dynamodb.md

@@ -366,6 +366,10 @@ const nextPage = await queryByScope({
 
 `storeExchange(envelope, { exchange?, scope? })` persists an `@jaypie/llm` exchange envelope (see `skill("llm")`) as an `exchange` entity. It registers the canonical exchange model (`registerExchangeModel()` from `@jaypie/fabric`), maps envelope fields onto reserved attributes (`input`, `content`, `data`, `llm`, `status`, `xid`), and owns 400KB item-limit safety (drops the history delta, then truncates long fields, marking `metadata.truncated`). It warns and returns `null` — never throws — when `initClient()` has not run or the write fails. `@jaypie/llm` calls it automatically when `LLM_EXCHANGE_ENABLED` is set; pass `exchange` (parent id) for turn chains and `scope` to nest under a parent entity.
 
+### Skill Storage
+
+`@jaypie/tildeskill/dynamodb` stores skills as `skill` entities queried through `indexModelCategory` (see `skill("tildeskill")`). Call `registerSkillModel()` from `@jaypie/tildeskill` before `getAllRegisteredIndexes()` so CDK declares the index.
+
 ### TTL (Time to Live)
 
 DynamoDB expires items whose TTL attribute holds a past Unix epoch **in seconds**. Jaypie writes that attribute (`ttl` by default) and the `JaypieDynamoDb` construct enables TTL on it by default.

package/skills/github.md

@@ -260,7 +260,7 @@ jobs:
 
 - Deploy jobs declare `permissions` with `contents: read` and `id-token: write`
 - Composite actions under `.github/actions` receive every value through `inputs` and never reference `vars.*` or `secrets.*`
-- `setup-environment` supplies fallback defaults when an input is empty
+- `setup-environment` supplies fallback defaults when an input is empty, except `project-nonce`, which fails the job
 - The OIDC subject for an environment job is `repo:<org>/<repo>:environment:<env>` (see ~cicd-environments for the trust policy)
 
 ## Audit

package/skills/jaypie.md

@@ -66,7 +66,7 @@ project/
 |----------|---------|
 | `PROJECT_ENV` | Environment: local, sandbox, production |
 | `PROJECT_KEY` | Project identifier for logging |
-| `PROJECT_NONCE` | Unique resource identifier |
+| `PROJECT_NONCE` | 8 lowercase hex characters, unique per environment |
 | `LOG_LEVEL` | Log level: trace, debug, info, warn, error |
 
 ### Error Handling

package/skills/mcp.md

@@ -27,11 +27,15 @@ skill("tests")          # Testing patterns
 
 ```
 release_notes()                                    # Show help
-release_notes("list")                              # List all release notes
+release_notes("list")                              # First page of all release notes
+release_notes("list", { limit: 20 })               # Smaller page (default 50, maximum 200)
 release_notes("list", { package: "mcp" })          # Filter by package
+release_notes("list", { cursor: "..." })           # Next page, from the footer
 release_notes("read", { package: "mcp", version: "0.5.0" })  # Read specific note
 ```
 
+`list` sorts by package ascending, then version descending. When more notes exist, the last line reads `Next page: release_notes("list", { cursor: "..." })`. The cursor carries `package`, `since_version`, and `limit`, so that call alone continues the listing.
+
 ## Datadog Tool
 
 Unified tool for logs, monitors, metrics, synthetics, and RUM.
@@ -134,6 +138,17 @@ Each directory resolves to the first match: its environment variable, the instal
 | `MCP_RELEASE_NOTES_PATH` | Release notes directory |
 | `MCP_SKILLS_PATH` | Client skills directory layered over the Jaypie skills (namespace `local`) |
 
+`getMcpBuildInfo` from `@jaypie/mcp/assets` returns `{ commit, version, versionString }` of the build that packed the markdown, the same values the `version` tool reports. A consumer that syncs the copied directories reads it from the same package without a registry call.
+
+```typescript
+import { getMcpBuildInfo } from "@jaypie/mcp/assets";
+
+const { commit, version, versionString } = getMcpBuildInfo();
+// versionString: "@jaypie/mcp@0.8.159#460f95c3"
+```
+
+`commit` is the first 8 characters of `PROJECT_COMMIT` at build time and is empty when it was unset. Unbuilt source returns version `0.0.0`.
+
 ### SDK Transport (`mcpExpressHandler`)
 
 `mcpExpressHandler` from `@jaypie/mcp` wraps the SDK's `StreamableHTTPServerTransport` with optional sessions. It suits a long-running Express server, not Lambda.

package/skills/recipe-api-server.md

@@ -178,7 +178,8 @@ See `skill("apikey")` for full key generation/validation/hashing documentation.
 
 ```bash
 # First deploy creates secrets and table
-PROJECT_ENV=sandbox PROJECT_NONCE=dev npx cdk deploy
+# PROJECT_NONCE is the environment's 8-hex nonce (see skill("cicd-environments"))
+PROJECT_ENV=sandbox PROJECT_NONCE=3f9c21ab npx cdk deploy
 ```
 
 No workflow secrets needed for generated values — CloudFormation creates them on first deploy and preserves them on subsequent deploys.

package/skills/releasenotes.md

@@ -9,12 +9,15 @@ How to access and write release notes for Jaypie packages.
 ## MCP Tools
 
 ```
-mcp__jaypie__list_release_notes()
-mcp__jaypie__list_release_notes(package: "mcp")
-mcp__jaypie__list_release_notes(package: "jaypie", since_version: "1.0.0")
-mcp__jaypie__read_release_note(package: "mcp", version: "0.3.4")
+release_notes("list")
+release_notes("list", { package: "mcp" })
+release_notes("list", { package: "jaypie", since_version: "1.0.0" })
+release_notes("list", { cursor: "..." })
+release_notes("read", { package: "mcp", version: "0.3.4" })
 ```
 
+`list` returns 50 notes per page by default (`limit`, maximum 200). When more notes exist, the last line is a `Next page` footer with a `cursor` that continues the same listing.
+
 ## Directory Structure
 
 ```

package/skills/tildeskill.md

@@ -1,6 +1,6 @@
 ---
 description: Skill/vocabulary storage with pluggable backends (pre-1.0)
-related: fabric, mcp
+related: dynamodb, fabric, mcp
 ---
 
 # @jaypie/tildeskill
@@ -14,6 +14,8 @@ This package provides a storage abstraction for skill/vocabulary documents with
 - Loading skills from markdown files with YAML frontmatter
 - In-memory storage for testing
 - Layered composition of multiple stores with namespace prefixes
+- DynamoDB storage through the `@jaypie/tildeskill/dynamodb` subpath
+- Store-to-store sync with `syncSkills`
 - Consistent alias normalization and validation
 - Filtering by namespace and tags
 - Searching across alias, name, description, content, and tags
@@ -46,6 +48,7 @@ interface ListFilter {
 }
 
 interface SkillStore {
+  delete(alias: string): Promise<boolean>;
   find(alias: string): Promise<SkillRecord | null>;
   get(alias: string): Promise<SkillRecord | null>;
   getByNickname(nickname: string): Promise<SkillRecord[]>;
@@ -87,6 +90,71 @@ const store = createMemoryStore([
 const skill = await store.get("test");
 ```
 
+## DynamoDB Store
+
+```typescript
+import { initClient } from "@jaypie/dynamodb";
+import { createSkillService } from "@jaypie/tildeskill";
+import { createDynamoDbStore } from "@jaypie/tildeskill/dynamodb";
+
+initClient();
+const store = createDynamoDbStore({ category: "jaypie" });
+const skillService = createSkillService(store);
+```
+
+`@jaypie/dynamodb` is an optional peer dependency. Only the
+`@jaypie/tildeskill/dynamodb` subpath imports it, so markdown-only consumers
+never load it. The store loads it with a dynamic import on first use, so a
+CJS consumer shares the host's initialized client. Call `initClient()` before
+using the store.
+
+- Records are `skill` entities at APEX scope. `category` is the store
+  namespace; `alias` is unqualified.
+- Ids are deterministic: `uuidv5("<category>:<alias>", SKILL_NAMESPACE)`.
+  `SKILL_NAMESPACE` is exported from the subpath and never changes.
+- `metadata.hash` holds `hashSkill(record)` (sha256) for change detection.
+- `includes`, `nicknames`, and `related` are stored in `metadata`, since
+  `related` is reserved for entity references.
+- `list`, `getByNickname`, and `search` query `indexModelCategory`.
+  `createDynamoDbStore` calls `registerSkillModel()`; declare the index in CDK
+  by calling `registerSkillModel()` before `getAllRegisteredIndexes()`.
+- `find` keeps the plural/singular fallback.
+- `delete` soft deletes with `deleteEntity`. Reads skip archived and deleted
+  entities, and a later `put` restores the same id.
+
+## Syncing Stores
+
+```typescript
+import { createMarkdownStore, syncSkills } from "@jaypie/tildeskill";
+
+const result = await syncSkills({
+  from: createMarkdownStore({ path: "./skills" }),
+  to: store,
+});
+// { added: ["aws"], removed: ["retired"], unchanged: ["tests"], updated: [] }
+```
+
+`syncSkills` makes `to` match `from`. It puts records missing from `to`
+(`added`) or whose `hashSkill` differs (`updated`), skips records whose hash
+matches (`unchanged`), and deletes records missing from `from` (`removed`).
+Each list holds aliases sorted alphabetically. An empty `from` with a
+non-empty `to` throws `ConfigurationError` before writing, since a markdown
+store pointed at a missing directory lists nothing. Pass
+`allowEmptySource: true` to empty `to` on purpose.
+
+## Deleting Records
+
+Every store implements `delete(alias)`. It matches the exact alias (no
+plural/singular fallback) and returns `true` when a record was removed and
+`false` when none existed.
+
+| Store | `delete` behavior |
+|-------|-------------------|
+| memory | Removes the record from the map |
+| markdown | Removes `<alias>.md`; throws `BadRequestError` for an invalid alias |
+| layered | Requires a namespace-qualified alias and delegates to that layer; throws `ConfigurationError` when unqualified |
+| dynamodb | Soft deletes the entity; reads skip it and `put` restores it |
+
 ## Skill Service Factory
 
 ```typescript
@@ -102,6 +170,8 @@ const skillService = createSkillService(store);
 await skillService({ alias: "aws" }); // → skill content (with expandIncludes)
 await skillService({ alias: "index" }); // → formatted listing
 await skillService(); // → same as "index"
+await skillService({ alias: "missing" }); // throws NotFoundError
+await skillService({ alias: "../bad" }); // throws BadRequestError
 
 // Use with fabricTool for Llm.operate toolkits
 import { fabricTool } from "@jaypie/fabric/llm";
@@ -159,11 +229,16 @@ const layered = createLayeredStore({
 
 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.find("skills"); // exact alias in any layer, then fallback
 await layered.list(); // prefixed aliases from every layer
 await layered.put({ alias: "local:new", content: "# New" }); // must be qualified
 ```
 
+`find` checks every layer for an exact alias before it tries plural/singular
+fallback in any layer. With `local:test` and `jaypie:tests`, `find("tests")`
+returns `jaypie:tests`, so a local skill cannot shadow a Jaypie skill under a
+different spelling. Namespace-qualified aliases search only their own layer.
+
 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`). A bundled build finds the Jaypie base layer in

package/skills/variables.md

@@ -13,7 +13,7 @@ Configuration variables used in Jaypie applications.
 |----------|-------------|--------|
 | `PROJECT_ENV` | Environment identifier; scopes physical resource names | local, sandbox, kitchen, lab, studio, production |
 | `PROJECT_KEY` | Project name for logging | e.g., my-api |
-| `PROJECT_NONCE` | Unique resource suffix; scopes physical resource names | e.g., dev, staging, prod |
+| `PROJECT_NONCE` | 8 lowercase hex characters, unique per environment; scopes physical resource names | e.g., ba342b91 |
 | `PROJECT_SPONSOR` | Sponsor segment of the generated stack name and the `sponsor` tag | e.g., finlaysonstudio |
 | `PROJECT_CHAOS` | Chaos engineering mode | none, partial, full |
 | `PROJECT_SALT` | Secret salt for HMAC hashing (API keys) | Generated by JaypieEnvSecret |
@@ -23,6 +23,8 @@ Configuration variables used in Jaypie applications.
 
 `PROJECT_ENV` and `PROJECT_NONCE` together scope physical AWS resource names to avoid collisions when multiple stacks deploy to the same account. Any explicitly named resource (ECR repos, log groups, ECS task families, EventBridge rules, etc.) must include both values. See `skill("cdk")` for the full naming convention.
 
+Generate `PROJECT_NONCE` once per environment with `openssl rand -hex 4` and store it as a GitHub environment variable (see `skill("github")`). A word or branch name repeats across projects and accounts, and S3 bucket names are global.
+
 ### Stack Naming
 
 `JaypieStack` generates `cdk-{PROJECT_SPONSOR}-{PROJECT_KEY}-{PROJECT_ENV}-{PROJECT_NONCE}[-{key}]`. Every segment must be set in CI or the name contains `undefined`, and a stack name is immutable. `skill("cicd-actions")` sets all four in `setup-environment`.