feat: add interactive terminal UI

.github/workflows/ci.yml

@@ -29,10 +29,19 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
           cache: npm
-          cache-dependency-path: package-lock.json
+          cache-dependency-path: |
+            package-lock.json
+            tui/package-lock.json
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.14
 
       - name: Install dependencies
-        run: npm ci
+        run: |
+          npm ci
+          npm ci --prefix tui
 
       - name: Build dashboard
         run: npm run build:dashboard
@@ -44,5 +53,42 @@ jobs:
       - name: Verify
         run: npm run verify
 
-      - name: Verify package payload
-        run: npm run verify:package
+  terminal-package:
+    runs-on: macos-14
+    timeout-minutes: 15
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: |
+            package-lock.json
+            tui/package-lock.json
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.14
+
+      - name: Install dependencies
+        run: |
+          npm ci
+          npm ci --prefix tui
+
+      - name: Build packaged terminal binaries
+        run: |
+          npm run build:dashboard
+          npm run build:tui
+          npm run build:catalog:tui
+
+      - name: Fast terminal verification
+        run: npm run verify:fast
+
+      - name: Verify installed current-host package
+        run: |
+          npm run verify:package
+          npm run test:global-install

.github/workflows/publish.yml

@@ -39,7 +39,14 @@ jobs:
           node-version: 22
           registry-url: https://registry.npmjs.org
           cache: npm
-          cache-dependency-path: package-lock.json
+          cache-dependency-path: |
+            package-lock.json
+            tui/package-lock.json
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.14
 
       - name: Refuse to publish from a non-main ref
         run: |
@@ -204,7 +211,9 @@ jobs:
 
       # Install from the RELEASE commit's lockfile so gate + publish match the released tree.
       - name: Install dependencies for the release commit
-        run: npm ci
+        run: |
+          npm ci
+          npm ci --prefix tui
 
       - name: Verify any existing remote tag
         env:
@@ -232,6 +241,8 @@ jobs:
       - name: Gate exact release commit
         run: |
           npm run build:dashboard
+          npm run build:tui
+          npm run build:catalog:tui
           npm run verify
           npm run verify:package
 

README.md

@@ -14,13 +14,25 @@ The global package installs the `burnlist` command and registers the bundled Bur
 
 Ask your agent to create a Burnlist for a goal or continue an existing one. The skill owns that workflow; the CLI provides the dashboard and protocol helpers.
 
+From any repository, the intended first interaction is simply:
+
+```text
+Set up Burnlist in this repo.
+```
+
+The globally installed skill initializes and registers the repository, briefly
+explains the workflow, and asks what you want to burn.
+
 Run the dashboard from any project:
 
 ```sh
 burnlist
 ```
 
-The server binds to loopback by default and prints its local URL.
+The server binds to loopback by default and prints its local URL. A global
+installation starts one persistent shared observer and `burnlist` prints its
+discovered URL; `burnlist service start|stop|restart|status` exposes its
+lifecycle. Use `burnlist serve` for an explicitly foreground server.
 
 ## How It Works
 
@@ -192,6 +204,34 @@ Untracked hook configs are added to `.git/info/exclude` by default; tracked conf
 
 Use `burnlist --help` for dashboard ports, scan roots, local state paths, and Oven data bindings.
 
+## Terminal UI
+
+The experimental terminal observer lives in `tui/`. Its landing page is a
+responsive full-width Burnlist list. Burnlist detail exposes navigable active
+and completed items, marks the latest completion, and opens item-specific Oven
+views. OpenTUI React owns layout and input; glyphcss from the adjacent
+`../../glyphcss` checkout renders the animated fire and effects. Visual Parity
+PNGs use the native image layer in the Burnlist OpenTUI fork on VS Code, iTerm,
+and WezTerm, with the 2×2 RGBA glyph renderer retained underneath as a portable
+fallback. In VS Code, enable `terminal.integrated.enableImages`. Backgrounds
+remain transparent and dividers adapt to the host terminal palette, including
+VS Code themes.
+The visual-review TUI is currently built from a source checkout rather than
+embedded in the universal npm package. This avoids sending large Darwin-only
+binaries to every host. Use `npm --prefix tui install && npm run build:tui`,
+then open it through the regular CLI with `burnlist -i`. The CLI validates the
+shared observer recorded in `~/.burnlist/server.json` and restores it when
+needed; `burnlist -i --local` instead owns one ephemeral observer for the TUI
+session. Screen layouts are declarative `.glyph` documents under
+`tui/screens/`. Pass an explicit dashboard with
+`burnlist -i --server http://127.0.0.1:4510`.
+
+Use up/down to navigate Burnlists and inspect their items. `o` opens the
+global generic Oven catalog; installed repository-specific Ovens remain scoped
+to their Burnlists. In a Burnlist, `[` and `]` move between compatible Oven
+lenses. `q` always goes back, and `escape` goes back from nested views or exits
+only from the main landing page. `r` refreshes the current data.
+
 ## Built-in Loops (Stage 1)
 
 Items may use direct execution or one of exactly three built-in Loops:
@@ -259,16 +299,19 @@ Burnlist's CLI, server, and dashboard support Node.js 18 or newer. The Storybook
 ```sh
 npm install
 npm run build:dashboard
+npm run build:tui
 npm run storybook
 npm run build:storybook
 npm run test:differential-testing
+npm run test:tui
+npm run verify:fast
 npm run verify
 npm run verify:clean
 npm run verify:package
 npm run test:global-install
 ```
 
-`verify:clean` checks the source, npm payload, and isolated global install from a temporary copy.
+`verify:fast` is the non-mutating inner loop for TUI types, tests, generated-frame freshness, and prototype coverage audits; it intentionally does not claim final 100% coverage. `verify` remains the required full gate (`verify:gate` is an alias). `verify:clean` checks the source, npm payload, and isolated global install from a temporary copy.
 
 ## Oven events
 

bin/burnlist.mjs

@@ -28,6 +28,8 @@ const knownSubcommands = new Set([
   "unregister",
   "roots",
   "init",
+  "service",
+  "serve",
 ]);
 
 function printSkillUsage(command) {
@@ -51,12 +53,49 @@ function printLifecycleUsage(command) {
 }
 
 async function main() {
+if (args.includes("-i") || args.includes("--interactive")) {
+  const { runInteractiveCli } = await import("../src/cli/interactive-cli.mjs");
+  process.exitCode = await runInteractiveCli({ args, packageRoot });
+  return;
+}
+
+if (args[0] === "service") {
+  const { runServiceCli } = await import("../src/cli/service-cli.mjs");
+  process.exitCode = await runServiceCli({ args, packageRoot });
+  return;
+}
+
 if (args[0] === "install" || args[0] === "uninstall") {
   if (args.includes("--help") || args.includes("-h")) {
     printSkillUsage(args[0]);
     return;
   }
+  let cleanupPurgedService;
+  if (args[0] === "uninstall" && args.includes("--global") && args.includes("--purge")
+    && !args.includes("--dry-run")) {
+    const packageJson = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8"));
+    const { ownedGlobalInstall, removeInstallMarker } = await import("../src/service/runtime.mjs");
+    const { serviceStatus, stopRuntime } = await import("../src/service/supervisor.mjs");
+    if (ownedGlobalInstall(packageRoot, packageJson.version)) {
+      cleanupPurgedService = async () => {
+        const status = await serviceStatus();
+        if (status.running && !await stopRuntime(status.runtime)) {
+          throw new Error("the owned global service did not stop");
+        }
+        removeInstallMarker(packageRoot);
+      };
+    }
+  }
   process.exitCode = runSkillsInstallCli({ args, packageRoot });
+  if (process.exitCode === 0 && cleanupPurgedService) {
+    try {
+      await cleanupPurgedService();
+      console.log("Burnlist: stopped and removed the global service registration.");
+    } catch (error) {
+      console.error(`Burnlist: ${error.message}`);
+      process.exitCode = 1;
+    }
+  }
   return;
 }
 
@@ -111,6 +150,9 @@ if (!["oven", "hooks", "loop", "agent", "route"].includes(args[0]) && (args.incl
 
 Usage:
   burnlist [--port <port>] [--scan-root <repo[,repo...]>]
+  burnlist -i [--server <url>]
+  burnlist service <start|stop|restart|status>
+  burnlist serve [dashboard options]
   burnlist --plan <burnlist.md> --check
   burnlist --plan <burnlist.md> --digest
   burnlist --close-completed [--scan-root <repo[,repo...]>]
@@ -154,6 +196,8 @@ Usage:
   burnlist uninstall [--global] [--agent codex,claude] [--dry-run] [--purge]
 
 Options:
+  -i, --interactive     Open the interactive terminal UI.
+  --local               With -i, force an ephemeral local server.
   --auto-port           Try the next available loopback port.
   --host <host>         Bind host; loopback is required by default.
   --state-dir <path>    Override ignored dashboard observer state.
@@ -190,8 +234,19 @@ if (args[0] === "oven") {
   await runLoopCliEntry(args.slice(1));
 } else if (["register", "unregister", "roots", "init"].includes(args[0])) {
   await import("../src/cli/registry-cli.mjs");
-} else {
+} else if (args[0] === "serve") {
+  process.argv.splice(2, 1);
   await import("../src/server/burnlist-dashboard-server.mjs");
+} else {
+  const packageJson = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8"));
+  const { ownedGlobalInstall } = await import("../src/service/runtime.mjs");
+  if (args.length === 0 && ownedGlobalInstall(packageRoot, packageJson.version)) {
+    const { ensureSharedService } = await import("../src/service/supervisor.mjs");
+    const runtime = await ensureSharedService({ packageRoot, version: packageJson.version });
+    console.log(runtime.url);
+  } else {
+    await import("../src/server/burnlist-dashboard-server.mjs");
+  }
 }
 }