@jaypie/mcp 0.8.154 → 0.8.155

package/README.md

@@ -28,6 +28,22 @@ export const handler = createLambdaStreamHandler(app);
 
 `mcpHttpHandler` answers JSON or server-sent events by `Accept` header, 202 for notifications, and 405 for GET and DELETE. Pass `suite` to serve any fabric `ServiceSuite`. Lifecycle options (`secrets`, `setup`, `validate`, ...) pass through to `expressHandler`. Requires `@jaypie/express` and `@jaypie/logger` (optional peers, included in `jaypie`).
 
+### Bundling
+
+A bundler (esbuild) leaves out the markdown that `skill` and `release_notes` read. Copy it beside the bundle at build time:
+
+```typescript
+import { cpSync } from "node:fs";
+import { join } from "node:path";
+import { getMcpAssetPaths, MCP_ASSET_DIRECTORY } from "@jaypie/mcp/assets";
+
+const assets = getMcpAssetPaths();
+cpSync(assets.releaseNotes, join("dist", MCP_ASSET_DIRECTORY.RELEASE_NOTES), { recursive: true });
+cpSync(assets.skills, join("dist", MCP_ASSET_DIRECTORY.SKILLS), { recursive: true });
+```
+
+`MCP_BUILTIN_SKILLS_PATH` and `MCP_RELEASE_NOTES_PATH` point at other locations.
+
 ### Filtering Tools
 
 `createMcpServer`, `mcpExpressHandler`, and `mcpHttpHandler` accept `services`, an allowlist of tool names:

package/dist/assets.d.ts

@@ -0,0 +1,34 @@
+declare const MCP_ASSET_DIRECTORY: {
+    readonly RELEASE_NOTES: "release-notes";
+    readonly SKILLS: "skills";
+};
+interface McpAssetPaths {
+    /** Absolute path of the release notes directory read by `release_notes` */
+    releaseNotes: string;
+    /** Absolute path of the Jaypie skills directory read by `skill` */
+    skills: string;
+}
+/**
+ * Absolute paths of the markdown directories `skill` and `release_notes` read
+ * at runtime
+ *
+ * A bundler (esbuild) inlines the code but not the markdown. Copy each
+ * directory beside the bundle under its own name (`skills/`,
+ * `release-notes/`) and the docs suite finds it without configuration. Call
+ * this from a build script, never from bundled code.
+ *
+ * @example
+ * ```typescript
+ * import { cpSync } from "node:fs";
+ * import { join } from "node:path";
+ * import { getMcpAssetPaths, MCP_ASSET_DIRECTORY } from "@jaypie/mcp/assets";
+ *
+ * const assets = getMcpAssetPaths();
+ * cpSync(assets.skills, join("dist", MCP_ASSET_DIRECTORY.SKILLS), { recursive: true });
+ * cpSync(assets.releaseNotes, join("dist", MCP_ASSET_DIRECTORY.RELEASE_NOTES), { recursive: true });
+ * ```
+ */
+declare function getMcpAssetPaths(): McpAssetPaths;
+
+export { MCP_ASSET_DIRECTORY, getMcpAssetPaths };
+export type { McpAssetPaths };

package/dist/assets.js

@@ -0,0 +1,47 @@
+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
+//
+const MCP_ASSET_DIRECTORY = {
+    RELEASE_NOTES: "release-notes",
+    SKILLS: "skills",
+};
+//
+//
+// Main
+//
+/**
+ * Absolute paths of the markdown directories `skill` and `release_notes` read
+ * at runtime
+ *
+ * A bundler (esbuild) inlines the code but not the markdown. Copy each
+ * directory beside the bundle under its own name (`skills/`,
+ * `release-notes/`) and the docs suite finds it without configuration. Call
+ * this from a build script, never from bundled code.
+ *
+ * @example
+ * ```typescript
+ * import { cpSync } from "node:fs";
+ * import { join } from "node:path";
+ * import { getMcpAssetPaths, MCP_ASSET_DIRECTORY } from "@jaypie/mcp/assets";
+ *
+ * const assets = getMcpAssetPaths();
+ * cpSync(assets.skills, join("dist", MCP_ASSET_DIRECTORY.SKILLS), { recursive: true });
+ * cpSync(assets.releaseNotes, join("dist", MCP_ASSET_DIRECTORY.RELEASE_NOTES), { recursive: true });
+ * ```
+ */
+function getMcpAssetPaths() {
+    // src/assets.ts and dist/assets.js both sit one level below the package root
+    const packageRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+    return {
+        releaseNotes: path.join(packageRoot, MCP_ASSET_DIRECTORY.RELEASE_NOTES),
+        skills: path.join(packageRoot, MCP_ASSET_DIRECTORY.SKILLS),
+    };
+}
+
+export { MCP_ASSET_DIRECTORY, getMcpAssetPaths };
+//# sourceMappingURL=assets.js.map

package/dist/assets.js.map

@@ -0,0 +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;;;;"}

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

@@ -0,0 +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";

package/dist/suites/docs/help.js

@@ -0,0 +1,42 @@
+// Inlined so bundled builds (esbuild, Lambda) need no shipped file
+const RELEASE_NOTES_HELP = `# Release Notes
+
+Browse Jaypie package release notes.
+
+## Commands
+
+| Command | Description | Required Parameters |
+|---------|-------------|---------------------|
+| \`list\` | List available release notes | - |
+| \`read\` | Read a specific release note | \`package\`, \`version\` |
+
+## Options for \`list\`
+
+| Option | Description |
+|--------|-------------|
+| \`package\` | Filter by package name (e.g., "mcp", "jaypie") |
+| \`since_version\` | Only versions newer than this (e.g., "1.0.0") |
+
+## Examples
+
+\`\`\`
+release_notes("list")
+release_notes("list", { package: "mcp" })
+release_notes("list", { package: "jaypie", since_version: "2.0.0" })
+release_notes("read", { package: "mcp", version: "0.4.2" })
+\`\`\`
+
+## Available Packages
+
+Release notes are available for all Jaypie packages including:
+- \`jaypie\` - Main package
+- \`mcp\` - MCP server
+- \`fabric\` - Service handlers and adapters
+- \`llm\` - LLM provider interface
+- And more...
+
+Use \`release_notes("list")\` to see all available packages and versions.
+`;
+
+export { RELEASE_NOTES_HELP };
+//# sourceMappingURL=help.js.map

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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/suites/docs/index.js

@@ -2,26 +2,97 @@ import { BadRequestError } from '@jaypie/errors';
 import { fabricService } from '@jaypie/fabric';
 import { parseFrontmatter } from '@jaypie/kit';
 import { createMarkdownStore, createLayeredStore, createSkillService } from '@jaypie/tildeskill';
+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 { RELEASE_NOTES_HELP } from './help.js';
 
 /**
  * Docs Suite - Documentation services (skill, version, release_notes)
  */
-const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.154#f76841e4"
+const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.155#dee71f8c"
     ;
-const __filename$1 = fileURLToPath(import.meta.url);
-const __dirname$1 = path.dirname(__filename$1);
-// From dist/suites/docs/, go up 3 levels to package root where skills/ and release-notes/ live
-// 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");
+// =============================================================================
+// ASSET PATHS
+// =============================================================================
+const ENV_BUILTIN_SKILLS_PATH = "MCP_BUILTIN_SKILLS_PATH";
+const ENV_RELEASE_NOTES_PATH = "MCP_RELEASE_NOTES_PATH";
+const MARKDOWN_EXTENSION = ".md";
+const WARNING_PREFIX = "[@jaypie/mcp]";
+// A bundler (esbuild) collapses every module into one file, so this module's
+// directory is the bundle directory rather than dist/suites/docs/
+const MODULE_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ASSET_PATHS = getMcpAssetPaths();
+/**
+ * An explicit environment path wins outright. Otherwise the package copy wins,
+ * then a copy beside the bundle. Returns the package path when neither exists.
+ */
+function resolveAssetDirectory({ bundled, envPath, packaged, }) {
+    if (envPath)
+        return envPath;
+    return ([packaged, bundled].find((candidate) => existsSync(candidate)) ?? packaged);
+}
+function hasEntries({ directory, isEntry, }) {
+    try {
+        return readdirSync(directory, { withFileTypes: true }).some(isEntry);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Warn once, on first use, when an asset directory is missing or empty. Waiting
+ * for first use keeps servers that never call the service quiet.
+ */
+function createAssetCheck({ directory, envName, isEntry, name, }) {
+    let checked = false;
+    return () => {
+        if (checked)
+            return;
+        checked = true;
+        if (hasEntries({ directory, isEntry }))
+            return;
+        // stderr keeps the stdio transport's stdout clean and still reaches CloudWatch
+        // eslint-disable-next-line no-console
+        console.warn(`${WARNING_PREFIX} No ${name} found in "${directory}". Copy the ${name} directory from getMcpAssetPaths() in @jaypie/mcp/assets beside the bundle or set ${envName}.`);
+    };
+}
+/** Run `check` before any property of `target` is read */
+function withAssetCheck({ check, target, }) {
+    return new Proxy(target, {
+        get(object, property, receiver) {
+            check();
+            return Reflect.get(object, property, receiver);
+        },
+    });
+}
+const RELEASE_NOTES_PATH = resolveAssetDirectory({
+    bundled: path.join(MODULE_DIRECTORY, MCP_ASSET_DIRECTORY.RELEASE_NOTES),
+    envPath: process.env[ENV_RELEASE_NOTES_PATH],
+    packaged: PACKAGE_ASSET_PATHS.releaseNotes,
+});
 // 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");
+// relocates them without disabling the built-in layer.
+const BUILTIN_SKILLS_PATH = resolveAssetDirectory({
+    bundled: path.join(MODULE_DIRECTORY, MCP_ASSET_DIRECTORY.SKILLS),
+    envPath: process.env[ENV_BUILTIN_SKILLS_PATH],
+    packaged: PACKAGE_ASSET_PATHS.skills,
+});
+const checkReleaseNoteAssets = createAssetCheck({
+    directory: RELEASE_NOTES_PATH,
+    envName: ENV_RELEASE_NOTES_PATH,
+    isEntry: (entry) => entry.isDirectory(),
+    name: MCP_ASSET_DIRECTORY.RELEASE_NOTES,
+});
+const checkSkillAssets = createAssetCheck({
+    directory: BUILTIN_SKILLS_PATH,
+    envName: ENV_BUILTIN_SKILLS_PATH,
+    isEntry: (entry) => entry.isFile() && entry.name.endsWith(MARKDOWN_EXTENSION),
+    name: MCP_ASSET_DIRECTORY.SKILLS,
+});
 const LOCAL_SKILLS_NAMESPACE = "local";
 const JAYPIE_SKILLS_NAMESPACE = "jaypie";
 const LAYER_SEPARATOR = ":";
@@ -37,7 +108,10 @@ if (process.env.MCP_SKILLS_PATH) {
 }
 skillLayers.push({
     namespace: JAYPIE_SKILLS_NAMESPACE,
-    store: createMarkdownStore({ path: BUILTIN_SKILLS_PATH }),
+    store: withAssetCheck({
+        check: checkSkillAssets,
+        target: createMarkdownStore({ path: BUILTIN_SKILLS_PATH }),
+    }),
 });
 const skillStore = createLayeredStore({
     layers: skillLayers,
@@ -122,12 +196,6 @@ const versionService = fabricService({
     input: {},
     service: async () => BUILD_VERSION_STRING,
 });
-// =============================================================================
-// RELEASE NOTES SERVICE
-// =============================================================================
-async function getReleaseNotesHelp() {
-    return fs.readFile(path.join(__dirname$1, "release-notes", "help.md"), "utf-8");
-}
 const releaseNotesService = fabricService({
     alias: "release_notes",
     description: "Browse Jaypie package release notes. Commands: list, read. Call with no args for help.",
@@ -145,8 +213,9 @@ const releaseNotesService = fabricService({
     },
     service: async ({ command, input: params, }) => {
         if (!command || command === "help") {
-            return getReleaseNotesHelp();
+            return RELEASE_NOTES_HELP;
         }
+        checkReleaseNoteAssets();
         const p = params || {};
         switch (command) {
             case "list": {

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 * as fs from \"node:fs/promises\";\nimport * as path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\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[] = [];\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: createMarkdownStore({ path: BUILTIN_SKILLS_PATH }),\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\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 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":["__filename","__dirname"],"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 } 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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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/mcp",
-  "version": "0.8.154",
+  "version": "0.8.155",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",
@@ -16,6 +16,12 @@
         "default": "./dist/index.js"
       }
     },
+    "./assets": {
+      "import": {
+        "types": "./dist/assets.d.ts",
+        "default": "./dist/assets.js"
+      }
+    },
     "./http": {
       "import": {
         "types": "./dist/http/index.d.ts",
@@ -66,9 +72,9 @@
     "@rollup/plugin-typescript": "^12.3.0",
     "@types/express": "^5.0.3",
     "@types/semver": "^7.7.1",
+    "esbuild": "^0.28.2",
     "express": "^5.1.0",
     "rollup": "^4.53.3",
-    "rollup-plugin-copy": "^3.5.0",
     "rollup-plugin-dts": "^6.1.1",
     "typescript": "^5.9.3"
   },

package/release-notes/mcp/0.8.155.md

@@ -0,0 +1,24 @@
+---
+version: 0.8.155
+date: 2026-09-12
+summary: Bundled builds serve skills and release notes, warn when either is missing, and add @jaypie/mcp/assets
+---
+
+## Changes
+
+- **Bundled builds** find `skills/` and `release-notes/` beside the bundle when
+  the package copy is absent. `MCP_BUILTIN_SKILLS_PATH` and
+  `MCP_RELEASE_NOTES_PATH` still win when set (#543).
+- **`release_notes` help** is inlined, so a bundle no longer needs
+  `suites/docs/release-notes/help.md`.
+- **Warning** logged to stderr on the first `skill` or `release_notes` call
+  when its directory is missing or empty, naming the directory and variable.
+- **`@jaypie/mcp/assets`** exports `getMcpAssetPaths()` and
+  `MCP_ASSET_DIRECTORY` for build scripts that copy the markdown beside a
+  bundle.
+- **`mcp` skill** documents the bundling copy step; the `express` skill's
+  esbuild banner aliases its imports to avoid duplicate declarations.
+- **`github` skill** documents the repository standard: the `main` ruleset,
+  environment classes and deployment branch policies, and secrets and variables
+  layered across organization, repository, and environment scopes. Linked from
+  `cicd`, `cicd-environments`, `infrastructure`, and `skills`.

package/skills/agents.md

@@ -34,7 +34,7 @@ Complete stack styles, techniques, and traditions.
 
 Contents: index, releasenotes
 Development: apikey, documentation, errors, llm, logs, mdaml, mocks, monorepo, repokit, style, subpackages, tests, tools
-Infrastructure: apigateway, aws, cdk, cicd, datadog, dns, dynamodb, email, express, lambda, migrations, ports, secrets, sqs, streaming, variables, waf, web, websockets
+Infrastructure: apigateway, aws, cdk, cicd, datadog, dns, dynamodb, email, express, github, lambda, migrations, ports, secrets, sqs, streaming, variables, waf, web, websockets
 Patterns: api, fabric, handlers, models, repository, services, vocabulary
 Recipes: recipe-api-server
 Meta: issues, jaypie, mcp, skills

package/skills/cicd-environments.md

@@ -1,6 +1,6 @@
 ---
 description: GitHub Environments configuration for CDK deployments
-related: cicd, cicd-actions, cicd-deploy, variables
+related: cicd, cicd-actions, cicd-deploy, github, variables
 ---
 
 # GitHub Environments Configuration

package/skills/cicd.md

@@ -1,6 +1,6 @@
 ---
 description: GitHub Actions CI/CD workflows
-related: cicd-actions, cicd-deploy, cicd-environments, cdk, tests
+related: cicd-actions, cicd-deploy, cicd-environments, cdk, github, tests
 ---
 
 # CI/CD with GitHub Actions
@@ -14,6 +14,7 @@ Jaypie projects use GitHub Actions for continuous integration and deployment.
 | `cicd-actions` | Reusable composite actions for workflows |
 | `cicd-deploy` | CDK deployment workflows (sandbox, production) |
 | `cicd-environments` | GitHub Environments configuration |
+| `github` | Repository rulesets, environments, and secret and variable scopes |
 
 ## Action Versions
 

package/skills/express.md

@@ -337,12 +337,12 @@ await build({
     ...builtinModules.map(m => `node:${m}`),
   ],
   banner: {
-    js: `import { createRequire } from "module";
-import { fileURLToPath } from "url";
-import { dirname } from "path";
-const require = createRequire(import.meta.url);
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);`,
+    js: `import { createRequire as __bannerCreateRequire } from "node:module";
+import { fileURLToPath as __bannerFileURLToPath } from "node:url";
+import { dirname as __bannerDirname } from "node:path";
+const require = __bannerCreateRequire(import.meta.url);
+const __filename = __bannerFileURLToPath(import.meta.url);
+const __dirname = __bannerDirname(__filename);`,
   },
 });
 ```
@@ -365,6 +365,8 @@ Node.js always treats `.mjs` files as ESM, regardless of `package.json`. No need
 
 Some dependencies use `require()` even when bundled. The banner provides CommonJS shims for `require`, `__filename`, and `__dirname`.
 
+Alias every banner import. esbuild hoists bundled imports such as `import { fileURLToPath } from "node:url"` into the same top-level scope as the banner, and a shared name fails at load with `Identifier 'fileURLToPath' has already been declared`.
+
 ### CDK Integration
 
 Reference the `.mjs` file in your CDK stack:

package/skills/github.md

@@ -0,0 +1,280 @@
+---
+description: GitHub repository standard for branch rulesets, environments, and layered secrets and variables
+related: cicd, cicd-actions, cicd-deploy, cicd-environments, secrets, variables
+---
+
+# GitHub Repository Standard
+
+Configuration for a Jaypie repository on GitHub. Values are layered in three scopes:
+
+| Scope | Holds |
+|-------|-------|
+| Organization | Values shared by every repository: region, sponsor, log levels, per-account AWS references, CI credentials, shared integrations |
+| Repository | Project identity and defaults for the lower environments |
+| Environment | Per-environment deployment targets and overrides, most heavily in production-class environments |
+
+Resolution order for `vars.*` and `secrets.*` is **environment → repository → organization**. A name defined at a narrower scope shadows the broader one for any job that targets that environment. Jobs with no `environment:` resolve repository, then organization.
+
+## Repository Settings
+
+| Setting | Value |
+|---------|-------|
+| Default branch | `main` |
+| Merge methods | merge, squash, and rebase allowed |
+| Delete branch on merge | off |
+| Auto-merge | off |
+| Allowed actions | all |
+
+## Branch Protection
+
+Protect `main` with a repository ruleset named `main`.
+
+| Field | Value |
+|-------|-------|
+| Target | `branch` |
+| Enforcement | `active` |
+| Include | `~DEFAULT_BRANCH`, `refs/heads/main` |
+| Bypass actors | Organization admins and the repository admin role (`RepositoryRole` 5), or a development team, `always` |
+
+| Rule | Setting |
+|------|---------|
+| `deletion` | blocked |
+| `non_fast_forward` | blocked |
+| `pull_request` | required; stale reviews dismissed on push; extra approval for unattributed changes |
+| `required_status_checks` | job names from the check workflow; strict (branch up to date) |
+
+Required status check contexts are the `name:` of jobs in the check workflow. Matrix jobs append the matrix value (`Test (24)`).
+
+```json
+{
+  "name": "main",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": { "include": ["~DEFAULT_BRANCH", "refs/heads/main"], "exclude": [] }
+  },
+  "bypass_actors": [
+    { "actor_id": null, "actor_type": "OrganizationAdmin", "bypass_mode": "always" },
+    { "actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "always" }
+  ],
+  "rules": [
+    { "type": "deletion" },
+    { "type": "non_fast_forward" },
+    {
+      "type": "pull_request",
+      "parameters": {
+        "allowed_merge_methods": ["merge", "squash", "rebase"],
+        "dismiss_stale_reviews_on_push": true,
+        "require_code_owner_review": false,
+        "require_extra_approval_for_unattributed_changes": true,
+        "require_last_push_approval": false,
+        "required_approving_review_count": 0,
+        "required_review_thread_resolution": false
+      }
+    },
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "do_not_enforce_on_create": false,
+        "strict_required_status_checks_policy": true,
+        "required_status_checks": [
+          { "context": "Lint", "integration_id": 15368 },
+          { "context": "Typecheck", "integration_id": 15368 },
+          { "context": "Test (24)", "integration_id": 15368 }
+        ]
+      }
+    }
+  ]
+}
+```
+
+`integration_id` 15368 is GitHub Actions.
+
+```bash
+gh api repos/<org>/<repo>/rulesets --method POST --input ruleset.json
+gh api repos/<org>/<repo>/rules/branches/main   # effective rules, including org rulesets
+```
+
+## Environments
+
+Environment names are lowercase and match `PROJECT_ENV`.
+
+| Environment | Class | Protection | Deployment refs |
+|-------------|-------|------------|-----------------|
+| `sandbox` | lower | none | any branch or tag |
+| `development` | lower | none | any branch or tag |
+| `test` | production-class | branch policy | custom |
+| `demo` | production-class | branch policy | `branch/*`, `feat/*`, `fix/*`, `main`; tags `demo-*`, `v0.*`, `v1.*` |
+| `production` | production-class | branch policy | `main`; tags `production-*`, `v0.*`, `v1.*.*` |
+
+Production may instead use the "protected branches only" policy (`protected_branches: true`), which admits `main` through its ruleset.
+
+```bash
+# Custom deployment policy
+gh api repos/<org>/<repo>/environments/production --method PUT \
+  -F "deployment_branch_policy[protected_branches]=false" \
+  -F "deployment_branch_policy[custom_branch_policies]=true"
+gh api repos/<org>/<repo>/environments/production/deployment-branch-policies \
+  --method POST -f name=main -f type=branch
+gh api repos/<org>/<repo>/environments/production/deployment-branch-policies \
+  --method POST -f name='production-*' -f type=tag
+```
+
+## Organization
+
+Values every repository can assume.
+
+### Variables
+
+| Variable | Example | Purpose |
+|----------|---------|---------|
+| `AWS_REGION` | `us-east-1` | Deployment region |
+| `LOG_LEVEL` | `trace` | Application log level default |
+| `MODULE_LOG_LEVEL` | `warn` | Dependency log level default |
+| `PROJECT_SPONSOR` | `<org>` | Sponsor segment of stack names |
+| `ACCOUNT_AWS_ROLE_ARN` | sandbox account role | Default account deploy role |
+| `ACCOUNT_DATADOG_API_KEY_ARN` | sandbox account secret | Default account Datadog key secret |
+| `ACCOUNT_<ENV>_AWS_ROLE_ARN` | per-account role | Deploy role for the account hosting `<ENV>` |
+| `ACCOUNT_<ENV>_DATADOG_API_KEY_ARN` | per-account secret | Datadog key secret in the account hosting `<ENV>` |
+| `ACCOUNT_<ENV>_<SERVICE>_*` | `ACCOUNT_DEVELOPMENT_AUTH0_DOMAIN` | Other per-account references |
+| Shared public identifiers | `HUBSPOT_PORTAL_ID`, `SLACK_TEAM_ID`, `CLOUDFLARE_TURNSTILE_SITE` | Integrations common to the organization |
+
+`ACCOUNT_*` variables are the organization record of each AWS account. `<ENV>` is `SANDBOX`, `DEVELOPMENT`, `TEST`, `DEMO`, or `PRODUCTION`; environments sharing an account carry the same values. Unprefixed `ACCOUNT_*` values point at the sandbox account.
+
+### Secrets
+
+| Secret | Purpose |
+|--------|---------|
+| `CICD_<PROVIDER>_API_KEY` | LLM provider keys for CI test jobs (`CICD_ANTHROPIC_API_KEY`, `CICD_OPENAI_API_KEY`, ...) |
+| `DATADOG_CICD_API_KEY`, `DATADOG_CICD_APP_KEY` | Datadog CI visibility |
+| `NPM_TOKEN` | Private package install |
+| `SLACK_WEBHOOK_<CHANNEL>` | Notification channels (`SLACK_WEBHOOK_NONPRODUCTION_DEPLOYMENT`, `SLACK_WEBHOOK_PRODUCTION_DEPLOYMENT`) |
+| Shared service credentials | Licenses and tokens used across repositories (`NUXT_UI_PRO_LICENSE`, `POSTMAN_API_KEY`, `SLACK_BOT_TOKEN`) |
+
+The `CICD_` prefix separates keys consumed by CI from runtime keys deployed into applications (`ANTHROPIC_API_KEY`).
+
+## Repository
+
+Project identity and the defaults that lower environments inherit.
+
+### Variables
+
+| Variable | Example | Purpose |
+|----------|---------|---------|
+| `PROJECT_KEY` | `mockpay` | Project identifier |
+| `PROJECT_SERVICE` | `mockpay` | Service identifier |
+| `AWS_HOSTED_ZONE` | `example.com` | Apex zone |
+| `AWS_SUBDOMAIN` | `evaluations` | Subdomain within the zone |
+| Lower-environment service config | `AUTH0_CLIENT_ID`, `AUTH0_DOMAIN` | Development tenant used unless an environment overrides |
+| Public client identifiers | `DATADOG_APPLICATION_ID`, `DATADOG_CLIENT_TOKEN`, Turnstile site keys | Browser-exposed values |
+| Feature flags | `LLM_EXCHANGE_ENABLED` | Project-wide toggles |
+
+A repository variable may shadow an organization default for the whole project (`MODULE_LOG_LEVEL`).
+
+### Secrets
+
+| Secret | Purpose |
+|--------|---------|
+| Lower-environment service secrets | `AUTH0_CLIENT_SECRET` for the development tenant |
+| Project integration credentials | Third-party keys specific to the project |
+
+## Environment
+
+Deployment targets live on every environment. Overrides concentrate on production-class environments.
+
+### Variables on Every Environment
+
+| Variable | Example | Purpose |
+|----------|---------|---------|
+| `AWS_ROLE_ARN` | `ACCOUNT_<ENV>_AWS_ROLE_ARN` value | OIDC deploy role |
+| `DATADOG_API_KEY_ARN` | `ACCOUNT_<ENV>_DATADOG_API_KEY_ARN` value | Datadog key secret in the target account |
+| `PROJECT_ENV` | `production` | Environment identifier; matches the environment name |
+| `PROJECT_NONCE` | `ba342b91` | 8 hex characters, unique per environment |
+
+Workflows may also read `vars.ACCOUNT_<ENV>_AWS_ROLE_ARN` from the organization directly in a workflow-level `env:` block, one workflow per environment.
+
+### Overrides
+
+| Override | Scope | Example |
+|----------|-------|---------|
+| Service tenant | production-class | `AUTH0_CLIENT_ID`, `AUTH0_DOMAIN`, `AUTH0_CLIENT_SECRET` for the production tenant |
+| Hosted zone | per environment | `AWS_HOSTED_ZONE` = `sandbox.example.com` |
+| Runtime keys | production | `ANTHROPIC_API_KEY` shadowing the repository key |
+| Environment-only resources | per environment | Additional role ARNs, bastion IDs, vendor endpoints |
+
+## Values in Secrets or Variables
+
+| Kind | Scope type |
+|------|------------|
+| Credentials, signing keys, private keys | secret |
+| AWS ARNs, including Secrets Manager ARNs | variable |
+| Public client identifiers (Auth0 client ID, Datadog RUM client token, Turnstile site key) | variable |
+| Secret material the application reads at runtime | AWS Secrets Manager, referenced by a `*_ARN` variable |
+
+## Workflows
+
+### Environment Selection
+
+| Pattern | Shape |
+|---------|-------|
+| One workflow per environment | `deploy-env-<env>.yml` with literal `environment: <env>` |
+| Reusable deploy | `deploy.yml` on `workflow_call` with `environment: ${{ inputs.environment }}`; callers pass `secrets: inherit` |
+| Manual | `workflow_dispatch` with a `choice` input listing environments |
+
+### Triggers
+
+| Environment | Branches | Tags |
+|-------------|----------|------|
+| `sandbox` | `branch/*`, `claude/*`, `feat/*`, `fix/*`, `sandbox/*` | `sandbox-*` |
+| `development` | `main`, `development/*` | `development-*` |
+| `production` | `main` | `production-*` |
+
+Deploy workflows set `concurrency: deploy-env-<env>` with `cancel-in-progress: false`. Production deploy jobs declare `needs: [lint, test]`.
+
+### Deploy Job
+
+```yaml
+jobs:
+  deploy:
+    environment: production
+    permissions:
+      contents: read
+      id-token: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: ./.github/actions/setup-environment
+        with:
+          aws-region: ${{ vars.AWS_REGION }}
+          hosted-zone: ${{ vars.AWS_HOSTED_ZONE }}
+          log-level: ${{ vars.LOG_LEVEL }}
+          module-log-level: ${{ vars.MODULE_LOG_LEVEL }}
+          project-env: ${{ vars.PROJECT_ENV }}
+          project-key: ${{ vars.PROJECT_KEY }}
+          project-nonce: ${{ vars.PROJECT_NONCE }}
+          project-sponsor: ${{ vars.PROJECT_SPONSOR }}
+      - uses: ./.github/actions/configure-aws
+        with:
+          aws-region: ${{ vars.AWS_REGION }}
+          role-arn: ${{ vars.AWS_ROLE_ARN }}
+```
+
+- 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
+- The OIDC subject for an environment job is `repo:<org>/<repo>:environment:<env>` (see ~cicd-environments for the trust policy)
+
+## Audit
+
+```bash
+gh api repos/<org>/<repo>/rulesets
+gh api repos/<org>/<repo>/environments --jq '.environments[]|{name,protection_rules,deployment_branch_policy}'
+gh api repos/<org>/<repo>/environments/<env>/deployment-branch-policies
+gh api repos/<org>/<repo>/actions/variables
+gh api repos/<org>/<repo>/actions/secrets
+gh api repos/<org>/<repo>/environments/<env>/variables
+gh api repos/<org>/<repo>/environments/<env>/secrets
+gh api "repos/<org>/<repo>/actions/organization-variables?per_page=100"
+gh api "repos/<org>/<repo>/actions/organization-secrets?per_page=100"
+```
+
+Organization-scoped listings (`orgs/<org>/actions/*`, `orgs/<org>/rulesets`) require the `admin:org` token scope. The `repos/.../organization-*` endpoints list what the repository can read without it and paginate at 10.

package/skills/infrastructure.md

@@ -1,6 +1,6 @@
 ---
 description: AWS, CDK, CI/CD, and observability
-related: aws, cdk, cicd, cicd-actions, cicd-deploy, cicd-environments, datadog, dns, dynamodb, email, secrets, variables, web, websockets
+related: aws, cdk, cicd, cicd-actions, cicd-deploy, cicd-environments, datadog, dns, dynamodb, email, github, secrets, variables, web, websockets
 ---
 
 # Infrastructure
@@ -21,6 +21,7 @@ Cloud infrastructure and deployment patterns.
 | `dns` | DNS and domain configuration |
 | `dynamodb` | DynamoDB patterns and queries |
 | `email` | SES inbound email receiving |
+| `github` | GitHub rulesets, environments, and layered secrets and variables |
 | `migrations` | DynamoDB migration custom resources |
 | `secrets` | AWS Secrets Manager |
 | `variables` | Environment variables reference |

package/skills/mcp.md

@@ -104,6 +104,36 @@ Methods: `initialize` (echoes a supported `protocolVersion`, else `2025-06-18`),
 - The endpoint is stateless: no sessions, no `Mcp-Session-Id`, no server-initiated GET stream. Every POST stands alone, which suits Lambda.
 - Put authentication in `setup` or `validate` so it runs for both JSON and SSE requests.
 
+#### Bundling
+
+A bundler (esbuild) inlines the code but not the markdown that `skill` and `release_notes` read. Without that markdown, `skill("index")` answers only its heading, and the first `skill` or `release_notes` call logs a `[@jaypie/mcp]` warning to stderr naming the missing directory.
+
+Copy both directories beside the bundle at build time. `getMcpAssetPaths` from `@jaypie/mcp/assets` returns their absolute paths in the installed package and loads nothing else.
+
+```javascript
+// esbuild.config.mjs (build options from skill("express"))
+import { cpSync } from "node:fs";
+import { join } from "node:path";
+import { build } from "esbuild";
+import { getMcpAssetPaths, MCP_ASSET_DIRECTORY } from "@jaypie/mcp/assets";
+
+const OUT_DIR = "dist";
+
+await build({ bundle: true, format: "esm", outfile: join(OUT_DIR, "index.mjs"), platform: "node" });
+
+const assets = getMcpAssetPaths();
+cpSync(assets.releaseNotes, join(OUT_DIR, MCP_ASSET_DIRECTORY.RELEASE_NOTES), { recursive: true });
+cpSync(assets.skills, join(OUT_DIR, MCP_ASSET_DIRECTORY.SKILLS), { recursive: true });
+```
+
+Each directory resolves to the first match: its environment variable, the installed package, then the directory beside the bundle.
+
+| Variable | Description |
+|----------|-------------|
+| `MCP_BUILTIN_SKILLS_PATH` | Jaypie skills directory (namespace `jaypie`) |
+| `MCP_RELEASE_NOTES_PATH` | Release notes directory |
+| `MCP_SKILLS_PATH` | Client skills directory layered over the Jaypie skills (namespace `local`) |
+
 ### 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/skills.md

@@ -17,7 +17,7 @@ Look up skills by alias: `mcp__jaypie__skill(alias)`
 |----------|--------|
 | contents | index, releasenotes |
 | development | apikey, documentation, errors, llm, logs, mdaml, mocks, monorepo, repokit, style, subpackages, tests, tools |
-| infrastructure | apigateway, aws, cdk, cicd, datadog, dns, dynamodb, email, express, lambda, migrations, ports, secrets, sqs, streaming, variables, waf, web, websockets |
+| infrastructure | apigateway, aws, cdk, cicd, datadog, dns, dynamodb, email, express, github, lambda, migrations, ports, secrets, sqs, streaming, variables, waf, web, websockets |
 | patterns | api, fabric, handlers, models, repository, services, vocabulary |
 | recipes | recipe-api-server |
 | meta | issues, jaypie, mcp, skills |

package/skills/streaming.md

@@ -14,7 +14,7 @@ Jaypie provides response streaming for real-time data delivery. Three handler pa
 | `lambdaStreamHandler` | `@jaypie/lambda` | Pure Lambda Function URL streaming |
 | `expressStreamHandler` | `@jaypie/express` | Express routes with SSE |
 | `createLambdaStreamHandler` | `@jaypie/express` | Express app on Lambda with streaming |
-| `mcpHttpHandler` | `@jaypie/mcp/http` | MCP streamable HTTP (JSON or SSE) over a `ServiceSuite`; see `skill("mcp")` |
+| `mcpHttpHandler` | `@jaypie/mcp/http` | MCP streamable HTTP (JSON or SSE) over a `ServiceSuite`; bundles copy the skill and release note markdown, see `skill("mcp")` |
 
 ## Stream Formats
 

package/skills/tildeskill.md

@@ -166,8 +166,9 @@ await layered.put({ alias: "local:new", content: "# New" }); // must be qualifie
 
 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.
+skills (namespace `jaypie`). A bundled build finds the Jaypie base layer in
+`skills/` beside the bundle, or at `MCP_BUILTIN_SKILLS_PATH`; see
+`skill("mcp")` for the copy step.
 
 ## Plural/Singular Fallback
 

package/dist/suites/docs/release-notes/help.md

@@ -1,37 +0,0 @@
-# Release Notes
-
-Browse Jaypie package release notes.
-
-## Commands
-
-| Command | Description | Required Parameters |
-|---------|-------------|---------------------|
-| `list` | List available release notes | - |
-| `read` | Read a specific release note | `package`, `version` |
-
-## Options for `list`
-
-| Option | Description |
-|--------|-------------|
-| `package` | Filter by package name (e.g., "mcp", "jaypie") |
-| `since_version` | Only versions newer than this (e.g., "1.0.0") |
-
-## Examples
-
-```
-release_notes("list")
-release_notes("list", { package: "mcp" })
-release_notes("list", { package: "jaypie", since_version: "2.0.0" })
-release_notes("read", { package: "mcp", version: "0.4.2" })
-```
-
-## Available Packages
-
-Release notes are available for all Jaypie packages including:
-- `jaypie` - Main package
-- `mcp` - MCP server
-- `fabric` - Service handlers and adapters
-- `llm` - LLM provider interface
-- And more...
-
-Use `release_notes("list")` to see all available packages and versions.