@jaypie/mcp 0.2.10 → 0.3.0

package/package.json

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

package/prompts/Jaypie_CDK_Constructs_and_Patterns.md

@@ -102,33 +102,27 @@ Preconfigured with API-optimized timeouts and role tags.
 
 ### Streaming Lambda Functions
 
-Use `JaypieStreamingLambda` for Express apps with AWS Lambda Web Adapter and streaming support:
+For streaming responses (SSE, real-time updates), use `createLambdaStreamHandler` from `@jaypie/express` with `JaypieDistribution`:
 
 ```typescript
-import { JaypieStreamingLambda, JaypieDistribution } from "@jaypie/constructs";
+import { JaypieExpressLambda, JaypieDistribution } from "@jaypie/constructs";
+import * as lambda from "aws-cdk-lib/aws-lambda";
 
-// Create streaming Lambda with Web Adapter
-const streamingLambda = new JaypieStreamingLambda(this, "StreamingApi", {
+// Create Lambda (handler uses createLambdaStreamHandler internally)
+const streamingApi = new JaypieExpressLambda(this, "StreamingApi", {
   code: "dist/api",
-  handler: "run.sh",           // Shell script to start Express app
-  streaming: true,             // Enables RESPONSE_STREAM invoke mode
-  port: 8000,                  // Port your app listens on (default: 8000)
+  handler: "index.handler",
 });
 
-// CloudFront auto-detects invokeMode from JaypieStreamingLambda
+// Use with CloudFront and RESPONSE_STREAM invoke mode
 new JaypieDistribution(this, "Distribution", {
-  handler: streamingLambda,
+  handler: streamingApi,
+  invokeMode: lambda.InvokeMode.RESPONSE_STREAM,
   host: "api.example.com",
   zone: "example.com",
 });
 ```
 
-Features:
-- Automatically adds AWS Lambda Web Adapter layer (supports ARM64 and x86_64)
-- Sets `AWS_LAMBDA_EXEC_WRAPPER` and `AWS_LWA_INVOKE_MODE` environment variables
-- Exposes `invokeMode` property for auto-detection by `JaypieDistribution`
-- Use `streaming: false` for buffered mode (traditional Lambda behavior)
-
 For direct Function URL access (bypass CloudFront):
 ```typescript
 import { FunctionUrlAuthType, InvokeMode } from "aws-cdk-lib/aws-lambda";
@@ -147,7 +141,7 @@ const functionUrl = streamingLambda.addFunctionUrl({
 new cdk.CfnOutput(this, "StreamingUrl", { value: functionUrl.url });
 ```
 
-Note: API Gateway has a 29-second timeout limit. For longer streaming operations, use Function URLs or CloudFront with Lambda Function URLs.
+Note: Streaming requires Lambda Function URLs (not API Gateway). `JaypieDistribution` uses Function URLs by default.
 
 ### Stack Types
 
@@ -323,21 +317,22 @@ Common usage:
 
 ### DynamoDB Tables
 
-Use `JaypieDynamoDb` for single-table design with Jaypie GSI patterns:
+Use `JaypieDynamoDb` for single-table design with Jaypie patterns:
 ```typescript
 // Shorthand: tableName becomes "myApp", construct id is "JaypieDynamoDb-myApp"
 const table = new JaypieDynamoDb(this, "myApp");
 
-// No GSIs
-const table = new JaypieDynamoDb(this, "MyTable", {
-  globalSecondaryIndexes: false,
+// With standard Jaypie GSIs (indexScope, indexAlias, indexClass, indexType, indexXid)
+const tableWithIndexes = new JaypieDynamoDb(this, "myApp", {
+  indexes: JaypieDynamoDb.DEFAULT_INDEXES,
 });
 
-// Use only specific GSIs
-const table = new JaypieDynamoDb(this, "MyTable", {
-  globalSecondaryIndexes: [
-    JaypieDynamoDb.GlobalSecondaryIndex.Ou,
-    JaypieDynamoDb.GlobalSecondaryIndex.Type,
+// With custom indexes using IndexDefinition from @jaypie/fabric
+const customTable = new JaypieDynamoDb(this, "myApp", {
+  indexes: [
+    { pk: ["scope", "model"], sk: ["sequence"] },           // indexScopeModel
+    { pk: ["scope", "model", "type"], sparse: true },       // indexScopeModelType
+    { name: "byAlias", pk: ["alias"], sk: ["createdAt"] },  // custom name
   ],
 });
 
@@ -352,9 +347,9 @@ Features:
 - Default partition key: `model` (string), sort key: `id` (string)
 - PAY_PER_REQUEST billing mode by default
 - RETAIN removal policy in production, DESTROY otherwise
-- GSI options: `true`/omit = all five, `false` = none, array = specific GSIs
-- Static constants: `JaypieDynamoDb.GlobalSecondaryIndex.*` and `JaypieDynamoDb.GlobalSecondaryIndexes`
-- All GSIs use partition key (string) + `sequence` (number) sort key
+- No GSIs by default - use `indexes` prop to add them
+- `JaypieDynamoDb.DEFAULT_INDEXES` provides standard Jaypie GSIs from `@jaypie/fabric`
+- Uses `IndexDefinition` from `@jaypie/fabric` for GSI configuration
 - Implements `ITableV2` interface
 
 For single-table design patterns, key builders, and query utilities, see `Jaypie_DynamoDB_Package.md`.

package/prompts/Jaypie_CICD_with_GitHub_Actions.md

@@ -6,6 +6,14 @@ description: conventions around deployment and environment variables, especially
 
 Reference for Jaypie CI/CD conventions. For setup instructions, see `Jaypie_Init_CICD_with_GitHub_Actions.md`.
 
+## Workspace Naming Conventions
+
+| Directory | Purpose |
+|-----------|---------|
+| `packages/` | Default workspace for npm packages (preferred when only one namespace needed) |
+| `stacks/` | CDK-deployed infrastructure and sites (as opposed to npm-published) |
+| `workspaces/` | Generic workspace for other work |
+
 ## Jaypie Environments
 
 Jaypie assumes multiple deployed environments:
@@ -19,11 +27,21 @@ Jaypie assumes multiple deployed environments:
 
 ## Naming Conventions
 
-Workflow files lead with the most important keyword and end with the environment:
-- `deploy-personal-build.yml`
-- `deploy-sandbox.yml`
-- `deploy-production.yml`
-- `npm-deploy.yml`
+### Workflow File Naming
+
+| Pattern | Purpose | Example |
+|---------|---------|---------|
+| `deploy-env-$ENV.yml` | Deploy all stacks to an environment | `deploy-env-sandbox.yml` |
+| `deploy-$ENV.yml` | Legacy alias for environment deploy | `deploy-sandbox.yml` |
+| `deploy-stack-$STACK.yml` | Deploy specific stack content | `deploy-stack-documentation.yml` |
+
+### Tag Naming
+
+| Pattern | Purpose | Example |
+|---------|---------|---------|
+| `v*` | Production version release | `v1.2.3` |
+| `$ENV-*` | Deploy to specific environment | `sandbox-hotfix` |
+| `stack-$STACK-*` | Deploy specific stack | `stack-documentation-v1.0.0` |
 
 Always prefer full words for maximum clarity.
 
@@ -54,11 +72,17 @@ jobs:        # alphabetical
 
 | Environment | Trigger |
 |-------------|---------|
-| production | tags: `v*` |
-| development | branches: `[main]` |
-| sandbox | branches: `[main, develop, sandbox, sandbox-*, sandbox/*]` |
+| production | tags: `v*`, `production-*` |
+| development | branches: `[main, development/*]`, tags: `development-*` |
+| sandbox | branches: `[feat/*, sandbox/*]`, tags: `sandbox-*` |
 | personal | branches-ignore: `[main, develop, nobuild-*, nobuild/*, sandbox, sandbox-*, sandbox/*]` |
 
+### Stack Triggers
+
+| Stack | Trigger |
+|-------|---------|
+| documentation | Push to `main` with path filter, tags: `stack-documentation-*` |
+
 ### Dependencies
 
 | Environment | Lint/Test Dependency |
@@ -74,14 +98,20 @@ Use `npm run lint` and `npm run test`. Verify the test script uses `vitest run`
 
 ## Concurrency
 
-New builds cancel in-progress builds. Environments run in parallel between each other but concurrently within an environment.
+Use concurrency groups without `cancel-in-progress` to avoid stuck deployments. Environments run in parallel between each other but concurrently within an environment.
+
+### Environment Builds
+
+```yaml
+concurrency:
+  group: deploy-env-production
+```
 
-### Static Builds
+### Stack Builds
 
 ```yaml
 concurrency:
-  group: deploy-production
-  cancel-in-progress: true
+  group: deploy-stack-documentation-${{ github.event.inputs.environment || 'development' }}
 ```
 
 ### Personal Builds
@@ -89,7 +119,6 @@ concurrency:
 ```yaml
 concurrency:
   group: deploy-personal-build-${{ github.actor }}
-  cancel-in-progress: true
 ```
 
 ## Personal Builds
@@ -122,6 +151,48 @@ Create GitHub environments matching deployment targets:
 
 Each environment contains variables and secrets specific to that deployment target.
 
+## GitHub Variable Scoping
+
+Variables are configured at different levels in GitHub Settings:
+
+### Organization Level
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AWS_REGION` | AWS region | `us-east-1` |
+| `LOG_LEVEL` | Application log level | `debug` |
+| `MODULE_LOG_LEVEL` | Module log level | `warn` |
+| `PROJECT_SPONSOR` | Organization name | `finlaysonstudio` |
+
+### Repository Level
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AWS_HOSTED_ZONE` | Route53 hosted zone | `example.com` |
+| `PROJECT_KEY` | Project identifier | `myapp` |
+| `PROJECT_SERVICE` | Service name | `stacks` |
+
+### Environment Level
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `AWS_ROLE_ARN` | IAM role ARN for OIDC | Yes |
+| `DATADOG_API_KEY_ARN` | Datadog API key ARN in Secrets Manager | No |
+| `PROJECT_ENV` | Environment identifier | Yes |
+| `PROJECT_NONCE` | Unique resource identifier | No |
+
+### Auto-Generated Variables
+
+These variables are set automatically from GitHub context:
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `CDK_DEFAULT_ACCOUNT` | `${{ github.repository_owner }}` | Repository owner |
+| `CDK_DEFAULT_REGION` | `AWS_REGION` | Same as AWS region |
+| `CDK_ENV_REPO` | `${{ github.repository }}` | Repository name (owner/repo) |
+| `PROJECT_COMMIT` | `${{ github.sha }}` | Current commit SHA |
+| `PROJECT_VERSION` | `package.json` | Version from package.json |
+
 ## Environment Variables Reference
 
 ### Application Variables
@@ -169,6 +240,8 @@ Follow naming from vendor documentation. If documentation does not reference env
 
 ## Secrets
 
+By default, no secrets are required. Dependencies add secrets as needed.
+
 ### Secret Naming
 
 Secrets follow the same conventions as variables. Use `SECRET_` prefix for secrets that will be resolved at runtime:
@@ -177,6 +250,8 @@ Secrets follow the same conventions as variables. Use `SECRET_` prefix for secre
 
 ### Passing Secrets
 
+Secrets are passed to CDK via `JaypieEnvSecret` construct and made available at runtime.
+
 Pass secrets only to steps that need them:
 
 ```yaml
@@ -190,6 +265,30 @@ Pass secrets only to steps that need them:
 
 Never expose secrets in logs or workflow outputs.
 
+### Adding Dependency Secrets
+
+When adding dependencies that require secrets, update the workflow accordingly.
+
+#### Example: Auth0 Integration
+
+**Environment Variables:**
+- `AUTH0_AUDIENCE` - API identifier
+- `AUTH0_CLIENT_ID` - Application client ID
+- `AUTH0_DOMAIN` - Auth0 tenant domain
+
+**Environment Secrets:**
+- `AUTH0_CLIENT_SECRET` - Application client secret
+
+Add to workflow:
+```yaml
+- name: Deploy CDK Stack
+  uses: ./.github/actions/cdk-deploy
+  with:
+    stack-name: AppStack
+  env:
+    AUTH0_CLIENT_SECRET: ${{ secrets.AUTH0_CLIENT_SECRET }}
+```
+
 ## CDK Stack Names
 
 The `stack-name` parameter in deploy workflows must match the stack ID defined in `packages/cdk/bin/cdk.ts`:
@@ -200,7 +299,7 @@ new AppStack(app, "AppStack");  // "AppStack" is the stack ID
 ```
 
 ```yaml
-# deploy-*.yml
+# deploy-env-*.yml
 - name: Deploy CDK Stack
   uses: ./.github/actions/cdk-deploy
   with:
@@ -209,6 +308,34 @@ new AppStack(app, "AppStack");  // "AppStack" is the stack ID
 
 If you rename the stack ID (e.g., to "MyProjectAppStack" for clarity in AWS), update all deploy workflows to match. Mismatched names cause "No stacks match the name(s)" errors.
 
+## Environment-Aware Hostnames
+
+Jaypie CDK constructs use `envHostname()` from `@jaypie/constructs` to determine deployment hostnames based on `PROJECT_ENV`:
+
+| `PROJECT_ENV` | Example Hostname |
+|---------------|------------------|
+| `production` | `example.com` (apex domain) |
+| `sandbox` | `sandbox.example.com` |
+| `development` | `development.example.com` |
+| `personal` | `personal.example.com` |
+
+**CRITICAL**: If `PROJECT_ENV` is not set or is set incorrectly in the GitHub environment, deployments may target the wrong hostname (e.g., deploying sandbox changes to production apex).
+
+### How It Works
+
+1. The `setup-environment` action reads `${{ vars.PROJECT_ENV }}` from the GitHub environment
+2. This is exported as `PROJECT_ENV` to `$GITHUB_ENV`
+3. CDK constructs read `process.env.PROJECT_ENV` via `envHostname()`
+4. For production, the environment prefix is omitted (apex domain)
+5. For all other environments, the prefix is prepended
+
+### Troubleshooting Wrong Hostname
+
+If deployment targets the wrong hostname:
+1. Go to GitHub Settings → Environments
+2. Select the environment (sandbox, development, production)
+3. Verify `PROJECT_ENV` variable matches the environment name exactly
+
 ## Integrations
 
 ### AWS

package/prompts/Jaypie_DynamoDB_Package.md

@@ -21,21 +21,21 @@ All entities share a single DynamoDB table with:
 - **Primary Key**: `model` (partition) + `id` (sort)
 - **Five GSIs**: All use `sequence` as sort key for chronological ordering
 
-### Organizational Unit (OU)
+### Scope
 
-The `ou` field creates hierarchical relationships:
-- Root entities: `ou = "@"` (APEX constant)
-- Child entities: `ou = "{parent.model}#{parent.id}"`
+The `scope` field creates hierarchical relationships:
+- Root entities: `scope = "@"` (APEX constant)
+- Child entities: `scope = "{parent.model}#{parent.id}"`
 
 ### GSI Pattern
 
 | GSI Name | Partition Key | Use Case |
 |----------|---------------|----------|
-| `indexOu` | `{ou}#{model}` | List all entities under a parent |
-| `indexAlias` | `{ou}#{model}#{alias}` | Human-friendly slug lookup |
-| `indexClass` | `{ou}#{model}#{class}` | Category filtering |
-| `indexType` | `{ou}#{model}#{type}` | Type filtering |
-| `indexXid` | `{ou}#{model}#{xid}` | External system ID lookup |
+| `indexScope` | `{scope}#{model}` | List all entities under a parent |
+| `indexAlias` | `{scope}#{model}#{alias}` | Human-friendly slug lookup |
+| `indexClass` | `{scope}#{model}#{class}` | Category filtering |
+| `indexType` | `{scope}#{model}#{type}` | Type filtering |
+| `indexXid` | `{scope}#{model}#{xid}` | External system ID lookup |
 
 ## Client Initialization
 
@@ -75,7 +75,7 @@ interface MyRecord extends StorableEntity {
 
   // Required fields
   name: string;
-  ou: string;         // APEX or hierarchical
+  scope: string;      // APEX or hierarchical
   sequence: number;   // Date.now()
 
   // Timestamps (ISO 8601)
@@ -108,7 +108,7 @@ const record = await putEntity({
     model: "record",
     id: crypto.randomUUID(),
     name: "Daily Log",
-    ou: APEX,
+    scope: APEX,
     sequence: Date.now(),
     alias: "2026-01-07",    // Optional
     class: "memory",        // Optional
@@ -118,7 +118,7 @@ const record = await putEntity({
 });
 
 // Result includes auto-populated indexes:
-// indexOu: "@#record"
+// indexScope: "@#record"
 // indexAlias: "@#record#2026-01-07"
 // indexClass: "@#record#memory"
 ```
@@ -187,16 +187,16 @@ await destroyEntity({ id: "123", model: "record" });
 
 ### Hierarchical Entities
 
-Use `calculateOu` to derive OU from parent:
+Use `calculateScope` to derive scope from parent:
 
 ```typescript
-import { calculateOu, putEntity, queryByOu } from "@jaypie/dynamodb";
+import { calculateScope, putEntity, queryByScope } from "@jaypie/dynamodb";
 
 // Parent reference
 const chat = { model: "chat", id: "abc-123" };
 
-// Calculate child OU
-const messageOu = calculateOu(chat); // "chat#abc-123"
+// Calculate child scope
+const messageScope = calculateScope(chat); // "chat#abc-123"
 
 // Create child entity
 const message = await putEntity({
@@ -204,39 +204,39 @@ const message = await putEntity({
     model: "message",
     id: crypto.randomUUID(),
     name: "First message",
-    ou: messageOu,
+    scope: messageScope,
     sequence: Date.now(),
     createdAt: now,
     updatedAt: now,
   },
 });
-// indexOu: "chat#abc-123#message"
+// indexScope: "chat#abc-123#message"
 
 // Query all messages in chat
-const { items } = await queryByOu({ model: "message", ou: messageOu });
+const { items } = await queryByScope({ model: "message", scope: messageScope });
 ```
 
 ## Query Functions
 
 All queries use object parameters and filter soft-deleted and archived records by default.
 
-### queryByOu - List by Parent
+### queryByScope - List by Parent
 
 List all entities of a model under a parent:
 
 ```typescript
-import { APEX, queryByOu } from "@jaypie/dynamodb";
+import { APEX, queryByScope } from "@jaypie/dynamodb";
 
 // Root-level records
-const { items, lastEvaluatedKey } = await queryByOu({
+const { items, lastEvaluatedKey } = await queryByScope({
   model: "record",
-  ou: APEX,
+  scope: APEX,
 });
 
 // Messages under a chat
-const { items: messages } = await queryByOu({
+const { items: messages } = await queryByScope({
   model: "message",
-  ou: "chat#abc-123",
+  scope: "chat#abc-123",
 });
 ```
 
@@ -250,7 +250,7 @@ import { APEX, queryByAlias } from "@jaypie/dynamodb";
 const record = await queryByAlias({
   alias: "2026-01-07",
   model: "record",
-  ou: APEX,
+  scope: APEX,
 });
 // Returns entity or null
 ```
@@ -263,14 +263,14 @@ import { APEX, queryByClass, queryByType } from "@jaypie/dynamodb";
 // All memory records
 const { items } = await queryByClass({
   model: "record",
-  ou: APEX,
+  scope: APEX,
   recordClass: "memory",
 });
 
 // All note-type records
 const { items: notes } = await queryByType({
   model: "record",
-  ou: APEX,
+  scope: APEX,
   type: "note",
 });
 ```
@@ -284,7 +284,7 @@ import { APEX, queryByXid } from "@jaypie/dynamodb";
 
 const record = await queryByXid({
   model: "record",
-  ou: APEX,
+  scope: APEX,
   xid: "ext-12345",
 });
 // Returns entity or null
@@ -295,9 +295,9 @@ const record = await queryByXid({
 ```typescript
 import type { BaseQueryOptions } from "@jaypie/dynamodb";
 
-const result = await queryByOu({
+const result = await queryByScope({
   model: "record",
-  ou: APEX,
+  scope: APEX,
   // BaseQueryOptions:
   limit: 25,                // Max items to return
   ascending: true,          // Oldest first (default: false = newest first)
@@ -310,15 +310,15 @@ const result = await queryByOu({
 ### Pagination
 
 ```typescript
-import { APEX, queryByOu } from "@jaypie/dynamodb";
+import { APEX, queryByScope } from "@jaypie/dynamodb";
 
 let startKey: Record<string, unknown> | undefined;
 const allItems: StorableEntity[] = [];
 
 do {
-  const { items, lastEvaluatedKey } = await queryByOu({
+  const { items, lastEvaluatedKey } = await queryByScope({
     model: "record",
-    ou: APEX,
+    scope: APEX,
     limit: 100,
     startKey,
   });
@@ -337,11 +337,11 @@ import { indexEntity } from "@jaypie/dynamodb";
 const indexed = indexEntity({
   model: "record",
   id: "123",
-  ou: "@",
+  scope: "@",
   alias: "my-alias",
   // ...
 });
-// indexOu: "@#record"
+// indexScope: "@#record"
 // indexAlias: "@#record#my-alias"
 ```
 
@@ -349,14 +349,14 @@ Use individual key builders for manual key construction:
 
 ```typescript
 import {
-  buildIndexOu,
+  buildIndexScope,
   buildIndexAlias,
   buildIndexClass,
   buildIndexType,
   buildIndexXid,
 } from "@jaypie/dynamodb";
 
-buildIndexOu("@", "record");                    // "@#record"
+buildIndexScope("@", "record");                 // "@#record"
 buildIndexAlias("@", "record", "my-alias");     // "@#record#my-alias"
 buildIndexClass("@", "record", "memory");       // "@#record#memory"
 buildIndexType("@", "record", "note");          // "@#record#note"
@@ -369,7 +369,7 @@ buildIndexXid("@", "record", "ext-123");        // "@#record#ext-123"
 import {
   APEX,           // "@" - Root-level marker
   SEPARATOR,      // "#" - Composite key separator
-  INDEX_OU,       // "indexOu"
+  INDEX_SCOPE,    // "indexScope"
   INDEX_ALIAS,    // "indexAlias"
   INDEX_CLASS,    // "indexClass"
   INDEX_TYPE,     // "indexType"
@@ -385,7 +385,7 @@ AttributeDefinitions:
     AttributeType: S
   - AttributeName: id
     AttributeType: S
-  - AttributeName: indexOu
+  - AttributeName: indexScope
     AttributeType: S
   - AttributeName: indexAlias
     AttributeType: S
@@ -405,9 +405,9 @@ KeySchema:
     KeyType: RANGE
 
 GlobalSecondaryIndexes:
-  - IndexName: indexOu
+  - IndexName: indexScope
     KeySchema:
-      - AttributeName: indexOu
+      - AttributeName: indexScope
         KeyType: HASH
       - AttributeName: sequence
         KeyType: RANGE
@@ -445,7 +445,7 @@ const created = await seedEntityIfNotExists({
   alias: "config-main",
   model: "config",
   name: "Main Configuration",
-  ou: APEX,
+  scope: APEX,
 });
 // Returns true if created, false if already exists
 ```
@@ -458,8 +458,8 @@ Seed multiple entities with idempotency:
 import { APEX, seedEntities } from "@jaypie/dynamodb";
 
 const result = await seedEntities([
-  { alias: "vocab-en", model: "vocabulary", name: "English", ou: APEX },
-  { alias: "vocab-es", model: "vocabulary", name: "Spanish", ou: APEX },
+  { alias: "vocab-en", model: "vocabulary", name: "English", scope: APEX },
+  { alias: "vocab-es", model: "vocabulary", name: "Spanish", scope: APEX },
 ]);
 // result.created: aliases of created entities
 // result.skipped: aliases of entities that already existed
@@ -476,7 +476,7 @@ Auto-generates `id` (UUID), `createdAt`, `updatedAt`, and `sequence` if missing.
 
 ### exportEntities
 
-Export entities by model and organizational unit:
+Export entities by model and scope:
 
 ```typescript
 import { APEX, exportEntities } from "@jaypie/dynamodb";
@@ -546,11 +546,11 @@ import {
   exportEntities,
   getEntity,
   putEntity,
-  queryByOu,
+  queryByScope,
   seedEntities,
 } from "@jaypie/testkit/mock";
 
-queryByOu.mockResolvedValue({
+queryByScope.mockResolvedValue({
   items: [{ id: "123", name: "Test" }],
   lastEvaluatedKey: undefined,
 });
@@ -644,12 +644,12 @@ await deleteEntity({ id: "123", model: "record" });
 await archiveEntity({ id: "123", model: "record" });
 
 // Queries exclude both by default
-const { items } = await queryByOu({ model: "record", ou: APEX });
+const { items } = await queryByScope({ model: "record", scope: APEX });
 
 // Include if needed
-const { items: all } = await queryByOu({
+const { items: all } = await queryByScope({
   model: "record",
-  ou: APEX,
+  scope: APEX,
   includeDeleted: true,
   includeArchived: true,
 });
@@ -704,7 +704,7 @@ const { tools } = registerDynamoDbTools({ server });
 #### Query Operations
 | Tool | Description |
 |------|-------------|
-| `dynamodb_query_ou` | Query by organizational unit |
+| `dynamodb_query_scope` | Query by scope |
 | `dynamodb_query_alias` | Query by human-friendly alias |
 | `dynamodb_query_class` | Query by category classification |
 | `dynamodb_query_type` | Query by type classification |
@@ -753,15 +753,15 @@ Generate docker-compose and create table:
   "id": "abc-123",
   "model": "record",
   "name": "My Record",
-  "ou": "@",
+  "scope": "@",
   "alias": "my-record",
   "class": "memory"
 }
 
-// dynamodb_query_ou
+// dynamodb_query_scope
 {
   "model": "record",
-  "ou": "@",
+  "scope": "@",
   "limit": 10
 }