austere-axi 0.1.1 → 0.3.0

package/README.md

@@ -1,95 +1,102 @@
 # austere-axi
 
-Review artifacts for coding agents, written in [OpenUI Lang](https://github.com/thesysdev/openui) instead of hand-written HTML.
+[![npm version](https://img.shields.io/npm/v/austere-axi)](https://www.npmjs.com/package/austere-axi)
+[![npm downloads](https://img.shields.io/npm/dm/austere-axi)](https://www.npmjs.com/package/austere-axi)
+[![jsDelivr hits](https://img.shields.io/jsdelivr/npm/hm/austere-axi)](https://www.jsdelivr.com/package/npm/austere-axi)
+[![skills.sh](https://skills.sh/b/mandalorianbatman/austere-axi)](https://skills.sh/mandalorianbatman/austere-axi)
+[![CI](https://github.com/MandalorianBatman/austere-axi/actions/workflows/ci.yml/badge.svg)](https://github.com/MandalorianBatman/austere-axi/actions/workflows/ci.yml)
+[![node](https://img.shields.io/node/v/austere-axi)](https://www.npmjs.com/package/austere-axi)
+[![license](https://img.shields.io/npm/l/austere-axi)](LICENSE)
 
-The agent writes a short program: one named statement per line, built from a fixed set of components. The reviewer opens it in the browser, points at anything, and the agent gets the feedback back addressed by statement name. To revise, the agent edits only the statements the feedback names, and the page updates in place.
-
-It is the same loop as [lavish-axi](https://github.com/kunchenguid/lavish-axi). The difference is that the agent never writes CSS or layout.
+Review pages for coding agents. The agent writes a short [OpenUI Lang](https://github.com/thesysdev/openui) program, not HTML. You open it in the browser, click on any part, and write a note. The agent gets each note with the name of the statement it points at. It edits only those statements, and the page updates in place.
 
 ```
 root = Stack([intro, flow, options, decide], "column", "l")
 intro = Card([CardHeader("Session storage migration", "Redis → Postgres"), introText])
 introText = MarkDownRenderer("Sessions are lost on failover. **Goal:** durable sessions, no forced logout.")
 flow = Card([CardHeader("Request path"), flowDiagram])
-flowDiagram = Mermaid("flowchart LR
-  client --> edge --> api --> pg[(Postgres)]")
+flowDiagram = Architecture([client, api, pg], [toApi, toPg])
+client = Node("Client", "external")
+api = Node("API", "backend", "Node :8080")
+pg = Node("Postgres", "database", "sessions table", "new")
+toApi = Edge(client, api, "HTTPS", "emphasis")
+toPg = Edge(api, pg, "SQL")
 options = Card([CardHeader("Rollout options"), optionTable])
 optionTable = Table([Col("Option", ["Big bang", "Dual-write"]), Col("Risk", [Tag("high", null, "sm", "danger"), Tag("low", null, "sm", "success")])])
 decide = Form("rollout", Buttons([Button("Send decision", @ToAssistant("Decision: rollout"), "primary")]), [strategyField])
 strategyField = FormControl("Rollout", RadioGroup("strategy", [RadioItem("Big bang", "", "bigbang"), RadioItem("Dual-write", "", "dualwrite")]))
 ```
 
-[`examples/session-migration.html`](examples/session-migration.html) is a full page: a KPI row, a diagram, a table, a chart, a diff, and a decision form. The whole file is about 900 tokens.
+[`examples/session-migration.html`](examples/session-migration.html) is a full page (KPIs, diagram, table, chart, diff, decision form) in about 1,000 tokens.
 
 ## Why
 
-Lavish makes the agent author an entire HTML page every time, and re-author it after every round of feedback. That is slow, because output tokens are the slow part, and it is expensive.
-
-austere-axi changes three things:
+The loop is the same as [lavish-axi](https://github.com/kunchenguid/lavish-axi). The difference: the agent never writes HTML, CSS or layout.
 
 | | lavish-axi | austere-axi |
 |---|---|---|
-| What the agent writes | Full HTML + CSS + inline SVG | OpenUI Lang statements |
-| Revising after feedback | Regenerate the file | Edit the named statements; the page patches in place and highlights what changed |
-| Feedback target | CSS selector + text | Statement name, its line in the file, plus cell / diff line / diagram node / selected text |
-| Validation | In-browser layout audit | `austere-axi check`: the renderer's own parser, in Node, no browser |
-| Look | Whatever the agent designs | One consistent dark design across agents |
+| Agent writes | Full HTML + CSS + SVG | OpenUI Lang statements |
+| After feedback | Writes the file again | Edits the named statements; the page patches in place |
+| Feedback points at | CSS selector + text | Statement name and line, plus table cell, diff line, diagram node or selected text |
+| Validation | Layout audit in the browser | `austere-axi check`, in Node, no browser |
+| Look | Different for each agent | One dark design |
 
-## How it works
-
-```
-agent writes plan.html ──► austere-axi plan.html ──► local server + browser review
-                                                        │  reviewer annotates, picks options,
-                                                        │  types, presses Send
-agent edits statements ◄── austere-axi poll plan.html ◄─┘  (long-poll returns the batch)
-          │
-          └─► page updates in place and flashes the changed statements
-```
-
-- **An artifact is a plain `.html` file.** It contains one `<script>` tag for the runtime and one `<script type="text/openui">` block holding the program. Opened directly, it renders from the CDN. Under review, the server points that tag at a local copy.
-- **The runtime** bundles the OpenUI React renderer with a curated component library: 58 of the stock components, plus `Mermaid`, `Diff` and `FileTree`. Every rendered statement is tagged with its name.
-- **Annotations** resolve to the innermost named statement. They also carry precise detail where it exists: table row and column, `file:+line` for diff lines, the label of a diagram node, or the selected text. The popover shows the parent chain, so the reviewer can retarget a note to an enclosing section.
-- **Buttons and forms** are feedback channels. `@ToAssistant("…")` queues a message along with the form's values. A button with no action sends its label.
-- **Remote review.** When Tailscale is running, the server also listens on this machine's tailnet IP, and `open` prints a phone link. The review UI has a mobile layout with a conversation sheet.
+Fewer output tokens means faster pages and lower cost.
 
 ## Install
 
-Requires Node.js 20 or later.
+You need Node.js 20 or later.
 
-**Run it without installing** (what agents use):
+**Let your agent do it.** Install the setup skill, then ask your agent to "set up austere-axi":
 
 ```sh
-npx -y austere-axi --help
+npx skills add MandalorianBatman/austere-axi --skill austere-setup
 ```
 
-`npx` downloads the package into npm's cache and runs it. `-y` skips the install prompt, so a non-interactive agent never stalls on it. Prefix every command below the same way: `npx -y austere-axi spec`, `npx -y austere-axi plan.html`, and so on.
+It checks Node, installs the `austere` skill, offers the optional items below, and opens a test page.
 
-**Or install the command globally:**
+**Or do it yourself.** Agents can run the CLI with no install:
 
 ```sh
-npm install -g austere-axi
-austere-axi --help
+npx -y austere-axi --help
 ```
 
-A global install stays on the version you installed until `npm update -g austere-axi`. Mixing the two is fine: a newer CLI replaces an older background server automatically.
-
-**Agent skill (optional):**
+`-y` skips the npm prompt, so an agent does not stop on it. Optional:
 
 ```sh
-npx skills add MandalorianBatman/austere-axi --skill austere
+npm install -g austere-axi                                  # `austere-axi` command, no npx
+npx skills add MandalorianBatman/austere-axi --skill austere   # tells agents when to make a page; adds /austere
 ```
 
-The skill tells an agent when a page beats prose and adds an `/austere <request>` command. It is a stub that sends the agent to `npx -y austere-axi --help` and `spec`, so an installed copy cannot go stale. Agents that can run shell commands do not need it.
+The `austere` skill is a stub that points at `--help` and `spec`, so it does not go out of date. A global install stays on its version until `npm update -g austere-axi`.
 
 ## Quick start
 
 ```sh
-npx -y austere-axi spec              # component reference for the agent (read once per session)
+npx -y austere-axi spec              # component reference (read once per session)
 npx -y austere-axi plan.html         # validate and open the page for review
-npx -y austere-axi poll plan.html    # wait for the reviewer to press Send
+npx -y austere-axi poll plan.html    # wait until the reviewer presses Send
 ```
 
-`--help` prints the file skeleton and the full review loop.
+`--help` prints the file skeleton and the full loop.
+
+## How it works
+
+```
+agent writes plan.html ──► austere-axi plan.html ──► local server + browser review
+                                                        │  reviewer annotates, picks options,
+                                                        │  types, presses Send
+agent edits statements ◄── austere-axi poll plan.html ◄─┘  (long-poll returns the batch)
+          │
+          └─► page updates in place and flashes the changed statements
+```
+
+- **A page is a plain `.html` file**: one runtime `<script>` tag and one `<script type="text/openui">` block. Opened directly, it loads the runtime from the CDN. Under review, the server serves a local copy.
+- **Components**: 58 stock OpenUI components, plus `Architecture` (`Node`, `Edge`, `Group`), `Diff` and `FileTree`. `Mermaid` is a bundled [pack](#components-and-packs).
+- **Architecture diagrams** lay out automatically ([dagre](https://github.com/dagrejs/dagre)). The agent never writes coordinates. Each node and edge is a click target. `lanes` puts each group in a column; `tone` colors a box or line to show risk. Use Mermaid for sequences, state machines, ER and gantt.
+- **Annotations** go to the smallest named statement under the click, with detail where it exists: table row and column, `file:+line` in a diff, a diagram node, or selected text. The reviewer can move a note to a parent section.
+- **Buttons and forms** send feedback. `@ToAssistant("…")` sends a message with the form values. A button with no action sends its label.
+- **Phone review**: when Tailscale runs, the server also listens on the tailnet IP and prints a phone link. The review UI has a mobile layout.
 
 ## CLI
 
@@ -99,99 +106,139 @@ austere-axi <file>               validate + open a review   [--no-open] [--reope
 austere-axi poll <file>          long-poll for feedback      [--agent-reply "..."] [--takeover]
 austere-axi reply <file>         post a reply without polling
 austere-axi end <file>           end the review as the agent
-austere-axi check <file>         validate the program (no browser)
+austere-axi feedback <file>      feedback no agent has answered yet   [--all] [--peek]
+austere-axi check <file>         validate the program (no browser)    [--fix]
 austere-axi patch <file>         merge statements from stdin into the program
-austere-axi spec [group...]      component reference (~5.9k tokens; groups narrow it)
+austere-axi spec [group|pack...] component reference (~5.8k tokens; groups narrow it)
+austere-axi components ...       list | search | show | add | remove | new | build
 austere-axi export <file>        one self-contained HTML file, works offline
+austere-axi hub on|off|status|list|open   persistent server with an index of every page
 austere-axi stop                 stop the background server
 ```
 
-Output is compact YAML, written for agents to read. `poll` returns each item with the statement it points at and that statement's line in the file, so the agent can edit it without re-reading the file.
+Output is compact YAML for agents. Each `poll` item has its statement and that statement's line, so the agent does not need to read the file again.
+
+Session rules:
+
+- One poll listens on a session at a time.
+- Feedback sent while no agent listens waits for the next poll.
+- A review the user ended does not open again unless you pass `--reopen`.
+- If all review tabs stay closed, `poll` returns `browser_disconnected`: 10 s after a tab closes, or 5 min after a dropped connection (for example, a locked phone).
+- `feedback <file>` returns notes no agent has answered, also from earlier days. Reading them marks them received; `reply` marks them answered.
+
+## Components and packs
+
+`spec` covers the common components (~5.8k tokens). Rare ones (area and scatter charts, sliders, switches, editable tables, …) are in the library but not in `spec`. Find them with `components`:
+
+```sh
+austere-axi components                  # every component, by group
+austere-axi components search scatter   # search by name, group, description
+austere-axi components show AreaChart   # signature, notes, example
+```
+
+**Packs** add components. A pack is an npm package with `dist/pack.js` (the components, a few KB) and `dist/catalog.json` (signatures, examples, schema).
+
+```sh
+austere-axi components add austere-pack-gantt --trust   # npm name, folder, or .tgz
+austere-axi check --fix plan.html                       # adds the pack tag to the page
+```
+
+A page names its packs in the head, so it renders wherever you open it:
+
+```html
+<meta name="austere-packs" content="austere-pack-gantt@1.2.0 sha384-…">
+```
+
+- Under review, the server serves installed packs only while they match the hash in `~/.austere-axi/packs.json`. Opened directly, the page loads them from jsDelivr with Subresource Integrity. `export` inlines them.
+- A pack component with no pack tag is a `missing-pack` error. `check --fix` repairs it.
+- Mermaid ships as a bundled pack. It loads only when the page calls `Mermaid(...)` and needs no tag.
+
+**Trust.** Pack code runs inside your review pages, where notes and button presses also come from. Packs under `@austere-axi/` on npm install directly. Other npm packs and any `.tgz` need `--trust`; read them first. A local folder counts as your own. A page with third-party packs shows a warning, and `poll` tells the agent.
+
+**Write a pack:**
+
+```sh
+austere-axi components new austere-pack-timeline
+cd austere-pack-timeline && npm install && npm run build
+austere-axi components add .
+```
+
+Each component uses `austereComponent` from `austere-axi/pack`: a PascalCase name, zod props in positional order (append-only after you publish), a one-line description and an example. The build loads the pack in Node, so build only code you trust. Publish with `npm publish`.
 
-Session rules follow lavish:
+## Hub
+
+The server starts when needed and stops after 30 idle minutes. `hub on` keeps it running and indexes every page you open or check:
+
+```sh
+austere-axi hub on      # http://127.0.0.1:4388/: pages by project and day, with search
+austere-axi hub list    # the same, for an agent: [words] [--project dir]
+austere-axi hub off     # back to on-demand; the index stays
+```
 
-- Only one poll listens on a session at a time.
-- Feedback sent while no agent is listening is queued until the next poll.
-- A review the user ended is not reopened unless `--reopen` is passed.
-- If every review tab stays closed, `poll` returns `browser_disconnected`. The wait is 10 s after a tab is closed, or 5 min after a dropped connection, such as a phone screen locking.
+The home page shows which reviews are live and how much feedback the agent has answered. The index is SQLite (`~/.austere-axi/hub.db`), copied from the session files; the review loop does not need it. The hub needs Node 22.13 or later (`node:sqlite`).
 
-### Environment
+## Environment
 
 | Variable | Default | |
 |---|---|---|
 | `AUSTERE_AXI_PORT` | `4388` | server port |
 | `AUSTERE_AXI_STATE_DIR` | `~/.austere-axi` | sessions, server log |
-| `AUSTERE_AXI_NO_OPEN` | | `1` = never launch a browser |
-| `AUSTERE_AXI_HOST` | | extra concrete bind address (never `0.0.0.0`) |
+| `AUSTERE_AXI_NO_OPEN` | | `1` = never open a browser |
+| `AUSTERE_AXI_HOST` | | extra bind address (never `0.0.0.0`) |
 | `AUSTERE_AXI_NO_TAILSCALE` | | `1` = loopback only |
-| `AUSTERE_AXI_LINK_HOST` | | host to print in the remote link |
+| `AUSTERE_AXI_LINK_HOST` | | host in the printed remote link |
 | `AUSTERE_AXI_ALLOWED_HOSTS` | | extra `Host` headers to accept (reverse proxy) |
-| `AUSTERE_AXI_DISCONNECT_GRACE_MS` | `300000` | how long a dropped connection may stay away before `poll` returns; `0` disables |
-| `AUSTERE_AXI_IDLE_TIMEOUT_MS` | `1800000` | idle server shutdown; `0` disables |
+| `AUSTERE_AXI_DISCONNECT_GRACE_MS` | `300000` | how long a dropped connection can stay away before `poll` returns; `0` disables |
+| `AUSTERE_AXI_IDLE_TIMEOUT_MS` | `1800000` | idle shutdown; `0` disables (the hub never idles out) |
+| `AUSTERE_AXI_NPM_REGISTRY` | `npm_config_registry`, else npmjs | where `components add` gets packs |
 
 ## Security
 
-The server binds to loopback, plus the Tailscale IP when Tailscale is up. It never binds to every interface.
+The server binds to loopback, plus the Tailscale IP when Tailscale is up. It never binds to all interfaces.
 
-- **CLI control routes** (`/api/*`) answer only loopback callers.
-- **Host headers** are checked against an allowlist, as a DNS-rebinding defense.
-- **Mutating browser routes** reject foreign `Origin` headers.
-- **The artifact** runs in a sandboxed iframe with no same-origin access.
-- **File access** covers only the artifact's own directory, with no dotfiles.
+- `/api/*` answers only loopback callers and refuses browser requests.
+- `Host` headers must be on an allowlist (DNS-rebinding defense).
+- Browser routes that change state refuse a foreign `Origin`.
+- The page runs in a sandboxed iframe with no same-origin access. Packs run there too.
+- The server serves files only from the page's own directory, with no dotfiles.
+- Third-party packs need `--trust`. Installed packs must match their lockfile hash; CDN loads use Subresource Integrity.
 
-The Node side of OpenUI ships PostHog telemetry. The CLI sets `OPENUI_TELEMETRY_DISABLED=1` so nothing is sent; the browser runtime never sends telemetry.
+OpenUI's Node side has PostHog telemetry. The CLI sets `OPENUI_TELEMETRY_DISABLED=1`. The browser runtime sends no telemetry.
 
 ## Not in v1
 
-These are left out of v1 on purpose:
-
-- **Image attachments** in feedback.
-- **Live data:** `Query` and `Mutation` are disabled, so artifacts are static.
-- **Themes:** there is one dark theme. Per-project accents via OpenUI's `ThemeProvider` are an easy follow-up.
-- **Hosted sharing:** use `export` to produce a single offline file instead.
+- Image attachments in feedback.
+- Live data: `Query` and `Mutation` are off, so pages are static.
+- Themes: one dark theme only.
+- Hosted sharing: use `export` to make one offline file.
 
 ## Development
 
 ```sh
 npm install
-npm run build     # dist/: austere.js (runtime), mermaid.min.js, spec.json, prompt.md, chrome/, cli.mjs
+npm run build     # dist/: runtime, packs, pack kit, Mermaid, spec, catalog, review UI, cli.mjs
 npm test
 node dist/cli.mjs examples/session-migration.html
 ```
 
 | Path | Contents |
 |---|---|
-| `src/runtime/components/` | Custom components (`Diff`, `Mermaid`, `FileTree`), one self-describing file each, collected automatically |
-| `src/runtime/stock.js` | Which stock OpenUI components ship, their prompt groups, renderer overrides |
-| `src/runtime/` | Library assembly, annotation layer, review bridge, styles |
-| `src/chrome/` | Review UI around the artifact iframe |
-| `src/cli/` | CLI, server, session store, `check`, `export` |
-| `src/shared/statements.js` | Statement splitter used by both sides |
-
-To add or change a component, follow [`.agents/skills/add-component/SKILL.md`](.agents/skills/add-component/SKILL.md). It is a maintainer-only skill and is not published; agents working in this repo pick it up through `AGENTS.md`. Tests enforce the mechanical rules:
-
-- every component sits in a prompt group
-- the component reference stays within its token budget
-- released prop orders are append-only (`npm run signatures`)
-- every example passes `check`
-
-For visual checks, `npm run gallery` and `npm run shot` render the components headlessly. `npm run test:browser` drives the real review loop in headless Chrome. It needs Chrome, or `CHROME_PATH` set to a browser, and it checks:
-
-- every component and example renders at desktop and phone width without errors or sideways scrolling
-- every clickable part reaches `poll` correctly
-
-Before committing, [`.agents/skills/review-change`](.agents/skills/review-change/SKILL.md) runs these checks plus three review agents from `.agents/agents/`:
-
-- **change-reviewer:** an independent code review
-- **visual-qa:** looks at screenshots, including stress inputs
-- **cold-start-author:** writes a page from `--help` and `spec` alone, to test the agent-facing docs
+| `src/runtime/components/` | Custom components (`Architecture` family, `Diff`, `FileTree`), one file each |
+| `src/runtime/stock.js` | Which stock components ship, which stay out of `spec`, their groups |
+| `packs/` | Packs bundled with austere-axi (`mermaid`) |
+| `src/runtime/pack-api.js`, `src/pack-kit/` | `austere-axi/pack` and the `components build` pipeline |
+| `src/shared/catalog.js` | Component catalog and prompt tiers |
+| `src/runtime/` | Library, annotation layer, review bridge, styles |
+| `src/chrome/` | Review UI around the page iframe |
+| `src/cli/` | CLI, server, sessions, `check`, `export`, packs, hub |
+| `skills/` | Published skills: `austere`, `austere-setup` |
 
-All of this is maintainer-only and is not published.
+Maintainer guides (not published): [`AGENTS.md`](AGENTS.md), [`.agents/skills/add-component`](.agents/skills/add-component/SKILL.md) to add a component, [`.agents/skills/review-change`](.agents/skills/review-change/SKILL.md) before you commit. Tests enforce the component rules: every component has a group, `spec` stays in its token budget, released prop orders are append-only (`npm run signatures`), and every example passes `check`.
 
-CI (`.github/workflows/ci.yml`) builds and tests on every push to `main` and every pull request: Node 20, 22 and 24 on Linux, Node 24 on Windows, plus the browser suite. To release, bump `version` in `package.json`, push, and publish a GitHub Release. `.github/workflows/publish.yml` then tests again and publishes to npmjs.org through npm trusted publishing, with no token secret.
+Visual checks: `npm run gallery`, `npm run shot`, and `npm run test:browser` (real review loop in headless Chrome; needs Chrome or `CHROME_PATH`).
 
-The runtime is about 3 MB minified. It is served locally and cached. `export` inlines it, and inlines Mermaid too when the artifact uses it.
+**CI** builds and tests every push to `main` and every pull request (Node 20, 22, 24 on Linux; Node 24 on Windows; browser suite). **Release:** bump `version` in `package.json`, push, and publish a GitHub Release. `publish.yml` tests again and publishes to npm with trusted publishing.
 
 ## License
 
-MIT. Builds on [OpenUI](https://github.com/thesysdev/openui) (MIT) and borrows the review-loop design of [lavish-axi](https://github.com/kunchenguid/lavish-axi) (MIT).
+MIT. Builds on [OpenUI](https://github.com/thesysdev/openui) (MIT). The review loop design comes from [lavish-axi](https://github.com/kunchenguid/lavish-axi) (MIT).