ds golden
On this page
- ds golden build (alias: load)
- ds golden push
- ds golden import
- ds golden reanchor
- ds golden status
- ds golden refresh-stage
- ds golden aichat
- ds golden enrich
- ds golden lifecycle
- ds golden reset
- ds golden cognito
- ds golden preview
- ds golden recertify
- ds golden reconcile
- ds golden release <action>
- ds golden install
- ds golden invite-admin
- ds golden cognito-sandbox / aichat-sandbox / s3-sandbox
Defined in cli/commands/golden.ts. Manages the golden demo/test dataset — the Acme organization — on the bound stage. Twenty subcommands, all lazy-imported so only the one you invoke loads the heavy backend graph. They fall into three groups:
| Group | Subcommands | Use it to |
|---|---|---|
| Seed a stage | build (load), push, import, refresh-stage, reanchor, aichat, cognito, enrich, reset, lifecycle, preview, status |
Get Acme onto a stage, keep its dates at "today", and check its health |
| Keep the golden source current | recertify, reconcile, release <action> |
Maintain the canonical source database every stage and training sandbox clones from |
| Training sandboxes | install, invite-admin, cognito-sandbox, aichat-sandbox, s3-sandbox |
Mint one customer-facing sandbox organization from the source, and tear its identities down |
Every mutating subcommand is guarded by assertGoldenStageWritable: all mutating golden subcommands refuse to run against prod. On the shared dev stage only the additive verbs are allowed — import, reanchor, refresh-stage, aichat and cognito — while build, reset, enrich, lifecycle and push are refused there. push is a whole-DB replace and is refused on both prod and dev; it is only safe on a fresh, disposable stage.
`--org` accepts only `acme`
Several subcommands' own help text still lists
acme|bright|indie|brightTrialfor--org. The golden spec'sORG_IDSis Acme-only, so every other name is rejected at runtime. Acme is the whole dataset.
ds golden build (alias: load)#
ds golden build [--no-reset] [--no-verify] [--skip-cognito] [--org <name>]
Rebuilds the golden Acme org, in the bound DB, from the generator spec (real CommandBus calls), ends with a full aggregation recalculation, runs the §16 assertion gate, then creates the Cognito logins. Scoped — only the Acme org's rows are reset/rebuilt; everything else on the stage is untouched. load is a Commander alias of build, not a separate implementation. On the fully-local Docker stack (ds worktree cli <instance> golden build) the §16 gate is skipped automatically.
| Flag | Description |
|---|---|
--no-reset |
Skip the reset — only on a clean target where the Acme org is absent |
--no-verify |
Skip the §16 assertion gate after building |
--skip-cognito |
Skip the Cognito login reconciliation at the end (ds golden cognito runs it later) |
--org <name> |
Rebuild a specific golden org in place (currently only acme) |
ds golden push#
ds golden push --force-full-reset [--allow-any-scale] [--skip-aichat] [--skip-cognito] [--dry-run] [--target-db <connectionString>]
Fast whole-database seed: pg_dumps the locally vitest-built golden template DB and pg_restores it straight into the bound stage's Postgres, then re-seeds the DynamoDB AI chats and Cognito logins. This is a whole-DB replace, intended only for fresh/disposable stages — it is refused by the stage guard on both prod and dev.
| Flag | Description |
|---|---|
--force-full-reset |
Required to proceed — drops the stage's public + drizzle schemas and replaces all stage data with the golden template |
--allow-any-scale |
Skip the full-scale floor check (allows pushing a dev-scale template) |
--skip-aichat |
Skip the DynamoDB AI-chat leg |
--skip-cognito |
Skip the Cognito login leg |
--dry-run |
Run preflight checks (container/template/scale) and print the target + template + row counts, but drop/restore nothing |
--target-db <connectionString> |
Push to an explicit Postgres connection string instead of the bound stage — used to publish the gated template into the dedicated golden source DB and for CI. Relaxes the stage journal guard and skips the AWS-bound aichat/Cognito legs |
ds golden import#
ds golden import [--org <name>] [--skip-aichat] [--source <envVarName|connectionString>] [--dry-run]
Additive, org-scoped seed: copies the golden persona org(s) from the canonical golden source (GOLDEN_DB_CONNECTION_STRING — distinct from the generic SOURCE_DB_CONNECTION_STRING used by ds data copy) into the bound stage without wiping it. This is the safe path for shared/populated stages such as app.devstride.dev. Cognito logins are created as part of the copy.
| Flag | Description |
|---|---|
--org <name> |
Import one persona org instead of all. Currently acme is the only golden persona org — the CLI's own help text still lists bright/indie/brightTrial as options, but ORG_IDS in the golden spec is Acme-only, so those other names are rejected at runtime |
--skip-aichat |
Skip the DynamoDB AI-chat leg |
--source <envVarName|connectionString> |
Golden source override — a connection string, or the name of an env var. Defaults to GOLDEN_DB_CONNECTION_STRING, then an interactive picker at a TTY |
--dry-run |
Run the parity/provenance checks and print the planned orgs, but make no changes |
The migration-drift guard
Both
ds golden pushandds golden importrefuse to run when the checkout, the golden source, and the target stage are not on the same set of migrations — the guard that stops a golden copy landing on a schema it was not built for. It compares journal membership, not order, so a database that applied a migration out of band is not mistaken for drift, and when it does fire the error names the migrations actually missing on each side rather than a position in the list.
ds golden reanchor#
ds golden reanchor [--to <YYYY-MM-DD|today>] [--shift <±days>] [--org <name>] [--target-db <connectionString>] [--dry-run]
Shifts an already-built stage's entire temporal dataset (item dates, transactions, activity logs, timeboxes, roadmaps, custom-field dates, …) by a uniform delta without rebuilding — re-anchors the demo to a new "today". Transactional, with a post-shift sanity probe. Operational times are left where they are: sign-in and authorization tokens, integration leases, billing records, jobs and sweep countdowns are never shifted, so a re-date cannot strand a lease, re-fire a sweep or rewrite an audit trail.
| Flag | Description |
|---|---|
--to <YYYY-MM-DD|today> |
Re-anchor to an absolute target date (delta = target − stored anchor). Default when no flag is given: today (real wall-clock UTC) |
--shift <±days> |
Relative shift in whole days (mutually exclusive with --to) |
--org <name> |
Reanchor one persona org instead of all. Currently acme-only in practice — see the note on ds golden import above |
--target-db <connectionString> |
Shift an explicit Postgres DB (e.g. the local golden template) instead of the bound stage — for testing; skips the AWS AI-chat leg |
--dry-run |
Read the stored anchor, compute the delta, print the plan + row counts, mutate nothing |
ds golden status#
ds golden status [--target-db <connectionString>] [--skip-source]
Read-only health report: are the persona orgs present, is the dataset anchored at today, is it in sync with the canonical source, does Acme carry the full 5-status cumulative-flow staircase. Mutates nothing; exits non-zero when missing/stale/out-of-sync.
| Flag | Description |
|---|---|
--target-db <connectionString> |
Inspect an explicit Postgres connection string instead of the bound stage |
--skip-source |
Skip the comparison against the canonical golden source |
ds golden refresh-stage#
ds golden refresh-stage [--org <name>] [--skip-aichat]
One-shot recovery command: additive import → reanchor --to today → verify. Use this when a dev stage was reset and the golden orgs disappeared. Rebuilds nothing (pulls the intact gated source); safe to re-run; leaves other tenants untouched.
| Flag | Description |
|---|---|
--org <name> |
Refresh one persona org instead of all. Currently acme-only in practice — see the note on ds golden import above |
--skip-aichat |
Skip the DynamoDB AI-chat leg of the import |
ds golden aichat#
ds golden aichat [--org <name>] [--force]
Seeds the golden AI-assistant chats in DynamoDB. Run after push or build if the Dynamo leg was skipped or failed.
| Flag | Description |
|---|---|
--org <name> |
Only seed one org's chat. Currently acme-only in practice — see the note on ds golden import above |
--force |
Delete each persona's existing chat(s) before seeding, so an updated transcript is written instead of the stale one being kept |
ds golden enrich#
ds golden enrich [--org <name>] [--aspect <names...>]
Additively patches an existing golden org in place — descriptions, activity, and similar polish — without a rebuild. Idempotent, never truncates. Distinct from build, which rebuilds from scratch.
| Flag | Description |
|---|---|
--org <name> |
The org to enrich. Default: acme (currently the only scaled org with an enrich profile) |
--aspect <names...> |
Which data point(s) to patch: descriptions, archive-example, feature-planning, admin-governance, pi-objectives, comments, time-entries, activity (slow). Default: all aspects. The command's own help text lists only six of the eight; ALL_ENRICH_ASPECTS in backend/tests/golden/generator/enrich.ts is the authority |
ds golden lifecycle#
ds golden lifecycle [--workers <n>] [--target-db <connectionString>]
Work in progress
The command's own description marks it "[WIP — not yet functional via the CLI]". The partition + walk logic is determinism-verified in-process, but the CLI path needs the DynamoDB item "state" read-model alive and populated locally, which vitest tears down after a build. Documented here for completeness, not as a reliable everyday tool.
Intended purpose: parallel lane walk that gives every scaled Acme item a back-dated PUBLISHED lane/status history across N worker processes. No-op at representative scale; idempotent and deterministic when it does run.
| Flag | Description |
|---|---|
--workers <n> |
Number of worker processes. Default: min(8, cores) or GOLDEN_LIFECYCLE_WORKERS |
--target-db <connectionString> |
Run the walk against an explicit Postgres DB instead of the bound stage — canonical use is the local Docker golden template |
ds golden reset#
ds golden reset [--org <name>]
Deletes the golden Acme org's rows in the bound DB. Scoped — only the Acme org is removed; all other data on the stage is left intact (never a whole-DB truncate).
| Flag | Description |
|---|---|
--org <name> |
Reset a specific golden org (currently only acme) |
ds golden cognito#
ds golden cognito [--org <name>]
Seeds Cognito logins (password Demo@123) for the golden persona users. Run after build.
| Flag | Description |
|---|---|
--org <name> |
Only seed one org's users. Currently acme-only in practice — see the note on ds golden import above |
ds golden preview#
ds golden preview
Renders the golden spec to text — pure spec-to-text dump, no DB access at all. No flags. ds -u golden preview skips the SSO bind as well.
ds golden recertify#
ds golden recertify [--source <envVarName|connectionString> | --bound] [--dry-run]
Re-runs the §16 assertion gate against an already-built golden source and re-stamps its clone certification, without rebuilding (minutes, not hours). Certification is bound to the checkout's full migration journal, so any migration that lands decertifies the source and makes sandbox clone and reset refuse; this is the cheap fix. It genuinely re-executes every assertion and stamps only on a clean pass — a failing gate leaves the source uncertified.
| Flag | Description |
|---|---|
--source <envVarName|connectionString> |
The database to re-certify. Default: GOLDEN_DB_CONNECTION_STRING, the canonical source. Certified with scope postgres-only: the Dynamo-backed AI-chat assertion is skipped because the source holds no chats |
--bound |
Re-certify the bound stage's own database instead (scope full). Mutually exclusive with --source |
--dry-run |
Check that the recorded gate handle is complete and the anchor resolves, then stop |
ds golden reconcile#
ds golden reconcile [--source <envVarName|connectionString>]
Brings the canonical golden source up to this checkout's revision. A source that already matches (expansion journal, contract journal and generator digest) is not re-stamped, which preserves sandbox provenance. Journal drift — a migration landed — takes the cheap tier: run both migration chains, re-run the §16 gate, re-stamp (it delegates to recertify). Generator drift, or a source with no recorded generator provenance, exits 42 immediately: re-certification re-proves data, it does not re-run the generator, so only a full rebuild helps. The Golden Dataset — Refresh Source workflow runs this after every push to master and pages the operator on exit 42; run by hand, it re-checks production liveness only when GOLDEN_RECONCILE_LIVENESS_COMMAND is set, so a manual run must come from a checkout at production's live revision. --source defaults to GOLDEN_DB_CONNECTION_STRING and refuses the bound stage's own database. The full runbook is Workflow B in the repository's docs/golden/stages-and-secrets.md.
ds golden release <action>#
ds golden release <probe|prepare|check|publish> [--candidate <sha>] [--artifact-root <directory>] [--source-env <name>] [--merge-commit <sha>]
ds golden release ahead <start|status|wait>
Prepares and verifies the golden source around a production release, so the source is never migrated ahead of production and no expensive build runs in cloud CI. probe reports what the candidate needs; prepare exports a current source, rehearses ordinary migrations against a local copy, and runs a full local build when the generator changed or a data check failed; check is the release's mandatory local pre-ship gate (golden-source-release-readiness in .claude/ds-config.json) and refuses missing, stale, corrupt or wrong-candidate evidence; publish runs after the matching production revision is live and healthy.
A full local build takes about two hours, so two things keep a release from paying for it more than once, or late:
- The build is filed under a preparation key, not under one commit. The key is a fingerprint of the golden generator and of the content of the database migrations. A fix commit added to the release afterwards keeps the prepared archive as long as it changes neither, so the release does not rebuild.
checkaccepts a keyed archive only when its key matches the release's, the release contains the commit it was built from, it is under 24 hours old, and it is a full build. Archives that are not full builds (a current source, or a rehearsed migration) are prepared in minutes and stay tied to the exact commit. - The build can start early, at the release train.
ahead startruns while the train's pull request is still in review. When the release needs a full build, it starts that build in the background in the main checkout only, and only when main is free: not leased, clean, not on someone's branch, and with no app, test run or shell open in it. Otherwise nothing starts early and the release prepares in its own checkout after the cut, as before. It never takes a worktree checkout. When the build ends, it stops what it started and hands main back, leaving it detached at the latestdevelop.ahead statusprintsREADY,RUNNING,FAILEDorNONEfor the checkout's key;ahead waitwaits for a running build, checking every minute for at most 150 minutes, and the release'scheckruns after it whatever the result.
| Flag | Description |
|---|---|
--candidate <sha> |
The reviewed release source commit. Default: HEAD |
--artifact-root <directory> |
Private absolute archive directory. Default: GOLDEN_RELEASE_ARTIFACT_ROOT, else the checkout default |
--source-env <name> |
Environment variable holding the canonical source URL. Default: GOLDEN_DB_CONNECTION_STRING |
--merge-commit <sha> |
The production merge to verify before publication |
Keyed full builds are stored on the machine under ~/.local/state/devstride/golden-release/by-key/key-<key>/, with the early build's log beside them. The repository's ds-golden-release skill owns the procedure; the release's train-stage check golden-prepare-ahead runs ahead start, and the release skill's post-deploy check (ds-post-deploy-release-check) runs publish.
ds golden install#
ds golden install --slug <slug> [--label <label>] [--org-id <uuid>] [--day <YYYY-MM-DD>] [--source <envVarName|connectionString>] [--target-db <connectionString>] [--customer-email <email>] [--skip-cognito] [--skip-aichat] [--resume] [--dry-run]
Never-truncate sandbox provisioning: mints one new sandbox organization from the certified golden source through the additive clone engine (insert-only, the target org identity must be free, bystander tenants untouched, §16-gated), reanchored so the clone reads as "today". There is no wipe flag here by design; whole-DB replaces belong to push.
| Flag | Description |
|---|---|
--slug <slug> |
Required. Becomes the org name and the acme.<slug>. user-identity namespace. acme is reserved |
--label <label> |
Display label for the sandbox org. Default: ACME-<SLUG> |
--org-id <uuid> |
Explicit target organization id. Default: freshly minted |
--day <YYYY-MM-DD> |
The UTC day the clone should read as "today". Default: today |
--source <envVarName|connectionString> |
Golden source override. Default: GOLDEN_DB_CONNECTION_STRING |
--target-db <connectionString> |
Install into an explicit Postgres connection string instead of the bound stage |
--customer-email <email> |
Invite this email as org Admin of the new sandbox (bound stage only; refused with --target-db). The customer completes signup with their own password |
--skip-cognito / --skip-aichat |
Skip the post-install persona-login or demo-chat legs; cognito-sandbox / aichat-sandbox run them later |
--resume |
Continue an install whose clone committed but whose post-clone legs failed: skips the clone and re-runs the idempotent Cognito, AI-chat and invite legs for this --slug |
--dry-run |
Resolve, validate and print the install plan; connect to nothing |
ds golden invite-admin#
ds golden invite-admin --org-id <uuid> --email <email>
Invites a customer's real email as org Admin of an already-installed sandbox: creates the invited placeholder user and Admin membership and sends the standard invitation email. The customer signs up with their own password, which mints their Cognito identity and activates the membership. Additive and idempotent: re-running resends the invite for a still-invited member and does nothing for an active one.
ds golden cognito-sandbox / aichat-sandbox / s3-sandbox#
ds golden cognito-sandbox --org-id <uuid> [--teardown]
ds golden aichat-sandbox --org-id <uuid> [--anchor-iso <iso>] [--force]
ds golden s3-sandbox --org-id <uuid> --teardown
The per-sandbox legs, all fail-closed to sandbox orgs and the acme.<slug>. namespace, so sibling orgs and the canonical golden data are never touched:
| Command | What it does |
|---|---|
cognito-sandbox |
Materializes the sandbox's persona logins in the shared per-stage pool (username = the cloned stable user id, a deterministic non-routable email, the permanent demo password). --teardown deletes only the sandbox's recorded identities and proves siblings intact |
aichat-sandbox |
Seeds the canonical demo AI-chat transcript into the sandbox, owned by the clone-mapped demo persona and stamped at the sandbox's anchor (--anchor-iso overrides it). --force deletes the persona's existing sandbox chats first |
s3-sandbox |
Teardown only (--teardown is required): deletes the S3 objects the sandbox's users uploaded live, under the sandbox's own org-id and persona key prefixes. There is no S3 provisioning at install — golden assets are inline data URIs |