@jaypie/mcp 0.8.158 → 0.8.160

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/mcp/0.8.160.md

@@ -0,0 +1,19 @@
+---
+version: 0.8.160
+date: 2026-09-15
+summary: Document forwarder invoke permissions, hardened log buckets, origin access control, WAF redaction, and JaypieMigration log props
+---
+
+## Changes
+
+- **`skill("JaypieDatadogForwarder")`** gains an "Invoke Permissions" section
+  covering token-ARN imports and the events-rule warning acknowledgement.
+- **`skill("cdk")`** gains "Origin Access Control" and "Importing a Lambda by
+  Token ARN" sections, and the WAF summary lists the new config keys.
+- **`skill("waf")`** documents the hardened log bucket, `waf.logRetention`, and
+  the merge semantics of `redactedHeaders` / `redactedFields`.
+- **`skill("web")`** gains an "Origin Access Control" section and documents
+  `logRetention` and the hardened log buckets.
+- **`skill("migrations")`** documents `logGroup`, `logRetention`, and
+  `reservedConcurrentExecutions`, including the inert-`logRetention` gap
+  deferred to 2.0 (#568) and the zero-concurrency throw.

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

@@ -72,6 +72,21 @@ const forwarderFunction = resolveDatadogForwarderFunction(this);
 
 This imports the Lambda via `Fn.importValue("account-datadog-forwarder")` and caches per scope (WeakMap), so multiple calls in the same stack return the same reference.
 
+## Invoke Permissions
+
+The forwarder ARN is always an unresolved token: a cross-stack export or a nested-stack output. `lambda.Function.fromFunctionArn` on a token ARN produces an import with an unknown environment, and `addPermission()` on such an import is a silent no-op that only emits an `UnclearLambdaEnvironment` warning. Every trigger wired to the forwarder then deploys with no invoke permission, and S3 rejects the notification configuration because it cannot validate the destination.
+
+Both import sites use `lambda.Function.fromFunctionAttributes(scope, id, { functionArn, sameEnvironment: true })`. The flag is correct here because the forwarder is always in the same account and region as its consumers.
+
+`JaypieDatadogForwarder` acknowledges `@aws-cdk/aws-events:ruleUnresolvedEnvironment` on its own `CloudFormationEventsRule`. Acknowledgements resolve by construct path, so a consumer creating a rule that targets `forwarder.forwarderFunction` sees that warning on their own rule and should acknowledge it with the same justification:
+
+```typescript
+Annotations.of(rule).acknowledgeWarning(
+  "@aws-cdk/aws-events:ruleUnresolvedEnvironment",
+  "The Datadog forwarder is always in the same account and region",
+);
+```
+
 ### For Log Subscription Filters
 
 Use `resolveDatadogLoggingDestination` to get a `LambdaDestination`:

package/skills/cdk.md

@@ -153,6 +153,8 @@ Props extend `StackProps` with one addition:
 
 If you see `undefined` or `unknown` in a generated stack name or tag, an env var is missing — fix the environment rather than overriding `stackName`.
 
+`JaypieStack` warns at synth (`@jaypie/constructs:projectNonceFormat`) when `CDK_DEFAULT_ACCOUNT` is set and `PROJECT_NONCE` is unset or is not lowercase hex of six or more characters. The warning fires before the first deploy makes a word or branch-name nonce permanent.
+
 #### `JaypieAppStack` / `JaypieInfrastructureStack`
 
 Thin convenience subclasses that pre-fill `key`:
@@ -206,12 +208,14 @@ See `skill("variables")` for the role of `PROJECT_ENV` and `PROJECT_NONCE`.
 
 ```bash
 # Deploy to sandbox
-PROJECT_ENV=sandbox PROJECT_NONCE=dev cdk deploy
+PROJECT_ENV=sandbox PROJECT_NONCE=3f9c21ab cdk deploy
 
 # Deploy to production
-PROJECT_ENV=production PROJECT_NONCE=prod cdk deploy
+PROJECT_ENV=production PROJECT_NONCE=ba342b91 cdk deploy
 ```
 
+Deploys run in CI (see `skill("cicd-deploy")`). Each environment carries its own `PROJECT_NONCE`, 8 lowercase hex characters generated once with `openssl rand -hex 4`. See `skill("github")` for provisioning.
+
 ## Lambda with DynamoDB Tables
 
 Pass tables to `JaypieLambda` for automatic permissions and environment wiring:
@@ -436,8 +440,50 @@ KnownBadInputsRuleSet, IP rate limiting, and WAF logging to S3 with Datadog
 forwarding.
 
 See **`skill("waf")`** for configuration: `rateLimitPerIp`, `webAclArn`,
-`logBucket`, `managedRuleOverrides`, `managedRuleScopeDowns`, the `allow`
-path-scoped relaxation prop, and the rule-name ↔ label casing trap.
+`logBucket`, `logRetention`, `managedRuleOverrides`, `managedRuleScopeDowns`,
+`redactedFields`, `redactedHeaders`, the `allow` path-scoped relaxation prop,
+and the rule-name ↔ label casing trap.
+
+WAF logs always redact `authorization`, `cookie`, `x-amz-content-sha256`, and
+`x-api-key`. A `redactedHeaders` list merges with that default rather than
+replacing it, so adding a header can only ever redact more.
+
+## Origin Access Control
+
+`JaypieDistribution` with an `IFunction` handler creates a Function URL with
+`authType: NONE`, so the Lambda is invokable around CloudFront and the WAF.
+`originAccessControl: true` makes CloudFront the only caller:
+
+```typescript
+new JaypieDistribution(this, "Dist", {
+  handler,
+  originAccessControl: true,
+});
+```
+
+- The Function URL becomes `AWS_IAM`, the origin becomes
+  `origins.FunctionUrlOrigin.withOriginAccessControl(...)`, and the construct
+  adds the `lambda:InvokeFunction` permission that `withOriginAccessControl`
+  omits (Lambda requires both it and `lambda:InvokeFunctionUrl`).
+- **Client requirement:** with OAC, Lambda rejects a POST or PUT unless the
+  client sends the body SHA-256 in `x-amz-content-sha256`. For a body carrying
+  low-entropy secrets, salt it with a nonce so the hash is not reversible. That
+  header is redacted from WAF logs by default.
+- The prop applies only to the `IFunction` path. A caller-supplied
+  `IFunctionUrl` or `IOrigin` owns its own auth; setting the prop there warns
+  at synth (`@jaypie/constructs:originAccessControlIgnored`).
+- `JaypieWebDeploymentBucket` has its own `originAccessControl` prop for the S3
+  case; see `skill("web")`.
+
+## Importing a Lambda by Token ARN
+
+`lambda.Function.fromFunctionArn` on an ARN that is a token (`Fn.importValue`,
+a nested-stack output) yields an import with an unresolved environment.
+`addPermission()` on it is a silent no-op that only warns
+(`UnclearLambdaEnvironment`), so every trigger deploys without invoke
+permission. Use
+`lambda.Function.fromFunctionAttributes(scope, id, { functionArn, sameEnvironment: true })`
+whenever the function is known to be in the same account and region.
 
 ## Organization Trail Security Baseline
 

package/skills/cicd-actions.md

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

package/skills/cicd-deploy.md

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

package/skills/cicd-environments.md

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

package/skills/debugging.md

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

package/skills/dynamodb.md

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

package/skills/github.md

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

package/skills/jaypie.md

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

package/skills/mcp.md

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

package/skills/migrations.md

@@ -35,7 +35,10 @@ new JaypieMigration(this, "SeedData", {
 | `dependencies` | `Construct[]` | `[]` | Constructs that must be created before the migration runs |
 | `environment` | `Record<string, string> \| (Record<string, string> \| string)[]` | - | Environment variables for the migration Lambda |
 | `handler` | `string` | `"index.handler"` | Lambda entry point |
+| `logGroup` | `logs.ILogGroup` | - | Log group for the migration Lambda; forwarded to `JaypieLambda`. Supply one to control KMS encryption and retention |
+| `logRetention` | `logs.RetentionDays \| number` | `90` days | Retention for the log group `JaypieLambda` creates. Ignored when `logGroup` is supplied |
 | `queryInterval` | `cdk.Duration` | `Duration.seconds(60)` | Polling interval between `isCompleteHandler` invocations |
+| `reservedConcurrentExecutions` | `number` | - | Reserved concurrency for the migration Lambda. `0` throws at synth; `1` leaves no headroom if onEvent overlaps a waiter poll |
 | `secrets` | `SecretsArrayItem[]` | `[]` | Secrets to make available to the Lambda |
 | `tables` | `dynamodb.ITable[]` | `[]` | DynamoDB tables to grant read/write access |
 | `timeout` | `cdk.Duration` | `Duration.minutes(15)` | Per-invocation Lambda timeout |
@@ -45,6 +48,9 @@ new JaypieMigration(this, "SeedData", {
 
 - **Timeout**: 15 minutes per invocation (Lambda max); `totalTimeout` controls the end-to-end ceiling across all polling invocations (default 2 hours)
 - **Role**: Tagged as `CDK.ROLE.PROCESSING`
+- **Logging**: `logGroup`, `logRetention`, and `reservedConcurrentExecutions` forward to the wrapped `JaypieLambda`. Pass `logGroup` when a compliance baseline requires a KMS-encrypted group or 12-month retention. The `cr.Provider` framework functions keep service-created log groups
+- **`logRetention` is inert when `logGroup` is supplied.** `JaypieLambda` resolves `logGroup ?? new logs.LogGroup(..., { retention: logRetention })`, so passing both silently drops the retention value. Set retention on the group you pass. Jaypie 2.0 will throw on that combination (#568)
+- **Concurrency**: the migration Lambda is both `onEventHandler` and `isCompleteHandler`. `reservedConcurrentExecutions: 0` blocks every invocation and throws `ConfigurationError` at synth
 - **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 `DescribeTable`, `DescribeTimeToLive`, and `DescribeContinuousBackups` scoped to the table ARN and its indexes. Migrations read and write data. They do not change table shape

package/skills/recipe-api-server.md

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

package/skills/releasenotes.md

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

package/skills/tildeskill.md

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

package/skills/variables.md

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