@intentius/behold 0.29.57 → 0.30.1

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 (48) hide show
  1. package/AGENTS.md +388 -57
  2. package/README.md +67 -50
  3. package/demos.json +1 -1
  4. package/dist/cli.js +9958 -3080
  5. package/example-choudoufu-estate/chant.workspace.json +1 -1
  6. package/example-terraform-estate/README.md +10 -10
  7. package/example-terraform-estate/chant.workspace.json +1 -1
  8. package/example-three-cloud/README.md +17 -9
  9. package/example-three-cloud/aws/chant.config.ts +1 -1
  10. package/example-three-cloud/aws/site.component.ts +13 -0
  11. package/example-three-cloud/azure/chant.config.ts +1 -1
  12. package/example-three-cloud/azure/src/site.component.ts +13 -0
  13. package/example-three-cloud/azure/src/site.ts +5 -7
  14. package/example-three-cloud/dns/chant.config.ts +1 -1
  15. package/example-three-cloud/dns/src/records.component.ts +14 -0
  16. package/example-three-cloud/dns/src/route53.ts +4 -5
  17. package/example-three-cloud/gcp/chant.config.ts +1 -1
  18. package/example-three-cloud/gcp/src/site.component.ts +13 -0
  19. package/example-three-cloud/gcp/src/site.ts +7 -7
  20. package/example-three-cloud/package-lock.json +19 -19
  21. package/example-three-cloud/package.json +4 -4
  22. package/example-three-cloud/scripts/front-door.ts +89 -15
  23. package/package.json +10 -11
  24. package/web/agent-move.js +60 -0
  25. package/web/agent-move.test.js +55 -0
  26. package/web/app.js +622 -79
  27. package/web/dots-lod.js +1 -1
  28. package/web/embed.d.ts +3 -0
  29. package/web/embed.js +5 -3
  30. package/web/embed.test.js +8 -0
  31. package/web/index.html +64 -9
  32. package/web/layout-store.js +3 -3
  33. package/web/panel.js +28 -4
  34. package/web/release.js +6 -4
  35. package/web/release.test.js +2 -2
  36. package/web/search-view.d.ts +27 -0
  37. package/web/search-view.js +213 -0
  38. package/web/search-view.test.js +144 -0
  39. package/web/shot-frame.d.ts +5 -0
  40. package/web/shot-frame.js +116 -0
  41. package/web/shot-frame.test.js +90 -0
  42. package/web/themes.js +1 -1
  43. package/web/view-url.d.ts +18 -0
  44. package/web/view-url.js +153 -6
  45. package/web/view-url.test.js +72 -1
  46. package/example-three-cloud/azure/composites/container-app-site.ts +0 -77
  47. package/example-three-cloud/dns/composites/latency-entry.ts +0 -73
  48. package/example-three-cloud/gcp/composites/public-cloud-run.ts +0 -102
package/AGENTS.md CHANGED
@@ -526,7 +526,8 @@ preview-locked, and one load runs at a time (409 otherwise).
526
526
  `?env=`, `/api/overlay` is the live entity overlay; `/api/diff?env=` slices
527
527
  per-node observed state, drift and field ownership; `/api/reconcile?env=`
528
528
  summarizes the pending change set; `/api/substrates` reports substrate
529
- readiness; `/api/events` (SSE) pushes `changed`/`op`/`apply`/`run`/`pr`.
529
+ readiness; `/api/events` (SSE) pushes `changed`/`op`/`apply`/`run`/`pr`,
530
+ and `view` when an agent moves the tab (below).
530
531
  With `?components=1&env=`, each component node carries `_liveStatus` (the
531
532
  `chant components status` verdict) and, when the release ledger recorded
532
533
  one, `_release` — `{runId, forge, originSource, url?, gitSha, digest,
@@ -734,7 +735,7 @@ block in M1.
734
735
 
735
736
  With a traffic level, `/api/overlay` predicts each member twice and carries
736
737
  both figures and their difference. The level is `?traffic=` on the request,
737
- else `.behold.json`'s `{"behaviour": {"traffic": "100 rps, p50"}}`, else none;
738
+ else the per-user settings' `{"behaviour": {"traffic": "100 rps, p50"}}` (src/user-settings.ts, #470), else none;
738
739
  with none nothing is asked for and the payload is exactly M1's. behold never
739
740
  defaults a level, because every figure is *at* one.
740
741
 
@@ -886,6 +887,248 @@ pass.
886
887
  There is still **no** endpoint that runs `terraform`. The handoff step hands
887
888
  back the runbook's commands as text.
888
889
 
890
+ ## A chant search query: `q` and `GET /api/search` (#913)
891
+
892
+ `q` is a view key holding a query in chant's search grammar. In a link
893
+ (`?q=...`), a `behold:view` message, `POST /api/view` and `behold shot`, it
894
+ draws the same way: the cards chant matched are lit, the cards and edges on
895
+ each match's path (chant's `paths[].hops`, and for a `cap:` term the hops
896
+ in `paths[].because[]` too, INTENTIUS/chant#4375) are drawn at full weight, and the
897
+ rest is dimmed, with nothing hidden. One line at the top left says the query,
898
+ the match count and chant's provenance line. A query with no matches dims
899
+ the whole graph, says "no matches" with the universe count, and outlines the
900
+ near-misses `--explain` names (hover one for the term it fails). A live read
901
+ that failed is said as a failure naming the lexicon, and its rows wear a
902
+ dashed ring. A query chant's grammar refuses lights and dims nothing and
903
+ shows chant's message and hint. A reload keeps `q`.
904
+
905
+ chant answers and behold draws. Every search goes through the workspace
906
+ reader (`src/workspace-reader.ts`, a fifth `BEHOLD_READS` entry held by
907
+ chant's reader conformance suite):
908
+
909
+ | Served | chant call |
910
+ |---|---|
911
+ | a declared workspace | `chant workspace search [flags] --json -- <q>` at the root (INTENTIUS/chant#4374). Ids are `<member>/<id>`, as `workspace graph` gives them. A member chant didn't search is named in a "not searched" line with chant's reason code, never shown as no matches |
912
+ | one chant project | `chant search [flags] --json -- <q>` in its directory |
913
+ | a bare Terraform folder | `chant workspace search` at a scratch workspace of one member (#925): `<tmpdir>/behold-tfws-<hash>`, whose `chant.workspace.json` declares one member of kind `chant`, named what the folder's box is named, at a link to the scratch project behold graphs the folder through. chant composes the `<member>/<id>` ids the cards carry; behold prefixes nothing. Nothing is written in the folder. The folder's box is named with a member name chant accepts (`^[a-z0-9][a-z0-9-]{0,39}$`, #927): a folder name that already is one is kept, any other is lowercased, with each run of other characters turned into `-`, and cut to 40 (`MyInfra` -> `myinfra`, `terraform_ec2` -> `terraform-ec2`), for the graph and the search alike. `code: "search-member-name"` is left only as a guard |
914
+ | a loose estate of several dirs | refused, `code: "search-estate"`: declare a workspace |
915
+
916
+ The mode follows the view: no `env` is the declared source, `env` is a live
917
+ read (`--live --env`), and `env` with `snapshot` replays a recorded snapshot
918
+ (`--snapshot <ref> --env`). `--explain` is always passed.
919
+
920
+ ```
921
+ GET /api/search?q=->kind:aws_kms_key&env=&snapshot=&show=
922
+ -> 200 {q, env, snapshot,
923
+ document: <chant's search document, unchanged>,
924
+ draw: {lit, onPath, edges, unobserved, nearMisses, provenance, failure, notSearched},
925
+ link}
926
+ ```
927
+
928
+ A query chant refuses answers 400 `code: "query"` with chant's hint as the
929
+ remedy (and the document). A chant below 0.124.46 answers 422
930
+ `code: "chant-too-old"` (`SEARCH_CONTRACT_CHANT_FLOOR` in
931
+ `src/chant-floors.ts`). A `--public` serve answers declared queries and
932
+ refuses `env` and `snapshot` (403).
933
+
934
+ `behold export --q "<query>"` (repeatable) captures each query's answer for
935
+ the source graph and every environment, so the bundle draws it with no
936
+ backend. The manifest lists `queries`; a link's `q` that wasn't captured is
937
+ named, with the captured ones, and lights nothing.
938
+
939
+ ### Groups and the plan: `countBy` and `plan` (#922)
940
+
941
+ Two more view keys, carried the same way as `q` (a link, `behold:view`,
942
+ `POST /api/view`, `behold shot --view`, the MCP tools, an export):
943
+
944
+ - `countBy=kind|module|attr:<name>` is chant's `--count-by`. The document is
945
+ chant's counts branch, verbatim: `countBy`, `groups[{group, count, ids}]`
946
+ and `total` (INTENTIUS/chant#4360; `ids` is INTENTIUS/chant#4382). The page
947
+ lights each group's cards from `ids`, outlines them in the group's colour,
948
+ labels the group's first drawn card `<group> · <count>`, and the top-left
949
+ line lists the groups and the total. `draw.counts` is `{by, total, groups}`.
950
+ With `countBy`, `q` may be empty: the whole graph is counted. A chant that
951
+ lists no ids per group lights nothing and the line says so. behold never
952
+ works out a node's group itself.
953
+ - `plan=1` is the plan read. The source graph's cards carry each stock
954
+ Terraform root's plan facts (`/api/graph?plan=1`, #910) on every load, and
955
+ `q` is answered at the plan depth: `CHANT_TERRAFORM_OBSERVE=plan` in the
956
+ environment of that one chant call, with `--live --env <env>`
957
+ (INTENTIUS/chant#4358). A bare Terraform folder needs no env (the plan
958
+ read's placeholder `behold-plan` is used); a chant project or workspace
959
+ needs one (422 `code: "plan-env"`). `plan` with `snapshot` is refused,
960
+ naming both: a 400 on the route, both keys in `refused` on a link or
961
+ `POST /api/view`. A `--public` serve refuses it (403). It runs
962
+ `terraform plan -lock=false` in each root: nothing is changed, but every
963
+ resource is read.
964
+
965
+ ```
966
+ GET /api/search?q=kind:aws_&countBy=module
967
+ GET /api/search?q=attr:planAction=replace&plan=1&show=planActions,planReplacePaths,planActionReason
968
+ ```
969
+
970
+ `behold export --count-by <g>` captures each `--q` grouped too (with no
971
+ `--q`, the whole graph's groups); `behold export --plan` captures the plan
972
+ cards on the source graph and each `--q` at the plan depth.
973
+
974
+ A `cap:` term (INTENTIUS/chant#4375) asks a capability, such as
975
+ `cap:internet-reachable(22)`. Its route is in the path's `because`, one
976
+ entry per capability the match relied on, each with the hops that proved it,
977
+ and `draw.edges` and `draw.onPath` include them (#926). A hop that ends on a
978
+ node inside a resource, `<id>#<attr>[n]` (a security group's ingress rule),
979
+ is drawn on the resource's card.
980
+
981
+ ### The capability catalog: `GET /api/capabilities` (#926)
982
+
983
+ Read it before asking a `cap:` question. It answers chant's capabilities
984
+ document byte for byte (capabilities.schema.json, contract 1), read through
985
+ the workspace reader from the same target a search asks:
986
+ `chant workspace search --capabilities --json` at a declared workspace's
987
+ root, `chant search --capabilities --json` in one project or a Terraform
988
+ folder's scratch project. Each capability has its `name`, `meaning`,
989
+ `params`, the `search` term that asks it, the questions it `answers`, what
990
+ it leaves `notEvaluated`, its `rule`, and per lexicon whether it is
991
+ supplied. A chant below 0.124.46 answers 422 `code: "chant-too-old"`
992
+ (`CAPABILITIES_CHANT_FLOOR`). behold mcp's `capabilities` tool returns the
993
+ same text.
994
+
995
+ ```
996
+ GET /api/capabilities
997
+ -> 200 {"$schema":".../capabilities/v1/capabilities.schema.json","contract":1,"chant":"0.124.46",
998
+ "capabilities":[{"name":"internet-facing","meaning":...,"search":"cap:internet-facing",...}],
999
+ "helpers":[...]}
1000
+ ```
1001
+
1002
+ ## Moving the person's open tab (#914)
1003
+
1004
+ `POST /api/view` changes what every open tab of this serve draws. It is a
1005
+ view change and writes nothing: no infrastructure, no project file, not
1006
+ the layout cache, and nothing kept on the server.
1007
+
1008
+ ```
1009
+ POST /api/view
1010
+ {"view": {"q": "attr:internetFacing=true", "env": "prod", "snapshot": "latest", "zoom": "resources"},
1011
+ "by": "claude-code via behold mcp"}
1012
+ ```
1013
+
1014
+ `view` takes the URL's view keys (`member`, `zoom`, `env`, `tier`, `lens`,
1015
+ `node`, `radial`, `alike`, `gates`, `focus`, `run`, `pull`, and #922's
1016
+ `plan` (a boolean) and `countBy`) plus `q`, a
1017
+ question in chant's search grammar, and `snapshot`, a recorded lifecycle
1018
+ snapshot (`latest` or a ref) that needs an `env`. They are settled with the
1019
+ same checks a link's query gets (`web/view-url.js`: `viewFromObject`,
1020
+ `settleView`, `checkQuery`); an env the project doesn't declare, a `q` with a
1021
+ control character or over 2000 characters, or a key that isn't a view key is
1022
+ named in `refused` and the rest still moves. `at` is refused by name: in
1023
+ chant's read contract it is a git revision, so a snapshot is `snapshot`.
1024
+ behold does not parse `q`. The tab draws it through `GET /api/search`
1025
+ (below): the matches lit, the rest dimmed.
1026
+
1027
+ The answer is `200 {id, movedAt, sent, link, view, refused}`, where `sent` is
1028
+ the number of open tabs it reached and `link` opens the same view. With no
1029
+ tab open it is `409 {code: "no-tab", link}`: hand the person the link. A
1030
+ view with nothing that can be applied is `400 {code: "view", refused}`.
1031
+
1032
+ Each tab gets a `view` event `{id, movedAt, by, view}` on `/api/events`,
1033
+ moves, and shows "Moved by an agent: `<by>` asked `<q>` at <time> (request
1034
+ <id>)" with a Back button. An agent's move pushes a browser history entry, so
1035
+ the banner's Back and the browser's Back both return to the view from before
1036
+ it; up to 20 moves in a row stack this way. The person's own changes keep
1037
+ replacing the entry they are on. An embedded frame with a host (`embed=1&host=`)
1038
+ ignores the event, because its host owns its view (#476).
1039
+
1040
+ `by` is a label of at most 80 printable characters. Without one it is the
1041
+ request's User-Agent product token. Anyone who can reach the serve can send
1042
+ any name, so `by` says who the caller claims to be and is not authentication.
1043
+
1044
+ Refused: under `serve --public` (405 from the request guard, and 403 `code:
1045
+ "public"` in the route itself), and under every `behold preview`, with or
1046
+ without `--emulator` (403 `code: "preview"`). A terragucci or SQL Yodeler
1047
+ repo allows it, since it writes nothing. A static export has no server, so no
1048
+ route.
1049
+
1050
+ ## A picture of a view (#915)
1051
+
1052
+ `behold shot "<query>" [project-dir] -o out.png` and `GET /api/shot` take a
1053
+ PNG of a view and give the link to the same view. Both call `src/shot.ts`.
1054
+ The page is behold's own, loaded in a headless browser with
1055
+ `embed=1&bare=1&frame=matches`: it lights what the view asks for, dims the
1056
+ rest, frames the lit cards with the kiosk's arithmetic (`web/kiosk-shot.js`),
1057
+ draws one caption line (what was asked, from where, when), and sets
1058
+ `data-behold-shot` on `<html>` to `drawn`, `no-matches` or `failed`. Nothing
1059
+ is photographed until it does: a page that never reports ready within 60 s,
1060
+ or one that draws no cards, is refused and no file is written.
1061
+
1062
+ ```
1063
+ GET /api/shot?node=aws_vpc.main&env=prod&width=1600&height=1000
1064
+ -> 200 image/png, Behold-View-Link: http://127.0.0.1:4600/?env=prod&node=aws_vpc.main,
1065
+ Behold-Shot-State: drawn | no-matches | failed
1066
+ ```
1067
+
1068
+ The browser comes from `playwright-core`, an optional peer behold does not
1069
+ install: the system Chrome first, then Playwright's `chromium-headless-shell`.
1070
+ Without either the CLI exits 1 with the install line and the route answers
1071
+ 501 `code: "no-browser"`. `--env`/`env=` draws the env's live view, and
1072
+ `--snapshot <ref>`/`snapshot=` a recorded snapshot of it (`at` is a git
1073
+ revision and is not taken). The route answers bytes, never a path, and is
1074
+ refused on `serve --public` (403), since each shot starts a browser. The CLI
1075
+ uses the serve at `--url`, or starts behold's app for the project on a free
1076
+ loopback port and stops it after; without `-o` the PNG goes under the OS temp
1077
+ directory. Nothing is written in the served project.
1078
+
1079
+ A query's matches are lit and framed (#913). Without a query, a shot frames
1080
+ the view's own `node` or `focus` (`behold shot "" --view node=<id>`).
1081
+
1082
+ Publishing is opt-in per call (#923, `src/shot-publish.ts`): `--publish
1083
+ <remote>[/<branch>]` (branch default `behold-shots`) commits the PNG to that
1084
+ branch of the remote, in the repo `--publish-repo <dir>` names (default: the
1085
+ current directory's), tracked with Git LFS (`*.png` in the branch's
1086
+ `.gitattributes`), pushes it, and prints the raw URL (at the commit, for
1087
+ GitHub and GitLab) after the view link. It is git plumbing on a private index:
1088
+ no checkout's tree, index or HEAD changes, and the branch checked out in the
1089
+ repo or the project, or its upstream, is refused. Without git-lfs, or when the
1090
+ remote does not take the LFS object, it refuses with the setup line and exits
1091
+ 1 before the branch moves; the local PNG is kept. `behold mcp`, `GET
1092
+ /api/shot` and a `--public` serve never publish.
1093
+
1094
+ ## Over MCP: `behold mcp` (#916)
1095
+
1096
+ `behold mcp [project-dir] [--url <serve> | --port <n>]` is a stdio MCP server
1097
+ with four tools, all clients of a running serve's HTTP API. An agent reads
1098
+ `capabilities` first (#926): it calls `GET /api/capabilities` and returns
1099
+ chant's capability catalog, the read contract's `capabilities` document
1100
+ (`chant search --capabilities --json`, INTENTIUS/chant#4375), byte for byte.
1101
+ It names each capability a `cap:` term asks, what it means, its parameters,
1102
+ the search term, the questions it answers, what it does not evaluate, its
1103
+ rule and which lexicons supply it, and it takes no arguments. `ask` calls
1104
+ `GET /api/search` and returns chant's search document verbatim, with `link`
1105
+ and `drawn: false` added after its own fields (a test holds it byte for byte
1106
+ to what chant prints); it takes `query`, `env`, `snapshot` and `show`, and
1107
+ never moves the tab. `show` calls
1108
+ `POST /api/view` (its `by` is the MCP client's name plus "via behold mcp"),
1109
+ and `shot` calls `GET /api/shot` and returns the PNG as MCP `image` content
1110
+ followed by a text block `{link, state, serve}`. They take `query`, `env`,
1111
+ `snapshot`, `member`, `zoom`, `focus` and `node`; `shot` also takes `width`
1112
+ and `height`. The answers are chant's: behold passes chant's documents
1113
+ through and computes none of its own.
1114
+
1115
+ It finds the serve through `--url`/`--port`, then the per-user registry at
1116
+ `<os.tmpdir()>/behold/serves/<pid>.json` (`{url, pid, projectDir, version,
1117
+ startedAt}`, written by every serve at start, rewritten on a project switch,
1118
+ removed at exit, a dead pid ignored; `BEHOLD_SERVES_DIR` moves it), then
1119
+ `http://127.0.0.1:4600`. It confirms the serve through `GET /api/project`.
1120
+ `show` refuses a serve of another project, naming both, and refuses with the
1121
+ serve command when none runs. `capabilities`, `ask` and `shot` with no serve of the project
1122
+ start behold in their own process for the call (`src/shot-cli.ts`), and the
1123
+ answer comes from the same route.
1124
+
1125
+ Arguments are checked against each tool's schema (`additionalProperties:
1126
+ false`), a credential-named one is refused by name, and a refusal is an
1127
+ `isError` result carrying the route's `{error, code, remedy}`. The server
1128
+ refuses to start with a tool whose name holds a write word (deploy, apply,
1129
+ approve, run, op, rollback, write and kin), and a call to an unlisted tool is
1130
+ refused with the same words.
1131
+
889
1132
  ## The act loop (delegated, never direct)
890
1133
 
891
1134
  behold does not apply. To change the estate:
@@ -938,12 +1181,21 @@ best-effort, and only its exit code is certain (src/ci-run.ts).
938
1181
 
939
1182
  ### The executor contract (#165, #61)
940
1183
 
941
- `.behold.json` may designate which forge deploys an environment:
1184
+ A member's `chant.config.ts` may designate which forge deploys an environment,
1185
+ on the environment's entry (#470):
942
1186
 
943
- ```json
944
- { "executor": { "prod": { "forge": "github", "workflow": "deploy-prod.yml" } } }
1187
+ ```ts
1188
+ environments: [{ name: "prod", executor: { forge: "github", workflow: "deploy-prod.yml" } }]
945
1189
  ```
946
1190
 
1191
+ behold reads it from `chant workspace graph --composites --json`
1192
+ (`components[].environments[].executor`, floor `EXECUTOR_CHANT_FLOOR` 0.124.47,
1193
+ src/executor.ts) through the workspace reader. It never reads `.behold.json`'s
1194
+ `executor` (retired; `behold doctor` warns), and never derives it from a
1195
+ `chant-components-<env>` workflow name (maintainer ruling, 2026-10-23). An older
1196
+ chant prints no `executor`, and no row means none declared. `reason.code`
1197
+ `executor-config-unreadable` stays designated and fails closed.
1198
+
947
1199
  It designates the committed WORKFLOW, not just the forge: two environments'
948
1200
  generated pipelines carry identical job ids, so a picker cannot tell them
949
1201
  apart, and a contract that names prod must not sit on a guess. For a
@@ -976,8 +1228,8 @@ A dispatched run is followed honestly (#165 §6, PR #350): only GitHub's own
976
1228
  follow deadline promotes the run to `lost` (chips frozen at last-observed,
977
1229
  the run possibly still live at its own page), never to a verdict. The adopted
978
1230
  run id is persisted as one JSON per project under `~/.behold/ci-runs/`, the
979
- operator's machine-state, outside the project tree, so the Invariant below
980
- still names the whole in-project write surface. `GET /api/ci/run` reads the
1231
+ operator's machine-state, outside the project tree, so behold still writes
1232
+ nothing in a served project (the Invariant below). `GET /api/ci/run` reads the
981
1233
  record; `POST /api/ci/readopt` (also attempted once at boot) re-follows an
982
1234
  unconcluded run by its saved id, so a restart mid-deploy leaves the run a
983
1235
  reader instead of nothing.
@@ -1047,13 +1299,13 @@ chant never signs a person in (ws-052); the surface that does passes the person
1047
1299
  to chant as `--actor` (ws-080). behold has no login, so `src/approver.ts` names
1048
1300
  the person for each request, in this order:
1049
1301
 
1050
- - `--identity-header <name>` (BEHOLD_IDENTITY_HEADER, `.behold.json`
1302
+ - `--identity-header <name>` (BEHOLD_IDENTITY_HEADER, the per-user settings'
1051
1303
  `approver.header`): behold sits behind a proxy that signed the person in
1052
1304
  through the forge or OIDC, and the header names them. A bare login is an
1053
1305
  account on `--identity-forge` (github unless set). A request without the
1054
1306
  header approves nothing (`403 no-identity`). Refused at startup with a
1055
1307
  `--host` other than loopback, since anyone reaching the port could send it.
1056
- - `--as <principal>` (BEHOLD_APPROVER, `.behold.json` `approver.as`): one
1308
+ - `--as <principal>` (BEHOLD_APPROVER, the per-user settings' `approver.as`): one
1057
1309
  person runs behold and names themselves, `github:<login>` or a principal the
1058
1310
  signers file lists.
1059
1311
  - Neither: chant's own fallback (GITHUB_ACTOR, GITLAB_USER_LOGIN, USER), and
@@ -1068,7 +1320,7 @@ Every approve route (`/api/workspace/gates/approve`, the converge gate's
1068
1320
  behold"`. chant's ledger has no channel for a surface (its `origin` is `cli`,
1069
1321
  `mcp` or `acp`), so the note is where behold is named. A workspace gate that
1070
1322
  status marks `signed` is approved with `--sign <key>` when behold holds the
1071
- person's key (`--signing-key` beside `--as`, or `.behold.json`'s
1323
+ person's key (`--signing-key` beside `--as`, or the per-user settings'
1072
1324
  `approver.keys` by principal) and refused `422 signed` with the line to run
1073
1325
  otherwise. The key path never reaches a page: `GET /api/workspace/gates`
1074
1326
  carries `approverIdentity: {principal, source, forge, signs}`, or `approver:
@@ -1333,6 +1585,14 @@ If a request would have behold write to a cloud or to source directly, it's wron
1333
1585
  behold shows truth and triggers Ops. Authority stays in the committed source and the
1334
1586
  executor.
1335
1587
 
1588
+ behold writes nothing in a served project (#469, ruled 2026-10-23). What it
1589
+ keeps for itself (the hand layout, the per-user settings, dispatched CI run
1590
+ ids, recents, the serve registry) lives in the user's own home, cache or temp directory, keyed by the
1591
+ project, never in the tree. The only files behold puts in a project are the
1592
+ ones a person asks for by name: `behold doctor --fix` writing
1593
+ `chant.workspace.json`, and the carve walkthrough writing into the demo copy
1594
+ behold made itself (both below).
1595
+
1336
1596
  The commands behold starts run with behold's own environment, so Deploy (`POST
1337
1597
  /api/apply`, chant's local executor) applies with the credentials of whoever
1338
1598
  started it. On a terragucci repo (a `terragucci.yml` in the served directory or
@@ -1343,8 +1603,9 @@ so the page offers no write, and auto-sync declines. The boundary is an
1343
1603
  allowlist (#500): every request whose method is not GET, HEAD or OPTIONS, on
1344
1604
  any path, answers that `409` unless `TERRAGUCCI_ALLOWED_WRITES` names its
1345
1605
  method and route, and that list holds only the exceptions below (the layout
1346
- sidecar, project open and reveal, demo open, refresh, and the four carve
1347
- steps). A new write route is refused on a terragucci repo until it is added
1606
+ cache, project open and reveal, demo open, refresh, and the four carve
1607
+ steps), plus `POST /api/view`, which moves the open tabs and writes nothing
1608
+ (#914). A new write route is refused on a terragucci repo until it is added
1348
1609
  there. `src/terragucci-repo.test.ts` walks every non-GET route of the real
1349
1610
  app (`app.routes`, built plain, with a carve report and with `--terragucci`)
1350
1611
  and asserts each one is allowlisted or answers 409, and that every allowlist
@@ -1388,35 +1649,52 @@ These are also the only writes a guarded product repo answers: terragucci
1388
1649
  (`terragucci.yml` and its siblings) and SQL Yodeler (`yodel.config.ts`), both
1389
1650
  listed in `TERRAGUCCI_ALLOWED_WRITES`.
1390
1651
 
1391
- `POST /api/layout` (#228) writes **one** file in the served project:
1392
- `.behold/layout.json`, the hand-layout sidecar, `{version, lenses: {<lens>:
1393
- {<node id>: {dx,dy,dw,dh}}}}`. That is the whole of behold's write surface
1394
- inside a project, and it does not weaken the invariant above:
1395
-
1396
- - It is **workspace metadata**, not estate truth. Deltas describe how *you* want
1397
- the picture arranged on top of dagre's layout; the graph underneath stays
1398
- chant's, and a delta for a node that left the estate is dropped on read.
1399
- - It **never touches the cloud and never touches your source**. No `.ts`, no
1400
- `chant.config.ts`, no `.behold.json`. The path is `cfg.projectDir` + two
1401
- constants; nothing from the request reaches the filesystem.
1652
+ `POST /api/layout` (#228) writes **one** file, and not in the served project:
1653
+ the hand layout is a per-user cache (#469), `<user cache>/behold/layouts/<key>.json`
1654
+ with `<user cache>` the OS's (`~/Library/Caches`, `%LOCALAPPDATA%`,
1655
+ `$XDG_CACHE_HOME` or `~/.cache`), `<key>` the first 32 hex characters of the
1656
+ sha256 of the project directory's realpath, and `BEHOLD_CACHE_DIR` replacing
1657
+ `<user cache>/behold`. The file is `{version, projectDir, lenses: {<lens>:
1658
+ {<node id>: {dx,dy,dw,dh}}}}`, mode 0600 in a 0700 directory (src/layout.ts):
1659
+
1660
+ - It is **one operator's view**, not estate truth. Deltas describe how *you*
1661
+ want the picture arranged on top of dagre's layout; the graph underneath
1662
+ stays chant's, and a delta for a node that left the estate is dropped on read.
1663
+ - It **never touches the cloud, your source or the project**. The path is a
1664
+ hash of `cfg.projectDir` + constants; nothing from the request reaches the
1665
+ filesystem.
1402
1666
  - It refuses politely when it shouldn't write: preview mode, a static-export
1403
- capture, a read-only project directory, an oversized or malformed body.
1404
- - It is **per-user state**, unlike `.behold.json` (config, meant to be tracked).
1405
- Projects should gitignore `.behold/`.
1667
+ capture, a cache directory that isn't writable, an oversized or malformed body.
1668
+ - A project served before #469 may carry `.behold/layout.json`. When the cache
1669
+ has no file for the project, that file is read once and copied into the
1670
+ cache; it is never written, moved or deleted. Clearing the last lens keeps
1671
+ an empty cache file, so the old one is not read back in.
1672
+
1673
+ The per-user settings (#470, src/user-settings.ts) sit beside it at
1674
+ `<user cache>/behold/settings/<key>.json`, same key, same modes: the operator's
1675
+ `approver` block and `behaviour.traffic`, which are not facts about the estate.
1676
+ No route writes them. When the cache has none for a project with a
1677
+ `.behold.json`, that file's two blocks are read once and copied in (key paths
1678
+ made absolute against the project), and a copy is kept even when neither
1679
+ block is there, so `.behold.json` is not read for them again. It is never
1680
+ written, moved or deleted. The tier axis is not a setting: it is the
1681
+ project's `chant.config.ts` `buildParams` entry with a string `enum`
1682
+ (src/project.ts `readTierParam`), read per request through `detectProject`
1683
+ and passed to `chant graph` as `--param`.
1406
1684
 
1407
1685
  `GET /api/layout` reads it back; `GET /api/graph?layout=1` (and `/api/overlay`)
1408
1686
  render with the deltas baked into the SVG, which is how `behold export` and
1409
1687
  static snapshots honour a hand layout.
1410
1688
 
1411
- A declared workspace (#464) keeps that file in the workspace root, the
1412
- directory holding `chant.workspace.json`, rather than in its first member.
1689
+ A declared workspace (#464) keys the layout by the workspace root, the
1690
+ directory holding `chant.workspace.json`, rather than by its first member.
1413
1691
 
1414
1692
  `behold doctor --fix` (#464, ws-015) is the third exception, and it runs only
1415
1693
  when you type the flag: for an estate root whose members are listed in
1416
1694
  `.behold.json`, it writes `chant.workspace.json` in that root (never over an
1417
- existing one) and moves the saved `.behold/layout.json` from the first member to
1418
- the root with its node ids rewritten. It then runs `chant workspace check`. The
1419
- old layout file and `.behold.json` are left as they were.
1695
+ existing one) and copies the first member's saved layout to the root's cache
1696
+ entry with its node ids rewritten. It then runs `chant workspace check`. The
1697
+ first member's layout and `.behold.json` are left as they were.
1420
1698
 
1421
1699
  The fourth exception is the carve walkthrough's two steps above (#254), and it
1422
1700
  is narrower still: they exist only when behold booted a `behold demo carve`
@@ -1652,7 +1930,7 @@ its own graph and overlay counts as it runs.
1652
1930
  | `terralith-1` | `terralith-gen` at scale 1 plus the `estate.chdf.hcl` sidecar it omits, applied by choudoufu from nothing: 79 cards, all 79 bound | docker, choudoufu, go |
1653
1931
  | `terralith-4` | the same at scale 4: 301 cards, all 301 bound. The estate behold is sized against | the same |
1654
1932
  | `terralith-4-adopt` | scale 4 again, but STOCK terraform applies it first, so nothing wears a marker: 301 cards — 85 UNOWNED, 84 bound by derived identity alone, 132 neutral. One `choudoufu live-import` line, which the up script prints and you run, and all 301 read bound | docker, choudoufu, go, terraform |
1655
- | `waterpark` | `../waterpark/access` in place as a bare Terraform directory (#384): five roots as boxes, 58 cards, 49 edges, nothing written under the estate | `@intentius/chant-lexicon-terraform` + `@cdktn/hcl2json` beside behold — optional peers behold declares and does not install |
1933
+ | `waterpark` | `../waterpark/access` in place as a bare Terraform directory (#384): five roots as boxes, 58 cards, 49 edges, nothing written under the estate | `@intentius/chant-lexicon-terraform` + `@cdktn/hcl2json` beside behold, dependencies of behold since #909 |
1656
1934
 
1657
1935
  **The scratch, by name and port.** Each emulator is the entry's own, booted by
1658
1936
  its up script and removed by the `scripts/down.sh` that script wrote into the
@@ -1716,8 +1994,9 @@ A Terraform estate reaches behold through chant.
1716
1994
  `@intentius/chant-lexicon-terraform` reads the HCL an estate already has and
1717
1995
  emits one entity per block, so **a Terraform estate is a chant project whose
1718
1996
  only lexicon is a reader** and `chant graph --format ir` serves it like any
1719
- other. behold parses no HCL and ships no HCL parser, the same posture
1720
- `src/carve-lens.ts` states for the carve report (#378).
1997
+ other. behold parses no HCL itself, the same posture `src/carve-lens.ts`
1998
+ states for the carve report (#378). The parser chant uses is installed with
1999
+ behold since #909, below.
1721
2000
 
1722
2001
  Three passes turn what arrives into a picture (`src/terraform-lens.ts`), in this
1723
2002
  order, guarded on the IR carrying terraform entities so every other estate gets
@@ -1774,23 +2053,30 @@ exists to draw is a directory of `.tf` files and nothing else, and #378 chose
1774
2053
  not to ask one for a `chant.config.ts` of its own — INTENTIUS/waterpark#88 was
1775
2054
  withdrawn because the estate is more useful untouched. So `behold serve
1776
2055
  <terraform-dir>` generates the reader config itself, outside the estate, and
1777
- points chant at it. The Invariant's one in-project write stays
1778
- `.behold/layout.json`; nothing is written under the served directory, and
2056
+ points chant at it. behold writes nothing in a served project (the
2057
+ Invariant), nothing is written under the served directory, and
1779
2058
  `src/terraform-member.test.ts` asserts the estate's source stamp is unchanged
1780
2059
  across a read. Three decisions, each a trade #384 left open and each measured on
1781
2060
  water park's `access/` before it was taken:
1782
2061
 
1783
- 1. **The lexicon is opt-in.** chant resolves the lexicon from the config file's
1784
- own location, so the generated project has to see it, and making it a
1785
- dependency would put `@cdktn/hcl2json`, a ~1.8 MB wasm blob, in the install
1786
- of every user who serves a chant project. `@intentius/chant-lexicon-terraform`
1787
- and `@cdktn/hcl2json` are therefore **optional peers**: declared in
1788
- package.json (the only place their versions are named, the refusal reads
1789
- them from there), never installed by behold, probed at serve and doctor time,
1790
- and refused with the one install line and where behold looked. The same gate
1791
- `behold demo` puts on a binary it does not ship. The lexicon's own chant peer
1792
- is what moved behold's `@intentius/chant` floor to `^0.61.0`: chant 0.54
1793
- loads no published version of it (`applyLineage is not a function`).
2062
+ 1. **The reader ships with behold, and is still probed.** chant resolves the
2063
+ lexicon from the config file's own location, so the generated project has to
2064
+ see it, and chant core (not the lexicon) imports `@cdktn/hcl2json` from its
2065
+ own real path; neither package declares the parser. #384 made both optional
2066
+ peers to keep a ~1.8 MB wasm blob out of chant-only installs. #909 reversed
2067
+ that so `npx @intentius/behold serve .` on a folder of `.tf` files is one
2068
+ command: `@intentius/chant-lexicon-terraform` and `@cdktn/hcl2json` are
2069
+ **dependencies** in package.json (the only place their versions are named;
2070
+ the refusal reads them from there). The maintainer accepted the cost on #909:
2071
+ +8.3 MB on a 195 MB install, six packages. The lexicon's range starts at
2072
+ behold's chant floor so its chant peer dedupes against behold's chant, and
2073
+ npm hoists both beside chant, which is where the scratch project's
2074
+ `node_modules` symlink and chant's parser import look. They are still probed
2075
+ at serve and doctor time and refused with the one install line and where
2076
+ behold looked, because an install that pruned them reaches a chant that
2077
+ warns, exits 0 and prints an empty graph. The lexicon's own chant peer is
2078
+ what moved behold's `@intentius/chant` floor to `^0.61.0`: chant 0.54 loads
2079
+ no published version of it (`applyLineage is not a function`).
1794
2080
  2. **Roots are discovered, and the skips are reported.** A root is a directory
1795
2081
  with a `.tf` declaring a line-start `terraform {` or `provider "` block
1796
2082
  beside a `resource`, `data` or `module` block, a regex probe at the depth
@@ -1843,21 +2129,36 @@ tag, path or mutability was changed out of band still carries its markers, so
1843
2129
  it is still bound, and it is still green.
1844
2130
 
1845
2131
  The other half of the terminal's answer ("would a plan change anything?") is
1846
- a **separate, opt-in read**: `choudoufu plan -input=false -out=<tmp>` then
1847
- `choudoufu show -json <tmp>`, whose `resource_changes[].change.{actions,before,
1848
- after}` name the attributes and both their values. (`choudoufu plan -json` is
1849
- NOT this: on 0.16.0 it prints choudoufu's own ownership document, the same
1850
- shape as `live-plan -json`, with no attribute values in it at all. The
1851
- measurement is in src/choudoufu-plan.ts's header.) The plan file is written to
1852
- a scratch directory of behold's own and removed after rather than inside the served
1853
- member, which would be a write into someone's source.
2132
+ a **separate, opt-in read**, and since #924 it goes through chant together with
2133
+ the ownership it is about (src/choudoufu-chant-read.ts): one `chant graph
2134
+ --live` over the member's `chdf` reader project at the plan depth
2135
+ (`CHANT_TERRAFORM_OBSERVE=plan`, INTENTIUS/chant#4371). chant runs `choudoufu
2136
+ live-plan -json` for ownership, then `choudoufu plan -input=false -lock=false
2137
+ -out=<its tmp>` and `show -json` for the attributes, and puts `planChanges`
2138
+ (live value `before`, declared value `after`) on each bound block. With
2139
+ `CHANT_TERRAFORM_LIVE_PLAN_DIR` set to a directory behold made under the OS
2140
+ temp directory (INTENTIUS/chant#4383), chant also hands back the `live-plan`
2141
+ document its verdicts came from, and behold paints ownership from that, so a
2142
+ re-check runs ONE `live-plan` per member and the plan sits on the same
2143
+ verdicts as the card. Nothing is written in the served member (chant writes
2144
+ its plan file and the handed document outside it, INTENTIUS/chant#4379).
2145
+ (`choudoufu plan -json` is not this read: on 0.16.0 it prints choudoufu's own
2146
+ ownership document with no attribute values in it at all, measured in #404.)
2147
+ On a live root drift IS the planned `update`: choudoufu rebuilds prior state
2148
+ from the account, so chant's `planDrift` is empty there and is not read. A
2149
+ path chant finds flagged sensitive on either side is `(sensitive)` on both,
2150
+ and so is every copy of a flagged string (`tags_all`): a choudoufu plan flags
2151
+ a sensitive variable's value on `after` only, with the old secret unflagged in
2152
+ `before`. Floor: `CHOUDOUFU_PLAN_CHANT_FLOOR` (0.124.46); below it, or with no
2153
+ terraform lexicon, a re-check paints from behold's own `live-plan` and reads
2154
+ no plan.
1854
2155
 
1855
2156
  It is opt-in because it costs differently: the ownership read is answered out
1856
2157
  of the tagging index and is flat in the estate's size, while `plan` refreshes
1857
2158
  every resource, one provider read per card, 301 of them on `terralith-4`. So:
1858
2159
 
1859
2160
  - **Never on an ordinary overlay read.** `GET /api/overlay?plan=1` and
1860
- `GET /api/diff?plan=1` are the only things that spawn one, and the palette's
2161
+ `GET /api/diff?plan=1` are the only things that read one, and the palette's
1861
2162
  **"Re-check live with plan (attribute drift)"** row is the only thing in the
1862
2163
  SPA that sends the flag. The cheap **"Re-check live (refresh drift)"** row is
1863
2164
  deliberately left alone — it is `POST /api/refresh`, a primary-only re-observe
@@ -1865,7 +2166,7 @@ every resource, one provider read per card, 301 of them on `terralith-4`. So:
1865
2166
  - **Cached under the member's source stamp**, the same key half `memberIr`
1866
2167
  uses. A read that did NOT ask is served that stored answer, so a reload after
1867
2168
  a refresh keeps showing the drift without paying for a second pass; a read
1868
- that DID ask always re-plans, because "re-check" means re-check.
2169
+ that DID ask always re-reads both halves, because "re-check" means re-check.
1869
2170
  - **The ownership verdict stays the card's colour.** A bound card that drifted
1870
2171
  is still painted bound and still counted `bound`; it gains `attrs._planDrift`
1871
2172
  and wears a dashed `--degraded` edge plus a `~ n attributes` corner glyph
@@ -1877,6 +2178,36 @@ every resource, one provider read per card, 301 of them on `terralith-4`. So:
1877
2178
  drifted: n}`. The two are different answers — "nobody looked" versus "looked,
1878
2179
  nothing drifted", and the legend prints a count only for the second.
1879
2180
 
2181
+ ### A stock Terraform root's plan comes from chant (#910)
2182
+
2183
+ `GET /api/graph?plan=1` (palette: **"Read the plan on the Terraform roots"**)
2184
+ reads each stock Terraform member's roots at chant's plan depth
2185
+ (INTENTIUS/chant#4358): behold's own chant over the member's scratch project,
2186
+ `CHANT_TERRAFORM_OBSERVE=plan chant graph . --live --overlay --env behold-plan
2187
+ --format ir --detail 3` (src/terraform-plan.ts). The plan runs with
2188
+ `-lock=false`, its file under the OS temp directory. Each resource or data card
2189
+ gains `attrs._plan` (`source`, `action`, `reason`, `replacePaths`,
2190
+ `forcedFrom`, `afterUnknown`, `changes`, `drift`), and the card's rows lead with
2191
+ `plan`, `forced by`, `from` and `read`. `GET /api/terraform/plan` answers the
2192
+ same facts per card as JSON.
2193
+
2194
+ - **Which read answered is per root**, parsed from chant's notes: `plan`,
2195
+ `state` (the plan failed, for missing credentials or a provider error) or
2196
+ `none` (declared only). A card in a root that fell back says `plan: not read`
2197
+ and which read answered. Never "no changes" unless the plan said `no-op`.
2198
+ - **Sensitive values arrive redacted** by chant, at any depth and every copy;
2199
+ behold copies plan facts only, never a block's other attributes.
2200
+ - **Floor**: `TERRAFORM_PLAN_CHANT_FLOOR` (0.124.46) for behold's chant and the
2201
+ lexicon; below it the read is refused with the upgrade line.
2202
+ - **A planned create has a card**: it reads absent at the plan depth, so it
2203
+ stays pending with no physical id, and chant carries its plan attributes
2204
+ onto the declared node anyway (chant#4372). Its rows read `plan: create`,
2205
+ `unknown: N until apply`, `read: plan`.
2206
+ - **choudoufu members read ownership and the plan through chant together**
2207
+ (src/choudoufu-chant-read.ts, #924): src/choudoufu-plan.ts is gone, and a
2208
+ re-check's `live-plan` is chant's, handed back to behold. See the choudoufu
2209
+ section above.
2210
+
1880
2211
  ### A lexicon behold draws but cannot aim (#430)
1881
2212
 
1882
2213
  `behold doctor`'s **targets** line. `SUBSTRATE_TARGET_VARS` (src/targets.ts)