austere-axi 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,13 @@
 # austere-axi
 
+[![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)
+
 Review artifacts for coding agents, written in [OpenUI Lang](https://github.com/thesysdev/openui) instead of hand-written HTML.
 
 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.
@@ -11,15 +19,19 @@ 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: a KPI row, a diagram, a table, a chart, a diff, and a decision form. The whole file is about 1,000 tokens.
 
 ## Why
 
@@ -47,18 +59,50 @@ agent edits statements ◄── austere-axi poll plan.html ◄─┘  (long-pol
 ```
 
 - **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.
+- **The runtime** bundles the OpenUI React renderer with a curated component library: 58 of the stock components, plus `Architecture` (with `Node`, `Edge` and `Group`), `Mermaid`, `Diff` and `FileTree`. Every rendered statement is tagged with its name.
+- **Architecture diagrams** are laid out automatically ([dagre](https://github.com/dagrejs/dagre)): the agent writes nodes, edges and groups as statements and never a coordinate. Each node and edge is its own click target, so feedback on a diagram arrives as `annotation: api (Node)` with its line. The layout runs across when that stays legible at the page width and down otherwise, so a phone gets a tall diagram. For a system split by owner or tier, `lanes` turns each group into a column with right-angle lines between them (stacked as bands on a phone); `tone` tints a box or line to mark risk or a store family. Mermaid stays for sequences, state machines, ER and gantt.
 - **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.
 
 ## Install
 
+Requires Node.js 20 or later.
+
+**Run it without installing** (what agents use):
+
+```sh
+npx -y austere-axi --help
+```
+
+`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.
+
+**Or install the command globally:**
+
+```sh
+npm install -g austere-axi
+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):**
+
 ```sh
 npx skills add MandalorianBatman/austere-axi --skill austere
 ```
 
-The skill is a stub that sends the agent to `npx -y austere-axi --help` and `spec`. The CLI is the source of truth, so an installed skill cannot go stale. No setup is needed: any agent can run `npx -y austere-axi` directly.
+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.
+
+## Quick start
+
+```sh
+npx -y austere-axi spec              # component reference for the agent (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
+```
+
+`--help` prints the file skeleton and the full review loop.
 
 ## CLI
 
@@ -70,7 +114,7 @@ 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 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...]      component reference (~6.5k tokens; groups narrow it)
 austere-axi export <file>        one self-contained HTML file, works offline
 austere-axi stop                 stop the background server
 ```
@@ -130,7 +174,7 @@ 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/components/` | Custom components (`Architecture` family, `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 |