feat: illustrated explainer, published as the GitHub Pages site

.github/workflows/pages.yml

@@ -0,0 +1,43 @@
+name: pages
+
+# Publishes explainer.html as the repo's GitHub Pages site
+# (https://pacphi.github.io/agentic-kit/). The file on main is the single
+# source of truth — this workflow just renames it to index.html at deploy
+# time, so nothing is committed twice and no gh-pages branch exists.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'explainer.html'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# One deploy at a time; let an in-flight deploy finish rather than cancel.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v7
+      - name: Stage site (explainer.html -> index.html)
+        run: |
+          mkdir -p _site
+          cp explainer.html _site/index.html
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: _site
+      - id: deployment
+        uses: actions/deploy-pages@v5

MAINTAINER.md

@@ -84,7 +84,7 @@ docs/
   UPGRADING.md           # upgrade and capability-adoption motion (shipped)
   archive/               # investigative history behind each guard (not shipped)
 .github/
-  workflows/{ci,release,nightly}.yml
+  workflows/{ci,release,nightly,devcontainers,pages}.yml
   dependabot.yml
 ```
 
@@ -220,6 +220,19 @@ CI additionally runs a **CLI smoke** against a sandboxed `HOME` (see `ci.yml`):
 `x reference sync` (asserts managed blocks present), `uninstall --dry-run`. If you
 change CLI output shape, expect the smoke to catch it.
 
+Two further workflows cover surfaces `ci.yml` doesn't:
+
+- **`devcontainers.yml`** builds and smoke-tests both dev container configs with
+  the reference `devcontainer` CLI — on PRs touching what each config depends on
+  (a `dorny/paths-filter` job scopes the maintainer and consumer jobs
+  independently) and monthly, to catch base-image or published-package drift with
+  no repo change. Guide: [docs/DEVCONTAINERS.md](docs/DEVCONTAINERS.md).
+- **`pages.yml`** publishes `explainer.html` as the GitHub Pages site
+  (<https://pacphi.github.io/agentic-kit/>): on any push to `main` touching that
+  file, it stages it as `index.html` and deploys. Pages source is "GitHub
+  Actions" (`build_type: workflow`) — there is no `gh-pages` branch, and the
+  file on `main` is the single source of truth.
+
 ---
 
 ## 5. Branching methodology

README.md

@@ -4,6 +4,7 @@
 [![npm version](https://img.shields.io/npm/v/@pacphi/agentic-kit/next?label=npm%40next)](https://www.npmjs.com/package/@pacphi/agentic-kit)
 [![node](https://img.shields.io/node/v/@pacphi/agentic-kit)](https://nodejs.org)
 [![license: MIT](https://img.shields.io/npm/l/@pacphi/agentic-kit)](LICENSE)
+[![explainer](https://img.shields.io/badge/explainer-read_the_field_manual-C9581D)](https://pacphi.github.io/agentic-kit/)
 
 **One npm package that installs, heals, and *proves* [ruflo](https://github.com/ruvnet/ruflo) (claude-flow) + [agentic-qe](https://github.com/proffesor-for-testing/agentic-qe), grounds them in *RuvNet Brain* — an offline, source-cited knowledge base over the rUv stack — and wires Claude Code + Codex (+ opencode) into one ambidextrous, self-routing setup. macOS · Linux · Windows.**
 
@@ -83,6 +84,8 @@ ak status       read-only dashboard: what's true, what's drifted   [--json] [--d
 ak sync         converge to good: upgrade + heal + verify          [--dry-run] [--no-upgrade]
 ak dashboard    open the local web dashboard (auto-opens your browser)
                 [--port N] [--no-open] [--live-source 'surface=path']
+ak admin        maintainer-only telemetry admin (localhost; GitHub/npm egress)
+                [--port N] [--no-open]
 ak about        what each installed component is and why it's there
 ak system       machine footprint: install size, runtime, storage, catalog, projects
                 [--deep] [--json]
@@ -92,7 +95,6 @@ ak host         manage execution hosts, routing, and provider bindings
                 status | pick | refresh | off
 ak run          execute a host-neutral activity pipeline (including explicit OpenCode routes)
                 <template> "<task>"  [--dry-run] [--route ...] [--max-concurrent N] [--timeout ms] [--json]
-ak x statusline manage Codex's native user-wide status line          status | codex native|extended|off
 ak uninstall    leave cleanly                [--dry-run] [--this-project] [--remove-ruflo] [--remove-aqe] [--purge] [--yes]
 ```
 
@@ -112,9 +114,11 @@ command always works.)
 | **setup** | Installs/updates ruflo + agentic-qe + the **agentdb** CLI globally (handling npm ≥11.17's `allow-scripts` so natives build; agentdb is pinned to ruflo's bundled version so the shared learning store stays coherent), installs the **RuvNet Brain** (an offline knowledge base over the rUv stack, powering the `search_ruvnet` MCP — a ~2 GB one-time download, prompted; skip with `--no-ruvnet-brain`), deploys the token-audit skill, merges the managed guidance blocks into the machine-wide guidance files (`~/.claude/CLAUDE.md`, plus `~/.codex/AGENTS.md` on codex machines), offers one-time MCP registration (user scope, with a tool-family picker), and — inside a repo — initializes the project: sanitized `ruflo init`, absolute memory-path pin, a **verified** store→disk write, statusline footer, and a background daemon with **local-only ($0) workers** (token-spending AI workers stay opt-in behind upstream's machine-wide budget). Project scope triggers on a `.git` entry in the current folder; without one it's skipped with a note. `--project` forces the same project setup in the current directory (e.g. a not-yet-`git init`-ed folder); it does not locate an ancestor repository. Project initialization runs `ruflo init --full --force` and can replace existing agent configuration, so read the [setup scope and project mutation contract](docs/SETUP.md) before using it on an existing project. `--minimal` skips it, `--yes` accepts all prompts (non-interactive), `--no-aqe` / `--no-ruvnet-brain` / `--no-security` disable those subsystems, and `--reconfigure` re-offers MCP registration. `--codex` enables + installs the Codex host during setup (ambidextrous dual-host mode; both hosts then run at once), and `--primary-host claude\|codex` picks which host leads (codex implies `--codex`). |
 | **status** | Per-subsystem ✓/⚠/✗ (versions, the kit's own version, **ruvnet-brain** (present + release drift, or "not installed"), natives (agentdb copies **and** ruflo's own memory runtime — the one `npx ruflo memory` loads — load-tested for a native better-sqlite3, not just the agentdb dirs), **memory-pin** (warns when `CLAUDE_FLOW_DB_PATH` points off the live DB), security, learning, aqe/RVF, **agentdb** (CLI present + coherent with ruflo's bundled version, or a store-skew warning), MCP, **hosts** (claude/codex/opencode version + install method; the Claude/Codex **primary** marked and failed when absent), **providers** (host wiring + aqe fallback chain, or "drifted"/claude-only default), **routing** (the persisted activity host+model policy; only Claude/Codex routes project into AQE), daemons, guidance-file blocks (`~/.claude/CLAUDE.md`, project `AGENTS.md`, and `~/.codex/AGENTS.md` on codex machines), statusline), each drift row naming what `sync` would do about it — plus a **health-history** line that flags regressions since the last sync (learning shrank, native slots dropped, drift/security backslid). |
 | **sync** | The one convergence verb: upgrades first when a new release exists, then re-heals everything an upgrade wipes, then re-checks and reports. Included in that heal: it **installs any enabled frontier host** (claude/codex/opencode) that's entirely absent — never touching an external (mise/brew/native) install — and **re-applies provider wiring** (the `ENABLE_*` host env, OpenCode's native configuration, the aqe fallback chain, and ruflo API providers) whenever it has drifted — and, on a dual-host project, **seeds/heals the Claude/Codex default routing policy** (materializing eligible routes into agentic-qe's `agentOverrides`, e.g. after an aqe upgrade first makes it eligible). It also **installs/repins the standalone `agentdb` CLI** to ruflo's bundled version (keeping the shared cognitive store coherent) and appends a **health-history snapshot** so `status` can flag regressions across syncs. It also **re-runs the RuvNet Brain installer** to pull the latest release when the on-disk KB has drifted (or installs it if absent, when enabled). It also **self-updates the kit**: when a newer `@pacphi/agentic-kit` exists it installs it as the *last* step (the new code applies from the next `ak` run, never mid-sync). Prerelease installs (`4.0.0-alpha.*`) track the `next` npm dist-tag as well as `latest`, so alphas see their successors; stable installs only ever follow `latest`. `--no-upgrade` skips the self-update along with the package upgrades. |
-| **dashboard** | Opens an observation-only local web dashboard (`127.0.0.1:7431`, localhost-only, never detaches) with three primary areas: **Overview · Usage · Observability**. One fixed, left-aligned secondary rail exposes Overview's Summary/Hosts & Routing/Providers/Runtime/Intelligence views, Usage's Scorecard/Limits/Findings/Sessions/Transcript views, and Observability's Live/History scopes. Canonical deep links are hierarchical (`#overview/summary`, `#usage/sessions`, `#usage/<session-id>`, `#observability/live`); arrow keys plus Home/End operate focused tab rows. Usage indexes local Claude/Codex/OpenCode transcripts on demand. Observability groups eligible sessions by project and pairs an interactive agent/tool execution canvas with masked transcript or review evidence; its Session Stream can collapse without disconnecting so Agent activity gets more room. Live shows only current roots; History shows only retained non-live roots. A bounded owner-only cache retains safe last-recorded workspace context; no dashboard action mutates agents or repositories. Ruflo and agentic-qe stores are opt-in through repeatable `--live-source 'surface=path'`. The page is self-contained, offline-first, localhost-only, and protected by a per-session token. See the [Dashboard guide](docs/DASHBOARD.md) and [Observability guide](docs/OBSERVABILITY.md). **Auto-opens your browser** (`--no-open` for headless/SSH); `--port N` changes the port. Stop with Ctrl-C. (Also available as `ak x dashboard`.) |
+| **dashboard** | Opens an observation-only local web dashboard (`127.0.0.1:7431`, localhost-only, never detaches) with five primary areas: **About · Overview · Usage · Observability · System**. About is a plain-words directory of everything the kit installed and why (the same content as `ak about`); Overview covers readiness, hosts & routing, providers, runtime, and machine-wide intelligence; Usage turns local Claude/Codex/OpenCode transcripts into scorecards, limits, findings, and per-session detail; Observability follows live and historical agent activity with masked evidence; System reports what the stack occupies on the machine (the same data as `ak system`). Deep links are hierarchical (`#about`, `#overview/summary`, `#usage/<session-id>`, `#observability/live`, `#system/storage`). No dashboard action mutates agents or repositories; ruflo and agentic-qe stores are opt-in through repeatable `--live-source 'surface=path'`. The page is self-contained, offline-first, and protected by a per-session token. Full navigation, keyboard behavior, and per-view semantics: [Dashboard guide](docs/DASHBOARD.md) and [Observability guide](docs/OBSERVABILITY.md). **Auto-opens your browser** (`--no-open` for headless/SSH); `--port N` changes the port. Stop with Ctrl-C. (Also available as `ak x dashboard`.) |
 | **usage** | Reads provider-account analytics from local cache (`ak usage status`) or performs one explicit OpenRouter management-API refresh (`ak usage refresh openrouter`). Refresh requires `OPENROUTER_MANAGEMENT_KEY`, writes a credential-free mode-`0600` cache, and discards endpoint/user/key/session identifiers. `status` and dashboard reads make no network request. OpenRouter account rows have no grounded host/session/project correlation and are never merged into transcript totals. |
 | **admin** | Opens the **maintainer admin** (`127.0.0.1:7432`, localhost-only, foreground) — the project-telemetry sibling of `dashboard`, with the same dark/light visual theme and persisted theme preference: unique repo visitors and cloners (GitHub traffic API, needs a push-access token via `GITHUB_TOKEN`/`GH_TOKEN`/`gh auth token` — panels degrade honestly without one), contributors and watchers, npm download momentum (last 7d vs prior 7d, sparklines — shown as trend only, never an absolute reach number, since mirrors/CI inflate the raw count), latest CI run status and open Dependabot alerts, a **"since you last looked"** delta strip over a local baseline, open issues/PRs from others (oldest first), and external humans ranked by recency (bots excluded). Access is gated by a **per-session token** carried in the URL fragment and sent header-only; the page makes **zero external fetches** (the server proxies GitHub/npm; your credential never reaches the page or the payload). Where `dashboard` is offline-first, `admin` does deliberate GitHub/npm egress — that contract split is why they're siblings, not tabs. `--port N`, `--no-open`; Ctrl-C stops. (Also available as `ak x admin`.) |
+| **about** | A plain-words directory of every component the kit installs and configures — one entry per component: what it is, what it does for you, where to read more, and an honest state chip read from the same detection `ak status` uses (the prose is authored with the release; the chip is the only runtime fact). `ak about [entry-id]` opens one entry; `--category` narrows to `hosts`, `engine-memory`, `quality`, `safety`, `knowledge`, `kit`, or `configured`; `--no-detect` skips state resolution for an instant editorial read; `--json` emits the directory with resolved chips. The dashboard's About area renders this identical directory. |
+| **system** | What the stack occupies on your machine. The default read is the cheap tier: the live agent-process census, the files growing fastest between scans, and the last deep scan's figures carried forward with their date. `--deep` re-walks install trees, storage, the cross-host catalog, and every discovered project (minutes on a large machine), then persists the result; `--json` emits the same snapshot payload `/api/system` serves. The dashboard's System area renders this same data across its Summary, Advisory, Sessions, Storage, Runtime, Catalog, and Projects views. |
 | **run** | **Canonical execution surface.** Executes the template vocabulary through host-neutral supervised adapters. It accepts an explicit OpenCode route (persisted or `--route`) alongside Claude/Codex; `--dry-run` prints the exact static plan (with each worker's escalation ladder); at runtime, successful dependencies pass runtime-only, sanitized handoffs capped at 2 KiB each/8 KiB fan-in, never exposed in public JSON. A handoff may cross hosts/vendors and must exclude secrets, credentials, raw logs, and transcript excerpts. `--escalate` advances a failed worker one rung of its route's ladder per attempt (bounded by the ladder; permission/consent and uncertain results are never escalated). `--timeout` is one absolute readiness→prepare→launch→observe budget per attempt, while separately bounded teardown proves whether resources terminated. An OpenCode worker runs an isolated loopback server with ephemeral basic authentication, returns only normalized observed facts, and aborts instead of approving a permission request. `ak run` does not turn OpenCode into an AQE provider or primary host. |
 | **host** | Execution-host status, selection, primary-host choice, activity routing, and reversible teardown: `ak host status\|pick\|refresh\|off`. The plumbing spelling is `ak x host`. Inference providers and bindings remain separate concepts even though their controls share this workflow. |
 | **uninstall** | Removes the kit's footprint (and any legacy shell-kit install); project data is never touched; `--purge` also offers to remove the global packages. |

docs/DASHBOARD.md

@@ -206,9 +206,9 @@ History/Review semantics, privacy limits, and troubleshooting.
 ## System
 
 System answers what this toolchain costs the machine itself — a different question from health
-(Overview), spend (Usage), or activity (Observability). Its five views are Summary, Storage,
-Runtime, Catalog, and Projects. Projects stays separate from Storage on purpose: lines of code and
-a git remote answer "what have I built here", not "where are my bytes".
+(Overview), spend (Usage), or activity (Observability). Its seven views are Summary, Advisory,
+Sessions, Storage, Runtime, Catalog, and Projects. Projects stays separate from Storage on purpose:
+lines of code and a git remote answer "what have I built here", not "where are my bytes".
 
 ### Two tiers, and why nothing scans on open
 
@@ -300,7 +300,7 @@ removes anything; where a CLI already owns the cleanup, the row names it.
 
 ### Platforms
 
-All five views work on macOS, Linux, and Windows. On Windows the process census (host, pid, CPU,
+All seven views work on macOS, Linux, and Windows. On Windows the process census (host, pid, CPU,
 memory, uptime) is always available; the bound project is a best-effort read that can be blocked by
 antivirus, execution policy, or permissions, in which case that one column reads
 "not attributable on Windows" with the reason and every other figure in the row still renders.