@intentius/behold 0.30.0 → 0.30.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/AGENTS.md +97 -33
  2. package/README.md +78 -56
  3. package/dist/cli.js +6913 -2448
  4. package/example-choudoufu-estate/chant.workspace.json +1 -1
  5. package/example-terraform-estate/README.md +1 -1
  6. package/example-terraform-estate/chant.workspace.json +1 -1
  7. package/example-terralith/README.md +1 -1
  8. package/example-three-cloud/package-lock.json +19 -19
  9. package/example-three-cloud/package.json +4 -4
  10. package/package.json +5 -5
  11. package/web/app.js +330 -19
  12. package/web/embed.js +2 -2
  13. package/web/event-help-modal.js +18 -12
  14. package/web/event-help-modal.test.js +28 -1
  15. package/web/index.html +18 -0
  16. package/web/kiosk-ask-layout.js +85 -0
  17. package/web/kiosk-ask-layout.test.js +83 -0
  18. package/web/kiosk-ask-tips.js +467 -0
  19. package/web/kiosk-ask-tips.test.js +359 -0
  20. package/web/kiosk-ask.js +774 -0
  21. package/web/kiosk-ask.test.js +593 -0
  22. package/web/kiosk-banner.js +108 -0
  23. package/web/kiosk-banner.test.js +72 -0
  24. package/web/kiosk-center-cards.test.js +110 -0
  25. package/web/kiosk-estate-scene.js +203 -0
  26. package/web/kiosk-estate-scene.test.js +21 -0
  27. package/web/kiosk-event-help.js +4 -1
  28. package/web/kiosk-graph-pane.js +63 -0
  29. package/web/kiosk-graph-pane.test.js +105 -0
  30. package/web/kiosk-light-frame.js +196 -0
  31. package/web/kiosk-light.js +509 -0
  32. package/web/kiosk-light.test.js +297 -0
  33. package/web/kiosk-metrics.js +7 -4
  34. package/web/kiosk-modal-sticky.test.js +2 -1
  35. package/web/kiosk-refit.test.js +81 -0
  36. package/web/kiosk-reset.js +49 -0
  37. package/web/kiosk-reset.test.js +11 -0
  38. package/web/kiosk-shot.js +40 -2
  39. package/web/kiosk-shot.test.js +23 -1
  40. package/web/kiosk-vendor.js +85 -7
  41. package/web/kiosk-vendor.test.js +9 -9
  42. package/web/kiosk-watch.js +8 -4
  43. package/web/kiosk.html +107 -1
  44. package/web/kiosk.js +149 -23
  45. package/web/kiosk.test.js +25 -1
  46. package/web/layout-store.js +3 -3
  47. package/web/small-stage.test.js +4 -0
  48. package/web/terragucci-change.js +30 -13
  49. package/web/tool-mark.js +4 -4
  50. package/web/tool-mark.test.js +1 -1
  51. package/web/vendors/atmos.svg +1 -0
  52. package/web/vendors/chant.svg +1 -0
  53. package/web/vendors/choudoufu.svg +1 -0
  54. package/web/vendors/terragrunt.svg +9 -0
  55. package/web/vendors/terragucci.svg +1 -0
  56. package/web/vendors/choudoufu-128.png +0 -0
  57. package/web/vendors/choudoufu-64.png +0 -0
package/AGENTS.md CHANGED
@@ -369,6 +369,34 @@ checkout declares no Terraform root (`controlRepo` in
369
369
  structural check otherwise. The page (`web/terragucci-estate.js`) draws it
370
370
  in a layer over the graph area.
371
371
 
372
+
373
+ ### The kiosk's prompt pane (#936)
374
+
375
+ A step of terragucci's `demo.json` may carry an `ask` (or `asks`, a list of
376
+ them played in order), and the file may carry `opening` and `closing` strings
377
+ (src/terragucci-demo.ts parses them; a field of the wrong type is null, and an
378
+ ask with none of a prompt, an action and a reply is dropped; a reply alone prints with no line of the person's, as an applied step's does). While a step has an ask,
379
+ the pane (`#k-ask`, web/kiosk-ask.js) takes the place of `#bar` and
380
+ `#k-caption` in Watch: a big monospace block at the foot of the screen. A
381
+ `prompt` is typed after `>` at 40 ms a character; an `action` shows at once
382
+ after a check mark; the `reply` prints after it, with `{roots}`, `{creates}`,
383
+ `{updates}`, `{deletes}` and `{error}` filled from the step's report (an
384
+ unknown token, or one without a value, is empty). The last three entries stay
385
+ above, faded. `opening` shows once at the scenario's first step
386
+ (`pull-request` or `planned`), `closing` at `applied`. While a job runs
387
+ (`pull-request`, `approved`, `merged`, `applying`, `resumed`) a status line
388
+ gives what is happening, the time since `started_at`, and `next`. With
389
+ `prefers-reduced-motion` everything shows at once. The pane's height is fixed
390
+ and replaces the caption in `captionRoomPx`, so it never covers the graph. A
391
+ step without an ask looks as it always did.
392
+
393
+ The pane tells the page through window events, each with detail
394
+ `{ ask, step, scenario }`: `behold:ask-start` before a beat is typed,
395
+ `behold:ask-done` when its reply has printed, and `behold:ask-clear` on a new
396
+ step with no ask. `{dependents}` is left to the lighting: it sets
397
+ `window.beholdAskTokens = { dependents: n }` on `behold:ask-start`, and the
398
+ reply reads it when it prints.
399
+
372
400
  ## Releases per environment, from the release ledger (#525)
373
401
 
374
402
  `GET /api/lifecycle/releases[?fresh=1]` (src/lifecycle-releases.ts) reads
@@ -735,7 +763,7 @@ block in M1.
735
763
 
736
764
  With a traffic level, `/api/overlay` predicts each member twice and carries
737
765
  both figures and their difference. The level is `?traffic=` on the request,
738
- else `.behold.json`'s `{"behaviour": {"traffic": "100 rps, p50"}}`, else none;
766
+ else the per-user settings' `{"behaviour": {"traffic": "100 rps, p50"}}` (src/user-settings.ts, #470), else none;
739
767
  with none nothing is asked for and the payload is exactly M1's. behold never
740
768
  defaults a level, because every figure is *at* one.
741
769
 
@@ -990,7 +1018,9 @@ folder's scratch project. Each capability has its `name`, `meaning`,
990
1018
  it leaves `notEvaluated`, its `rule`, and per lexicon whether it is
991
1019
  supplied. A chant below 0.124.46 answers 422 `code: "chant-too-old"`
992
1020
  (`CAPABILITIES_CHANT_FLOOR`). behold mcp's `capabilities` tool returns the
993
- same text.
1021
+ same text. behold keeps the document per checkout and commit, so a second
1022
+ read of an unmoved checkout runs no chant; a `--public` serve refuses the
1023
+ route with 403 (#978).
994
1024
 
995
1025
  ```
996
1026
  GET /api/capabilities
@@ -1003,7 +1033,7 @@ GET /api/capabilities
1003
1033
 
1004
1034
  `POST /api/view` changes what every open tab of this serve draws. It is a
1005
1035
  view change and writes nothing: no infrastructure, no project file, not
1006
- `.behold/layout.json`, and nothing kept on the server.
1036
+ the layout cache, and nothing kept on the server.
1007
1037
 
1008
1038
  ```
1009
1039
  POST /api/view
@@ -1181,12 +1211,21 @@ best-effort, and only its exit code is certain (src/ci-run.ts).
1181
1211
 
1182
1212
  ### The executor contract (#165, #61)
1183
1213
 
1184
- `.behold.json` may designate which forge deploys an environment:
1214
+ A member's `chant.config.ts` may designate which forge deploys an environment,
1215
+ on the environment's entry (#470):
1185
1216
 
1186
- ```json
1187
- { "executor": { "prod": { "forge": "github", "workflow": "deploy-prod.yml" } } }
1217
+ ```ts
1218
+ environments: [{ name: "prod", executor: { forge: "github", workflow: "deploy-prod.yml" } }]
1188
1219
  ```
1189
1220
 
1221
+ behold reads it from `chant workspace graph --composites --json`
1222
+ (`components[].environments[].executor`, floor `EXECUTOR_CHANT_FLOOR` 0.124.47,
1223
+ src/executor.ts) through the workspace reader. It never reads `.behold.json`'s
1224
+ `executor` (retired; `behold doctor` warns), and never derives it from a
1225
+ `chant-components-<env>` workflow name (maintainer ruling, 2026-10-23). An older
1226
+ chant prints no `executor`, and no row means none declared. `reason.code`
1227
+ `executor-config-unreadable` stays designated and fails closed.
1228
+
1190
1229
  It designates the committed WORKFLOW, not just the forge: two environments'
1191
1230
  generated pipelines carry identical job ids, so a picker cannot tell them
1192
1231
  apart, and a contract that names prod must not sit on a guess. For a
@@ -1219,8 +1258,8 @@ A dispatched run is followed honestly (#165 §6, PR #350): only GitHub's own
1219
1258
  follow deadline promotes the run to `lost` (chips frozen at last-observed,
1220
1259
  the run possibly still live at its own page), never to a verdict. The adopted
1221
1260
  run id is persisted as one JSON per project under `~/.behold/ci-runs/`, the
1222
- operator's machine-state, outside the project tree, so the Invariant below
1223
- still names the whole in-project write surface. `GET /api/ci/run` reads the
1261
+ operator's machine-state, outside the project tree, so behold still writes
1262
+ nothing in a served project (the Invariant below). `GET /api/ci/run` reads the
1224
1263
  record; `POST /api/ci/readopt` (also attempted once at boot) re-follows an
1225
1264
  unconcluded run by its saved id, so a restart mid-deploy leaves the run a
1226
1265
  reader instead of nothing.
@@ -1290,13 +1329,13 @@ chant never signs a person in (ws-052); the surface that does passes the person
1290
1329
  to chant as `--actor` (ws-080). behold has no login, so `src/approver.ts` names
1291
1330
  the person for each request, in this order:
1292
1331
 
1293
- - `--identity-header <name>` (BEHOLD_IDENTITY_HEADER, `.behold.json`
1332
+ - `--identity-header <name>` (BEHOLD_IDENTITY_HEADER, the per-user settings'
1294
1333
  `approver.header`): behold sits behind a proxy that signed the person in
1295
1334
  through the forge or OIDC, and the header names them. A bare login is an
1296
1335
  account on `--identity-forge` (github unless set). A request without the
1297
1336
  header approves nothing (`403 no-identity`). Refused at startup with a
1298
1337
  `--host` other than loopback, since anyone reaching the port could send it.
1299
- - `--as <principal>` (BEHOLD_APPROVER, `.behold.json` `approver.as`): one
1338
+ - `--as <principal>` (BEHOLD_APPROVER, the per-user settings' `approver.as`): one
1300
1339
  person runs behold and names themselves, `github:<login>` or a principal the
1301
1340
  signers file lists.
1302
1341
  - Neither: chant's own fallback (GITHUB_ACTOR, GITLAB_USER_LOGIN, USER), and
@@ -1311,7 +1350,7 @@ Every approve route (`/api/workspace/gates/approve`, the converge gate's
1311
1350
  behold"`. chant's ledger has no channel for a surface (its `origin` is `cli`,
1312
1351
  `mcp` or `acp`), so the note is where behold is named. A workspace gate that
1313
1352
  status marks `signed` is approved with `--sign <key>` when behold holds the
1314
- person's key (`--signing-key` beside `--as`, or `.behold.json`'s
1353
+ person's key (`--signing-key` beside `--as`, or the per-user settings'
1315
1354
  `approver.keys` by principal) and refused `422 signed` with the line to run
1316
1355
  otherwise. The key path never reaches a page: `GET /api/workspace/gates`
1317
1356
  carries `approverIdentity: {principal, source, forge, signs}`, or `approver:
@@ -1576,6 +1615,14 @@ If a request would have behold write to a cloud or to source directly, it's wron
1576
1615
  behold shows truth and triggers Ops. Authority stays in the committed source and the
1577
1616
  executor.
1578
1617
 
1618
+ behold writes nothing in a served project (#469, ruled 2026-10-23). What it
1619
+ keeps for itself (the hand layout, the per-user settings, dispatched CI run
1620
+ ids, recents, the serve registry) lives in the user's own home, cache or temp directory, keyed by the
1621
+ project, never in the tree. The only files behold puts in a project are the
1622
+ ones a person asks for by name: `behold doctor --fix` writing
1623
+ `chant.workspace.json`, and the carve walkthrough writing into the demo copy
1624
+ behold made itself (both below).
1625
+
1579
1626
  The commands behold starts run with behold's own environment, so Deploy (`POST
1580
1627
  /api/apply`, chant's local executor) applies with the credentials of whoever
1581
1628
  started it. On a terragucci repo (a `terragucci.yml` in the served directory or
@@ -1586,7 +1633,7 @@ so the page offers no write, and auto-sync declines. The boundary is an
1586
1633
  allowlist (#500): every request whose method is not GET, HEAD or OPTIONS, on
1587
1634
  any path, answers that `409` unless `TERRAGUCCI_ALLOWED_WRITES` names its
1588
1635
  method and route, and that list holds only the exceptions below (the layout
1589
- sidecar, project open and reveal, demo open, refresh, and the four carve
1636
+ cache, project open and reveal, demo open, refresh, and the four carve
1590
1637
  steps), plus `POST /api/view`, which moves the open tabs and writes nothing
1591
1638
  (#914). A new write route is refused on a terragucci repo until it is added
1592
1639
  there. `src/terragucci-repo.test.ts` walks every non-GET route of the real
@@ -1632,35 +1679,52 @@ These are also the only writes a guarded product repo answers: terragucci
1632
1679
  (`terragucci.yml` and its siblings) and SQL Yodeler (`yodel.config.ts`), both
1633
1680
  listed in `TERRAGUCCI_ALLOWED_WRITES`.
1634
1681
 
1635
- `POST /api/layout` (#228) writes **one** file in the served project:
1636
- `.behold/layout.json`, the hand-layout sidecar, `{version, lenses: {<lens>:
1637
- {<node id>: {dx,dy,dw,dh}}}}`. That is the whole of behold's write surface
1638
- inside a project, and it does not weaken the invariant above:
1639
-
1640
- - It is **workspace metadata**, not estate truth. Deltas describe how *you* want
1641
- the picture arranged on top of dagre's layout; the graph underneath stays
1642
- chant's, and a delta for a node that left the estate is dropped on read.
1643
- - It **never touches the cloud and never touches your source**. No `.ts`, no
1644
- `chant.config.ts`, no `.behold.json`. The path is `cfg.projectDir` + two
1645
- constants; nothing from the request reaches the filesystem.
1682
+ `POST /api/layout` (#228) writes **one** file, and not in the served project:
1683
+ the hand layout is a per-user cache (#469), `<user cache>/behold/layouts/<key>.json`
1684
+ with `<user cache>` the OS's (`~/Library/Caches`, `%LOCALAPPDATA%`,
1685
+ `$XDG_CACHE_HOME` or `~/.cache`), `<key>` the first 32 hex characters of the
1686
+ sha256 of the project directory's realpath, and `BEHOLD_CACHE_DIR` replacing
1687
+ `<user cache>/behold`. The file is `{version, projectDir, lenses: {<lens>:
1688
+ {<node id>: {dx,dy,dw,dh}}}}`, mode 0600 in a 0700 directory (src/layout.ts):
1689
+
1690
+ - It is **one operator's view**, not estate truth. Deltas describe how *you*
1691
+ want the picture arranged on top of dagre's layout; the graph underneath
1692
+ stays chant's, and a delta for a node that left the estate is dropped on read.
1693
+ - It **never touches the cloud, your source or the project**. The path is a
1694
+ hash of `cfg.projectDir` + constants; nothing from the request reaches the
1695
+ filesystem.
1646
1696
  - It refuses politely when it shouldn't write: preview mode, a static-export
1647
- capture, a read-only project directory, an oversized or malformed body.
1648
- - It is **per-user state**, unlike `.behold.json` (config, meant to be tracked).
1649
- Projects should gitignore `.behold/`.
1697
+ capture, a cache directory that isn't writable, an oversized or malformed body.
1698
+ - A project served before #469 may carry `.behold/layout.json`. When the cache
1699
+ has no file for the project, that file is read once and copied into the
1700
+ cache; it is never written, moved or deleted. Clearing the last lens keeps
1701
+ an empty cache file, so the old one is not read back in.
1702
+
1703
+ The per-user settings (#470, src/user-settings.ts) sit beside it at
1704
+ `<user cache>/behold/settings/<key>.json`, same key, same modes: the operator's
1705
+ `approver` block and `behaviour.traffic`, which are not facts about the estate.
1706
+ No route writes them. When the cache has none for a project with a
1707
+ `.behold.json`, that file's two blocks are read once and copied in (key paths
1708
+ made absolute against the project), and a copy is kept even when neither
1709
+ block is there, so `.behold.json` is not read for them again. It is never
1710
+ written, moved or deleted. The tier axis is not a setting: it is the
1711
+ project's `chant.config.ts` `buildParams` entry with a string `enum`
1712
+ (src/project.ts `readTierParam`), read per request through `detectProject`
1713
+ and passed to `chant graph` as `--param`.
1650
1714
 
1651
1715
  `GET /api/layout` reads it back; `GET /api/graph?layout=1` (and `/api/overlay`)
1652
1716
  render with the deltas baked into the SVG, which is how `behold export` and
1653
1717
  static snapshots honour a hand layout.
1654
1718
 
1655
- A declared workspace (#464) keeps that file in the workspace root, the
1656
- directory holding `chant.workspace.json`, rather than in its first member.
1719
+ A declared workspace (#464) keys the layout by the workspace root, the
1720
+ directory holding `chant.workspace.json`, rather than by its first member.
1657
1721
 
1658
1722
  `behold doctor --fix` (#464, ws-015) is the third exception, and it runs only
1659
1723
  when you type the flag: for an estate root whose members are listed in
1660
1724
  `.behold.json`, it writes `chant.workspace.json` in that root (never over an
1661
- existing one) and moves the saved `.behold/layout.json` from the first member to
1662
- the root with its node ids rewritten. It then runs `chant workspace check`. The
1663
- old layout file and `.behold.json` are left as they were.
1725
+ existing one) and copies the first member's saved layout to the root's cache
1726
+ entry with its node ids rewritten. It then runs `chant workspace check`. The
1727
+ first member's layout and `.behold.json` are left as they were.
1664
1728
 
1665
1729
  The fourth exception is the carve walkthrough's two steps above (#254), and it
1666
1730
  is narrower still: they exist only when behold booted a `behold demo carve`
@@ -2019,8 +2083,8 @@ exists to draw is a directory of `.tf` files and nothing else, and #378 chose
2019
2083
  not to ask one for a `chant.config.ts` of its own — INTENTIUS/waterpark#88 was
2020
2084
  withdrawn because the estate is more useful untouched. So `behold serve
2021
2085
  <terraform-dir>` generates the reader config itself, outside the estate, and
2022
- points chant at it. The Invariant's one in-project write stays
2023
- `.behold/layout.json`; nothing is written under the served directory, and
2086
+ points chant at it. behold writes nothing in a served project (the
2087
+ Invariant), nothing is written under the served directory, and
2024
2088
  `src/terraform-member.test.ts` asserts the estate's source stamp is unchanged
2025
2089
  across a read. Three decisions, each a trade #384 left open and each measured on
2026
2090
  water park's `access/` before it was taken:
package/README.md CHANGED
@@ -446,12 +446,17 @@ log, which the loop driver copies into the bucket under `runs/`. It needs
446
446
  `--terragucci`, asks only GETs, and has no control.
447
447
  The docs' terragucci page says what it shows.
448
448
 
449
- Each tool in the loop has a page of its own at `/<tool>`: `/terraform`,
450
- `/terragrunt`, `/cdk-terrain` and `/choudoufu` (behold#571). It shows that
451
- tool's scenario and runs alone, with a footer saying who makes the tool.
452
- While another tool's scenario runs, the page replays the tool's latest cycle at
453
- the pace it ran (`cycles/<tool>/latest.json` beside `demo.json`), and says so in
454
- a banner. Any other short path answers 404 with a link to `/kiosk`.
449
+ The demo is served at `/`: the live demo's page, else the first listed one.
450
+ `/kiosk` redirects to `/`. The listed demos are the multi-state plan-and-apply
451
+ ones, each at a path of its own (`/choudoufu-compose`, `/terragrunt-choudoufu`,
452
+ `/atmos-choudoufu`, `/chant-compose`); one is listed once its tool has a published cycle
453
+ (`cycles/<tool>/latest.json` beside `demo.json`) or is live, and
454
+ `/api/terragucci/demos` says which. A page shows the demo's live run, or replays
455
+ its latest cycle, under a banner with the example's name, its products, a link to
456
+ its code in INTENTIUS/terragucci, and a switcher when more than one is listed.
457
+ The older tools' URLs (`/terraform`, `/terragrunt`, `/cdk-terrain`, `/choudoufu`,
458
+ `/chant`, and the fan-out pages) redirect to `/`. Any other short path answers
459
+ 404 with a link to the front page.
455
460
 
456
461
  In a declared workspace, the gates waiting on a person come from
457
462
  `chant workspace status <env> --json`, keyed `member/op/gate` the way arugula's
@@ -460,7 +465,7 @@ button says who chant will record before the click: the person `--as` names
460
465
  (`--as github:<login>`), the person an authenticating proxy names in the header
461
466
  `--identity-header` trusts, or else the user running behold. A gate the
462
467
  workspace names in `identity.gates` is signed with that person's key when
463
- `--signing-key` (or `.behold.json`'s `approver.keys`) gives one, and sent to the
468
+ `--signing-key` (or `approver.keys` in behold's per-user settings) gives one, and sent to the
464
469
  command line otherwise (#690). Every approve route refuses in preview mode.
465
470
 
466
471
  In a declared workspace, the inspect pane of a member's box or a card has a
@@ -560,50 +565,67 @@ nothing else. Your Terraform is never edited; see AGENTS.md, "Invariant".
560
565
  ## Configuration: `.behold.json`
561
566
 
562
567
  An optional `.behold.json` in the served project's root is **behold's own**
563
- config, kept separate from `chant.config.ts` so behold's concerns (like the
564
- tier picker) don't leak into chant's. Three keys: `tiers` below, `executor`
565
- (which forge deploys an environment), and `members`, spelled `[{ "dir": "x", "kind":
568
+ config, which #470 retired. One key is still read, `members`, spelled `[{ "dir": "x", "kind":
566
569
  "chant" | "choudoufu" | "terraform" }]`, how an estate root names what it
567
570
  composes, fail-closed on a kind behold has no reader for. `members` is
568
571
  deprecated: a chant workspace declaration (`chant.workspace.json`) lists an
569
572
  estate's members for every reader, and beside one, `.behold.json`'s list is
570
573
  ignored. `behold doctor --fix` writes the declaration from it (see
571
- [Serve a chant workspace](https://intentius.io/behold/using/workspace/)). First, the
572
- project's deploy-**tier** axis, a dimension orthogonal to `environment` (chant
573
- has no native tier concept; it is entirely a project convention, e.g. Loom's
574
- components branching on an env-conditioned `namingParams.tier`):
574
+ [Serve a chant workspace](https://intentius.io/behold/using/workspace/)).
575
575
 
576
- ```json
577
- {
578
- "tiers": {
579
- "envVar": "LOOM_TIER",
580
- "values": ["light", "production", "production-ha"]
581
- }
582
- }
576
+ ### The tier axis: `buildParams` in `chant.config.ts`
577
+
578
+ The deploy-**tier** axis, a dimension orthogonal to `environment`, is a chant
579
+ build-time parameter (#470): a `buildParams` entry with a string `enum`, the
580
+ one named `tier` first, else the first such entry.
581
+
582
+ ```typescript
583
+ buildParams: {
584
+ tier: { type: "string", enum: ["light", "production", "production-ha"], default: "light", env: "LOOM_TIER" },
585
+ },
583
586
  ```
584
587
 
585
- - `envVar` is the env var name the project's source branches on; behold sets it
586
- for the chant shell-out whenever a tier is picked (`?tier=` → this var, never
587
- a chant CLI flag).
588
- - `values` is the tier picker's options.
588
+ - The `enum` is the tier picker's options.
589
+ - A picked tier (`?tier=`) reaches `chant graph` as `--param tier=<value>`, and
590
+ the parameter's `env` variable is set for the chant shell-out when it
591
+ declares one, so a chant command without `--param` sees it too.
592
+ - The current tier in the header is that `env` variable's value in behold's
593
+ own environment, when the parameter declares one.
594
+
595
+ No such parameter means no tier axis: the picker doesn't render and the graph
596
+ loads with no tier selected. `.behold.json`'s old `tiers` block is not read;
597
+ `behold doctor` warns where one is left.
598
+
599
+ ### Per-user settings: `approver` and `behaviour.traffic`
589
600
 
590
- **No `.behold.json` (or no `tiers` key) → no tier axis:** the picker doesn't
591
- render and the graph loads with no tier selected, which is the default for any
592
- project that doesn't opt in. There's no other tier config surface (not
593
- `chant.config.ts`, not an env var behold guesses the name of).
601
+ Who is approving (`approver`, see [Approving](https://intentius.io/behold/using/approving/))
602
+ and the traffic level the behaviour overlay predicts at (`behaviour.traffic`)
603
+ are one operator's settings, so since #470 they live in a per-user file outside
604
+ the project, beside the hand layout: `<cache>/behold/settings/<key>.json`
605
+ (`~/Library/Caches/behold/settings/` on macOS, `~/.cache/behold/settings/` on Linux, `%LOCALAPPDATA%\behold\settings\` on Windows; `BEHOLD_CACHE_DIR` moves it), keyed by the project's realpath like the layout. A project
606
+ whose `.behold.json` carried either block has it copied in on the first read
607
+ (relative key paths made absolute against the project); `.behold.json` is
608
+ never written or deleted.
594
609
 
595
610
  ### Deploy executors: `executor`
596
611
 
597
- The same file can designate which forge deploys an environment (#165):
612
+ A member's `chant.config.ts` designates which forge deploys an environment
613
+ (#165, #470), on the environment's entry:
598
614
 
599
- ```json
600
- {
601
- "executor": {
602
- "prod": { "forge": "github", "workflow": "deploy-prod.yml" }
603
- }
604
- }
615
+ ```ts
616
+ environments: [
617
+ "staging",
618
+ { name: "prod", executor: { forge: "github", workflow: "deploy-prod.yml" } },
619
+ ],
605
620
  ```
606
621
 
622
+ behold reads it from chant (`chant workspace graph --composites`, each
623
+ `components[].environments[]` row's `executor`, chant 0.124.47 or newer), and
624
+ never from the name of a generated `chant-components-<env>` workflow. A chant
625
+ older than that, or an environment that declares none, reads as no designation.
626
+ `.behold.json`'s old `executor` block is not read; `behold doctor` warns where
627
+ one is left, with the entry to add.
628
+
607
629
  It names the committed **workflow**, not just the forge, because two
608
630
  environments' generated pipelines carry identical job ids and a picker cannot
609
631
  tell them apart. For a designated environment the Deploy button dispatches that
@@ -624,33 +646,33 @@ state outside the project, so a behold restarted mid-deploy re-adopts the run
624
646
  and keeps following it. A follow whose stream dies is reported as `lost`, never
625
647
  as a verdict; `just e2e-ci-github` proves the whole contract against GitHub.
626
648
 
627
- ### The hand-layout sidecar: `.behold/layout.json`
649
+ ### The hand layout: a per-user cache
628
650
 
629
651
  dagre places your nodes; you can move them. Drag a card, resize a containment
630
652
  box, and the offsets are remembered per project and lens: in `localStorage`
631
- first, and (when the served project is writable) in a `.behold/layout.json`
632
- sidecar beside it, so a layout is shareable, reviewable in a diff, and honoured
633
- by `behold export`:
653
+ first, and in a per-user cache file outside the project, which is what
654
+ `behold export` bakes into its SVGs:
634
655
 
635
656
  ```json
636
- { "version": 1, "lenses": { "components": { "src/api#Component": { "dx": 40, "dy": -25 } } } }
657
+ { "version": 1, "projectDir": "/path/to/project", "lenses": { "components": { "src/api#Component": { "dx": 40, "dy": -25 } } } }
637
658
  ```
638
659
 
639
- This is the **only** file behold writes inside a served project. It stores
640
- deltas rather than absolute positions, so the graph stays chant's and your
641
- layout sits on top of it. A delta whose node has left the estate is dropped.
642
- `POST /api/layout` refuses politely in preview mode, during a static-export
643
- capture, on a read-only directory, and above its size caps. `↺ layout` in the
644
- graph clears the current lens on both tiers.
645
-
646
- **Gitignore it.** `.behold.json` (above) is config and belongs in the repo;
647
- `.behold/` is per-user state, one person's arrangement of the picture, so add
648
- it to the served project's `.gitignore` unless you actually want to share and
649
- review a layout:
650
-
651
- ```gitignore
652
- .behold/
653
- ```
660
+ The file is `<user cache>/behold/layouts/<key>.json`, where `<user cache>` is
661
+ `~/Library/Caches` on macOS, `%LOCALAPPDATA%` on Windows and `$XDG_CACHE_HOME`
662
+ (or `~/.cache`) elsewhere, and `<key>` is a hash of the project directory's
663
+ realpath. `BEHOLD_CACHE_DIR` moves `<user cache>/behold`. behold writes nothing
664
+ inside a served project (#469), so there is nothing to gitignore.
665
+
666
+ It stores deltas rather than absolute positions, so the graph stays chant's and
667
+ your layout sits on top of it. A delta whose node has left the estate is
668
+ dropped. `POST /api/layout` refuses politely in preview mode, during a
669
+ static-export capture, when the cache isn't writable, and above its size caps.
670
+ `↺ layout` in the graph clears the current lens on both tiers.
671
+
672
+ A project served by an older behold may have a `.behold/layout.json`. The first
673
+ time the cache has nothing for that project, behold reads the old file once
674
+ and copies it into the cache. It never changes or deletes it; remove it
675
+ yourself when you like.
654
676
 
655
677
  ## Layout
656
678