spexcode 0.2.0 → 0.2.1

package/README.md

@@ -1,52 +1,52 @@
 <img src="docs/sdd-tuxedo-pooh.png" alt="Writing code vs. authoring a living, executable specification artifact" width="420">
 
+English | [中文](./README.zh-CN.md)
+
 > Spec-driven development fails two ways: the spec drifts out of sync with the code, or it
-> bloats into stale ceremony. SpexCode keeps each spec short and current — rewritten in place,
-> versioned by git, never an accumulating changelog.
+> bloats into stale ceremony. SpexCode keeps each spec short and current: rewritten in place
+> and versioned by git, not an accumulating changelog.
 
 **SpexCode** is a spec-driven, self-developing dev tool. Every part of a project becomes a versioned
-*spec node* — a `.spec/**/spec.md` whose body states the part's *present* intent — and **git is the
-database**: a node's version is its count of content commits, and "drift" is governed code that moved
-ahead of its spec. A `spex` CLI plus a live dashboard read all of it straight from git; there is no
+*spec node*: a `.spec/**/spec.md` whose body states the part's present intent. Git is the database:
+a node's version is its count of content commits, and "drift" is governed code that moved ahead of
+its spec. The `spex` CLI and the live dashboard read everything straight from git; there is no
 separate store.
 
 - **[Using SpexCode](#using-spexcode)** — adopt the `spex` CLI and drive it through your coding agent to govern *your own* project.
 - **[Contributing to SpexCode](#contributing-to-spexcode)** — hack on the tool itself, in this repo.
-- **[Working with agents →](https://spexcode.net/working-with-agents/)** — the deeper narrative on the docs site, behind this landing.
+- **[Working with agents →](https://spexcode.net/working-with-agents/)** — the longer write-up on the docs site.
 
 ---
 
 ## Using SpexCode
 
-You set SpexCode up once — `npm i -g spexcode` then `spex init` in your repo — and after that the primary
-way you use it is **by talking to your coding agent**. You describe what you want in plain language —
-*"add a spec node for the auth flow", "extract specs for this package", "dispatch a worker to implement
-Y"* — and the agent runs the `spex` CLI for you while you supervise on the board. The manual CLI below is
-the substrate; your agent is the daily interface.
+You set SpexCode up once (`npm i -g spexcode`, then `spex init` in your repo). After that, the main
+way to use it is by talking to your coding agent. You describe what you want in plain language
+(*"add a spec node for the auth flow", "extract specs for this package", "dispatch a worker to
+implement Y"*) and the agent runs the `spex` CLI for you while you supervise on the board. The
+manual CLI below is the substrate; your agent is the daily interface.
 
-That works because a freshly-launched agent **already knows SpexCode**. `spex init` materializes the whole
-contract — the spec-node ritual, the commit-before-declare gate, the merge style — into a
+That works because a freshly launched agent already knows SpexCode. `spex init` materializes the
+contract (the spec-node ritual, the commit-before-declare gate, the merge style) into a
 `<!-- spexcode -->` managed block in your repo's `CLAUDE.md`/`AGENTS.md`, which
-**[Claude Code](https://www.anthropic.com/claude-code)** and **Codex** **auto-discover** as always-on
-context (no `--append-system-prompt`, nothing to wire). From there the agent self-serves detail on demand
-from the built-in manual — `spex guide` (the workflow), `spex guide spec` / `spex guide yatsu` (the file
-formats), and `spex guide config` (every `spexcode.json` setting). You can literally say *"run `spex guide
-config` and set me up a launcher"* and it will.
-
-For the full narrative — the three pillars of driving SpexCode by talking to your agent (agent
-self-learning via the materialized block + `spex guide`, config, and the init artifacts) — see
-**[working with agents](https://spexcode.net/working-with-agents/)** on the docs site;
-**[getting started](https://spexcode.net/getting-started/)** walks the setup end to end. This README is
-the concise landing; the site goes deep.
-
-> **It's also just plain tooling.** Strip the agent away and the core is still useful on its own: **spec
-> files versioned by git**, checked by `spex lint` and shown on a read-only dashboard — no AI, and nothing
-> to run but Node and git. The vibe-coding path sits *on top* of that; it doesn't replace it.
-
-> **Requirements.** Core: **Node ≥ 22** and **git**. Driving SpexCode through an agent (or dispatching
-> workers onto your nodes) also needs **tmux** and an authenticated **Claude Code or Codex** on your PATH
-> — and those agents run commands on your machine, so read [`SECURITY.md`](./docs/SECURITY.md) before
-> exposing the backend.
+**[Claude Code](https://www.anthropic.com/claude-code)** and **Codex** auto-discover as always-on
+context. From there the agent self-serves detail on demand from the built-in manual: `spex guide`
+(the workflow), `spex guide spec` / `spex guide yatsu` (the file formats), and `spex guide config`
+(every `spexcode.json` setting). You can tell it *"run `spex guide config` and set me up a
+launcher"*.
+
+The docs site covers this in full: **[working with agents](https://spexcode.net/working-with-agents/)**
+for the agent-driven workflow, **[getting started](https://spexcode.net/getting-started/)** for the
+setup end to end.
+
+> **It's also just plain tooling.** Strip the agent away and the core is still useful on its own:
+> spec files versioned by git, checked by `spex lint` and shown on a read-only dashboard. No AI,
+> nothing to run but Node and git. The vibe-coding path sits on top of that; it doesn't replace it.
+
+> **Requirements.** Core: **Node ≥ 22** and **git**. Driving SpexCode through an agent (or
+> dispatching workers onto your nodes) also needs **tmux** and an authenticated **Claude Code or
+> Codex** on your PATH. Those agents run commands on your machine, so read
+> [`SECURITY.md`](./docs/SECURITY.md) before exposing the backend.
 
 ### Set it up
 
@@ -58,17 +58,18 @@ cd ~/my-app
 spex init              # additive — never restructures your code
 ```
 
-`spex init` is additive: it seeds a starter **`.spec/`** tree (a root `project` node plus the `.config`
-plugins that define the dev flow), a starter **`spexcode.json`**, and the per-clone **git hooks** (a
-`pre-commit` hook that runs **spec-lint** — blocking on broken spec↔code links — and **main-guard**,
-which blocks direct commits to `main`, plus a `prepare-commit-msg` hook that stamps each commit's
-session attribution). It also **materializes** the harness artifacts that make the agent path
-work: the `<!-- spexcode -->` contract block in `CLAUDE.md`/`AGENTS.md`, and the `.claude/` / `.codex/`
-shims (the `settings.json` hooks) a self-launched agent discovers. Those artifacts are generated and
-gitignored — regenerated on each machine, never committed.
+`spex init` is additive: it seeds a starter **`.spec/`** tree (a root `project` node plus the
+`.config` plugins that define the dev flow), a starter **`spexcode.json`**, and the per-clone
+**git hooks** (a `pre-commit` hook that runs **spec-lint**, blocking on broken spec↔code links, and
+**main-guard**, which blocks direct commits to `main`, plus a `prepare-commit-msg` hook that stamps
+each commit's session attribution). It also **materializes** the harness artifacts that make the
+agent path work: the `<!-- spexcode -->` contract block in `CLAUDE.md`/`AGENTS.md`, and the
+`.claude/` / `.codex/` shims (the `settings.json` hooks) a self-launched agent discovers. Those
+artifacts are generated and gitignored; they are regenerated on each machine, never committed.
 
-Then make it yours — either ask your agent to, or do it by hand: edit `.spec/project/spec.md` to describe
-the project, point `spexcode.json`'s `lint.governedRoots` at your real source dir(s), and check the graph:
+Then make it yours — either ask your agent to, or do it by hand: edit `.spec/project/spec.md` to
+describe the project, point `spexcode.json`'s `lint.governedRoots` at your real source dir(s), and
+check the graph:
 
 ```sh
 spex lint              # the "coverage" warnings are your adoption TODO list
@@ -76,18 +77,18 @@ spex lint              # the "coverage" warnings are your adoption TODO list
 
 ### Configure it
 
-Two optional JSON files at the repo root hold every setting, split by portability — pick the right one and
-that's the whole discipline:
+Two optional JSON files at the repo root hold every setting, split by portability:
 
-- **`spexcode.json`** — *committed, portable*: layout, dashboard identity (`title` + `icon`), lint budgets,
-  and launcher **names**. Facts that are true for the project.
-- **`spexcode.local.json`** — *gitignored, host-specific*: absolute launcher command paths, cert/secret
-  paths, and the private-overlay switch (`private: true`, which makes `spex materialize` leave zero trace
-  in the tracked tree — ignores go to the local git exclude, not the committed `.gitignore` — so you can
-  run SpexCode on a repo you share but don't own). Facts that are true for one machine.
+- **`spexcode.json`** — *committed, portable*: layout, dashboard identity (`title` + `icon`), lint
+  budgets, and launcher **names**. Facts that are true for the project.
+- **`spexcode.local.json`** — *gitignored, host-specific*: absolute launcher command paths,
+  cert/secret paths, and the private-overlay switch (`private: true`, which makes `spex materialize`
+  leave zero trace in the tracked tree — ignores go to the local git exclude, not the committed
+  `.gitignore` — so you can run SpexCode on a repo you share but don't own). Facts that are true for
+  one machine.
 
-There is no `spex config set` — you (or your agent) edit the files directly. **`spex guide config`** is the
-authoritative manual for every field and which of the two files it belongs in.
+There is no `spex config set` — you (or your agent) edit the files directly. **`spex guide config`**
+is the authoritative manual for every field and which of the two files it belongs in.
 
 ### Run it
 
@@ -100,11 +101,11 @@ spex dashboard      # the board UI on :5173, proxying /api to the backend
 
 Open <http://localhost:5173>.
 
-Both ports are flags (`spex serve --port 8788`, `spex dashboard --port 5174 --api-port 8788`), so you can
-run several projects' boards side by side — the working directory picks which project each serves. Give
-each tab its own identity in that project's `spexcode.json`: `dashboard.title` names it and
-`dashboard.icon` sets the favicon — an emoji (`"🔭"`), an Iconify name (`"mdi:rocket-launch"`), or a URL,
-nothing to download.
+Both ports are flags (`spex serve --port 8788`, `spex dashboard --port 5174 --api-port 8788`), so
+you can run several projects' boards side by side; the working directory picks which project each
+serves. Give each tab its own identity in that project's `spexcode.json`: `dashboard.title` names it
+and `dashboard.icon` sets the favicon — an emoji (`"🔭"`), an Iconify name (`"mdi:rocket-launch"`),
+or a URL.
 
 Day to day (the commands your agent runs for you — and that you can run yourself):
 
@@ -115,15 +116,12 @@ Day to day (the commands your agent runs for you — and that you can run yourse
 | `spex guide` | print the full workflow, plus the `spec.md` / `yatsu.md` / `config` manuals |
 | `spex board` | dump the current board state as JSON |
 
-The spec tree is ground truth and git is its database: every change is a `spec.md` node, **rewritten in
-place** (never a `## vN` changelog) and versioned by its commits.
-
 ---
 
 ## Contributing to SpexCode
 
-This repository *is* the SpexCode source, and it **dogfoods itself**: every change to the tool lands as a
-spec node merged into `main`. Set up a checkout:
+This repository *is* the SpexCode source, and it dogfoods itself: every change to the tool lands as
+a spec node merged into `main`. Set up a checkout:
 
 ```sh
 git clone https://github.com/shuxueshuxue/spexcode && cd spexcode
@@ -132,8 +130,8 @@ npm --prefix spec-dashboard install
 npm run hooks          # install the per-clone git hooks (main-guard + the session-stamp hook)
 ```
 
-The development loop runs from source, with hot-reload — this is what `npm run web` is for, as opposed
-to an installed user's `spex dashboard`:
+The development loop runs from source, with hot reload (`npm run web`, as opposed to an installed
+user's `spex dashboard`):
 
 ```sh
 npm run api            # backend on :8787, hot-reloads on spec-cli/src changes
@@ -142,6 +140,11 @@ npm run web            # the dashboard via Vite (HMR), proxying /api → :8787
 
 ---
 
+## Credits
+
+SpexCode was first introduced publicly on [LINUX DO](https://linux.do) — thanks to the community
+there for the first round of discussion and feedback.
+
 ## License
 
 [MIT](./LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,135 @@
+<img src="docs/sdd-tuxedo-pooh.png" alt="写代码 vs. 维护一份活的、可执行的规格文档" width="420">
+
+[English](./README.md) | 中文
+
+> Spec 驱动开发通常死于两种方式:spec 和代码脱节,或者膨胀成一堆过时的仪式文档。SpexCode 让每个
+> spec 保持简短、保持当前态:原地重写,由 git 记版本,不做累积式的 changelog。
+
+**SpexCode** 是一个 spec 驱动、用自己开发自己的开发工具。项目的每个部分都是一个带版本的
+*spec 节点*,即一个 `.spec/**/spec.md`,正文描述这个部分当前的意图。git 就是数据库:节点的版本号
+是它的内容 commit 数,"drift" 指被管辖的代码走到了 spec 前面。`spex` CLI 和实时看板直接从 git
+读取这一切,没有第二份存储。
+
+- **[使用 SpexCode](#使用-spexcode)**:安装 `spex` CLI,通过你的 coding agent 治理*你自己的*项目。
+- **[参与开发](#参与开发)**:在本仓库里改进工具本身。
+- **[Working with agents →](https://spexcode.net/working-with-agents/)**:文档站上更完整的介绍。
+
+---
+
+## 使用 SpexCode
+
+SpexCode 只需要设置一次(`npm i -g spexcode`,然后在你的仓库里 `spex init`)。之后的主要用法是和
+你的 coding agent 对话:用自然语言说你要什么(*"给鉴权流程加一个 spec 节点""把这个包的 spec
+提取出来""派一个 worker 去实现 Y"*),agent 替你执行 `spex` CLI,你在看板上盯进度。下面的手动
+CLI 是底座,agent 才是日常界面。
+
+这套之所以成立,是因为新启动的 agent 已经认识 SpexCode。`spex init` 会把整套约定(spec 节点流程、
+先 commit 再声明完成、merge 方式)生成到仓库 `CLAUDE.md`/`AGENTS.md` 里的 `<!-- spexcode -->`
+托管块中,**[Claude Code](https://www.anthropic.com/claude-code)** 和 **Codex** 启动时自动读到。
+更细的内容 agent 自己按需查内置手册:`spex guide`(工作流)、`spex guide spec` /
+`spex guide yatsu`(文件格式)、`spex guide config`(`spexcode.json` 的全部配置项)。你可以直接
+对它说*"跑一下 `spex guide config`,帮我配好 launcher"*。
+
+完整的说明在文档站:**[working with agents](https://spexcode.net/working-with-agents/)** 讲
+agent 驱动的用法,**[getting started](https://spexcode.net/getting-started/)** 从头到尾走一遍安装。
+
+> **抛开 agent,它也是一套普通工具。** 核心部分单独用也成立:git 记版本的 spec 文件,`spex lint`
+> 检查,只读看板展示。不含 AI,除了 Node 和 git 什么都不用跑。vibe coding 的玩法建立在这层之上,
+> 不是替代它。
+
+> **环境要求。** 核心:**Node ≥ 22** 和 **git**。要通过 agent 驱动(或者往节点上派 worker),
+> 还需要 **tmux** 和 PATH 里已登录的 **Claude Code 或 Codex**。这些 agent 会在你的机器上执行
+> 命令,对外暴露后端之前请先读 [`SECURITY.md`](./docs/SECURITY.md)。
+
+### 安装
+
+装一次发布版 CLI,然后在任何项目里接入:
+
+```sh
+npm i -g spexcode      # 安装 spex 命令(需要 Node ≥ 22)
+cd ~/my-app
+spex init              # 纯增量,不会动你的代码结构
+```
+
+`spex init` 是增量式的:生成一棵起始 **`.spec/`** 树(根 `project` 节点,加上定义开发流程的
+`.config` 插件)、一份起始 **`spexcode.json`**、每个 clone 各自的 **git hooks**(`pre-commit`
+跑 **spec-lint**,spec↔code 链接坏了会拦下;**main-guard** 拦截直接向 `main` 的提交;
+`prepare-commit-msg` 给每个 commit 盖 session 归属戳)。同时生成 agent 路径需要的产物:
+`CLAUDE.md`/`AGENTS.md` 里的 `<!-- spexcode -->` 契约块,以及 `.claude/`、`.codex/` 的
+settings hooks。这些产物是生成物,已被 gitignore,每台机器各自重新生成,不进版本库。
+
+然后把它变成你的项目,让 agent 改或者自己动手都行:编辑 `.spec/project/spec.md` 描述项目,把
+`spexcode.json` 的 `lint.governedRoots` 指向真实源码目录,再检查一遍:
+
+```sh
+spex lint              # coverage 警告就是你的接入 TODO 清单
+```
+
+### 配置
+
+仓库根目录两个可选的 JSON 文件承载全部设置,按可移植性分开:
+
+- **`spexcode.json`**:提交进仓库,可移植。布局、看板标识(`title` + `icon`)、lint 预算、
+  launcher 的**名字**。对整个项目成立的事实。
+- **`spexcode.local.json`**:gitignore,单机。launcher 命令的绝对路径、证书和密钥路径、私有覆盖
+  开关(`private: true`,让 `spex materialize` 在被跟踪的文件里不留任何痕迹,ignore 写进本地
+  git exclude 而不是提交的 `.gitignore`,适合你参与但不拥有的仓库)。只对这台机器成立的事实。
+
+没有 `spex config set`,你(或你的 agent)直接编辑文件。每个字段的含义、该放哪个文件,
+**`spex guide config`** 是权威手册。
+
+### 运行
+
+启动后端和看板,打开页面:
+
+```sh
+spex serve          # 后端(API + sessions),:8787
+spex dashboard      # 看板 UI,:5173,/api 代理到后端
+```
+
+打开 <http://localhost:5173>。
+
+两个端口都是参数(`spex serve --port 8788`、`spex dashboard --port 5174 --api-port 8788`),
+多个项目的看板可以并排跑,工作目录决定各自服务哪个项目。每个标签页的身份在各自项目的
+`spexcode.json` 里配:`dashboard.title` 定名字,`dashboard.icon` 定 favicon,emoji(`"🔭"`)、
+Iconify 名字(`"mdi:rocket-launch"`)或 URL 都行。
+
+日常命令(agent 替你跑,你也可以自己跑):
+
+| 命令 | 作用 |
+| --- | --- |
+| `spex lint` | 检查 spec↔code 图:coverage、drift、living 规则 |
+| `spex watch` | 实时输出 session / 看板的状态变化 |
+| `spex guide` | 打印完整工作流,以及 `spec.md` / `yatsu.md` / `config` 手册 |
+| `spex board` | 以 JSON 输出当前看板状态 |
+
+---
+
+## 参与开发
+
+这个仓库就是 SpexCode 的源码,而且它 dogfood 自己:工具的每个改动都以 spec 节点的形式合入
+`main`。搭一个开发环境:
+
+```sh
+git clone https://github.com/shuxueshuxue/spexcode && cd spexcode
+npm --prefix spec-cli install
+npm --prefix spec-dashboard install
+npm run hooks          # 安装每个 clone 各自的 git hooks(main-guard + session 戳)
+```
+
+开发循环直接跑源码,带热重载(开发用 `npm run web`,区别于安装用户的 `spex dashboard`):
+
+```sh
+npm run api            # 后端 :8787,spec-cli/src 改动即热重载
+npm run web            # Vite 起看板(HMR),/api 代理到 :8787
+```
+
+---
+
+## 致谢
+
+SpexCode 的首次公开介绍发在 [LINUX DO](https://linux.do),感谢佬友们的第一轮讨论和反馈。
+
+## License
+
+[MIT](./LICENSE)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",

package/spec-cli/src/cli.ts

@@ -37,7 +37,7 @@ function flushExit(code = 0): Promise<never> {
 }
 const has = (name: string) => process.argv.includes(`--${name}`)
 // bare positionals after argv index `from`, skipping flags and their values (selectors for ls/watch).
-const VALUE_FLAGS = new Set(['--status', '--as', '--interval', '--propose', '--note', '--node', '--prompt', '--timeout', '--reason', '--out', '--password', '--tls-cert', '--tls-key', '--harness', '--launcher', '--harness-session', '--port', '--api-port', '--preset'])
+const VALUE_FLAGS = new Set(['--status', '--as', '--interval', '--propose', '--note', '--node', '--prompt', '--timeout', '--reason', '--out', '--password', '--tls-cert', '--tls-key', '--harness', '--launcher', '--harness-session', '--port', '--api-port', '--host', '--preset'])
 function positionals(from: number): string[] {
   const out: string[] = []
   for (let i = from; i < process.argv.length; i++) {
@@ -137,13 +137,15 @@ if (cmd === 'serve') {
   }
   await import('./supervise.js')
 } else if (cmd === 'dashboard') {
-  // the natural post-install UI: serve the bundled dashboard on its OWN loopback port, proxying /api +
-  // the terminal socket to a separately-run `spex serve`. Replaces the dogfood-only `npm run web` (vite).
+  // the natural post-install UI: serve the bundled dashboard on its OWN port (loopback by default;
+  // --host widens the bind for LAN/tailnet viewing), proxying /api + the terminal socket to a
+  // separately-run `spex serve`. Replaces the dogfood-only `npm run web` (vite).
   const { serveDashboardLocal } = await import('./gateway.js')
   const port = Number(flag('port') ?? process.env.SPEXCODE_DASHBOARD_PORT ?? 5173)
   const apiPort = Number(flag('api-port') ?? process.env.PORT ?? 8787)
+  const host = flag('host') ?? '127.0.0.1'
   if (!Number.isInteger(port) || !Number.isInteger(apiPort)) { console.error('spex dashboard: --port and --api-port must be integers'); process.exit(2) }
-  serveDashboardLocal({ port, apiPort })
+  serveDashboardLocal({ port, apiPort, host })
 } else if (cmd === undefined || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   // `spex help <cmd>` drills into one command; bare help is the map. Both name the next layer down.
   const { commandHelp, overviewHelp } = await import('./help.js')
@@ -421,7 +423,14 @@ if (cmd === 'serve') {
   } else if (sub === 'done') {
     // sugar for awaiting; --propose merge|nothing|close, optional --note
     const p = (flag('propose') as any) || 'nothing'
-    const closeNote = p === 'close' ? CLOSE_CLEANUP : ''
+    let closeNote = p === 'close' ? CLOSE_CLEANUP : ''
+    if (p === 'close') {
+      // the DATA half of the close nudge ([[local-issues]] closeoutNudge): the still-open local issues this
+      // session touched, listed by id — empty/OFF/no-identity prints nothing. Loud on failure but never
+      // gating: the declaration must land whatever the issue store is doing.
+      try { closeNote += (await import('./localIssues.js')).closeoutNudge(sess ?? s.ownSessionId()) }
+      catch (e) { console.error(`issue closeout check failed (declaration unaffected): ${e instanceof Error ? e.message : e}`) }
+    }
     console.log(s.markDone(p, sess) ? `done (${p})${DECLARED}${closeNote}` : 'no session record')
   } else if (sub === 'park') {
     // sugar: the agent is waiting on a background task; it will self-resume (NOT idle/awaiting)

package/spec-cli/src/gateway.ts

@@ -173,15 +173,17 @@ export function startGateway(opts: GatewayOpts): void {
     socket.on('error', bail); up.on('error', bail)
   })
 
-  // `spex dashboard` passes an explicit loopback host; `--public` passes none → bind ALL interfaces (the
-  // original behaviour, IPv4+IPv6), so adding the local path never narrows the public gateway's reach.
-  const isLocal = !!opts.host
+  // `spex dashboard` passes an explicit host (loopback by default, --host to widen); `--public` passes
+  // none → bind ALL interfaces (the original behaviour, IPv4+IPv6), so adding the local path never
+  // narrows the public gateway's reach. The gate note keys on LOOPBACK, not on host-being-explicit:
+  // an ungated loopback bind is normal, an ungated wide bind is announced — never silent.
+  const isLoopback = opts.host === '127.0.0.1' || opts.host === 'localhost' || opts.host === '::1'
   const onListen = () => {
     const scheme = secure ? 'https' : 'http'
     const label = opts.label ?? 'public mode'
-    const gate = isLocal ? '' : ` — ${gated ? 'password-gated' : 'OPEN (no password)'}`   // ungated loopback is normal, not a warning
-    console.log(`[gateway] ${label} on ${scheme}://${isLocal ? 'localhost' : '0.0.0.0'}:${opts.publicPort}${gate}, proxying /api to :${opts.upstreamPort}`)
-    if (!secure && !isLocal) console.log('[gateway] (TLS off — --http)')
+    const gate = isLoopback ? '' : ` — ${gated ? 'password-gated' : 'OPEN (no password)'}`
+    console.log(`[gateway] ${label} on ${scheme}://${isLoopback ? 'localhost' : (opts.host ?? '0.0.0.0')}:${opts.publicPort}${gate}, proxying /api to :${opts.upstreamPort}`)
+    if (!secure && !isLoopback && !opts.host) console.log('[gateway] (TLS off — --http)')
   }
   // a busy public port is a hard, loud, non-zero exit — the SAME contract as the supervisor's proxy
   // (see [[spec-cli]] / listen.ts), so `spex serve` and `spex dashboard` fail a port clash identically.
@@ -270,13 +272,15 @@ export function ensureDashboardBuilt(repoRoot: string, distDir: string): void {
 }
 
 // @@@ serveDashboardLocal - the engine behind `spex dashboard`: the SAME gateway as public mode, bound to
-// loopback with no TLS and no password. It serves the bundled dist and proxies /api + the terminal socket
-// to a separately-run `spex serve`. This is the post-install replacement for the dogfood-only `npm run web`
-// (a vite dev server an installed user has no source tree for). See [[packaging]].
-export function serveDashboardLocal(opts: { port: number; apiPort: number }): void {
+// loopback by default with no TLS and no password — `--host` widens the bind to a chosen interface
+// (LAN/tailnet viewing) while staying plain HTTP; the internet face remains `spex serve --public`.
+// It serves the bundled dist and proxies /api + the terminal socket to a separately-run `spex serve`.
+// This is the post-install replacement for the dogfood-only `npm run web` (a vite dev server an
+// installed user has no source tree for). See [[packaging]].
+export function serveDashboardLocal(opts: { port: number; apiPort: number; host?: string }): void {
   const pkgRoot = fileURLToPath(new URL('..', import.meta.url))
   const distDir = resolveDistDir()
   ensureDashboardBuilt(join(pkgRoot, '..'), distDir) // bundled dist already has index.html → returns at once
   console.log(`[dashboard] serving ${distDir.endsWith('dashboard-dist') ? 'bundled' : 'monorepo'} build, /api → backend :${opts.apiPort}`)
-  startGateway({ host: '127.0.0.1', publicPort: opts.port, upstreamPort: opts.apiPort, password: '', tls: null, distDir, label: 'dashboard' })
+  startGateway({ host: opts.host ?? '127.0.0.1', publicPort: opts.port, upstreamPort: opts.apiPort, password: '', tls: null, distDir, label: 'dashboard' })
 }

package/spec-cli/src/guide.ts

@@ -3,9 +3,13 @@ const SETUP = `spex guide — run SpexCode on your own repo
 The product model: install SpexCode ONCE, then use it across all your projects — an agent drives
 the rest, you don't hand-author the spec tree or wire the dashboard yourself.
 
-1. Install the CLI (one-time, global — this ONE checkout serves every project)
-     cd spec-cli && npm install && npm link      # \`spex\` now runs from ANY directory
+1. Install the CLI (one-time, global — ONE install serves every project)
+     npm i -g spexcode                           # ONE command lands on PATH: \`spex\` (Node ≥ 22)
    It always operates on the repo of your current directory — that cwd is the only "which repo" knob.
+   (Dogfooding an unpublished HEAD from a source checkout? \`npm link\` at the repo ROOT — that links
+   the \`spexcode\` package itself, never the internal @spexcode/spec-cli. Both paths own the same
+   \`spex\` bin, so uninstall one before switching (\`npm rm -g spexcode\`). A source link ships no
+   prebuilt dashboard dist — \`spex dashboard\` needs a manual dashboard build, or use the dev server.)
 
 2. Adopt a repo
      cd <your-repo> && spex init                 # seeds .spec/ + git hooks (additive, never overwrites)
@@ -17,11 +21,11 @@ the rest, you don't hand-author the spec tree or wire the dashboard yourself.
    Serve a different repo by running it from there; two repos at once = two \`spex serve\` on two PORTs.
 
 4. Open the dashboard — the SAME board for every project, pointed per project
-     cd spec-dashboard && npm install                        # once
-     API_URL=http://localhost:<port> npm run dev             # point this board at step 3's backend
-   The board is a viewer: API_URL is how the shared install points at each project (one dev-server
-   per project). "dashboard": { "apiUrl": "..." } in spexcode.json is the default ONLY when the board
-   lives inside the project (the dogfood layout) — for a shared install, use API_URL.
+     spex dashboard                              # serves the bundled board on :5173, proxying /api
+   Point it at another backend with --api-port (pairs with \`spex serve --port\`); one dashboard per
+   project. The board is a viewer — which backend it proxies is the only "which project" knob.
+   (Dogfood/source alternative: API_URL=http://localhost:<port> npm run dev in spec-dashboard —
+   the dev server; "dashboard": { "apiUrl": "..." } in spexcode.json applies only to that layout.)
 
 5. Govern your layout (optional)
      spexcode.json sets lint's governedRoots/sourceExtensions and any non-default worktree layout.

package/spec-cli/src/help.ts

@@ -276,10 +276,12 @@ TLS (own cert via --tls-cert/--tls-key; --http drops TLS).`,
   },
   dashboard: {
     line: 'dashboard             serve the dashboard UI (default :5173), proxying /api to a running serve',
-    body: `Usage: spex dashboard [--port N=5173] [--api-port N=8787]
+    body: `Usage: spex dashboard [--port N=5173] [--api-port N=8787] [--host H=127.0.0.1]
 
 Serves the bundled dashboard on its own port and proxies /api + the terminal socket to a running
-\`spex serve\`. The installed replacement for the dev-only \`npm run web\`.`,
+\`spex serve\`. The installed replacement for the dev-only \`npm run web\`. Loopback-only by default;
+--host 0.0.0.0 (or a specific interface) opens it to a LAN/tailnet — still plain HTTP with no gate,
+so bind wide only on a network you trust (for the internet, use \`spex serve --public\`).`,
     see: 'spex serve (must be running first)',
   },
 

package/spec-cli/src/index.ts

@@ -4,8 +4,8 @@ import { cors } from 'hono/cors'
 import { etag } from 'hono/etag'
 import { createNodeWebSocket } from '@hono/node-ws'
 import { loadSpecs, loadSpecsLite, specContent, specHistory, specDiffAt, loadConfig } from './specs.js'
-import { issuesEnabled, postLocalIssue, remarkOnHost, resolveRemark, retractRemark } from './localIssues.js'
-import { closeIssue, mergedIssues, replyIssue } from './issues.js'
+import { issuesEnabled, remarkOnHost, resolveRemark, retractRemark } from './localIssues.js'
+import { closeIssue, createIssue, issueStores, mergedIssues, replyIssue } from './issues.js'
 import { residentForgeState, refreshForgeNow } from '../../spec-forge/src/resident.js'
 import { summarize } from './mentions.js'
 import { resolveLayout, mainBranch } from './layout.js'
@@ -159,6 +159,7 @@ app.get('/api/launchers', (c) => c.json({
 app.get('/api/issues', etag(), (c) =>
   c.json({
     enabled: issuesEnabled(),
+    stores: issueStores(),
     issues: mergedIssues({ host: 'github', state: residentForgeState() }, loadSpecsLite().map((s) => s.id)),
   }))
 // the WRITE surface ([[local-issues]] / [[issues-view]]) — the human reply path, STORE-ROUTED through the one
@@ -211,10 +212,16 @@ app.post('/api/issues', async (c) => {
   if (!concern) return c.json({ error: 'empty concern' }, 400)
   const nodes = Array.isArray(body?.nodes) ? (body.nodes as unknown[]).filter((n): n is string => typeof n === 'string') : []
   const postBody = typeof body?.body === 'string' ? body.body : undefined
+  const store = typeof body?.store === 'string' && body.store.trim() ? body.store.trim() : 'local'
   // typed evidence[] — yatsu content-addressed hashes (the annotator's clip reference rides here, not prose)
   const evidence = Array.isArray(body?.evidence) ? (body.evidence as unknown[]).filter((h): h is string => typeof h === 'string' && /^[0-9a-f]{64}$/.test(h)) : []
-  const { thread, outcomes } = await postLocalIssue(concern, { nodes, body: postBody, evidence, author: 'human' })
-  return c.json({ ok: true, id: thread.id, outcomes: summarize(outcomes) }, 201)
+  try {
+    const r = await createIssue(concern, { store, nodes, body: postBody, evidence, author: 'human' })
+    if (r.store !== 'local') await refreshForgeNow()
+    return c.json({ ok: true, id: r.id, store: r.store, url: r.url, outcomes: summarize(r.outcomes) }, 201)
+  } catch (e) {
+    return c.json({ error: String((e as Error).message || e) }, store === 'local' ? 500 : 502)
+  }
 })
 
 // the REMARK write surface ([[remark-substrate]]) — server PARITY with the CLI: the dashboard can author /