@jaypie/mcp 0.8.157 → 0.8.159

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

@@ -131,7 +131,7 @@ workspaces/
    `cdk-{PROJECT_SPONSOR}-{PROJECT_KEY}-{PROJECT_ENV}-{PROJECT_NONCE}[-{key}]`,
    so naming stays consistent across sandbox, personal, and production deploys.
 2. **Account & region** resolved from `CDK_DEFAULT_ACCOUNT` / `CDK_DEFAULT_REGION` (overridable via `env`).
-3. **Standard tags** applied to the stack and propagated to every taggable child resource: `env`, `project`, `sponsor`, `nonce`, `commit`, `buildHex`, `buildDate`, `buildTime`, `version`, `service`, `creation`, `role`, `stack`. Per-build tags (`buildDate`, `buildHex`, `buildTime`, `commit`, `version`, and `JaypieInfrastructureStack`'s `stackSha`) skip `AWS::DynamoDB::GlobalTable` and `AWS::DynamoDB::Table` so tables stay unchanged across deploys (see `skill("migrations")`).
+3. **Standard tags** applied to the stack and propagated to every taggable child resource: `env`, `project`, `sponsor`, `nonce`, `commit`, `buildHex`, `buildDate`, `buildTime`, `version`, `service`, `creation`, `role`, `stack`. Per-build tags update every table on every deploy, so a table must declare its indexes in CDK (see `skill("dynamodb")`).
 
 ```typescript
 import { Construct } from "constructs";
@@ -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:
@@ -235,7 +239,7 @@ const handler = new JaypieLambda(this, "ApiHandler", {
 | 1 table | `grantReadWriteData()` plus `Query`/`Scan` on `index/*` | `DYNAMODB_TABLE_NAME` set automatically |
 | 2+ tables | `grantReadWriteData()` plus `Query`/`Scan` on `index/*` for each | No auto env var — set `CDK_ENV_TABLE` manually |
 
-CDK grants index ARNs only for indexes declared in CDK. The explicit `index/*` grant covers GSIs created by migrations (`UpdateTable`) and indexes on imported tables.
+The explicit `index/*` grant also covers indexes on imported tables, which CDK does not know about.
 
 Single table example — at runtime, use `process.env.DYNAMODB_TABLE_NAME`:
 

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

@@ -270,9 +270,9 @@ const { items: chats } = await queryByScope({ model: "chat", scope: APEX });
 
 GSIs are defined using `fabricIndex()` from `@jaypie/fabric`. **Do not create all GSIs upfront** — start with zero and add only what your access patterns require. The most common first GSI is `indexModel` for listing entities by model.
 
-**Important:** DynamoDB allows only **one GSI to be added per deployment**. If you need multiple GSIs, add them sequentially across separate deploys. For production tables, the AWS CLI is often better suited for adding GSIs than CDK (which may try to replace the table).
+**Indexes belong in CDK.** Declare every registered `fabricIndex()` in `JaypieDynamoDb` `indexes` (see [Share Indexes Between CDK and Runtime](#share-indexes-between-cdk-and-runtime)). A new table is created with all declared GSIs in one deploy. DynamoDB adds only **one GSI per update** to an existing table, so add indexes to a deployed table one per deploy.
 
-**Grants:** CDK adds `${tableArn}/index/*` to grants only for indexes declared in CDK. GSIs created by migrations or the CLI are invisible to CDK, so a role needs `Query` and `Scan` on the index ARN explicitly. `JaypieLambda` and `JaypieMigration` grant this for every table in `tables`; hand-rolled roles must add it.
+**Grants:** `JaypieLambda` and `JaypieMigration` grant `Query` and `Scan` on `${tableArn}/index/*` for every table in `tables`, which also covers indexes on imported tables. Hand-rolled roles must add it.
 
 All GSIs use a composite sort key of `scope#updatedAt` (stored as `{indexName}Sk`). Queries use `begins_with` on the sk to filter by scope; omitting scope lists across all scopes.
 
@@ -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.
@@ -474,27 +478,75 @@ const table = new JaypieDynamoDb(this, "myApp", {
 
 Wire tables to Lambda using the `tables` prop — see `skill("cdk")` for details.
 
-### Keep Table Properties Stable
+### Share Indexes Between CDK and Runtime
+
+The model registry is the single source of indexes. Register models in a module that both the CDK workspace and the runtime import, then pass the registry to the construct:
+
+```typescript
+// packages/models/src/index.ts
+import { fabricIndex, registerModel } from "@jaypie/fabric";
+
+registerModel({ model: "record", indexes: [fabricIndex(), fabricIndex("alias")] });
+registerModel({ model: "session", indexes: [fabricIndex()], ttl: "30 days" });
+```
 
-Once a migration creates a GSI through `UpdateTable`, every CloudFormation update to the table fails:
+```typescript
+// workspaces/cdk/lib/data-stack.ts
+import "@project/models"; // registers models
+import { JaypieDynamoDb } from "@jaypie/constructs";
+import { getAllRegisteredIndexes } from "@jaypie/fabric";
+
+const table = new JaypieDynamoDb(this, "myApp", {
+  indexes: getAllRegisteredIndexes(),
+});
+```
+
+`JaypieDynamoDb` sorts indexes by name, so import order does not change the template. The registry is module state: the CDK workspace and the models module must resolve the same `@jaypie/fabric` copy, or `getAllRegisteredIndexes()` returns an empty list.
+
+### Indexes Created Outside CDK
+
+A GSI created through `UpdateTable` (a migration, the console, or the CLI) blocks every later CloudFormation update to the table:
 
 ```
 Invalid AttributeDefinitions Expected the following attributes to be present: [indexModel, ...]
 ```
 
-CloudFormation sends only the key attributes the template declares, and DynamoDB rejects a request that omits attributes existing indexes reference. Table properties, tags included, must stay the same across deploys. Jaypie keeps per-build tags (`buildDate`, `buildHex`, `buildTime`, `commit`, `version`, `stackSha`) off `AWS::DynamoDB::GlobalTable` and `AWS::DynamoDB::Table` for this reason. Change a migration-owned table through migrations, or declare its indexes in CDK.
+CloudFormation sends only the attributes the template declares, and DynamoDB rejects a request that omits attributes an existing index references. Tag, TTL, point-in-time recovery, and billing changes all fail. `JaypieMigration` grants no `UpdateTable` for this reason.
+
+CloudFormation cannot adopt an existing GSI. Recover by declaring the indexes in `JaypieDynamoDb` and recreating the table. Outside production, delete and redeploy the stack. In production, deploy a new CDK-declared table beside the old one, copy items with `scanTable` and `updateEntity` (see [Migration: v0.4.x to v0.5.0](#migration-v04x-to-v050)), and switch `tables` to the new table.
 
 ## Local Development
 
 Use docker-compose for local DynamoDB. The `@jaypie/dynamodb` MCP tool can generate a `docker-compose.yml` with custom ports.
 
+`createTable()` builds the table with every registered GSI, the same indexes CDK declares. Import the models module, create the table, then run the seed the deployed migration runs (see `skill("migrations")`):
+
+```typescript
+// scripts/dynamo-create-table.ts
+import "@project/models"; // registers models
+import { createTable, initClient } from "@jaypie/dynamodb";
+
+import { seed } from "../packages/api/src/migrations/seed/seed.js";
+
+initClient({
+  credentials: { accessKeyId: "local", secretAccessKey: "local" },
+  endpoint: "http://127.0.0.1:9060",
+  tableName: "jaypie-local",
+});
+
+await createTable();
+await seed();
+```
+
+`createTable()` leaves an existing table unchanged and adds no indexes to it. After registering a new index, run `npm run dynamo:remove && npm run dynamo:init` to rebuild the local table.
+
 ### Suggested package.json Scripts
 
 ```json
 {
   "scripts": {
     "dynamo:init": "docker compose up -d && npm run dynamo:create-table",
-    "dynamo:create-table": "AWS_ACCESS_KEY_ID=local AWS_SECRET_ACCESS_KEY=local aws dynamodb create-table --table-name jaypie-local --attribute-definitions AttributeName=id,AttributeType=S --key-schema AttributeName=id,KeyType=HASH --billing-mode PAY_PER_REQUEST --endpoint-url http://127.0.0.1:9060 2>/dev/null || true",
+    "dynamo:create-table": "tsx scripts/dynamo-create-table.ts",
     "dynamo:remove": "docker compose down -v",
     "dynamo:start": "docker compose up -d",
     "dynamo:stop": "docker compose down"

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/migrations.md

@@ -47,26 +47,38 @@ new JaypieMigration(this, "SeedData", {
 - **Role**: Tagged as `CDK.ROLE.PROCESSING`
 - **Execution**: Uses `cr.Provider` with both `onEventHandler` and `isCompleteHandler` pointing to the same Lambda. The `onEventHandler` returns `PhysicalResourceId` immediately; the migration code runs in `isCompleteHandler` invocations, which are polled by Step Functions until `IsComplete: true`. `Delete` requests skip the migration entirely.
 - **Dependencies**: Use `dependencies` to ensure tables and other resources exist before the migration executes
-- **Permissions**: Tables passed via `tables` get data-plane (`grantReadWriteData`), `Query` and `Scan` on `${tableArn}/index/*`, plus control-plane access (`DescribeTable`, `UpdateTable`, `UpdateTimeToLive`, `UpdateContinuousBackups`) scoped to the table ARN and its indexes — migrations that add GSIs, toggle TTL, or change backups work without extra IAM, and later migrations can query the GSIs earlier ones created
-- **Migration-owned indexes**: after a migration creates a GSI, any CloudFormation update to the table fails with `Invalid AttributeDefinitions`. Keep table props and tags stable across deploys; per-build tags already skip tables (see `skill("dynamodb")`). Stacks deployed before `@jaypie/constructs` 1.2.85 carry build tags on the table, and removing them is itself a failing table update: recover by recreating the table or declaring its indexes in CDK
+- **Permissions**: Tables passed via `tables` get data-plane (`grantReadWriteData`), `Query` and `Scan` on `${tableArn}/index/*`, plus `DescribeTable`, `DescribeTimeToLive`, and `DescribeContinuousBackups` scoped to the table ARN and its indexes. Migrations read and write data. They do not change table shape
+- **Indexes**: CDK owns indexes, TTL, and backups. Declare every registered `fabricIndex()` in `JaypieDynamoDb` `indexes` (see `skill("dynamodb")`). A GSI created outside CDK blocks every later CloudFormation update to the table, so `JaypieMigration` grants no `UpdateTable`. Synth warns (`@jaypie/constructs:migrationTableWithoutIndexes`) when a `JaypieDynamoDb` in `tables` declares no indexes; acknowledge it for tables that need none
 
 ## Migration Lambda Handler
 
 Use `migrationHandler` from `jaypie` so errors propagate as CFN failures and the waiter protocol is handled automatically.
 
-```typescript
-// src/migrations/seed/index.ts
-import { initClient, seedEntities, APEX } from "@jaypie/dynamodb";
-import { migrationHandler } from "jaypie";
+Keep the seed in its own module so the local table script runs the same seed (see Local Development in `skill("dynamodb")`):
 
-export const handler = migrationHandler(async (event) => {
-  await initClient();
+```typescript
+// src/migrations/seed/seed.ts
+import { APEX, seedEntities } from "@jaypie/dynamodb";
 
-  await seedEntities([
+export async function seed() {
+  return seedEntities([
     { alias: "config-main", model: "config", name: "Main Config", scope: APEX },
     { alias: "vocab-en", model: "vocabulary", name: "English", scope: APEX },
   ]);
+}
+```
 
+```typescript
+// src/migrations/seed/index.ts
+import "@project/models"; // registers models; indexEntity requires them
+import { initClient } from "@jaypie/dynamodb";
+import { migrationHandler } from "jaypie";
+
+import { seed } from "./seed.js";
+
+export const handler = migrationHandler(async () => {
+  await initClient();
+  await seed();
   return { status: "complete" };
 });
 ```

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/secrets.md

@@ -71,7 +71,7 @@ Synth fails fast whenever a declared secret source produces no secret string, so
 ```typescript
 new JaypieSecret(this, "ApiKey", { value: process.env.MISSING }); // throws ConfigurationError
 new JaypieSecret(this, "ApiKey", { envKey: "MISSING" });          // throws ConfigurationError
-new JaypieSecret(this, "Placeholder");                            // allowed: empty secret, no source declared
+new JaypieSecret(this, "Placeholder");                            // allowed: CDK generates a random value
 ```
 
 `JaypieEnvSecret` applies the same guard, except in consumer environments, where the secret is imported rather than created.
@@ -91,6 +91,8 @@ jobs:
       - run: npx cdk deploy
 ```
 
+An env-sourced value is written into the synthesized template. Copies persist in the deployed stack template, the CDK assets bucket, `cdk.out`, and `cdk diff` output. Use [External Secrets](#external-secrets) for credentials that must stay out of those places.
+
 ## Runtime: Retrieving Secrets
 
 Use `getEnvSecret` to fetch secrets in Lambda:
@@ -202,6 +204,66 @@ new JaypieEnvSecret(this, "AdminSeed", {
 
 With `excludePunctuation: true` and `includeSpace: false`, the generated value contains only base62 characters.
 
+## External Secrets
+
+`external: true` creates an empty secret (no `SecretString` or `GenerateSecretString`), so the value never enters the template, the assets bucket, `cdk.out`, or `cdk diff`. CI sets the value after deploy. `envKey` still names the runtime variable (`SECRET_ANTHROPIC_API_KEY`) but is never read at synth. Combining `external` with `value` or `generateSecretString` throws `ConfigurationError`.
+
+```typescript
+const anthropicSecret = new JaypieSecret(this, "ANTHROPIC_API_KEY", {
+  external: true,
+});
+
+new JaypieLambda(this, "Handler", {
+  code: "dist/lambda",
+  handler: "index.handler",
+  secrets: [anthropicSecret],
+});
+```
+
+The construct outputs the secret ARN with the `envKey` (or construct id) as the output description. Set the value in a step after `cdk deploy`, and keep the value out of the deploy step's environment:
+
+```yaml
+- name: Set external secrets
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+    STACK_NAME: my-stack
+  run: |
+    ARN=$(aws cloudformation describe-stacks --stack-name "$STACK_NAME" \
+      --query "Stacks[0].Outputs[?Description=='ANTHROPIC_API_KEY'].OutputValue" \
+      --output text)
+    printf '%s' "$ANTHROPIC_API_KEY" > "$RUNNER_TEMP/secret"
+    aws secretsmanager put-secret-value --secret-id "$ARN" \
+      --secret-string "file://$RUNNER_TEMP/secret" > /dev/null
+    rm -f "$RUNNER_TEMP/secret"
+```
+
+- A new external secret has no value until the step runs; `getEnvSecret` fails until then.
+- CloudFormation never writes the value, so a hand-rotated secret is not overwritten by a later deploy.
+- Switching an existing secret to `external` removes `SecretString` from the template. Run the value step in the same workflow.
+- Each `put-secret-value` creates a secret version. Compare with `get-secret-value` first to skip unchanged writes.
+- In `JaypieEnvSecret` consumer environments the secret is imported; set the value on the provider stack.
+
+### SSOSync Credentials
+
+`JaypieSsoSyncApplication` writes `googleCredentials` and `scimEndpointAccessToken` into the template and warns at synth (`@jaypie/constructs:ssoSyncLiteralCredentials`). Pass secrets instead:
+
+```typescript
+new JaypieSsoSyncApplication(this, "SsoSync", {
+  googleCredentialsSecret: new JaypieSecret(this, "SsoSyncGoogleCredentials", {
+    external: true,
+  }),
+  scimEndpointAccessTokenSecret: new JaypieSecret(this, "SsoSyncScimToken", {
+    external: true,
+  }),
+});
+```
+
+- The application deploys SSOSync as "App only". The construct creates secrets for the admin email, SCIM endpoint URL, region, and identity store ID (still read from `CDK_ENV_SSOSYNC_*`), then passes all six ARNs in `CrossStackConfig`.
+- Both secret props are required together, and neither combines with the literal props.
+- Secrets need a complete ARN: created in the stack or imported with `Secret.fromSecretCompleteArn`. SSOSync reads them with the AWS managed key.
+- Switching an existing application from "App + secrets" deletes the SAR-created `SSOSync*` secrets. Sync fails until CI writes the new secret values. Do not name new secrets `SSOSync*`.
+- SSOSync accepts secret ARNs in `us`, `us-gov`, `ap`, `ca`, `cn`, `eu`, and `sa` regions only.
+
 ## Seeds and API Keys in Workflows
 
 Seeds are secrets used to derive deterministic values (like API keys) at runtime. The generated-secret pattern is ideal for seeds because: