create-agent-rig 0.3.2 → 0.5.0

package/templates/hash-history.json

@@ -0,0 +1,264 @@
+{
+  "versions": [
+    "0.3.0",
+    "0.3.1",
+    "0.3.2",
+    "0.4.0"
+  ],
+  "files": {
+    ".claude/agents/cdk-diff-reviewer.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "2286fbc01c0342b9bac9909890876c079615db5b398e3499a0f2fddb1a334098"
+      ]
+    },
+    ".claude/agents/code-reviewer.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "58969edc0820463298002c618b6ec49913e1cb3aa90dec4aed2aec14c7bcfd3b",
+        "be3d2992d1f278dde46b555df1840b02f91403db1ec2fd4d489fb5efa940f019",
+        "ec403373ef6bc0575d61c6ca11f82792817b272221fad8317ef6c45388b52628"
+      ]
+    },
+    ".claude/agents/prose-reviewer.md": {
+      "since": "0.3.2",
+      "hashes": [
+        "8d5762849afd328fdc1aabf053ad207f2e306e013665e3ff934b06cbb1bbda38"
+      ]
+    },
+    ".claude/agents/security-scanner.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "43e5d59315483e369ad19f3070175f146e88deabd3a12dc09339ac4fac0f2aee"
+      ]
+    },
+    ".claude/agents/test-writer.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "333feef12383dea51791ae4923c44ba542438de793f0792fb51d96aa15b8b1b8"
+      ]
+    },
+    ".claude/hooks/block-no-verify.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "ece5a81db41bd48695a1a009239837b682d247baf6d19214eaa859a7519ab246"
+      ]
+    },
+    ".claude/hooks/dod-checks.json": {
+      "since": "0.3.0",
+      "hashes": [
+        "413e59fecca1453e54369b1e302925b4f6843273767ebc33ac311fe825cfc4b2"
+      ]
+    },
+    ".claude/hooks/gate-stop-dod.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "de1f331eaf93bad6ef0e1734789fd3c4ab07550a85ed2d8ff8888bc6f0bcfb0f",
+        "9fb8fad4d95756fb2424a97550aa85dfab0ca8dbcf91e6d0385263ba3b929135"
+      ]
+    },
+    ".claude/hooks/guard-bash.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "4d396f412fc53094188b14348c5af4e79c7542a182630c20c4687d79899c5b0e"
+      ]
+    },
+    ".claude/hooks/guard-core-purity.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "e36fbb92ee8395c6686fef582f29f2701747074b3b781bed42fe068f5c000bd7"
+      ]
+    },
+    ".claude/hooks/guard-web-boundary.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "93d4fa0fd1c18261cc8ef2b1ae2abe3a0200cc4b5a7b1d1d4ae433ca92c514b1"
+      ]
+    },
+    ".claude/hooks/inject-rules.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "c472419f1076ea3707d640cd5246c0e69a94c55455f6648e2cbaf300a382c8df"
+      ]
+    },
+    ".claude/queue.json": {
+      "since": "0.3.0",
+      "hashes": [
+        "00671bfdd83326e7561f1ce955b7ad79dcf566faf2eae3684b4287af0d54c14c"
+      ]
+    },
+    ".claude/rules/architecture.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "c63ee846180efcf4bacb4a13ca19bdc043c0885103fcea11f702e0685921facf"
+      ]
+    },
+    ".claude/rules/autonomy.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "ce2104ce697d3e5ed9210e85fe0daeb66b432a36868493f06fec54073a5fff31"
+      ]
+    },
+    ".claude/rules/aws-cdk.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "e0a283559710d15035668d8b04e47228fce442ac4e37458caca24b429a65b25e"
+      ]
+    },
+    ".claude/rules/invariants.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "b24bbf3e596033719eff463d317ba1e933d0661e48bfa8eafba8d6dca1453a59",
+        "518d9b3d7cbae50f30c86d33b2b4bbea11ab3ba6cfef270876e92604b2af5f50"
+      ]
+    },
+    ".claude/rules/node-ts.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "3db68a4280cc30655be56fed9385179c378f560f3df55e21952a24066427e845"
+      ]
+    },
+    ".claude/rules/workflow.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "dbe8025e10583e03fee5056e88aa6b73e4399453711d9156d82528a02d6e0402",
+        "9e60d0300e856a9b3f81ab748bf2c0a9de27233ad0aa58a8c7141413fa0f3cae"
+      ]
+    },
+    ".claude/scripts/detect-missed-gate.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "bad5ce92a1c1f97ef2c25ebd216e945329e544337aa33e530631ed922ea8c495",
+        "edcebe8ac78cf832a42e3b6fb70fe458a9fec4cb5f8b7b4cf276efc4f9c06a64"
+      ]
+    },
+    ".claude/scripts/preflight.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "21083ff7baeebf8aedbdf85679a353f671276a9e0201a58a8235ae63f55f081c",
+        "ceb6d35fa028f9c5e5e2d5965c627095d5ba80c37191a584627b4bc645b6be15"
+      ]
+    },
+    ".claude/scripts/queue/core.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "214f36e39f3809da5a121f404005d16a694280ca672ed10150b1b07d47912f6a",
+        "d8a5916bae71efcc6a21978af713112c9ec33a7554fd07f5978bdf2c3633b560"
+      ]
+    },
+    ".claude/scripts/queue/github-issues.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "f473f0ee5fc469f47b2b21ee601310944faa1abed21942e97ed251aba826cd5d",
+        "86489ac7fcd06e43e31fb3d0ac9ab23174ef9c95196b08f127f1ae74da620c0c"
+      ]
+    },
+    ".claude/scripts/queue/index.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "cd149245dc29ef7489ae0e5394fa5a063dea2cc017bd3cbbface1ace6f8d7b46"
+      ]
+    },
+    ".claude/scripts/queue/jira.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "13e187a4005136a9a1fae5fb5a3d2a61c3cf5dc097b467c12622ad82a0fd5d52",
+        "86591a48b9264d641c2530238ea3720705f12e17af2ec8dccecabfa3a742a2e7"
+      ]
+    },
+    ".claude/scripts/queue/plan-md.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "d137dad23f263b1a12b04b46625247fea648ded36d0fea7c5b4e4f2211a142eb",
+        "07eab69bd86b19b7a1f01eb14efe4f8c007481806cbe029d4014fe9bf0703000"
+      ]
+    },
+    ".claude/scripts/reconcile-external-prs.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "a326acd64ea19a50d093c91e711ad0234eb05c76d00066db5657c22f4355c190"
+      ]
+    },
+    ".claude/scripts/stop-flag.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "ff4c8edbb715e7b552e8b5a5299e151871e85416568ce20ff8d8a0b4300a78a8"
+      ]
+    },
+    ".claude/settings.json": {
+      "since": "0.3.0",
+      "hashes": [
+        "55a6938b4d9967291a26e93301e34e5ffdef74a88f8c773a4d11b5d87d864fff"
+      ]
+    },
+    ".claude/skills/check-premises/SKILL.md": {
+      "since": "0.3.2",
+      "hashes": [
+        "d69396da276f748c89ca0284fcd606ce70da8a791defafe9c9b27ce5f8ffd29e"
+      ]
+    },
+    ".claude/skills/loop/SKILL.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "e14318a1bf4cbb19edaaabadcf14482bc70bcdcfdc2057231b15685d149db550",
+        "8f687f92fa60d4cc679fa13bff997cec92227f6bc0b90c1dc5b8a5400f2abef0"
+      ]
+    },
+    ".claude/skills/new-invariant/SKILL.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "b15abfba29cd52b2fc29f30d63803bc0fc2741429c8faab21d2f907ee1ce0828"
+      ]
+    },
+    ".claude/skills/new-invariant/guard-invariant.example.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "0fec41841de1fc07f4da08d023fdda2906c62e3c71b22827c874f2809719b955"
+      ]
+    },
+    ".claude/skills/new-invariant/guard-invariant.example.test.mjs": {
+      "since": "0.3.0",
+      "hashes": [
+        "7bef9179c5b56d280d462cf21fb2c38dc4cb759b671b114b3995aac93720caf8"
+      ]
+    },
+    ".claude/skills/post-deploy-verify/SKILL.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "321ae18feff82f1f8a64e19a6170056dc9b18a71e6f2a80d46293510b9748a46"
+      ]
+    },
+    ".claude/skills/pr-ship/SKILL.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "368a50be809f7be865d6d29ab3e54b9d69acd2ea3ba7929c0edeef161c2521b7",
+        "75adb84414a330db621ff4f1363b3926f537133199236a9e25bb9880b935e02e"
+      ]
+    },
+    ".claude/skills/ro-debug/SKILL.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "4a391a0a42b613683d897e2b4fa46db4eb0e778cbfc1e4d4340bb855073de528"
+      ]
+    },
+    ".claude/skills/worktree-task/SKILL.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "1eedb9b3429f2d032181606924815dd8befbe7a79ba209655858fcdac189793c"
+      ]
+    },
+    "CLAUDE.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "8a4f5fab7cbaf3ba2482035f7ddb3cf6e3a3a3313596d25a856506e970d55db7",
+        "a247fdd1d198777f4963da42ccc10dfd9c372f4bb0488d2c0201a49d6bfd1910"
+      ]
+    },
+    "PLAN.md": {
+      "since": "0.3.0",
+      "hashes": [
+        "1691fba2791d7d893e366e4a18bc120d4e4a96213bebbfb2a28881e13de74389"
+      ]
+    }
+  }
+}

package/templates/skeleton/aws-serverless/.github/workflows/deploy.yml

@@ -53,5 +53,38 @@ jobs:
           role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
           aws-region: ${{ vars.AWS_REGION || '__REGION__' }}
 
+      # `--require-approval never` is deliberate and dev-only: this workflow has
+      # no production path at all (see the header), so the approval prompt would
+      # only ever block an unattended dev deploy on a change nobody is watching.
       - if: steps.guard.outputs.skip != 'true'
-        run: pnpm --filter @app/infra exec cdk deploy AppStack WebStack --require-approval never
+        run: >
+          pnpm --filter @app/infra exec cdk deploy AppStack WebStack
+          --require-approval never --outputs-file cdk-outputs.json
+
+      # The bundle is built above and the bucket is created by the deploy — but
+      # nothing puts one into the other, so without this step CloudFront keeps
+      # serving whatever was uploaded by hand, last time somebody remembered.
+      # `web-stack.ts` deliberately does not use BucketDeployment (synth must
+      # never depend on `next build` having run), which is why the upload lives
+      # here rather than in the stack.
+      - if: steps.guard.outputs.skip != 'true'
+        name: Upload the web bundle and invalidate the edge cache
+        run: |
+          # `jq -r` prints the string "null" and exits 0 for a missing key, and
+          # GitHub's shell is `bash -e` with no `-u` and no pipefail — so a
+          # renamed stack or a half-finished deploy would sync the bundle into
+          # `s3://null`, a real bucket in a global namespace someone else owns,
+          # and issue --delete against it. `-e` makes jq exit non-zero instead.
+          set -euo pipefail
+          BUCKET=$(jq -er '.WebStack.WebBucketName' infra/cdk-outputs.json)
+          DISTRIBUTION=$(jq -er '.WebStack.WebDistributionId' infra/cdk-outputs.json)
+          # An existing-but-empty bundle syncs zero objects, and --delete then
+          # empties the live site with a green checkmark.
+          [ -n "$(ls -A apps/web/out 2>/dev/null)" ] || {
+            echo "apps/web/out is empty — refusing to sync"; exit 1;
+          }
+          # --delete makes the bucket the bundle's territory alone: anything not
+          # in this build is removed from it.
+          aws s3 sync apps/web/out "s3://$BUCKET" --delete
+          aws cloudfront create-invalidation \
+            --distribution-id "$DISTRIBUTION" --paths '/*'

package/templates/skeleton/aws-serverless/README.md

@@ -45,13 +45,27 @@ do not edit the workflow:
 
 1. In AWS, create an IAM role your repo can assume via GitHub's OIDC provider
    (`token.actions.githubusercontent.com`) — a short-lived federated role, no
-   long-lived access keys anywhere.
-2. Add its ARN as the repository secret **`AWS_DEPLOY_ROLE_ARN`** (and,
-   optionally, repo variables `AWS_REGION` and `API_URL`).
-
-The workflow then assumes the role, builds the web bundle, and runs
-`cdk deploy AppStack WebStack`. The web bundle is served from S3 + CloudFront
-(the `WebUrl` output).
+   long-lived access keys anywhere. Beyond what `cdk deploy` needs, the
+   workflow uploads the bundle itself, so the role also needs
+   **`s3:ListBucket`, `s3:PutObject`, `s3:DeleteObject`** on the web bucket and
+   **`cloudfront:CreateInvalidation`** on the distribution. A role scoped only
+   to CDK's bootstrap roles gets through the deploy and fails on the upload —
+   after both stacks are already up.
+2. Add its ARN as the repository secret **`AWS_DEPLOY_ROLE_ARN`**, and set the
+   repo variable **`API_URL`** to the deployed API's URL (the `ApiUrl` output
+   of a first deploy). It becomes `NEXT_PUBLIC_API_URL`, which Next **inlines
+   into the bundle at build time** — unset, the site calls `/notes` on its own
+   CloudFront domain, where nothing answers. `AWS_REGION` is genuinely
+   optional. The first deploy is therefore two passes: deploy, read `ApiUrl`
+   from the job's `cdk deploy` Outputs, set the variable, then re-run the
+   workflow (push, or **Run workflow** — it is `workflow_dispatch`-enabled).
+
+The workflow then assumes the role, builds the web bundle, runs
+`cdk deploy AppStack WebStack --outputs-file`, then **uploads `apps/web/out` to
+the web bucket (`aws s3 sync --delete`) and invalidates the CloudFront cache**,
+reading both destinations from the stack outputs. You do not sync anything by
+hand on this path. The site is served from S3 + CloudFront (the `WebUrl`
+output).
 
 ### Local / manual
 
@@ -59,8 +73,26 @@ The workflow then assumes the role, builds the web bundle, and runs
 # needs AWS credentials; region comes from your profile (generator default: __REGION__)
 cd infra
 npx cdk bootstrap   # first time per account/region
-npx cdk deploy AppStack WebStack
-aws s3 sync ../apps/web/out "s3://<WebBucketName output>"
+npx cdk deploy AppStack WebStack --outputs-file cdk-outputs.json
+# --delete makes the bucket the bundle's territory alone, so a stale or missing
+# `out/` would empty the live site — or restore last month's. The workflow
+# builds two steps before its sync; by hand, build here.
+# Read the outputs into variables FIRST. `jq -er` exits non-zero on a missing
+# key, but a command substitution inside an assignment or an argument throws
+# that status away — which is how a stale outputs file becomes a bundle built
+# against `null` and an `aws s3 sync … s3://null --delete`.
+API=$(jq -er '.AppStack.ApiUrl' cdk-outputs.json) || { echo "no ApiUrl"; exit 1; }
+BUCKET=$(jq -er '.WebStack.WebBucketName' cdk-outputs.json) || { echo "no WebBucketName"; exit 1; }
+DIST=$(jq -er '.WebStack.WebDistributionId' cdk-outputs.json) || { echo "no WebDistributionId"; exit 1; }
+
+# NEXT_PUBLIC_API_URL is inlined at build time: without it the bundle calls its
+# own CloudFront domain instead of the API, and the sync below makes that live.
+(cd .. && NEXT_PUBLIC_API_URL="$API" pnpm build:web)
+[ -f ../apps/web/out/index.html ] || { echo "no web bundle — build failed"; exit 1; }
+aws s3 sync ../apps/web/out "s3://$BUCKET" --delete
+# a synced bucket whose distribution still serves the old objects has not
+# deployed — invalidate, or you are looking at the previous build
+aws cloudfront create-invalidation --paths '/*' --distribution-id "$DIST"
 ```
 
 ### Production — a human step, on purpose
@@ -76,12 +108,41 @@ your own approval — reusing the dev workflow's OIDC pattern.
 After every deploy:
 
 ```sh
+# From the deploy's outputs file — run this from `infra/`, where the manual
+# section leaves you. Deployed through CI instead? That file is written on the
+# runner and never lands here: take both values from the job's `cdk deploy`
+# Outputs, or re-run `cdk deploy … --outputs-file cdk-outputs.json` locally.
+API_URL=$(jq -er '.AppStack.ApiUrl' cdk-outputs.json)
+WEB_URL=$(jq -er '.WebStack.WebUrl' cdk-outputs.json)
+
 curl -s -X POST "$API_URL/notes" \
   -H 'content-type: application/json' \
   -d '{"title":"smoke test","tags":["deploy"]}'
 # expect: HTTP 201 with { "note": { … } }
 ```
 
+**That checks the API, not the site.** The two fail independently: a bundle
+built without `NEXT_PUBLIC_API_URL` calls its own CloudFront domain, and a
+misnamed origin is refused by the browser — neither is visible to a `curl` that
+sends no `Origin` header. So also open the `WebUrl` output, create a note in
+the form, and reload:
+
+```sh
+curl -s -I "$WEB_URL" | head -1                      # the bundle is served
+
+# API Gateway answers a preflight 204 whether or not the origin matched, so the
+# status code proves nothing here. The browser gates on the echoed header —
+# that is what to look for. `content-type` is sent because the real call uses
+# it, and a non-safelisted header is what makes `allowHeaders` matter.
+curl -s -X OPTIONS "$API_URL/notes" -D - -o /dev/null \
+  -H "Origin: $WEB_URL" \
+  -H 'access-control-request-method: POST' \
+  -H 'access-control-request-headers: content-type' \
+  | grep -i '^access-control-allow-origin:'
+# expect: a line echoing $WEB_URL. No line = the browser will refuse the call,
+# whatever the status code said.
+```
+
 Then confirm the pipeline: the worker logs `note.created processed`, and the
 **DLQ alarm stays quiet**. If the smoke test regresses: `npx cdk deploy` the
 previous revision (or `git revert` and redeploy) **first**, diagnose second.
@@ -95,5 +156,26 @@ previous revision (or `git revert` and redeploy) **first**, diagnose second.
 - `packages/db` is the only module that touches the storage SDK.
 - A failing queue message is poison: it throws, SQS retries ×3, the DLQ alarm
   fires. Never wrap the worker in a broad catch.
+- **Creating a note is a dual write, and it is not atomic.** `create-note`
+  puts to DynamoDB and then publishes to SQS. If the publish fails, the note
+  is stored and its event never happened — the worker never runs, and nothing
+  compensates; the caller gets a 500 for a note that exists. That is a
+  deliberate simplification for a starter. When it starts to matter, the two
+  ways out are an **outbox** (write the event alongside the note, relay it
+  afterwards) or DynamoDB Streams feeding the worker, which deletes the second
+  write instead of coordinating it.
+- **CORS names who may call the API, and that half is wired for you.**
+  `bin/app.ts` builds `WebStack` first and passes its CloudFront origin to
+  `AppStack`, so the API allows the deployed site without you configuring it.
+  The other half is not automatic: the bundle has to know where the API *is*,
+  and that is `NEXT_PUBLIC_API_URL` above. For a custom domain or a second
+  origin, deploy with `-c allowedOrigins=https://app.example.com` (comma-
+  separated for several) — the entrypoint prefers the flag over the wired
+  default, and the cross-stack export disappears with it. An `allowedOrigins`
+  that parses to nothing, or an entry no browser could send, is refused at
+  synth rather than deployed as an API nobody can call. `*` is not the default
+  and never will be, but the flag does take it: you get a warning naming the
+  consequence, not a refusal, because the alternative is people editing the
+  stack.
 
 See `.claude/rules/architecture.md` for the full rules.

package/templates/skeleton/aws-serverless/apps/web/src/lib/api.ts

@@ -2,8 +2,15 @@
 // (the guard-web-boundary hook refuses such imports at the tool layer).
 import type { Note } from '@app/core';
 
-// Same-origin by default (the API server serves this bundle); set
-// NEXT_PUBLIC_API_URL at build time when the API lives elsewhere.
+// In THIS target the API is never same-origin: the bundle is served from
+// CloudFront and the API is API Gateway, so `NEXT_PUBLIC_API_URL` has to be set
+// at build time — Next inlines it, and an unset one leaves the empty string
+// here, which sends every call to whatever is serving this page.
+//
+// The `?? ''` is a fallback to nothing, not to a working default: there is no
+// dev proxy in this project, so `pnpm --filter @app/web dev` needs the variable
+// too. It exists only so a missing value is a relative URL rather than the
+// string "undefined" in a request path.
 const base = process.env.NEXT_PUBLIC_API_URL ?? '';
 
 export async function createNote(input: { title: string; tags: string[] }): Promise<Note> {

package/templates/skeleton/aws-serverless/gitignore

@@ -2,16 +2,53 @@ node_modules/
 dist/
 coverage/
 cdk.out/
+# what `cdk deploy --outputs-file` writes: bucket names, distribution ids,
+# endpoints. Harmless today, and the file that accumulates the ones that are not.
+cdk-outputs.json
 *.tsbuildinfo
 .DS_Store
 .next/
 out/
 next-env.d.ts
 .claude/worktrees/
+# per-checkout queue state: the tier the last close recorded. The queue CONFIG
+# is composed and tracked; this is runtime state and must never be committed.
+.claude/queue.state.json
+# gate rounds, one count per branch
+.claude/gate-rounds.json
+# per-run machine trace (.claude/scripts/run-journal.mjs): forensics that churn
+# on every gate and collide across concurrent sessions. Unlike a committed
+# evidence directory, this one is per-run and stays out of the repository.
+.claude/runs/
 
 # secrets — never commit these
+*.env
 .env
 .env.*
 !.env.example
+.envrc
+.npmrc
+.netrc
+.pgpass
+id_rsa
+id_ed25519
 *.pem
 *.key
+*.p12
+*.pfx
+*.keystore
+*.jks
+*.secret
+*.secrets
+*.token
+*.tokens
+*.password
+*.passwords
+*.credential
+*.credentials
+*.apikey
+*.apikeys
+*.passwd
+*.creds
+*.jwt
+*.bearer

package/templates/skeleton/aws-serverless/infra/bin/app.ts

@@ -1,19 +1,79 @@
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { App } from 'aws-cdk-lib';
-import { AppStack } from '../lib/app-stack.js';
+import { AppStack, nothingGiven } from '../lib/app-stack.js';
 import { WebStack } from '../lib/web-stack.js';
 
-const app = new App();
+/**
+ * The composition, as a function so a test can synthesise the same wiring the
+ * CLI gets. A test that re-wires the stacks itself would pass while this file
+ * stayed broken, which is the one failure worth catching here.
+ */
+export function createApp(): App {
+  const app = new App();
 
-// Region-agnostic by default; `cdk deploy` uses your CLI profile. Pin it here
-// when the project settles (the generator's default region is __REGION__).
-const env = { region: process.env.CDK_DEFAULT_REGION };
+  // Region-agnostic by default; `cdk deploy` uses your CLI profile. Pin it here
+  // when the project settles (the generator's default region is __REGION__).
+  const env = { region: process.env.CDK_DEFAULT_REGION };
 
-new AppStack(app, 'AppStack', {
-  description: 'API + worker for __PROJECT_NAME__ (generated by create-agent-rig)',
-  env,
-});
+  // The web stack first: the API has to allow the origin the browser loads the
+  // app from, and that origin is a CloudFront domain this stack owns. Passing
+  // it makes CORS correct on the first deploy instead of after someone
+  // discovers the app is blocked and reaches for `*`.
+  //
+  // The price, so it is not discovered later: this is a cross-stack export, so
+  // WebStack is deploy-ordered before AppStack and cannot be torn down while
+  // AppStack still imports it — CDK warns about the reference strength on
+  // synth. Pass `allowedOrigins` explicitly (a custom domain, several origins)
+  // and the export disappears with it.
+  const web = new WebStack(app, 'WebStack', {
+    description: 'Static web serving for __PROJECT_NAME__ (generated by create-agent-rig)',
+    env,
+  });
 
-new WebStack(app, 'WebStack', {
-  description: 'Static web serving for __PROJECT_NAME__ (generated by create-agent-rig)',
-  env,
-});
+  // `-c allowedOrigins=…` wins over the wired default — a custom domain is a
+  // deliberate act, and props short-circuit the context inside AppStack, so
+  // passing them unconditionally would accept the flag and ignore it. Omitting
+  // the prop hands the flag to AppStack's own validation instead of dropping
+  // it: an unusable value is refused at synth rather than deployed.
+  // `nothingGiven` is imported rather than restated: this file and the stack
+  // both decide whether the operator supplied an origin, and two spellings of
+  // that question is how `"allowedOrigins": null` in cdk.json comes to mean
+  // "they chose one" here and "use the default" there — a green synth whose
+  // deployed API allows only localhost.
+  const override = app.node.tryGetContext('allowedOrigins');
+
+  new AppStack(app, 'AppStack', {
+    description: 'API + worker for __PROJECT_NAME__ (generated by create-agent-rig)',
+    env,
+    ...(nothingGiven(override) ? { allowedOrigins: [web.origin] } : {}),
+  });
+
+  return app;
+}
+
+/**
+ * Only when the CDK CLI runs this file. A test importing `createApp` would
+ * otherwise build a second composition — and re-bundle three Lambdas — for an
+ * App nobody looks at.
+ *
+ * Both sides go through realpath: ESM resolves `import.meta.url` through
+ * symlinks while `process.argv[1]` keeps the path as typed, so a checkout
+ * behind a link (a macOS temp dir, a symlinked home) would fail a plain
+ * comparison and synthesise an empty app.
+ */
+function invokedDirectly(): boolean {
+  if (!process.argv[1]) return false;
+  const real = (p: string) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  return real(fileURLToPath(import.meta.url)) === real(process.argv[1]);
+}
+
+if (invokedDirectly()) {
+  createApp();
+}