@jaypie/mcp 0.7.37 → 0.7.39

package/dist/suites/docs/index.js

@@ -9,7 +9,7 @@ import { gt } from 'semver';
 /**
  * Docs Suite - Documentation services (skill, version, release_notes)
  */
-const BUILD_VERSION_STRING = "@jaypie/mcp@0.7.37#b65e6395"
+const BUILD_VERSION_STRING = "@jaypie/mcp@0.7.39#e7380f8a"
     ;
 const __filename$1 = fileURLToPath(import.meta.url);
 const __dirname$1 = path.dirname(__filename$1);

package/package.json

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

package/release-notes/express/1.2.16.md

@@ -0,0 +1,17 @@
+---
+version: 1.2.16
+date: 2026-03-14
+summary: Fix setup array mutation causing duplicate execution on warm Lambda containers
+---
+
+# @jaypie/express 1.2.16
+
+## Bug Fixes
+
+- **Setup array mutation on warm containers**: `expressHandler` and `expressStreamHandler` mutated the shared `setup` array via `unshift`/`push` on every request. On warm Lambda containers, this caused `loadEnvSecrets` and other setup functions to accumulate and execute multiple times per invoke. Now builds a request-local setup array each invocation, leaving the shared array untouched.
+
+## Impact
+
+- Eliminates duplicate `loadEnvSecrets` execution per request
+- Eliminates increasing duplication over time on warm containers
+- Reduces unnecessary Secrets Manager traffic and latency

package/release-notes/jaypie/1.2.22.md

@@ -0,0 +1,12 @@
+---
+version: 1.2.22
+date: 2026-03-14
+summary: Bump @jaypie/express and @jaypie/kit for warm container and logging fixes
+---
+
+# jaypie 1.2.22
+
+## Dependencies
+
+- `@jaypie/express` 1.2.15 -> 1.2.16: Fix setup array mutation causing duplicate execution on warm Lambda containers
+- `@jaypie/kit` 1.2.4 -> 1.2.5: Use shared logger singleton so invoke tags propagate to kit lifecycle logs

package/release-notes/kit/1.2.5.md

@@ -0,0 +1,16 @@
+---
+version: 1.2.5
+date: 2026-03-14
+summary: Use shared logger singleton so invoke/shortInvoke tags propagate to kit lifecycle logs
+---
+
+# @jaypie/kit 1.2.5
+
+## Bug Fixes
+
+- **Logger invoke tags not propagating**: `@jaypie/kit` created its own logger instance via `createLogger()` instead of using the shared `@jaypie/logger` singleton. Tags like `invoke` and `shortInvoke` set by upstream adapters (e.g., `@jaypie/express`) never reached kit lifecycle logs (`[jaypie] Handler init`, `[handler] Setup`, etc.). Now uses the shared singleton so all tags propagate across packages.
+
+## Impact
+
+- Datadog queries on `@invoke:<uuid>` now include `@jaypie/kit` lifecycle logs
+- Full correlation across middleware/framework layers in a single invoke

package/release-notes/mcp/0.7.38.md

@@ -0,0 +1,19 @@
+---
+version: 0.7.38
+date: 2026-03-14
+summary: Unify skill documentation with cross-linking, recipe guides, and @jaypie/dynamodb runtime docs
+---
+
+## Changes
+
+- Expanded `dynamodb` skill with full `@jaypie/dynamodb` runtime package documentation (entity operations, GSI queries, scope hierarchy, seed/export, key builders)
+- Added GSI guidance: start with zero, add one per deploy, CLI recommended for production
+- Clarified key naming conventions: `model`/`id` (Jaypie default) vs `pk`/`sk` (generic DynamoDB)
+- Added `Lambda with DynamoDB Tables` and `Lambda with Secrets` sections to `cdk` skill
+- Documented personal environment secret consumer gotcha in `secrets` skill with `consumer: false` fix
+- Added version note for `seed` support and DynamoDB hash storage pattern to `apikey` skill
+- Added missing environment variables to `variables` skill (PROJECT_SALT, PROJECT_ADMIN_SEED, CDK_ENV_PERSONAL, DYNAMODB_TABLE_NAME, BASE_URL, PROJECT_BASE_URL)
+- Created `recipe-api-server` skill: end-to-end guide for API server with DynamoDB + API keys
+- Added `## See Also` sections to 11 skills for consistent cross-linking
+- Added category taxonomy to `index` skill
+- Added `recipes` category to skill index

package/release-notes/mcp/0.7.39.md

@@ -0,0 +1,12 @@
+---
+version: 0.7.39
+date: 2026-03-14
+summary: Add release notes for @jaypie/express 1.2.16 and jaypie 1.2.22
+---
+
+# @jaypie/mcp 0.7.39
+
+## Documentation
+
+- Added release notes for `@jaypie/express` 1.2.16 (setup array mutation fix)
+- Added release notes for `jaypie` 1.2.22 (dependency bump)

package/skills/apikey.md

@@ -1,6 +1,6 @@
 ---
 description: API key generation, validation, and hashing with Jaypie keys
-related: secrets, style, tests
+related: dynamodb, secrets, style, tests
 ---
 
 # API Keys
@@ -43,6 +43,8 @@ generateJaypieKey({ prefix: "", issuer: "jaypie" });
 
 ### With Seed
 
+> **Version note:** `seed` support requires `jaypie >= 1.2.17` / `@jaypie/kit >= 1.2.2`.
+
 Pass `seed` to derive a deterministic key from a secret. Uses HMAC-SHA256 with the `issuer` (defaulting to `"jaypie"`) as the HMAC message:
 
 ```typescript
@@ -211,3 +213,21 @@ new JaypieEnvSecret(this, "ProjectAdminSeed", {
 ```
 
 See `~secrets` for the full secrets management pattern.
+
+## DynamoDB Storage Pattern
+
+Store hashed API keys in DynamoDB for direct lookup without a GSI:
+
+```typescript
+// model = "apikey", id = hash — enables direct get-item lookup
+{ model: "apikey", id: hashJaypieKey(key), ownerId: "user_123", createdAt: "..." }
+```
+
+This uses the `JaypieDynamoDb` default key convention (`model`/`id`). See `skill("dynamodb")` for table setup and query patterns.
+
+## See Also
+
+- **`skill("cdk")`** - CDK constructs for Lambda with secrets and tables
+- **`skill("dynamodb")`** - DynamoDB key conventions and query patterns
+- **`skill("secrets")`** - Generated secrets for PROJECT_SALT and PROJECT_ADMIN_SEED
+- **`skill("recipe-api-server")`** - End-to-end guide for API server with DynamoDB + API keys

package/skills/aws.md

@@ -277,3 +277,11 @@ describe("Handler", () => {
   });
 });
 ```
+
+## See Also
+
+- **`skill("cdk")`** - CDK constructs for deploying AWS infrastructure
+- **`skill("dynamodb")`** - DynamoDB key design and query patterns
+- **`skill("lambda")`** - Lambda handler wrappers with secrets loading
+- **`skill("secrets")`** - Secret management with JaypieEnvSecret
+- **`skill("tools-aws")`** - Interactive AWS MCP tools

package/skills/cdk.md

@@ -1,6 +1,6 @@
 ---
 description: CDK constructs and deployment patterns
-related: aws, cicd, dynamodb, streaming, websockets
+related: apikey, aws, cicd, dynamodb, express, lambda, secrets, streaming, websockets
 ---
 
 # CDK Constructs
@@ -120,6 +120,79 @@ PROJECT_ENV=sandbox PROJECT_NONCE=dev cdk deploy
 PROJECT_ENV=production PROJECT_NONCE=prod cdk deploy
 ```
 
+## Lambda with DynamoDB Tables
+
+Pass tables to `JaypieLambda` for automatic permissions and environment wiring:
+
+```typescript
+import { JaypieDynamoDb, JaypieLambda } from "@jaypie/constructs";
+
+const table = new JaypieDynamoDb(this, "myApp");
+
+const handler = new JaypieLambda(this, "ApiHandler", {
+  entry: "src/handler.ts",
+  handler: "handler",
+  tables: [table],
+});
+```
+
+**Behavior:**
+
+| Tables Count | Permissions | Environment |
+|-------------|-------------|-------------|
+| 1 table | `grantReadWriteData()` | `DYNAMODB_TABLE_NAME` set automatically |
+| 2+ tables | `grantReadWriteData()` for each | No auto env var — set `CDK_ENV_TABLE` manually |
+
+Single table example — at runtime, use `process.env.DYNAMODB_TABLE_NAME`:
+
+```typescript
+const table = new JaypieDynamoDb(this, "myApp");
+new JaypieLambda(this, "Handler", {
+  tables: [table],
+  // DYNAMODB_TABLE_NAME is set automatically
+});
+```
+
+Multi-table example — set environment variables explicitly:
+
+```typescript
+const usersTable = new JaypieDynamoDb(this, "users");
+const ordersTable = new JaypieDynamoDb(this, "orders");
+
+new JaypieLambda(this, "Handler", {
+  tables: [usersTable, ordersTable],
+  environment: {
+    USERS_TABLE: usersTable.tableName,
+    ORDERS_TABLE: ordersTable.tableName,
+  },
+});
+```
+
+See `skill("dynamodb")` for table key conventions and query patterns.
+
+## Lambda with Secrets
+
+Pass secrets as strings (auto-creates `JaypieEnvSecret`) or as construct instances:
+
+```typescript
+// String shorthand — creates JaypieEnvSecret from env vars at deploy time
+new JaypieLambda(this, "Handler", {
+  secrets: ["MONGODB_URI", "ANTHROPIC_API_KEY"],
+});
+
+// Construct instances — for generated secrets or custom config
+const salt = new JaypieEnvSecret(this, "ProjectSalt", {
+  envKey: "PROJECT_SALT",
+  generateSecretString: { excludePunctuation: true, passwordLength: 64 },
+});
+
+new JaypieLambda(this, "Handler", {
+  secrets: [salt, "ANTHROPIC_API_KEY"],
+});
+```
+
+See `skill("secrets")` for the full secrets pattern including generated secrets and personal environment gotchas.
+
 ## Environment Variables
 
 Pass configuration to Lambda via environment variables:
@@ -207,5 +280,11 @@ new JaypieDistribution(this, "Dist", {
 
 ## See Also
 
+- **`skill("apikey")`** - API key generation, validation, and hashing
+- **`skill("dynamodb")`** - DynamoDB key design and query patterns
+- **`skill("express")`** - Express handler and Lambda adapter
+- **`skill("lambda")`** - Lambda handler wrappers and lifecycle
+- **`skill("secrets")`** - Secret management with JaypieEnvSecret
 - **`skill("streaming")`** - JaypieDistribution and JaypieNextJs streaming configuration
+- **`skill("variables")`** - Environment variables reference
 - **`skill("websockets")`** - JaypieWebSocket and JaypieWebSocketTable constructs

package/skills/datadog.md

@@ -192,3 +192,10 @@ describe("CheckoutService", () => {
 });
 ```
 
+## See Also
+
+- **`skill("cdk")`** - CDK Lambda construct with Datadog integration
+- **`skill("logs")`** - Logging patterns for structured observability
+- **`skill("tools-datadog")`** - Interactive Datadog MCP tools
+- **`skill("variables")`** - Datadog and environment variables reference
+

package/skills/dns.md

@@ -132,3 +132,7 @@ dig @ns-123.awsdns-45.com app.example.com
 openssl s_client -connect app.example.com:443 -servername app.example.com
 ```
 
+## See Also
+
+- **`skill("cdk")`** - CDK constructs including JaypieDistribution and JaypieNextJs
+

package/skills/dynamodb.md

@@ -1,108 +1,342 @@
 ---
-description: DynamoDB code patterns, key design, and queries
-related: aws, cdk, models, tools-dynamodb
+description: DynamoDB runtime package, key design, entity operations, and queries
+related: apikey, aws, cdk, models, tools-dynamodb
 ---
 
 # DynamoDB Patterns
 
-Best practices for DynamoDB with Jaypie applications.
+Jaypie provides `@jaypie/dynamodb` for single-table DynamoDB with entity operations, GSI-based queries, hierarchical scoping, and soft delete. Access through the main `jaypie` package or directly.
 
 ## MCP Tools
 
 For interactive DynamoDB tools (query, scan, get-item, describe-table), see **tools-dynamodb**.
 
-## Key Design
+## Key Naming Conventions
 
-### Single Table Design
+Jaypie uses two key naming patterns. Understanding when to use each avoids confusion.
 
-Use prefixed keys for multiple entity types:
+### Jaypie Default: `model` / `id`
+
+`JaypieDynamoDb` creates tables with `model` (partition key) and `id` (sort key) by default. This is the **recommended convention for new Jaypie tables** and the convention used by `@jaypie/dynamodb`:
 
 ```typescript
-// User entity
-{
-  pk: "USER#123",
-  sk: "PROFILE",
-  name: "John Doe",
-  email: "john@example.com"
-}
+const table = new JaypieDynamoDb(this, "myApp");
+// Creates table with: model (HASH), id (RANGE)
+```
 
-// User's orders
-{
-  pk: "USER#123",
-  sk: "ORDER#2024-01-15#abc",
-  total: 99.99,
-  status: "completed"
-}
+Items look like:
+
+```typescript
+{ model: "user", id: "u_abc123", name: "John", email: "john@example.com" }
+{ model: "apikey", id: "a1b2c3d4...", ownerId: "u_abc123" }
 ```
 
-### Access Patterns
+### Generic DynamoDB: `pk` / `sk`
+
+The `pk` / `sk` pattern is the standard DynamoDB convention used in broader DynamoDB literature. Jaypie uses it in local development scripts and educational examples. It's functionally equivalent — just different attribute names.
+
+### Entity Prefixing (Value Pattern)
+
+Entity prefixes like `USER#123` are a **value-level pattern** (how you structure the data stored in keys), not an attribute naming convention. You can use entity prefixes with either `model`/`id` or `pk`/`sk` attribute names.
 
-| Access Pattern | Key Condition |
-|---------------|---------------|
-| Get user profile | pk = USER#123, sk = PROFILE |
-| List user orders | pk = USER#123, sk begins_with ORDER# |
-| Get specific order | pk = USER#123, sk = ORDER#2024-01-15#abc |
+## @jaypie/dynamodb Package
 
-## Query in Code
+The runtime package provides entity operations, GSI-based queries, key builders, and client management.
 
 ```typescript
-import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
-import { QueryCommand } from "@aws-sdk/lib-dynamodb";
+import {
+  APEX,
+  initClient,
+  putEntity,
+  getEntity,
+  deleteEntity,
+  queryByScope,
+  queryByCategory,
+} from "@jaypie/dynamodb";
+```
 
-const client = new DynamoDBClient({});
+Or through the main package:
 
-const result = await client.send(new QueryCommand({
-  TableName: process.env.CDK_ENV_TABLE,
-  KeyConditionExpression: "pk = :pk AND begins_with(sk, :prefix)",
-  ExpressionAttributeValues: {
-    ":pk": "USER#123",
-    ":prefix": "ORDER#",
-  },
-  ScanIndexForward: false,  // Newest first
-  Limit: 10,
-}));
+```typescript
+import { APEX, initClient, putEntity, queryByScope } from "jaypie";
 ```
 
-## GSI Patterns
+### Client Initialization
 
-Start with zero GSIs. Add indexes only when a real access pattern requires them — GSIs cost money and can always be added later.
+Call `initClient()` once at startup. In Lambda, use the handler's `setup` option:
+
+```typescript
+import { initClient } from "@jaypie/dynamodb";
 
-### By-Status Index (example)
+// Production: uses DYNAMODB_TABLE_NAME and AWS_REGION env vars
+initClient();
+
+// Local development: explicit config
+initClient({
+  endpoint: "http://127.0.0.1:8000",
+  tableName: "jaypie-local",
+  credentials: { accessKeyId: "local", secretAccessKey: "local" },
+});
+```
+
+| Function | Description |
+|----------|-------------|
+| `initClient(config?)` | Initialize the DynamoDB client (call once) |
+| `getDocClient()` | Get the initialized Document Client |
+| `getTableName()` | Get the configured table name |
+| `isInitialized()` | Check if client is initialized |
+| `resetClient()` | Reset client state (for testing) |
+
+### Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `APEX` | `"@"` | Root-level scope marker (DynamoDB prohibits empty strings) |
+| `SEPARATOR` | `"#"` | Composite key separator |
+| `ARCHIVED_SUFFIX` | `"#archived"` | Suffix for archived entity GSI keys |
+| `DELETED_SUFFIX` | `"#deleted"` | Suffix for soft-deleted entity GSI keys |
+
+### StorableEntity Type
+
+All entities follow this shape:
 
 ```typescript
-// GSI for querying by status across all users
-{
-  pk: "USER#123",
-  sk: "ORDER#2024-01-15#abc",
-  gsi1pk: "ORDER#pending",
-  gsi1sk: "2024-01-15T10:00:00Z",
+interface StorableEntity {
+  // Primary Key
+  model: string;              // Partition key (e.g., "record", "message")
+  id: string;                 // Sort key (UUID)
+
+  // Required
+  name: string;
+  scope: string;              // APEX ("@") or "{parent.model}#{parent.id}"
+  sequence: number;           // Date.now() for chronological ordering
+
+  // Optional (trigger GSI index population when present)
+  alias?: string;             // Human-friendly slug
+  category?: string;          // Category for filtering
+  type?: string;              // Type for filtering
+  xid?: string;               // External ID for cross-system lookup
+
+  // GSI Keys (auto-populated by putEntity/updateEntity)
+  indexAlias?: string;
+  indexCategory?: string;
+  indexScope?: string;
+  indexType?: string;
+  indexXid?: string;
+
+  // Timestamps (ISO 8601)
+  createdAt: string;
+  updatedAt: string;
+  archivedAt?: string;
+  deletedAt?: string;
 }
 ```
 
-Query pending orders:
+### Entity Operations
 
 ```typescript
-const result = await client.send(new QueryCommand({
-  TableName: process.env.CDK_ENV_TABLE,
-  IndexName: "gsi1",
-  KeyConditionExpression: "gsi1pk = :status",
-  ExpressionAttributeValues: {
-    ":status": "ORDER#pending",
+import { APEX, putEntity, getEntity, updateEntity, deleteEntity, archiveEntity, destroyEntity } from "@jaypie/dynamodb";
+
+const now = new Date().toISOString();
+
+// Create entity — auto-populates GSI keys
+const record = await putEntity({
+  entity: {
+    model: "record",
+    id: crypto.randomUUID(),
+    name: "Daily Log",
+    scope: APEX,
+    sequence: Date.now(),
+    alias: "2026-01-07",
+    category: "memory",
+    createdAt: now,
+    updatedAt: now,
   },
-}));
+});
+// indexScope: "@#record" (auto-populated)
+// indexAlias: "@#record#2026-01-07" (auto-populated)
+// indexCategory: "@#record#memory" (auto-populated)
+
+// Get by primary key
+const item = await getEntity({ id: "abc-123", model: "record" });
+
+// Update — sets updatedAt, re-indexes
+await updateEntity({ entity: { ...item, name: "Updated Name" } });
+
+// Soft delete — sets deletedAt, re-indexes with #deleted suffix
+await deleteEntity({ id: "abc-123", model: "record" });
+
+// Archive — sets archivedAt, re-indexes with #archived suffix
+await archiveEntity({ id: "abc-123", model: "record" });
+
+// Hard delete — permanently removes
+await destroyEntity({ id: "abc-123", model: "record" });
+```
+
+| Function | Description |
+|----------|-------------|
+| `putEntity({ entity })` | Create or replace (auto-indexes GSI keys) |
+| `getEntity({ id, model })` | Get by primary key |
+| `updateEntity({ entity })` | Update (sets `updatedAt`, re-indexes) |
+| `deleteEntity({ id, model })` | Soft delete (`deletedAt`, `#deleted` suffix) |
+| `archiveEntity({ id, model })` | Archive (`archivedAt`, `#archived` suffix) |
+| `destroyEntity({ id, model })` | Hard delete (permanent) |
+
+### Scope and Hierarchy
+
+The `scope` field enables parent-child relationships:
+
+```typescript
+import { APEX, calculateScope, putEntity, queryByScope } from "@jaypie/dynamodb";
+
+// Root-level entity: scope = APEX ("@")
+await putEntity({ entity: { model: "chat", scope: APEX, ... } });
+
+// Child entity: scope = "{parent.model}#{parent.id}"
+const chat = { model: "chat", id: "abc-123" };
+const messageScope = calculateScope(chat); // "chat#abc-123"
+
+await putEntity({
+  entity: { model: "message", scope: messageScope, ... },
+});
+
+// Query all messages in a chat
+const { items } = await queryByScope({ model: "message", scope: messageScope });
+
+// Query all root-level chats
+const { items: chats } = await queryByScope({ model: "chat", scope: APEX });
+```
+
+### GSI Schema
+
+Jaypie defines five GSI patterns, but **do not create all five upfront**. Start with zero GSIs and add only what your access patterns require. The most common first GSI is `indexScope` for hierarchical queries.
+
+**Important:** DynamoDB allows only **one GSI to be added per deployment**. If you need multiple GSIs, add them sequentially across separate deploys. For production tables, the AWS CLI is often better suited for adding GSIs than CDK (which may try to replace the table).
+
+All GSIs use `sequence` (Number) as the sort key for chronological ordering.
+
+| GSI Name | Partition Key Pattern | Purpose | Add When |
+|----------|----------------------|---------|----------|
+| `indexScope` | `{scope}#{model}` | List entities by parent | You need hierarchical queries |
+| `indexAlias` | `{scope}#{model}#{alias}` | Human-friendly slug lookup | You need slug-based lookups |
+| `indexCategory` | `{scope}#{model}#{category}` | Category filtering | You need to filter by category |
+| `indexType` | `{scope}#{model}#{type}` | Type filtering | You need to filter by type |
+| `indexXid` | `{scope}#{model}#{xid}` | External ID lookup | You need cross-system ID lookups |
+
+### Query Functions
+
+All queries return `{ items, lastEvaluatedKey }` and support pagination:
+
+```typescript
+import { APEX, queryByScope, queryByAlias, queryByCategory, queryByType, queryByXid } from "@jaypie/dynamodb";
+
+// List by parent scope (most common)
+const { items } = await queryByScope({ model: "record", scope: APEX });
+
+// Filter by category
+const { items: memories } = await queryByCategory({
+  model: "record", scope: APEX, category: "memory",
+});
+
+// Lookup by alias (returns single or null)
+const item = await queryByAlias({ model: "record", scope: APEX, alias: "2026-01-07" });
+
+// Filter by type
+const { items: drafts } = await queryByType({
+  model: "record", scope: APEX, type: "draft",
+});
+
+// Lookup by external ID (returns single or null)
+const item = await queryByXid({ model: "user", scope: APEX, xid: "github:12345" });
+```
+
+#### Query Options
+
+```typescript
+const { items, lastEvaluatedKey } = await queryByScope({
+  model: "record",
+  scope: APEX,
+  limit: 10,              // Max items
+  ascending: true,        // Oldest first (default: false, newest first)
+  deleted: true,          // Query soft-deleted entities
+  archived: true,         // Query archived entities
+});
+
+// Pagination
+const nextPage = await queryByScope({
+  model: "record",
+  scope: APEX,
+  startKey: lastEvaluatedKey,
+});
+```
+
+### Seed and Export
+
+Idempotent seeding for bootstrapping data and export for migrations:
+
+```typescript
+import { APEX, seedEntities, seedEntityIfNotExists, exportEntities } from "@jaypie/dynamodb";
+
+// Seed a single entity if it doesn't exist (checks by alias)
+const created = await seedEntityIfNotExists({
+  alias: "config-main", model: "config", name: "Main Config", scope: APEX,
+});
+
+// Seed multiple entities (idempotent)
+const result = await seedEntities([
+  { alias: "vocab-en", model: "vocabulary", name: "English", scope: APEX },
+  { alias: "vocab-es", model: "vocabulary", name: "Spanish", scope: APEX },
+]);
+// result.created: ["vocab-en"] — aliases that were created
+// result.skipped: ["vocab-es"] — aliases that already existed
+// result.errors: [] — any failures
+
+// Dry run
+await seedEntities(entities, { dryRun: true });
+
+// Replace existing
+await seedEntities(entities, { replace: true });
+
+// Export entities
+const { entities, count } = await exportEntities("vocabulary", APEX);
+
+// Export as JSON
+const json = await exportEntitiesToJson("vocabulary", APEX);
+```
+
+### Key Builders
+
+Build composite GSI keys manually when needed:
+
+```typescript
+import { buildIndexScope, buildIndexAlias, buildIndexCategory, calculateScope } from "@jaypie/dynamodb";
+
+buildIndexScope(APEX, "record");                    // "@#record"
+buildIndexAlias(APEX, "record", "daily-log");       // "@#record#daily-log"
+buildIndexCategory(APEX, "record", "memory");       // "@#record#memory"
+calculateScope({ model: "chat", id: "abc-123" });   // "chat#abc-123"
 ```
 
 ## CDK Table Definition
 
-Start with a basic table and add indexes only when access patterns demand them.
+`JaypieDynamoDb` provides these defaults:
+
+| Setting | Default | Source |
+|---------|---------|--------|
+| Partition key | `model` (String) | Jaypie construct |
+| Sort key | `id` (String) | Jaypie construct |
+| Billing mode | PAY_PER_REQUEST | Jaypie construct |
+| Removal policy | DESTROY (non-production), RETAIN (production) | Jaypie construct |
+| Point-in-time recovery | Enabled | Jaypie construct |
+| Encryption | AWS-owned key | CDK default |
 
 ```typescript
 import { JaypieDynamoDb } from "@jaypie/constructs";
 
-// Recommended: start with no indexes
+// Recommended: start with no indexes (uses model/id keys)
 const table = new JaypieDynamoDb(this, "myApp");
 
-// Add indexes later when driven by real access patterns
+// Add indexes when driven by real access patterns
 const table = new JaypieDynamoDb(this, "myApp", {
   indexes: [
     { pk: ["scope", "model"], sk: ["sequence"] },
@@ -110,6 +344,8 @@ const table = new JaypieDynamoDb(this, "myApp", {
 });
 ```
 
+Wire tables to Lambda using the `tables` prop — see `skill("cdk")` for details.
+
 ## Local Development
 
 Use docker-compose for local DynamoDB. The `@jaypie/dynamodb` MCP tool can generate a `docker-compose.yml` with custom ports.
@@ -128,35 +364,43 @@ Use docker-compose for local DynamoDB. The `@jaypie/dynamodb` MCP tool can gener
 }
 ```
 
-| Script | Description |
-|--------|-------------|
-| `dynamo:init` | Start containers and create the default table |
-| `dynamo:create-table` | Create the local table (idempotent) |
-| `dynamo:remove` | Stop containers and delete data volumes |
-| `dynamo:start` | Start containers (data persists) |
-| `dynamo:stop` | Stop containers (data persists) |
+## Raw SDK Patterns
 
-Adjust the `--endpoint-url` port and `--table-name` to match your `docker-compose.yml`.
+For cases where you need direct SDK access instead of `@jaypie/dynamodb`:
 
-### Manual Setup
+```typescript
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { QueryCommand } from "@aws-sdk/lib-dynamodb";
 
-```bash
-# Start local DynamoDB
-docker run -p 8000:8000 amazon/dynamodb-local
+const client = new DynamoDBClient({});
 
-# Create table
-AWS_ACCESS_KEY_ID=local AWS_SECRET_ACCESS_KEY=local \
-  aws dynamodb create-table \
-  --table-name MyTable \
-  --attribute-definitions AttributeName=pk,AttributeType=S AttributeName=sk,AttributeType=S \
-  --key-schema AttributeName=pk,KeyType=HASH AttributeName=sk,KeyType=RANGE \
-  --billing-mode PAY_PER_REQUEST \
-  --endpoint-url http://127.0.0.1:8000
+const result = await client.send(new QueryCommand({
+  TableName: process.env.CDK_ENV_TABLE,
+  KeyConditionExpression: "pk = :pk AND begins_with(sk, :prefix)",
+  ExpressionAttributeValues: {
+    ":pk": "USER#123",
+    ":prefix": "ORDER#",
+  },
+  ScanIndexForward: false,
+  Limit: 10,
+}));
 ```
 
 ## Testing
 
-Mock DynamoDB in tests:
+Mock `@jaypie/dynamodb` via testkit. Key builders and `indexEntity` work correctly in tests:
+
+```typescript
+import {
+  APEX,
+  indexEntity,
+  putEntity,
+  queryByScope,
+  seedEntities,
+} from "@jaypie/testkit/mock";
+```
+
+For raw SDK mocking:
 
 ```typescript
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
@@ -167,11 +411,10 @@ vi.mock("@aws-sdk/client-dynamodb");
 describe("OrderService", () => {
   it("queries user orders", async () => {
     vi.mocked(DynamoDBClient.prototype.send).mockResolvedValue({
-      Items: [{ pk: "USER#123", sk: "ORDER#abc" }],
+      Items: [{ model: "order", id: "order-abc" }],
     });
 
     const orders = await getOrders("123");
-
     expect(orders).toHaveLength(1);
   });
 });
@@ -193,3 +436,9 @@ Version 0.4.0 renamed `class` → `category` and `indexClass` → `indexCategory
 | `INDEX_CLASS` | `INDEX_CATEGORY` |
 | `queryByClass()` | `queryByCategory()` |
 
+## See Also
+
+- **`skill("apikey")`** - API key hash storage in DynamoDB
+- **`skill("cdk")`** - JaypieDynamoDb construct and Lambda table wiring
+- **`skill("models")`** - Data model and type definition patterns
+- **`skill("tools-dynamodb")`** - Interactive DynamoDB MCP tools

package/skills/errors.md

@@ -140,3 +140,9 @@ it("includes context in error", async () => {
 });
 ```
 
+## See Also
+
+- **`skill("handlers")`** - Handler lifecycle and automatic error formatting
+- **`skill("logs")`** - Logging patterns for error context
+- **`skill("tests")`** - Testing error types with Vitest
+

package/skills/index.md

@@ -5,3 +5,14 @@ description: Skill directory listing
 # Jaypie Skills
 
 Query the Jaypie MCP `skill` tool with one of the following alias keywords `mcp__jaypie__skill(alias: String)`:
+
+## Categories
+
+| Category | Skills |
+|----------|--------|
+| contents | index, releasenotes |
+| development | apikey, documentation, errors, llm, logs, mocks, monorepo, style, subpackages, tests |
+| infrastructure | aws, cdk, cicd, datadog, dns, dynamodb, express, lambda, secrets, streaming, variables, websockets |
+| patterns | fabric, handlers, models, services, vocabulary |
+| recipes | recipe-api-server |
+| meta | issues, jaypie, skills, tools |

package/skills/logs.md

@@ -158,3 +158,9 @@ export const handler = lambdaHandler(async (event) => {
 });
 ```
 
+## See Also
+
+- **`skill("datadog")`** - Datadog integration and log forwarding
+- **`skill("handlers")`** - Handler lifecycle with automatic log context
+- **`skill("variables")`** - LOG_LEVEL and other environment variables
+

package/skills/mocks.md

@@ -172,3 +172,8 @@ export function mockJaypie(vi) {
 }
 ```
 
+## See Also
+
+- **`skill("errors")`** - Error types used in mock assertions
+- **`skill("tests")`** - Testing patterns with Vitest
+

package/skills/models.md

@@ -176,6 +176,12 @@ export interface PaginatedResponse<T> {
 4. **Document fields** - Add JSDoc comments for complex types
 5. **Prefer interfaces** - Use `interface` over `type` for objects
 
+## See Also
+
+- **`skill("dynamodb")`** - DynamoDB key conventions and table patterns
+- **`skill("fabric")`** - Fabric service input schema definitions
+- **`skill("services")`** - Service layer architecture patterns
+
 ## Type Documentation
 
 ```typescript

package/skills/recipe-api-server.md

@@ -0,0 +1,205 @@
+---
+description: Task-oriented guide for building a Jaypie API server with DynamoDB and API keys
+related: apikey, cdk, dynamodb, express, secrets, variables
+---
+
+# Recipe: API Server with DynamoDB + API Keys
+
+Step-by-step guide for creating a Jaypie API server stack with DynamoDB storage, generated secrets, and API key authentication.
+
+## 1. Create the DynamoDB Table
+
+```typescript
+import { JaypieDynamoDb } from "@jaypie/constructs";
+
+const table = new JaypieDynamoDb(this, "myApi");
+// Default keys: model (partition), id (sort)
+// Billing: PAY_PER_REQUEST
+// Removal: DESTROY (non-prod), RETAIN (prod)
+```
+
+No indexes needed initially. API key hashes are stored with `model: "apikey"` and `id: <hash>`, giving direct lookup by hash without a GSI.
+
+See `skill("dynamodb")` for key conventions and query patterns.
+
+## 2. Create Generated Secrets
+
+Two secrets support API key workflows:
+
+```typescript
+import { JaypieEnvSecret } from "@jaypie/constructs";
+import { isProductionEnv } from "@jaypie/kit";
+
+// PROJECT_SALT — HMAC salt for hashing keys before storage
+// If lost, all stored key hashes become unverifiable
+const salt = new JaypieEnvSecret(this, "ProjectSalt", {
+  envKey: "PROJECT_SALT",
+  generateSecretString: {
+    excludePunctuation: true,
+    includeSpace: false,
+    passwordLength: 64,
+  },
+  removalPolicy: isProductionEnv(),
+});
+
+// PROJECT_ADMIN_SEED — derives the bootstrap owner key deterministically
+const adminSeed = new JaypieEnvSecret(this, "ProjectAdminSeed", {
+  envKey: "PROJECT_ADMIN_SEED",
+  generateSecretString: {
+    excludePunctuation: true,
+    includeSpace: false,
+    passwordLength: 64,
+  },
+});
+```
+
+**Personal environment note:** If deploying to a personal environment (`CDK_ENV_PERSONAL=true`), these generated secrets auto-detect as consumers and try to import from sandbox. Since they don't exist there, the deploy fails with `No export named env-sandbox-...`. Fix by adding `consumer: false`:
+
+```typescript
+new JaypieEnvSecret(this, "ProjectSalt", {
+  envKey: "PROJECT_SALT",
+  consumer: false,  // Create in this stack, don't import
+  generateSecretString: { /* ... */ },
+});
+```
+
+See `skill("secrets")` for the full provider/consumer pattern.
+
+## 3. Create the Lambda
+
+```typescript
+import { JaypieExpressLambda } from "@jaypie/constructs";
+
+new JaypieExpressLambda(this, "ApiLambda", {
+  code: "../api/dist",
+  handler: "index.handler",
+  tables: [table],     // Auto-grants read/write, sets DYNAMODB_TABLE_NAME
+  secrets: [salt, adminSeed, "ANTHROPIC_API_KEY"],
+});
+```
+
+The `tables` prop:
+- Calls `grantReadWriteData()` automatically
+- Sets `DYNAMODB_TABLE_NAME` when exactly 1 table is passed
+
+The `secrets` prop accepts both construct instances and string env var names.
+
+See `skill("cdk")` for full Lambda configuration options.
+
+## 4. Express Routes
+
+### Key Generation Endpoint
+
+```typescript
+import { expressHandler, generateJaypieKey, hashJaypieKey } from "jaypie";
+
+app.post("/api/keys", expressHandler(async (req, res) => {
+  const key = generateJaypieKey({ issuer: "myapi" });
+  const hash = hashJaypieKey(key); // Uses process.env.PROJECT_SALT
+
+  // Store hash in DynamoDB
+  await dynamoClient.send(new PutItemCommand({
+    TableName: process.env.DYNAMODB_TABLE_NAME,
+    Item: {
+      model: { S: "apikey" },
+      id: { S: hash },
+      ownerId: { S: req.userId },
+      createdAt: { S: new Date().toISOString() },
+    },
+  }));
+
+  // Return plaintext key to user (only time it's visible)
+  return { key };
+}));
+```
+
+### Key Validation Middleware
+
+```typescript
+import { validateJaypieKey, hashJaypieKey, ForbiddenError } from "jaypie";
+
+async function authenticateApiKey(req, res, next) {
+  const key = req.headers["x-api-key"];
+
+  if (!key || !validateJaypieKey(key, { issuer: "myapi" })) {
+    throw new ForbiddenError("Invalid API key");
+  }
+
+  const hash = hashJaypieKey(key);
+  const result = await dynamoClient.send(new GetItemCommand({
+    TableName: process.env.DYNAMODB_TABLE_NAME,
+    Key: { model: { S: "apikey" }, id: { S: hash } },
+  }));
+
+  if (!result.Item) {
+    throw new ForbiddenError("API key not found");
+  }
+
+  req.apiKeyOwner = result.Item.ownerId.S;
+  next();
+}
+```
+
+### Seed-Derived Bootstrap Key
+
+On first startup, derive the admin key from the seed:
+
+```typescript
+import { expressHandler, generateJaypieKey, hashJaypieKey, loadEnvSecrets } from "jaypie";
+
+export default expressHandler(handler, {
+  secrets: ["PROJECT_SALT", "PROJECT_ADMIN_SEED"],
+  setup: async () => {
+    // Derive the bootstrap key (deterministic — same every time)
+    const adminKey = generateJaypieKey({
+      seed: process.env.PROJECT_ADMIN_SEED,
+      issuer: "myapi",
+    });
+    const hash = hashJaypieKey(adminKey);
+
+    // Auto-provision if not exists
+    await dynamoClient.send(new PutItemCommand({
+      TableName: process.env.DYNAMODB_TABLE_NAME,
+      Item: {
+        model: { S: "apikey" },
+        id: { S: hash },
+        ownerId: { S: "admin" },
+        createdAt: { S: new Date().toISOString() },
+      },
+      ConditionExpression: "attribute_not_exists(id)",
+    })).catch(() => {}); // Ignore if already exists
+  },
+});
+```
+
+See `skill("apikey")` for full key generation/validation/hashing documentation.
+
+## 5. Deploy
+
+```bash
+# First deploy creates secrets and table
+PROJECT_ENV=sandbox PROJECT_NONCE=dev npx cdk deploy
+```
+
+No workflow secrets needed for generated values — CloudFormation creates them on first deploy and preserves them on subsequent deploys.
+
+## Jaypie Defaults vs CDK Defaults
+
+| Setting | Value | Source |
+|---------|-------|--------|
+| DynamoDB keys: `model`/`id` | Jaypie construct | Jaypie |
+| DynamoDB billing: PAY_PER_REQUEST | Jaypie construct | Jaypie |
+| DynamoDB removal: env-aware | Jaypie construct | Jaypie |
+| DynamoDB PITR: enabled | Jaypie construct | Jaypie |
+| DynamoDB encryption: AWS-owned | CDK default | CDK |
+| Secret consumer auto-detect | Jaypie construct | Jaypie |
+| Lambda `DYNAMODB_TABLE_NAME` | Jaypie construct (1 table) | Jaypie |
+
+## See Also
+
+- **`skill("apikey")`** - Key generation, validation, hashing, and seed options
+- **`skill("cdk")`** - CDK constructs, tables, and secrets integration
+- **`skill("dynamodb")`** - Key conventions, queries, and local development
+- **`skill("express")`** - Express handler and Lambda adapter
+- **`skill("secrets")`** - Secret management and personal environment gotchas
+- **`skill("variables")`** - Environment variables reference

package/skills/secrets.md

@@ -1,6 +1,6 @@
 ---
 description: Secret management with AWS Secrets Manager
-related: aws, cdk, variables
+related: apikey, aws, cdk, variables
 ---
 
 # Secret Management
@@ -88,7 +88,49 @@ new JaypieEnvSecret(this, "SHARED_API_KEY", { provider: true });
 new JaypieEnvSecret(this, "SHARED_API_KEY"); // consumer auto-detected
 ```
 
-The construct auto-detects consumer mode for personal/ephemeral environments (`PROJECT_ENV=personal` or `CDK_ENV_PERSONAL=true`).
+### Auto-Detection
+
+The construct auto-detects consumer mode when any of these conditions is true:
+
+| Condition | Trigger |
+|-----------|---------|
+| `PROJECT_ENV=personal` | Personal environment |
+| `CDK_ENV_PERSONAL=true` | Personal environment flag |
+| `CDK_ENV_EPHEMERAL=true` | Legacy ephemeral flag |
+
+When consumer mode is active, the construct **imports** a secret from the sandbox stack via CloudFormation exports instead of creating a new one. The export name follows the pattern: `env-sandbox-{PROJECT_KEY}-{SecretName}`.
+
+### Personal Environment Gotcha
+
+**When adding new generated secrets in a personal environment**, the consumer auto-detection can cause deploy failures:
+
+```
+No export named env-sandbox-myproject-ProjectSalt found
+```
+
+This happens because the personal stack tries to import from sandbox, but sandbox has no such export yet (the secret is new).
+
+**Fix**: Set `consumer: false` for secrets that should be created per-stack:
+
+```typescript
+new JaypieEnvSecret(this, "ProjectSalt", {
+  envKey: "PROJECT_SALT",
+  consumer: false,  // Create in this stack, don't import from sandbox
+  generateSecretString: {
+    excludePunctuation: true,
+    includeSpace: false,
+    passwordLength: 64,
+  },
+});
+```
+
+**When to use `consumer: false`:**
+- Generated secrets (`generateSecretString`) that don't need to be shared
+- Secrets unique to each environment (salts, seeds)
+
+**When to let consumer auto-detect (default):**
+- Shared vendor credentials (API keys, database URIs) that exist in sandbox
+- Secrets that must be identical across sandbox and personal stacks
 
 ## Generated Secrets
 
@@ -274,6 +316,12 @@ secret.grantRead(lambdaFunction);
 
 Or use the `secrets` array on `JaypieLambda`, which handles permissions automatically.
 
+## See Also
+
+- **`skill("apikey")`** - API key infrastructure using PROJECT_SALT and PROJECT_ADMIN_SEED
+- **`skill("cdk")`** - CDK constructs including JaypieLambda secrets integration
+- **`skill("variables")`** - Environment variables reference
+
 ## Testing
 
 Mock secret functions in tests:

package/skills/services.md

@@ -173,3 +173,9 @@ describe("getUser", () => {
 });
 ```
 
+## See Also
+
+- **`skill("fabric")`** - Fabric service pattern for multi-platform deployment
+- **`skill("handlers")`** - Handler lifecycle and integration with services
+- **`skill("models")`** - Data model and type definitions
+

package/skills/skills.md

@@ -19,4 +19,5 @@ Look up skills by alias: `mcp__jaypie__skill(alias)`
 | development | apikey, documentation, errors, llm, logs, mocks, monorepo, style, subpackages, tests |
 | infrastructure | aws, cdk, cicd, datadog, dns, dynamodb, express, lambda, secrets, streaming, variables, websockets |
 | patterns | fabric, handlers, models, services, vocabulary |
+| recipes | recipe-api-server |
 | meta | issues, jaypie, skills, tools |

package/skills/style.md

@@ -165,3 +165,9 @@ export default [...jaypie];
 ```
 
 Always run `npm run format` before committing.
+
+## See Also
+
+- **`skill("documentation")`** - Writing style for Jaypie docs
+- **`skill("errors")`** - Error handling conventions
+- **`skill("tests")`** - Testing patterns and conventions

package/skills/variables.md

@@ -1,6 +1,6 @@
 ---
 description: Environment variables reference
-related: secrets, cdk, datadog
+related: apikey, cdk, datadog, secrets
 ---
 
 # Environment Variables
@@ -15,6 +15,8 @@ Configuration variables used in Jaypie applications.
 | `PROJECT_KEY` | Project name for logging | e.g., my-api |
 | `PROJECT_NONCE` | Unique resource suffix | e.g., dev, staging, prod |
 | `PROJECT_CHAOS` | Chaos engineering mode | none, partial, full |
+| `PROJECT_SALT` | Secret salt for HMAC hashing (API keys) | Generated by JaypieEnvSecret |
+| `PROJECT_ADMIN_SEED` | Secret seed for deterministic key derivation | Generated by JaypieEnvSecret |
 
 ### Usage
 
@@ -52,6 +54,8 @@ LOG_LEVEL=debug npm run dev
 | `CDK_ENV_SNS_TOPIC_ARN` | SNS topic ARN |
 | `CDK_ENV_DATADOG_API_KEY_ARN` | Datadog API key ARN |
 | `CDK_ENV_TABLE` | DynamoDB table name |
+| `CDK_ENV_PERSONAL` | Personal environment flag (triggers consumer mode for secrets) |
+| `DYNAMODB_TABLE_NAME` | Auto-set by JaypieLambda when exactly 1 table is passed |
 
 ### Passing to Lambda
 
@@ -113,6 +117,13 @@ environment: {
 }
 ```
 
+## Application Variables
+
+| Variable | Description |
+|----------|-------------|
+| `BASE_URL` | Application base URL (used by CORS) |
+| `PROJECT_BASE_URL` | Project base URL (used by CORS) |
+
 ## Local Development
 
 ### .env Files
@@ -144,3 +155,10 @@ const isLocal = process.env.PROJECT_ENV === "local";
 const isDevelopment = !isProduction;
 ```
 
+## See Also
+
+- **`skill("apikey")`** - Uses PROJECT_SALT and PROJECT_ADMIN_SEED
+- **`skill("cdk")`** - CDK constructs that set infrastructure variables
+- **`skill("cors")`** - Uses BASE_URL and PROJECT_BASE_URL
+- **`skill("secrets")`** - Secret management and CDK_ENV_PERSONAL behavior
+