@intentius/behold 0.2.3 → 0.4.0

package/AGENTS.md

@@ -0,0 +1,64 @@
+# Driving behold (for agents)
+
+behold is a **read-only control plane** over a chant estate, with **delegated,
+gated** writes. As an agent you drive it the same way a human does — and the
+mutating capabilities are chant's MCP Op tools, not behold's, so nothing here holds
+apply creds.
+
+## The division of labour
+
+- **behold** serves the live, mixed-substrate graph (and, later, the deployment-lanes
+  timeline). It reads; it never mutates.
+- **chant's MCP** is where the real capabilities live. Prefer it over shelling.
+  - Reads: `lifecycle-diff`, `lifecycle-snapshot`, `build`, `lint`.
+  - Actions (delegated writes): `op-run` (start an `ApplyOp`/`ReconcileOp`),
+    `op-signal` (approve a gate), `op-status` / `op-report` (watch it).
+
+## Getting a server
+
+```sh
+npx @intentius/behold serve <chant-project-dir> --port 4600   # or: preview / demo
+```
+
+`behold demo` needs no project at all — it copies the bundled example and serves
+it against a local emulator (Docker). A directory that is not a chant project
+gets a structured `{code: "no-project"}` error from `/api/graph`, not a blank
+graph.
+
+## The read loop
+
+0. **discover** — GET `/api` lists every route with a one-line description,
+   plus the server's version and a link back to this guide.
+1. **observe** — GET `/api/graph` (JSON: `{ ir, svg, meta }`). The mixed graph
+   of the project, every node with `id`/`kind`/`lexicon`/`attrs`/`sourceLoc`. Drift
+   status, when present, is `attrs._status` (`good`=managed, `warn`=foreign,
+   `accent`=pending, `neutral`=unobserved, `runtime`=runtime child). With
+   `?env=`, `/api/overlay` is the live entity overlay; `/api/diff?env=` slices
+   per-node observed state, drift and field ownership; `/api/reconcile?env=`
+   summarizes the pending change set; `/api/substrates` reports substrate
+   readiness; `/api/events` (SSE) pushes `changed`/`op`/`apply`/`pr`.
+2. **focus** — narrow with chant graph options as query params: `?detail=0..3`,
+   `?components=1`, `?logical=1`, `?lens=blast:<id>&down=1`, `?lens=lexicon:aws`,
+   `?env=`, `?stack=`, `?tier=`, `?target=`.
+3. **inspect** — a node's `sourceLoc.file` is the typed source that declared it;
+   edit there to change the estate (chant is the source of truth, not behold).
+
+## The act loop (delegated, never direct)
+
+behold does not apply. To change the estate:
+
+1. Edit the chant `.ts` source (the node's `sourceLoc`), or
+2. Trigger a committed Op via chant's MCP:
+   - `op-run <name>` — start the project's `ApplyOp` (code→cloud) or `ReconcileOp`
+     (cloud→code PR).
+   - `op-signal <name> <gate>` — approve a gate (e.g. a destructive apply).
+   - `op-status <name>` — watch phases; `op-report <name>` — the run report.
+
+Every mutation is a gated, durable Temporal workflow with a human-confirmable gate
+and saga rollback. There is no behold endpoint that mutates the cloud.
+
+## Invariant
+
+If a request would have behold write to a cloud or to source directly, it's wrong.
+behold shows truth and triggers Ops. Authority stays in the committed source and the
+executor.

package/README.md

@@ -16,11 +16,35 @@ chant source ──build/lint──▶ graph IR ──behold──▶ live graph
               (deterministic)          (server + browser)
 ```
 
+## Quick start (npm)
+
+No chant project yet? The bundled demo is the five-minute path — an S3 bucket +
+policy served against a local emulator, no cloud account, no credentials
+(needs Docker):
+
+```sh
+npx @intentius/behold demo            # copies the example to ./behold-demo, installs, serves
+# → http://localhost:4600 — blue = declared; click Deploy, watch it turn green
+```
+
+The copied project is yours: edit its source and watch the graph change live.
+
+Already have a chant project?
+
+```sh
+cd my-chant-project
+npx @intentius/behold preview         # → http://localhost:4600, this project's graph
+npx @intentius/behold serve . --env prod --poll 30   # live drift overlay
+```
+
+Driving it from an agent or script? `GET /api` lists every JSON route;
+[AGENTS.md](./AGENTS.md) (shipped in the package) is the read/act contract.
+
 ## Preview: your project, or the Loom-on-Floci demo (v0.1.0)
 
 `behold preview` is the quick way to look at a chant project's graph in a
 browser at one port. Plain, it just opens the project you point it at — no env,
-no emulator:
+no emulator. From a repo checkout the same commands run through `npm run dev`:
 
 ```sh
 npm install