create-mirinjs 0.1.0-alpha.2 → 0.1.0-alpha.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mirinjs",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.22",
   "description": "Scaffold a new mirin desktop app: bun create mirinjs",
   "type": "module",
   "license": "MIT",
@@ -22,11 +22,13 @@
     "create-mirinjs": "./src/index.ts"
   },
   "exports": {
-    ".": "./src/scaffold.ts"
+    ".": "./src/scaffold.ts",
+    "./skill": "./src/skill.ts"
   },
   "files": [
     "src",
-    "template"
+    "template",
+    "skill"
   ],
   "engines": {
     "bun": ">=1.2.0"

package/skill/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: mirin
+description: Verify and drive a mirin desktop app without a terminal in front of you. Use when working in a project with a mirin.config.ts and you need to answer "did my change actually work?" — booting the app headlessly, reading its structured event stream, capturing a screenshot or UI snapshot, driving a real user flow and asserting on it, or diagnosing a window that never appeared, a blank screen, a renderer exception, or a failing RPC call. Triggers include "run the app", "check the app", "does this still work", "screenshot the app", "why is the window blank", "the app won't start", "test this flow", "click the button and see what happens".
+---
+
+# Verifying a mirin app
+
+mirin apps are native desktop apps: a Bun main process, a CEF webview, typed RPC
+between them. `bun run dev` opens a real window and never exits, which means a tool
+that backgrounds it has a pid and no idea whether anything worked.
+
+Everything below exists so you never have to guess. **Never report a change as
+working because the code looks right — run `mirin check` and read the result.**
+
+## The loop
+
+```bash
+mirin check                       # boot once, capture, report, exit non-zero on failure
+mirin check --json                # one JSON object on stdout, nothing else
+mirin check --scenario ./check.ts # drive a real user flow and assert, then capture
+mirin doctor                      # environment/config preflight, without building
+```
+
+`mirin check` runs the real startup path, waits for a window, captures a screenshot
+and an accessibility snapshot, collects every error the app produced, stops the app,
+and **exits non-zero when something went wrong**. Treat the exit code as a test
+result. If the project has a `check` script, `bun run check` is the same thing.
+
+Exit 1 means: no window appeared, the inspector never came up, an `error`-level
+event was recorded, or a scenario assertion failed. The `reason` field says which.
+
+## Reading the result
+
+In `--json`, every stdout line parses — progress events, then one `result` object.
+Subprocess chatter goes to stderr, so `mirin check --json | jq` is safe.
+
+```jsonc
+{
+  "phase": "result",
+  "ok": false,
+  "reason": "scenario failed at \"typed mutation updates the list\": the todo never reached the list",
+  "windows": [{ "id": 1, "name": "main", "title": "…" }],
+  "screenshot": "/…/.mirin/dev/<session>/screenshots/….png",
+  "snapshot": "RootWebArea …",          // the UI as an accessibility tree
+  "errors": [ /* full events, with stack traces */ ],
+  "scenario": { "steps": [ /* name, ok, ms */ ] }
+}
+```
+
+Read `errors` first — each carries `src` (`main`, `renderer`, `native`, `rpc`), the
+message, and a stack when there is one. `snapshot` is the UI in a few hundred bytes;
+prefer it over the DOM. `screenshot` is a **path** — read the file to look at it.
+
+## When the app already exited
+
+Every run writes a session directory, so you can diagnose a crash with file access
+alone — no live process, no terminal.
+
+```bash
+SESSION=$(bun -e 'console.log(JSON.parse(await Bun.file(".mirin/dev/current.json").text()).session)')
+
+tail -n 50 "$SESSION/events.jsonl"   # the full stream: logs, exceptions, RPC, native events
+cat "$SESSION/session.json"          # startup phase timeline — how far did it get?
+cat "$SESSION/exit.json"             # post-mortem: exit code, signal, last 50 events
+ls "$SESSION/screenshots"
+```
+
+`session.json` answers "how far did startup get?" (`compile` → `bundle` → `vite` →
+`launch`, each with a status). `exit.json` answers "how did it die?".
+
+## Driving a real flow
+
+A scenario clicks, types, and asserts against the running app, then fails the check
+when an assertion does. This is how you verify a *flow*, not just a boot.
+
+```ts
+// check.ts
+import { defineCheck } from "mirinjs/check";
+
+export default defineCheck(async (app) => {
+  app.step("adding a todo");
+  await app.click("text=add a todo");   // CSS, or text= matching the a11y name
+  await app.type("ship it");
+  await app.click("text=Add");
+  await app.waitUntil(
+    async () => (await app.evaluate<number>('document.querySelectorAll("li").length')) > 0,
+    "the todo never reached the list",
+  );
+  await app.screenshot("todo-added");
+});
+```
+
+Run it with `mirin check --scenario ./check.ts`. Read
+`reference/scenarios.md` for the full driver API and **two mistakes that produce
+passing checks which verify nothing** — read that file before writing assertions.
+
+## Inspecting a running app
+
+While `mirin dev` is up, the same stream plus live state, screenshots, snapshots,
+expression evaluation and synthetic input are available over a token-authenticated
+loopback HTTP server. Use this for exploration; use `check --scenario` for anything
+you want to be repeatable.
+
+See `reference/inspector.md` for auth and the full route list.
+
+## Rules
+
+- Prefer `mirin check` over `mirin dev`. `dev` never exits; backgrounding it and
+  guessing is the failure mode this whole surface exists to remove.
+- Report what the run actually said. If `check` exits 1, say so and quote the
+  `reason` — do not describe a change as working against a failing check.
+- The screenshot of a transparent window is composited over an opaque backdrop so
+  it is readable; the response sets `composited: true`. It is not pixel-truth.
+- This is a development surface and is off in packaged builds. Do not set
+  `devtools.production` to make something work — it ships an endpoint that can
+  evaluate arbitrary code in the app.
+- Do not add a test framework to answer "does this still work". A scenario file and
+  `mirin check` already are the test.

package/skill/reference/inspector.md

@@ -0,0 +1,175 @@
+# The inspector: driving a running app over HTTP
+
+While `mirin dev` is running, the app serves a token-authenticated loopback HTTP
+server. `mirin dev` prints the URL; the endpoint and token are also on disk.
+
+Use this for exploration and one-off questions. For anything you want to be
+repeatable, write a scenario (`reference/scenarios.md`) — it runs the same
+operations through `mirin check` and gates on the result.
+
+## Connecting
+
+```bash
+SESSION=$(bun -e 'console.log(JSON.parse(await Bun.file(".mirin/dev/current.json").text()).session)')
+PORT=$(bun -e "console.log(JSON.parse(await Bun.file('$SESSION/inspector.json').text()).port)")
+TOKEN=$(bun -e "console.log(JSON.parse(await Bun.file('$SESSION/inspector.json').text()).token)")
+
+curl -s "http://127.0.0.1:$PORT/?token=$TOKEN"     # route index — the surface is self-describing
+```
+
+Every request needs the token, as `?token=…` or `Authorization: Bearer …`.
+
+## Routes
+
+| Route | Purpose |
+|---|---|
+| `GET /` | Route index |
+| `GET /health` | Liveness, pid, stream cursor, log file path |
+| `GET /state` | Windows, RPC routes, app-published state, platform |
+| `GET /logs` | The event stream, filterable |
+| `GET /logs/stream` | The same as SSE, with replay |
+| `GET /screenshot` | PNG of a window |
+| `GET /snapshot` | Accessibility tree (default) or DOM HTML |
+| `POST /eval` | Evaluate an expression in a window |
+| `POST /act` | `click` / `type` / `key` / `scroll` / `wait` |
+| `POST /cdp` | Any DevTools-protocol command |
+| `GET /cdp/targets` | Which windows the DevTools bridge is attached to |
+
+## Answering common questions
+
+```bash
+# What is open, what RPC exists, what has the app published?
+curl -s "http://127.0.0.1:$PORT/state?token=$TOKEN"
+
+# Just the errors
+curl -s "http://127.0.0.1:$PORT/logs?level=error&token=$TOKEN"
+
+# What did the app do since sequence 42? (cursor from a previous lastSeq)
+curl -s "http://127.0.0.1:$PORT/logs?since=42&token=$TOKEN"
+
+# Every failed RPC call
+curl -s "http://127.0.0.1:$PORT/logs?type=rpc.error&token=$TOKEN"
+
+# The UI, cheaply — a few hundred bytes where the DOM is tens of kilobytes
+curl -s "http://127.0.0.1:$PORT/snapshot?token=$TOKEN"
+
+# Watch live (replays from `since` first)
+curl -sN "http://127.0.0.1:$PORT/logs/stream?since=0&token=$TOKEN"
+```
+
+`/logs` accepts `since` (exclusive), `level` (minimum severity), `src`, `window`,
+`type` (prefix match), `contains`, and `limit`. Unknown filter values are dropped
+rather than rejected, so a near-miss still returns logs.
+
+## HTTP traffic
+
+Every request and response the page makes is in the stream — method, URL, status,
+type, time to headers, and headers.
+
+```bash
+# everything the app called
+curl -s "http://127.0.0.1:$PORT/logs?type=network&token=$TOKEN"
+
+# just the failures
+curl -s "http://127.0.0.1:$PORT/logs?type=network&level=warn&token=$TOKEN"
+
+# one endpoint
+curl -s "http://127.0.0.1:$PORT/logs?type=network&contains=/api/todos&token=$TOKEN"
+```
+
+Successful traffic is `debug`, a 4xx is `warn`, a 5xx is `error` — so a failing API
+call fails `mirin check`, and a missing favicon does not.
+
+**Bodies are not in the stream** — they are the most likely place for a credential
+to sit, and the stream is plaintext on disk. Each event carries a `requestId`;
+fetch the body when you actually need it:
+
+```bash
+curl -s -X POST "http://127.0.0.1:$PORT/cdp?token=$TOKEN" \
+  -H 'content-type: application/json' \
+  -d '{"method":"Network.getResponseBody","params":{"requestId":"76030.15"}}'
+```
+
+Headers and URLs are recorded with credential values replaced by `[redacted]`
+(`Authorization`, `Cookie`, anything that looks like a token/key/secret/session, in
+a header or a query parameter). If you need the real value, you are debugging the
+credential itself — read it from the app's own config, not from the stream.
+
+## Raw DevTools protocol
+
+`POST /cdp` sends any CDP command, for whatever the routes above do not cover:
+
+```bash
+curl -s -X POST "http://127.0.0.1:$PORT/cdp?token=$TOKEN" \
+  -H 'content-type: application/json' \
+  -d '{"method":"Performance.getMetrics"}'
+```
+
+Useful ones: `Network.getResponseBody`, `Performance.getMetrics` (heap size, node
+count, layout count — call `Performance.enable` first), `DOM.getDocument`,
+`CSS.getComputedStyleForNode`, `Profiler.*`, `HeapProfiler.*`.
+
+Returns `{ ok, method, window, result }`. A protocol error comes back as
+`{ ok: false, error }` — a stale `requestId` or an unsupported domain is
+information, not a crash. Inside a scenario, the same thing is `app.cdp(method,
+params)`.
+
+## Screenshots
+
+`GET /screenshot` writes the PNG into the session's `screenshots/` dir and returns
+`{ path, bytes, format, window, composited }`. Read the path — a path costs a few
+dozen bytes where an inlined base64 PNG costs megabytes. `?inline=1` returns raw
+bytes. Also accepts `window`, `format=png|jpeg`, `quality`, `full=1`, and `label`.
+
+If the window is transparent (a glass/OSR window), the page has no background of its
+own and a raw capture is alpha 0 — every viewer composites it onto white and it
+reads as blank. Such a page is captured over an opaque backdrop chosen to contrast
+with its text, and the response sets `composited: true`. That image is readable but
+is **not** pixel-truth, and it does not include the native material behind the
+webview. `?backdrop=#rrggbb` forces a colour; `?backdrop=none` opts out.
+
+## Driving
+
+```bash
+curl -s -X POST "http://127.0.0.1:$PORT/act?token=$TOKEN" \
+  -H 'content-type: application/json' \
+  -d '{"action":"click","selector":"text=Open settings"}'
+```
+
+Actions: `click` (`selector`, `clickCount`), `type` (`text`, optional `selector`),
+`key` (`key`), `scroll` (`deltaY`, `deltaX`), `wait` (`selector`, `timeoutMs`).
+Selectors accept CSS or `text=…` matching the accessible label. Add `?window=2` to
+target a specific window.
+
+```bash
+curl -s -X POST "http://127.0.0.1:$PORT/eval?token=$TOKEN" \
+  -H 'content-type: application/json' \
+  -d '{"expression":"document.title"}'
+```
+
+## Making app state visible
+
+If you find yourself guessing at main-process state, publish it — it then appears in
+`/state`, in `app.exposed()` inside a scenario, and in `mirin check`'s report
+(`exposed`, printed as `app state:` when non-empty):
+
+```ts
+import { devtools } from "mirinjs";
+
+devtools.expose("route", () => currentRoute);
+devtools.event({ type: "order.submitted", msg: id });
+```
+
+This is the highest-leverage thing you can add to a mirin app for a tool's benefit:
+it lifts state that no DOM snapshot could ever show into the same surface as windows
+and logs.
+
+## Security
+
+The inspector can evaluate JavaScript and synthesize input, so it is a capability,
+not a read-only view. It binds `127.0.0.1` only, requires the session token, and
+rejects requests whose `Host` header does not name loopback.
+
+It is **off in packaged builds**. Do not set `devtools.production` to make something
+work — that ships an endpoint which can run arbitrary code in the app. `mirin
+doctor` warns when it is set.

package/skill/reference/scenarios.md

@@ -0,0 +1,146 @@
+# Scenarios: driving and asserting
+
+A scenario is a module that default-exports an async function. `mirin check
+--scenario ./check.ts` boots the app, waits for the first window to settle, runs the
+scenario, then captures — so the screenshot in the report shows the state the run
+ended in, including the state it failed in.
+
+The file is loaded *before* the build, so a bad path fails in milliseconds.
+
+```ts
+import { defineCheck } from "mirinjs/check";
+
+export default defineCheck(async (app) => {
+  app.step("a name for this phase");
+  // …drive and assert; throw (or fail an assertion) to fail the check
+});
+```
+
+## Two traps
+
+Both produce a **passing check that verifies nothing**. Both were hit while building
+this surface, on the first real scenario.
+
+### 1. Assert on the thing that changed
+
+`expectText` matches anywhere in the accessibility tree — including the input you
+just typed into.
+
+```ts
+await app.click("text=add a todo");
+await app.type("ship it");
+await app.click("text=Add");
+await app.expectText("ship it");   // ✗ passes even when the mutation is broken:
+                                   //   the text is still sitting in the input
+```
+
+Assert against the thing the interaction was supposed to change:
+
+```ts
+await app.waitUntil(
+  async () =>
+    (await app.evaluate<string[]>('[...document.querySelectorAll("li")].map((n) => n.textContent)'))
+      .includes("ship it"),
+  "the todo never reached the list",
+);
+```
+
+### 2. Use `waitUntil`, not `assert`, after an interaction
+
+An action returns as soon as the input is dispatched. The RPC round trip it
+triggered has *not* landed yet, so a plain `assert` reads the previous state and
+races.
+
+```ts
+await app.click("text=Add");
+const items = await app.evaluate<number>('document.querySelectorAll("li").length');
+app.assert(items > 0, "…");        // ✗ races the round trip
+```
+
+`waitUntil` polls (2s default) and only fails if the condition never holds.
+`expectText` already polls for the same reason. `assert` is for facts that are
+already true — a value you just read, a shape you already have.
+
+## Driver API
+
+Every method targets the only window unless you pass `{ window: id }`.
+
+### Drive
+
+| Method | Notes |
+|---|---|
+| `click(selector, { clickCount?, window? })` | `clickCount: 3` selects a field's contents so `type` replaces them |
+| `type(text, { selector?, window? })` | Focuses `selector` first when given |
+| `key(name, { window? })` | `Enter`, `Escape`, `Tab`, … |
+| `scroll({ deltaY?, deltaX?, window? })` | |
+| `waitFor(selector, { timeoutMs?, window? })` | Waits for a selector to match |
+| `sleep(ms)` | A guess — prefer `waitFor`/`waitUntil` |
+
+Selectors are CSS **or** `text=Save`, which matches an element's accessible label:
+trimmed text, `value`, `aria-label`, `placeholder`, or `title`. Prefer `text=` — it
+matches the names `snapshot()` prints, so you never guess at class attributes.
+
+Input is synthesized through the DevTools protocol, not `element.click()`, so a
+scenario exercises the same event path a person's interaction would.
+
+### Observe
+
+| Method | Returns |
+|---|---|
+| `snapshot({ format?, window? })` | Accessibility tree (default) or `format: "dom"` for HTML |
+| `evaluate<T>(expression, { window? })` | The expression's value from the page |
+| `screenshot(label?, { window? })` | Path to the PNG; `label` goes into the file name |
+| `windows()` | `{ id, name, url, title }[]` — every window has a name |
+| `exposed()` | Slices the app published with `devtools.expose` |
+| `logs(query?)` | The event stream, filtered like the inspector's `/logs` |
+| `cdp<T>(method, params?, { window? })` | Any DevTools-protocol command |
+
+`logs` is how you assert on things the DOM cannot show:
+
+```ts
+const failed = await app.logs({ type: "rpc.error" });
+app.assert(failed.length === 0, `${failed.length} RPC call(s) failed`);
+```
+
+HTTP traffic is in the same stream, so a scenario can assert on what the app called
+and what came back — including the body, fetched on demand:
+
+```ts
+const [call] = await app.logs({ type: "network.response", contains: "/api/todos" });
+app.assert(call !== undefined, "the app never called /api/todos");
+app.assert(call.data.status === 200, `/api/todos returned ${call.data.status}`);
+
+const { body } = await app.cdp<{ body: string }>("Network.getResponseBody", {
+  requestId: call.data.requestId,
+});
+app.assert(JSON.parse(body).length > 0, "the API returned an empty list");
+```
+
+Bodies are never captured into the stream (it is plaintext on disk), and headers and
+URLs have credential values redacted — so `logs` will not hand you a token.
+
+### Verify
+
+| Method | Notes |
+|---|---|
+| `assert(condition, message)` | Right now. Not after an interaction — see trap 2 |
+| `waitUntil(condition, message, { timeoutMs? })` | Polls until truthy; a throwing condition counts as "not yet" |
+| `expectText(text, { timeoutMs?, window? })` | Polls the a11y tree — see trap 1 |
+
+### Report
+
+`app.step(name)` names the phase. Steps appear in the report with pass/fail and a
+duration, stream as `step` events in `--json`, and a failure names the step it
+happened in:
+
+```
+✓ typed query round-trips to the main process (21ms)
+✗ typed mutation updates the list (11ms)
+  → the todo never reached the list (waited 2000ms)
+```
+
+## Worked examples
+
+In the mirin repo: `examples/hello-react/check.ts` (typed query, mutation, push
+events, no failed RPC) and `examples/kitchen-sink/check.ts` (app-shell state via
+`exposed()`, opening a second window and checking it is addressable).

package/src/index.ts

@@ -16,8 +16,8 @@ try {
   console.log(`  cd ${target}`);
   console.log("  bun install");
   console.log("  bun run dev     # launches a native window with HMR + typed RPC");
-  console.log("  bun run build   # packages a standalone .app\n");
-  console.log("Requires macOS arm64, Bun, and the Xcode command-line tools.");
+  console.log("  bun run build   # packages a standalone app\n");
+  console.log("Requires Bun on macOS arm64, Windows x64/arm64, or Linux x64/arm64.");
 } catch (err) {
   console.error(`create-mirinjs: ${err instanceof Error ? err.message : err}`);
   process.exit(1);

package/src/scaffold.ts

@@ -6,13 +6,14 @@
 import {
   cpSync,
   existsSync,
-  readFileSync,
   readdirSync,
+  readFileSync,
   renameSync,
   statSync,
   writeFileSync,
 } from "node:fs";
 import { join } from "node:path";
+import { installSkill } from "./skill.ts";
 
 const TEMPLATE_DIR = join(import.meta.dir, "..", "template");
 
@@ -37,17 +38,23 @@ export function scaffold(targetDir: string, options: ScaffoldOptions = {}): stri
   const ignore = join(targetDir, "_gitignore");
   if (existsSync(ignore)) renameSync(ignore, join(targetDir, ".gitignore"));
 
-  const replacements: Record<string, string> = {
-    __APP_NAME__: appName,
-    __APP_ID__: appId,
-    __MIRIN_VERSION__: version,
-  };
+  const replacements = [
+    ["__APP_NAME__", appName],
+    ["__APP_ID__", appId],
+    ["__MIRIN_VERSION__", version],
+  ] as const;
   for (const file of walk(targetDir)) applyReplacements(file, replacements);
 
+  // After the replacement pass: the skill has no placeholders and must not be walked.
+  installSkill(targetDir);
+
   return appName;
 }
 
-function applyReplacements(file: string, replacements: Record<string, string>): void {
+function applyReplacements(
+  file: string,
+  replacements: readonly (readonly [string, string])[],
+): void {
   let text: string;
   try {
     text = readFileSync(file, "utf8");
@@ -55,7 +62,7 @@ function applyReplacements(file: string, replacements: Record<string, string>):
     return; // skip binary/unreadable files
   }
   let changed = text;
-  for (const [from, to] of Object.entries(replacements)) {
+  for (const [from, to] of replacements) {
     changed = changed.split(from).join(to);
   }
   if (changed !== text) writeFileSync(file, changed);

package/src/skill.ts

@@ -0,0 +1,37 @@
+/**
+ * Install the mirin agent skill into a project. Ships in this package because both
+ * `bun create mirinjs` (no CLI) and `mirin skill`/`mirin init` need it.
+ */
+
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+const SKILL_DIR = join(import.meta.dir, "..", "skill");
+
+/** Where a Claude Code project skill lives. */
+const INSTALL_PATH = join(".claude", "skills", "mirin");
+
+export interface InstallSkillResult {
+  /** Absolute path the skill was written to. */
+  path: string;
+  /** Relative to the project, for printing. */
+  relativePath: string;
+  replaced: boolean;
+}
+
+/** Copy the skill into `projectDir/.claude/skills/mirin`. An existing install is
+ *  replaced wholesale, not merged: a stale reference file would read as current. */
+export function installSkill(projectDir: string): InstallSkillResult {
+  if (!existsSync(SKILL_DIR)) {
+    throw new Error(`mirin skill assets are missing from the package (${SKILL_DIR})`);
+  }
+
+  const path = join(projectDir, INSTALL_PATH);
+  const replaced = existsSync(path) && readdirSync(path).length > 0;
+  if (replaced) rmSync(path, { recursive: true, force: true });
+
+  mkdirSync(path, { recursive: true });
+  cpSync(SKILL_DIR, path, { recursive: true });
+
+  return { path, relativePath: INSTALL_PATH, replaced };
+}

package/template/AGENTS.md

@@ -0,0 +1,92 @@
+# AGENTS.md — __APP_NAME__
+
+Notes for AI coding tools (and anyone driving this app without a terminal in front
+of them). This app is built with [mirin](https://github.com/Netko-Labs/mirin), which
+ships a development observability surface so you can see what the app is doing
+instead of guessing.
+
+If your tool supports skills, the detail below is also installed as one at
+`.claude/skills/mirin/`, loaded on demand rather than kept in context. Refresh it
+after upgrading the CLI with `bunx mirin skill`.
+
+## Commands
+
+```bash
+bun install
+bun run dev      # native window with Vite HMR + typed RPC (long-lived, interactive)
+bun run check    # boot once, capture a screenshot + UI snapshot, report, exit
+bun run doctor   # check the project and environment without building
+bun run build    # standalone app in ./build
+```
+
+## Verifying a change
+
+Prefer `bun run check` over `bun run dev`. It runs the same startup path but is
+**not** interactive: it waits for a window, captures a screenshot and an
+accessibility snapshot, collects errors, stops the app, and **exits non-zero if
+anything went wrong**. Treat it like a test.
+
+```bash
+bun run check            # human summary
+bun run check --json     # one JSON object on stdout
+```
+
+If it fails, `bun run doctor` names environmental causes (missing entry file, port
+in use, unsupported platform) and reports how the previous run ended.
+
+## Seeing what the app did
+
+Every run writes a structured event stream to a gitignored session directory. It
+contains main-process logs, renderer console output, uncaught exceptions with stack
+traces, failed network requests, every RPC call, and native window events.
+
+```bash
+# the newest session directory
+SESSION=$(bun -e 'console.log(JSON.parse(await Bun.file(".mirin/dev/current.json").text()).session)')
+
+tail -n 50 "$SESSION/events.jsonl"          # the stream
+cat "$SESSION/session.json"                 # startup phase timeline
+cat "$SESSION/exit.json"                    # post-mortem, after the app exits
+ls "$SESSION/screenshots"                   # captures
+```
+
+While the app is running, the same stream is queryable over a loopback HTTP
+inspector, along with live window state, a screenshot endpoint, an accessibility
+snapshot of the UI, expression evaluation, and synthetic input (click/type/key).
+`bun run dev` prints its URL; the token is in `$SESSION/inspector.json`.
+
+```bash
+PORT=$(bun -e 'console.log(JSON.parse(await Bun.file(process.argv[2]).text()).port)' "$SESSION/inspector.json")
+TOKEN=$(bun -e 'console.log(JSON.parse(await Bun.file(process.argv[2]).text()).token)' "$SESSION/inspector.json")
+
+curl -s "http://127.0.0.1:$PORT/state?token=$TOKEN"              # windows, RPC routes, app state
+curl -s "http://127.0.0.1:$PORT/logs?level=error&token=$TOKEN"   # just the errors
+curl -s "http://127.0.0.1:$PORT/snapshot?token=$TOKEN"           # the UI as an accessibility tree
+curl -s "http://127.0.0.1:$PORT/screenshot?token=$TOKEN"         # returns a PNG path to read
+```
+
+`GET /` lists every route. See mirin's `docs/agent-devtools.md` for the full surface.
+
+This is a development surface only: it is disabled in packaged builds.
+
+## Making app state visible
+
+If you find yourself guessing at internal state, publish it — it then appears in
+`/state` and in `mirin check` output:
+
+```ts
+import { devtools } from "mirinjs";
+
+devtools.expose("route", () => currentRoute);
+devtools.event({ type: "order.submitted", data: { id } });
+```
+
+## Layout
+
+- `mirin.config.ts` — the app manifest (windows, ids, devtools settings).
+- `main/` — the Bun main process: RPC handlers, app lifecycle. Runs in a Worker.
+- `ui/` — the React UI, served over the `app://` scheme in builds.
+
+The UI and the main process talk over typed RPC, not HTTP. Add a procedure in
+`main/rpc.ts` and call it from `ui/` through the generated client — don't reach for
+`fetch` between them.

package/template/README.md

@@ -5,12 +5,17 @@ TypeScript + Chromium.
 
 ```bash
 bun install
-bun run dev     # native window with Vite HMR + typed RPC
-bun run build   # standalone .app in ./build
+bun run dev      # native window with Vite HMR + typed RPC
+bun run check    # boot once, capture a screenshot + UI snapshot, exit non-zero on errors
+bun run doctor   # check the project and environment without building
+bun run build    # standalone app in ./build
 ```
 
 - `mirin.config.ts` — the app manifest (windows, ids).
 - `main/` — the Bun main process (RPC handlers, app lifecycle).
 - `ui/` — the React UI, served via the `app://` scheme in builds.
+- `AGENTS.md` — how to inspect a running app (structured logs, screenshots, UI
+  snapshots), for AI coding tools and for you.
 
-Requires macOS arm64, Bun, and the Xcode command-line tools.
+Requires Bun on macOS arm64, Windows x64/arm64, or Linux x64/arm64. macOS
+distribution builds also need the Xcode command-line tools for signing.

package/template/main/main.ts

@@ -1,11 +1,18 @@
-import { app } from "mirinjs";
+import { app, devtools } from "mirinjs";
 import { router } from "./rpc.ts";
 
 const mirin = app.serve(router);
 
+let count = 0;
+
+// Publish main-process state to the devtools inspector's `/state`. A tool driving
+// this app can read the page's DOM, but nothing here — the tick counter lives in
+// the Bun process. The getter runs per read, so this is always current.
+// See docs/agent-devtools.md; delete it if you don't want the visibility.
+devtools.expose("app", () => ({ ticks: count, windows: app.windows.all().length }));
+
 app.on("ready", () => {
   // Push a typed tick to every webview once a second.
-  let count = 0;
   setInterval(() => {
     mirin.rpc.tick.broadcast({ count: ++count });
   }, 1000);

package/template/package.json

@@ -4,6 +4,8 @@
   "type": "module",
   "scripts": {
     "dev": "mirin dev",
+    "check": "mirin check",
+    "doctor": "mirin doctor",
     "build": "mirin build"
   },
   "dependencies": {

package/template/vite.config.ts

@@ -1,5 +1,5 @@
-import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
 
 export default defineConfig({
   root: ".",