viewable-one 0.0.0-stage → 0.12.1

package/README.md

@@ -1,3 +1,756 @@
-# Temporary Holding Version
+# Viewable
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Viewable connects coding agents to the Viewable board over a hosted
+MCP endpoint (`https://app.viewable.one/mcp`), the same one claude.ai,
+Claude Code, Codex and opencode all reach over OAuth. Agents can read the
+board, propose changes, ask you questions on the canvas, and report their
+work. A background runner can also start Claude Code, Codex and opencode
+sessions requested from the board.
+
+The package is one command, `viewable`: the background runner, plus `init`,
+`doctor`, `login` and `uninstall` to connect a project, sign this machine in
+and take it all away again. It starts no server of its own. The board tools
+are served from the hosted endpoint, and a run is a row your runner claims,
+so both work the same whether or not the app is open.
+
+Linking a folder is for the project files - the file tree, documents,
+briefs on disk. `.glytch/` inside the project holds only the saved agent
+selection, image staging and a repo-map cache: this machine's own scratch,
+never the board.
+
+## Quick start
+
+You need Node.js 22 or newer and Chrome or Edge for the board's folder link.
+
+1. Install the coding agents you want to use - Claude Code, Codex, opencode.
+2. `npm install -g viewable-one@latest` (Windows PowerShell: `npm.cmd i -g viewable-one@latest`).
+   Never use sudo. If npm reports a permissions error, use a user-owned prefix.
+   Persist its bin directory in your shell startup configuration or Windows user
+   PATH. Open a new normal terminal and check `viewable -v` (`viewable.cmd -v`
+   in PowerShell) before continuing. A temporary PATH export is not enough.
+3. `viewable init` inside the project folder. Choose one or more agents with
+   the arrow keys (`j`/`k` also work); Enter or Space checks the row under the
+   cursor, `a` checks or unchecks all, and Enter on the "Continue" row below
+   the agents finishes. Without a terminal - a script, CI, a pipe - there is
+   no picker to drive: pass `--agents claude,codex` (names, comma separated)
+   or `--yes` for every agent this machine already has installed.
+4. Open the board and run an idea on your coding agent. With one project
+   connected it is picked for you; with more, pick one in Settings >
+   Connection. Linking the folder in the app is optional: it only shows the
+   project's files on the board.
+
+`viewable init` signs this machine in and then connects each selected agent, so
+a browser opens once for the machine and once per agent rather than leaving
+you a list of commands to run - Claude Code needs 2.1.186 or newer for its
+part, and below that floor `init` prints the `/mcp` step instead.
+
+Then restart your coding agent's MCP connection to load the board tools - in
+Codex, the project must also be trusted - and ask it to read the board.
+`viewable doctor` names anything that still needs attention.
+
+Repeat `viewable init` in each project you want to connect. Installing the npm
+package and signing this machine in are one-time steps; agent choices and
+board connections are per project.
+
+### Windows
+
+PowerShell blocks npm's shim by default: `viewable : File ...\viewable.ps1
+cannot be loaded because running scripts is disabled on this system`. Either
+run the command with `.cmd` once (`viewable.cmd init`), or allow your own
+scripts once with `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` and
+use plain `viewable init` from then on. Check `node -v` is 22 or newer first,
+and run `viewable init` from inside the project folder itself, not a parent
+folder or a shortcut to it.
+
+## Uninstall
+
+`viewable uninstall` is the one command: it disconnects every project this
+machine has registered (agent sign-outs, config entries, `.glytch/agents.json`,
+each folder's registry entry), stops the login daemon and removes its file,
+revokes this machine's board sign-in and forgets the credential, and deletes
+`~/.viewable` entirely. It confirms once - the plan is printed and it asks you
+to type `yes` - before touching anything.
+
+```bash
+viewable uninstall
+```
+
+- `--project` disconnects only the current folder; nothing machine-wide runs.
+- `--keep-login` leaves this machine signed in to the board.
+- `--dry-run` reports what each step would do and changes nothing.
+- `--yes` skips the confirmation prompt (required without a terminal).
+
+Two things it cannot do for you, printed at the end: uninstall the npm
+package itself (`npm uninstall -g viewable-one`, or `npm unlink -g viewable-one` from
+`bridge/` in a checkout), and unlink the folder in the app's Project panel.
+
+`forget`, `stop` and `logout` remain as the three partial verbs `uninstall`
+runs together - use one of them directly when you want only its own piece.
+
+## Choose coding agents
+
+| Selection | Project configuration | Board MCP tools | Sessions launched from the board |
+| --- | --- | --- | --- |
+| `claude` | `.mcp.json` | Yes, once you sign in (`/mcp` in a session) | Yes |
+| `codex` | `.codex/config.toml` | Yes, once you sign in (`codex mcp login viewable`) | Yes |
+| `opencode` | `opencode.jsonc` if present, otherwise `opencode.json` | Yes, once you sign in (`opencode mcp auth viewable`) | Yes |
+
+The board is one hosted connection now (`https://app.viewable.one/mcp`), not a
+binary this package spawns: `viewable init` writes the URL into each selected
+agent's configuration, and the agent's own OAuth flow is the one-time step
+that finishes connecting it - `viewable doctor` names the same step again if
+you skip it.
+
+`viewable init` defaults to detected agents on the first run and the saved
+selection on later runs. You can select an agent before installing it; the
+configuration will be ready, and `doctor` will report the missing executable.
+
+For scripts, pass the selection explicitly:
+
+```bash
+viewable init --agents claude,codex
+viewable init --agents claude,opencode,codex
+```
+
+`viewable init --yes` accepts saved choices, or all detected agents when there
+are no saved choices. It fails if neither provides an agent. Without a
+terminal, a first run requires `--agents` or `--yes`; subsequent runs can reuse
+the saved selection without a prompt.
+
+Choosing an agent here connects its MCP tools. Which agent runs a prompt is
+chosen separately on the board.
+
+## What setup changes
+
+`viewable init`:
+
+- Saves the selection in `.glytch/agents.json` in the project.
+- Registers the project in `~/.glytch/folders.json`.
+- Adds the board's hosted URL (`https://app.viewable.one/mcp`) to each
+  selected agent's project configuration.
+- Signs this machine in when it is not already, the same flow as
+  `viewable login`. `--no-login` skips it.
+- Runs each selected and installed agent's own sign-in. `--no-agent-login`
+  skips all of them.
+- Installs or repairs one login daemon that watches registered projects.
+- Reports which coding agents are installed and Claude Code's login status.
+
+Existing board entries are preserved, including custom commands and disabled
+entries. Other servers and settings are kept; Codex and opencode comments
+are kept too. A file that cannot be safely extended is reported without being
+overwritten. Codex inline tables such as `mcp_servers = {...}` may need to be
+converted to TOML sections before adding a new board entry.
+
+One exception to "preserved": an entry written by an older version of this
+package is recognised as its own and upgraded in place on the next `glytch
+init` or `viewable doctor`. That covers both shapes it could be in - an entry
+that spawns a local command, which is rewritten to the hosted URL because no
+such server runs any more, and an entry keyed `board` already sitting at
+the hosted URL, which is renamed to the key this version writes. Any other
+custom entry, including one that merely looks similar, is left untouched.
+
+The MCP server key is `viewable`. A `board` entry pointing anywhere but the
+hosted URL is left exactly alone.
+
+The board is one hosted connection, so there is no more `PM_BOARD_ROOT` or
+working directory to write into a Codex or opencode board entry, and no
+per-machine path to update if you copy a config or move the project - the URL
+is the same everywhere.
+
+What each agent still needs once, per project, is its own sign-in, and `init`
+now runs it for you rather than printing it. Each agent keeps its own token
+under its own account; there is no shared credential written into any config
+file. Claude Code's shell verb needs 2.1.186 or newer - below that, `init`
+prints the `/mcp` step to run inside a session. An agent that already holds a
+token is skipped, except Codex, which does not report whether it holds one,
+so its sign-in runs every time and short-circuits itself. With no terminal,
+or with `--no-agent-login`, `init` prints each command instead of running it,
+and `viewable doctor` names the same step again if you skip it.
+
+`viewable doctor` and background repair maintain the saved selection. Changing
+it does not uninstall an existing connection; it stops maintaining deselected
+agents. Older installs retain their legacy Claude/opencode repair behavior
+until `viewable init` saves choices. An invalid selection file stops repair
+rather than silently choosing other agents.
+
+### Background runner
+
+| Platform | Login daemon |
+| --- | --- |
+| macOS | LaunchAgent at `~/Library/LaunchAgents/ai.glytch.runner.plist` |
+| Windows | Per-user onlogon task `ai.glytch.runner`, registered from `~/.glytch/ai.glytch.runner.xml`, running `~/.glytch/ai.glytch.runner.cmd` |
+| WSL / Linux | User service at `~/.config/systemd/user/ai.glytch.runner.service` |
+
+The daemon carries `PM_SPAWN_RUNNER=on` and your shell's PATH. It runs approved
+board requests using your coding agent subscription; installing the bridge
+itself does not make a model call. `viewable stop` stops the daemon. On Linux or
+WSL without a user systemd service, setup prints the manual command:
+
+```bash
+PM_SPAWN_RUNNER=on viewable runner watch
+```
+
+On Windows the task is registered from an XML definition rather than from
+`schtasks /create /sc onlogon /tr`: the command line names no principal, so
+Task Scheduler registers the logon trigger for the Users group, and writing
+an all-users task into the root of the library needs an administrator. The
+XML names your own account on the trigger and on the principal
+(`InteractiveToken`, `LeastPrivilege`), which is a registration you may make
+yourself. If Task Scheduler still refuses it - a policy, or a task of that
+name owned by another account - `viewable doctor` says so and names the two
+ways out instead of sending you back to `viewable init`: run `viewable init` once
+from a terminal opened with **Run as administrator**, or skip the daemon and
+run the runner by hand:
+
+```powershell
+$env:PM_SPAWN_RUNNER="on"; viewable runner watch
+```
+
+or, in `cmd.exe`:
+
+```bat
+set PM_SPAWN_RUNNER=on && viewable runner watch
+```
+
+### MCP-only setup by hand
+
+For board tools without the background runner, install the package and add
+one of these project configurations directly, then sign in. There is no path
+or working directory to fill in: the board is one hosted URL, the same on
+every machine.
+
+Claude Code, in `.mcp.json`:
+
+```json
+{ "mcpServers": { "viewable": { "type": "http", "url": "https://app.viewable.one/mcp" } } }
+```
+
+Then, in a session on this project, run `/mcp` and authenticate the board
+connection.
+
+Codex, in `.codex/config.toml`:
+
+```toml
+[mcp_servers.viewable]
+url = "https://app.viewable.one/mcp"
+```
+
+Then sign in: `codex mcp login viewable`.
+
+opencode, in `opencode.json` or `opencode.jsonc`:
+
+```json
+{ "mcp": { "viewable": { "type": "remote", "url": "https://app.viewable.one/mcp", "enabled": true } } }
+```
+
+Then sign in: `opencode mcp auth viewable`.
+
+Configuration references: [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
+and [opencode MCP](https://opencode.ai/docs/mcp-servers/).
+
+## The board tools
+
+Fifteen tools reach the board from a session, over the hosted endpoint. They
+work with no app open at all; what to authenticate with when no browser is
+signed in is in [Reading the board with no app
+open](#reading-the-board-with-no-app-open).
+
+| tool | what it does |
+| --- | --- |
+| `get_board(board_id?, tag?, group?, kind?, since_days?, match?, limit?, view?, geometry?, detail?)` | The board as a readable digest: ids, one line per idea, groups, edges, question state, open flags, ages. Slim by default. The filters narrow it, and the reply always says what it left out. `view:"full"` returns everything, `geometry:true` adds positions and sizes. |
+| `get_node(id)` | One node in full from the graph mirror, with its incoming and outgoing edges. Images attached to the idea come back as image blocks to look at, each labelled with the node and field it came from. An image the mirror does not hold is named as unavailable rather than quietly left out. |
+| `get_library()` | The component library a DRAWN idea is written against, generated from the same registry the app renders with: every tag, its attributes, which are required, a working example, and the rules a drawing must keep. Read it once before passing `snippet` on `addIdea` or `addTextNote`. About 2k tokens, so once per session, not once per drawing. |
+| `propose(ops[], label?)` | Sends board change requests and returns its op id. Every create, edit and delete lands as a proposal you accept or reject. |
+| `ask_user(question, why, options?, from_id?)` | Adds a question to an idea's conversation and returns at once; the answer comes back through `check_answer` or `collect_session`. `why` is required: it is shown under the question and is the context that travels with it. With no `from_id` the question goes on the idea the run belongs to. |
+| `check_answer(question_id, wait_s?)` | Where an earlier question stands: answered with the decision, still open, dismissed, or not yet ingested. With `wait_s` (up to 50) it waits that long for the answer and returns as soon as it lands; an agent that cannot go on without the answer keeps calling it until it is answered or dismissed. |
+| `report(did[], decide?, flags?, title?)` | The end of session report, as ideas rather than a paragraph. See below. |
+| `collect_session(since?, key?)` | What you have said about this session's run: answered questions with the decision, questions still open, and notes on any idea the run produced. Pass `since` for only what is new. |
+| `set_brief_status(id, status, result?)` | Moves a brief through draft, sent or done. Done needs a one line result, which lands as an idea. This applies without a proposal, the way a comment does. |
+| `list_sessions()` | Every run row on this account, in one of three states: open to messages, running one-shot, or finished. Only the first can be talked to. |
+| `mark(kind, ids[], why, evidence?)` | Points at one or more ideas that deserve attention, with a reason and a receipt. It changes nothing on the board: the mark draws as a badge and lands in your inbox, where you act on it or dismiss it. `why` and the evidence are required - a mark is read far from the turn that made it. A pair you already dismissed is not raised again until one of the ideas changes. |
+| `get_log(since?, limit?)` | The calling agent's own log: one line per turn it took, what it read and called, what it produced, what it cost, and what you did with the result afterwards - accepted, rejected, dismissed, edited or deleted, with your reason. Its own rows only, never another agent's. |
+| `send_message(to_session_id, message, from)` | Delivers a message into a running persistent session, which its runner hands over as a user turn within a couple of seconds (the row equivalent of a reply file, `bridge/lib/rowsAnswers.mjs`). Refused for a finished session, a one-shot session and an unknown id, each with the reason. |
+| `open_session(title, brief?)` | Accepted and ignored. Session frames are gone, so this opens nothing; it stays so a session that still calls it is told plainly instead of getting an unknown tool error. |
+| `close_session()` | Accepted and ignored, for the same reason. Calling `report` is the whole ending. |
+
+`list_sessions` and `send_message` are a PULL, not a push. Nothing holds a
+session's stdin open over the network, so a session is OPEN TO MESSAGES only
+while it keeps calling tools, STALE once it has gone quiet without closing,
+and FINISHED once it has. `send_message` refuses a STALE or FINISHED target,
+and a message to an OPEN one is delivered the next time that session calls
+`collect_session`.
+
+There is deliberately no way to answer a question or run an idea from these
+tools. Questions are yours to answer. A run uses your own Claude Code or Codex plan.
+
+Every rule these tools state, they also check. A bad call is refused before
+any file is written and every violation comes back in one message, so nothing
+lands half applied on your board: `report`'s counts, lengths and evidence
+rule, `propose`'s op count, call names and `$name` references, `ask_user`'s
+options and required `why`, `set_brief_status`'s status and result.
+
+### Reading the board with no app open
+
+Every board read goes over the hosted endpoint. There is no mode to turn on
+and no local board server to start. What decides whether a read has anything
+to authenticate with:
+
+1. **`viewable login`** - opens a browser, you sign in and approve, and the
+   credential lands in `~/.glytch/auth.json` (mode 0600; `GLYTCH_HOME` moves
+   it). This is the OAuth flow claude.ai's own connector uses
+   (`supabase/functions/board-oauth`), driven from a terminal instead of a
+   phone. `viewable logout` forgets it.
+2. **`GLYTCH_BOARD_TOKEN`**, for a script that would rather not open a
+   browser: a personal access token minted in Viewable (**Settings,
+   Connection, Access tokens** - it starts with `pmb_`, shown once). It wins
+   outright over a `viewable login` credential and needs no file.
+
+That bearer is what every board tool call uses, including every call made by
+a session the runner started - its own bearer is resolved the same way, once
+per run (see `bridge/SPAWN.md`).
+
+If a read says the token was refused or expired, run `viewable login` again, or
+mint a fresh personal access token and set it again. `viewable doctor`'s board
+sign-in row names the account the credential actually reaches, which is worth
+checking when work lands somewhere you are not looking.
+
+### How `ask_user` waits, and `check_answer` collects
+
+`ask_user` does not wait. It writes the question note and returns a
+`question_id` (the note's id) at once, because nothing on a stateless HTTP endpoint can hold
+a connection open while you think. `check_answer(question_id)` is the way
+back to that one question's decision, dismissed or open state, and it works
+across restarts because it re-reads the row rather than anything held in
+memory.
+
+`collect_session(since?)` is the wider door: everything THIS run's own key
+has asked that now has an answer (every one, every call - there is no time
+filter on an answered question), every message another session sent this
+one (drained, `delivered_at`-stamped, on the way out), and notes written
+on any idea the run produced (these ARE filtered by `since`). Pass the
+`next_since` a previous call returned to see only what is new.
+
+**A runner-spawned child gets this pushed, not polled by hand.** While the
+child is still running, the runner itself calls `collect_session` under the
+child's own run key every `PM_ROWS_POLL_MS` (default 5s) and, for anything
+new, writes a message onto the child's stdin the same door a human's typed
+reply uses - an answered question once (the runner's own delivered-set is
+what stops the "every answered question, every call" shape above from
+saying the same ruling to the child twice), a message as `[message from
+<from>] <text>` (`bridge/lib/rowsAnswers.mjs`). After the child exits, ONE
+more `collect_session` call catches anything that arrived in the gap between
+the last live poll and the exit - a persistent session's late answer or
+message becomes a resume request through the same mechanism a reply typed
+into an already-finished session does; a one-shot session has nothing to
+resume into, so it is logged and dropped. See `bridge/SPAWN.md`, "Answers and
+comments coming back", for the full mechanism and its one known gap.
+
+### How `report` lands
+
+`report` takes three lists, and each lands differently:
+
+- **`did[]`** goes to the board's own Viewable Agent, which reads the board and
+  places it: an item about an idea that already exists becomes an edit or a
+  tag on it, and the rest land as ideas beside their relatives, all as
+  proposals you rule on. The result names each idea and where it went, so
+  write each line in words that name the ideas it touches.
+- **`decide[]`** lands each fork as a live question note with its own
+  durable `question_id`, and each item needs its own `why`, for the same
+  reason `ask_user` does.
+- **`flags[]`** lands each one as a note on the idea it is about.
+  Every flag must carry evidence the board cannot produce about itself: a
+  commit sha, a `file:line`, a test count, or a shipped on date. A flag
+  without one is refused.
+
+While the app is closed, the report still lands: `did[]` arrives as machine
+ideas inside one titled frame, drawn rather than dropped as plain text,
+pale until you touch them and with nothing to accept. Nothing waits in a
+queue and nothing is lost.
+
+`summary` is a deprecated single blob form, kept for a hand rolled MCP client
+that cannot produce `did`.
+
+## Running sessions from the board
+
+The spawn runner is the outside actor that turns "run a session on this" into
+a real process, because a browser cannot spawn one. The full contract, every
+row it reads and writes and every bound it respects, is in
+[SPAWN.md](./SPAWN.md).
+
+A run is a row in Postgres, reached through `supabase/functions/board-runner/`
+(`bridge/lib/runnerApi.mjs`), an ordinary session and a chat turn alike.
+
+The shape of a run:
+
+1. An idea (or a DM, for a chat turn) files a run row, unapproved.
+   It never runs until it is approved.
+2. Approval is the click in the app, or an agent acting under its own caps.
+3. A watcher polls `claim`, which atomically hands back the oldest approved,
+   unclaimed, pending row on one of this machine's registered projects -
+   claiming a row IS the run's start, with nothing left to wait on. It then
+   gives the session its own git worktree and starts the engine. A planning
+   draft is the exception: it researches read-only in the project checkout,
+   so no worktree is made for it. A chat turn is the other exception: it
+   runs in the DM's own long-lived chat worktree and mints no tree per
+   message.
+4. The run's card on the board shows it working, driven by the row's own
+   `status` and by `run_events` streaming its output live. At the end the
+   runner writes ONE `update` carrying the verdict, the cost and the
+   sidecar together; `result` is write-once.
+5. The session reports back through `report` before it finishes (a chat
+   turn's answer belongs in the room instead - it proposes nothing to the
+   board at all).
+
+The runner is off by default and has no default on path: nothing spawns
+without `PM_SPAWN_RUNNER=on`, which the login daemon carries in its own file
+so it is set once at install rather than once per session. The MCP server does
+not import the runner, so a session cannot start one however it is prompted.
+
+### The engines
+
+| engine | what it is |
+| --- | --- |
+| `claude` | Claude Code, and the default. Fenced by a named tool allowlist. |
+| `opencode` | opencode, run with `--auto`, which approves anything not explicitly denied. Select opencode during `viewable init` to register its project board connection. |
+| `codex` | Codex, through its own app-server protocol and your signed-in Codex account. Sandboxed to workspace writes, and it never approves an escalation. Like every engine, its receipts show turns and time, never a cost. See [CODEX.md](CODEX.md). |
+| `acp-claude` | The same Claude Code reached through the Agent Client Protocol adapter instead of the CLI. Same allowlist, answered at the permission door rather than passed as a flag. The cost on its receipt is an estimate, because ACP reports tokens and no dollars, and it is the least exercised of these. |
+
+An unknown engine name falls back to the default rather than failing, and the
+receipt says which one ran, so a typo runs something rather than nothing.
+
+"Fenced" is narrower than it sounds: the allowlist includes `Bash(node:*)` and
+`Bash(npx:*)`, so a Claude session can run arbitrary code too, and both
+engines can write to any path the process can reach. What bounds the damage is
+the git worktree and the wall clock. opencode also
+namespaces the board tools as `glytch_get_board`, `glytch_report`,
+`glytch_ask_user`, so
+telling an opencode session to call `report` names something that does not
+exist.
+
+### Planning drafts
+
+A run can ask for a plan instead of an implementation. The session researches
+read-only, writes nothing, and returns the plan as its final answer: findings
+in their own sections, then the work under an `## Implementation plan`
+heading with one `### Step N: ...` heading per item. The app reads that shape
+to lay the plan out for you to edit, approve or reject. An approved plan is
+handed to a second session as the exact instructions to follow.
+
+### Reference images
+
+An idea can carry images: screenshots, mockups, anything on it or on an idea
+wired into it. Every attached image is delivered or the run is refused before an
+agent starts and before anything is billed, and the refusal names which
+attachment and why. Nothing is silently dropped.
+
+- PNG, JPEG, GIF and WebP are supported. Another format, or damaged data,
+  refuses the run.
+- Claude Code streaming, Codex and ACP take the images as native image
+  content. An engine that has no image channel gets the files written beside
+  the run instead, with their paths listed in the prompt.
+- An ACP adapter that does not advertise image support refuses the turn
+  rather than sending the text without the pictures.
+- Sessions are told to inspect each reference and state what they see before
+  planning or editing, and to compare finished visual work against it.
+
+Delivery is checked all the way to the engine. Whether the model then reads
+the picture correctly is the model's own business, so treat a session's
+description of a reference as a claim to verify, not a guarantee.
+
+### What it costs
+
+Installing the package and exchanging board files make no model calls.
+Your coding agent can still bill for its own work, and the board agent may
+use a model to place reports.
+
+Turning on the runner is different: from that point the board can start coding
+agents on your machine, and they bill your subscription. The bounds are real
+and they stay on. Nothing spawns without `PM_SPAWN_RUNNER=on`, nothing starts
+without an approval, each implementing session gets its own git worktree (a
+read-only planning draft stays in the project checkout), a failed session is
+not retried, and editing an idea does not re-run it. Rerun is its own press.
+
+One wall bounds a single run: the wall clock, 90 minutes by default and 2
+hours at most. Past it the process is killed. There is no spend or token
+limit on a run; the free AI that comes with a new account is the only limit,
+and it applies to Viewable's free AI, not to your own subscription.
+
+What you do not get is a confirmation box per run, deliberately: a dialog you
+click through fifty times is not a safety feature. The cost of a careless run
+is real money, and the run happens the moment you ask for it.
+
+## Sessions in a git worktree
+
+Dispatched sessions run in their own git worktree by default (read-only
+planning drafts being the exception), and a session's board entry is the
+hosted URL - `{"type":"http","url":"https://app.viewable.one/mcp"}`, or
+`{"type":"remote", ...}` on opencode. There is no local process and no folder
+to point it at, so a session reaches the board over the network the same way
+whichever worktree it is standing in.
+
+`PM_BOARD_ROOT` is how you point the runner, or a `bridge/lib` script, at a
+project folder that is not its working directory's: set it in the runner's own
+environment (the login daemon's file, or `PM_SPAWN_RUNNER=on
+PM_BOARD_ROOT=... viewable runner watch` by hand).
+
+A session reports by calling the `report` tool. There is no fallback behind
+it: a session that never calls it has told the board nothing.
+
+## Commands
+
+| command | what it does |
+| --- | --- |
+| `viewable init` | Choose coding agents and connect this project. Safe to run twice. |
+| `viewable init --agents claude,codex` | Configure the named agents without a prompt. |
+| `viewable init --yes` | Use saved choices or detected agents. |
+| `viewable login` | Sign in to the hosted board over OAuth. See ["Reading the board with no app open"](#reading-the-board-with-no-app-open). |
+| `viewable logout` | Forget the signed-in credential (`~/.glytch/auth.json`). |
+| `viewable doctor` | Grouped Project, Runner, Coding agents and System checks. Labels are `OK`, `WARN` or `FAIL`; exit 0 when no check fails. |
+| `viewable forget` | Stop watching this folder. Nothing inside it is deleted: `.mcp.json`, `.glytch/` and every session it holds stay. |
+| `viewable stop` | Stop the login daemon. The file it runs from stays on disk, so `viewable init` brings it back without a reinstall. |
+| `viewable uninstall` | Every registered project, the login daemon, this machine's board sign-in, and `~/.viewable` - one command. Confirms once; `--project`, `--keep-login`, `--dry-run` and `--yes` narrow or skip pieces of it. |
+| `viewable runner ...` | The spawn runner. `watch` with no `PM_BOARD_ROOT` watches every registered folder; with it set, it watches that one. |
+| `glytch mcp` | Retired. Prints one line pointing at `viewable init` and `viewable login`, and exits 1. There is no local board MCP server to start. |
+| `viewable --version` | The installed version. |
+
+`pm-spawn-runner` is installed as an alias of `viewable runner`, so anything
+already wired to that name keeps working. The second bin alias every version
+up to 0.6.0 installed is gone from 0.7.0, with the local MCP server it
+started.
+
+The runner's own subcommands act on `PM_BOARD_ROOT` or the folder you are
+standing in: `watch` polls and runs what is approved, `once` does one pass
+instead of a loop, and `merge`/`delete-worktree`, each taking a worktree
+path, finish with a session's branch by hand.
+
+`request`, `approve`, `status`, `show` and `release` are retired. They filed,
+approved, listed, inspected and released a run as a FILE; a run is a row now,
+and this CLI holds no Supabase JWT to reach the app's own
+`run_request`/`run_approve` RPCs directly. Each prints a one-line pointer at
+`supabase/functions/board-runner/` and exits 1. File and approve a run from
+the board instead.
+
+Unchanged one-shot worktrees are removed after a run. Worktrees containing
+commits or uncommitted changes are kept for review. If Git cannot verify the
+changes or comparison base, cleanup keeps the worktree and reports why.
+Persistent prompt sessions and agent chat worktrees stay available for resume;
+a question-only turn does not end that conversation or delete its workspace.
+
+Run `viewable update` (`viewable.cmd update` in PowerShell) to install the latest
+published package and restart the computer's connection. It verifies the CLI
+from a new normal terminal before touching the service (with Volta, through
+`volta which viewable`), switches an old npx
+service to the persistent installation, and restarts even when the script path
+and version stay the same. It waits for a successful hosted heartbeat from a
+new process reporting that version before claiming success. Folders, sign-in
+and agent configuration are kept; it does not run init or an agent session.
+
+What changed in each version is on the
+[release notes](https://glytch.ai/release-notes) page. To check an update
+worked, open Settings in the app: each connected computer shows the version it
+runs.
+
+Older versions (including 0.11.0) have no update command. If `viewable` is missing
+or update is unrecognized, first install with `npm i -g viewable@latest` (Windows:
+`npm.cmd i -g viewable-one@latest`), make the bin directory persistent as above, and
+verify `viewable -v` in a new terminal. Then use `viewable update` once a published
+version supports it. This repository change does not publish that version.
+
+The daily version checker stays notice-only. Installation, PATH, restart or
+connection failures report partial completion and a next step; retry update
+after fixing them. Without a working user service (including older WSL without
+systemd), update does not report a verified connection. No command here
+publishes npm or redeploys the app or Supabase functions.
+
+`init` also verifies the persistent CLI, compares the loaded process's version
+proof and replaces an older or unverified loaded process even at the same path.
+A process that has attested the installed version is left running, including
+while busy or waiting for its next heartbeat. It waits for its folder's fresh
+successful heartbeat before printing that it is watching. Setup copied from
+the app carries a non-secret attempt id; only a matching verified CLI version
+and that attempt's heartbeat completes the setup screen. Local `cli.json` and
+`health.json` under `~/.viewable` hold version/process proof without credentials.
+
+## Where things live
+
+- `~/.glytch/folders.json`, the registry of folders the daemon watches, and
+  `~/.glytch/logs/runner.log`, rotated at 5 MB with three kept. `GLYTCH_HOME`
+  moves both, and the daemon file with them.
+- `.glytch/agents.json`, the project's saved coding-agent selection.
+- The selected agents' project configs, from the setup table above.
+- The login daemon's own file for your platform, from the table above.
+  `GLYTCH_NO_DAEMON_INSTALL=1` writes it and registers nothing.
+- `.glytch/images/<id>/` in the linked folder, where an image on its way to a
+  run is staged, and the repo-map cache beside it. Both are this machine's own
+  scratch. Nothing in this package writes a board file: every board write and
+  every run is a row, reached over the hosted endpoint.
+
+A second project needs no restart: `viewable init` in another folder adds it to
+the registry, and the daemon is watching that file, so it starts watching the
+new folder within seconds without touching sessions already running elsewhere.
+`viewable forget` is the other half. Nothing needs `launchctl`, `schtasks` or
+`systemctl` by hand.
+
+## Troubleshooting
+
+`viewable doctor` is the first thing to run. It groups checks under Project,
+Runner, Coding agents and System, and exits 0 only when no check fails. The
+`OK`, `WARN` and `FAIL` labels remain visible without color; interactive
+terminals color them, while piped output is plain. Set `NO_COLOR` to disable
+styling (`NO_COLOR` wins over `FORCE_COLOR`). Run it inside the linked project
+folder, for example `cd ~/Projects/my-project`; from your home folder doctor
+prints a warning because the registry, mirror and heartbeat may belong to a
+different project.
+
+The daemon checks are separate: `daemon loaded` means the operating system is
+holding the login service, and `daemon beating` means the board has heard from
+it about this folder recently - which is also how you know the folder is
+linked. Immediately after `viewable init`, a loaded daemon may need a few seconds
+before its first beat; rerun doctor after that grace period. The rows cover the
+platform, folder and agent configuration, daemon PATH, daemon state and
+version, the heartbeat, the board sign-in and which account it reaches, coding
+agents, Claude Code login, git and the npm version.
+
+Common failures, and what the row says:
+
+| row | what it means, and what to do |
+| --- | --- |
+| `daemon beating  never` | The daemon is loaded but has not checked this folder yet, or this folder is not registered. Wait a few seconds and rerun doctor; if it persists, run `viewable init` from this project folder. |
+| `daemon beating  stopped` | This folder has not been reported recently; a stale beat alone does not prove the daemon is stopped. If it persists, restart with `viewable stop` then `viewable init --yes`, and inspect the runner log. |
+| `board sign-in  signed in as <someone else>` | The credential works, but it reaches a different account from the board you are watching. `viewable logout` then `viewable login` as the right one. |
+| `daemon loaded  not loaded` | The OS does not have `ai.glytch.runner`. Run `viewable init` from this project folder. |
+| `daemon loaded  no systemd here` | An older WSL with no `systemctl --user`. Run `PM_SPAWN_RUNNER=on viewable runner watch` instead. |
+| `coding agents  none` | "no coding agent on PATH - install Claude Code, opencode or Codex". |
+| `Claude Code login  logged out` | "run `claude` once and log in, or sessions fail at spawn". |
+| `git  missing` (a warning) | "no git - sessions run unisolated in the linked folder, with no worktree of their own". On Windows the row adds that Claude Code's Bash tool needs Git for Windows. |
+| `.mcp.json  unreadable` | The file exists and is not JSON glytch can extend. It is your work, so nothing was written: add the `viewable` server by hand. |
+| `version  unknown` | npm did not answer. Being offline is not a broken install. |
+
+One failure doctor cannot see: an opencode session whose board tools do
+nothing. Run `viewable init` in the folder and include opencode in the
+selection. opencode namespaces the tools as `glytch_get_board`,
+`glytch_report`, `glytch_ask_user` and so on, so a session told to call
+`report` or `get_board` by their plain names finds nothing there.
+
+## For maintainers
+
+`npm ci` then `npm test` inside `bridge/` runs the suite on Node's built in
+runner: the CLI's commands, the doctor rows, the wall clock, and the spawn
+runner end to end. It also covers the hosted board tools in
+`supabase/functions/board-mcp/tools.mjs`, which live in the app's repository
+but are exercised from here. The spawn runner's tests never touch a real
+account, because `PM_CLAUDE_BIN` points at a fake binary that exits, hangs or
+floods on demand. CI runs everything on `ubuntu-latest` and `windows-latest`,
+and both block.
+
+Versions follow semver over the commands, their flags, and what the runner
+promises a session, not the internals: renaming a command, dropping a flag or
+changing that promise is breaking, and rewriting how one of them does its job
+is not. The board tools are served from the hosted endpoint and ship on their
+own schedule, not with this package. [CHANGELOG.md](./CHANGELOG.md) is the
+record, written by hand from the commit bodies.
+
+One workflow publishes, **release glytch**, and it has two ways in.
+
+The usual one is the Actions tab, Run workflow, and a `patch`, `minor` or
+`major` bump. It installs dependencies, runs tests, updates
+`bridge/package.json` and `bridge/package-lock.json`, rotates the changelog's
+`## [Unreleased]` section into a dated version, commits, tags
+`glytch-v<version>`, pushes and publishes, so pull afterwards. The bump is
+refused when nothing sits under `## [Unreleased]`: a version with no changelog
+entry is a release nobody can read. `scripts/release-glytch.mjs` with a bump
+prepares that same commit locally.
+
+The other is a tag, for a version already written into `package.json` and
+already dated in the changelog - there is nothing left to bump, so pushing the
+tag is the whole release:
+
+```bash
+git tag -a glytch-v0.8.0 -m "glytch v0.8.0"
+git push origin glytch-v0.8.0
+```
+
+The prefix changed on 2026-09-14 when the release path took the package's
+name. Tags cut before then carry the old prefix; the workflow no longer
+answers to them, and they stay in the history as they were cut.
+
+It checks the tag against `package.json` before it publishes, because a tag
+pushed by hand can disagree with the file and a publish is the wrong place to
+find that out.
+
+Neither path needs an npm token. Publishing is over OIDC trusted publishing,
+switched on once by hand on npmjs.com under the package's Publishing access.
+
+Nothing publishes on a bridge commit. This package is what a stranger
+installs, the runner spends that stranger's subscription, and a publish cannot
+be taken back.
+
+### Developing against a local app
+
+`GLYTCH_APP_URL=http://localhost:<port> viewable login` works once the app's dev server (`npm run dev`, or `npx vite --port <port>`
+from the repo root) is up - `vite.config.ts` generates a dev-server proxy
+from `routes.json`'s own rewrites (`vite/routeProxy.ts`), so the discovery
+document, `/oauth/*` and `/mcp` reach the real, deployed Supabase functions
+instead of falling through to the SPA's `index.html`. The discovery
+document itself still names the production issuer
+(`https://app.viewable.one`) no matter what port the app is running on -
+`board-oauth`'s issuer is a deploy-time config value, not derived from the
+request - so this doesn't stand up a local OAuth server; it's for testing
+the local app's UI against the real, deployed board while signed in.
+
+### Automatic preview tunnel setup
+
+Installing the package does not download Cloudflare's `cloudflared`; there is no
+install script. The runner downloads it the first time a shared preview starts,
+so that first preview needs the network. If the download fails, the preview does
+not start and the next one tries again; nothing else in the runner needs it.
+No Homebrew, administrator access, or system service is needed.
+
+Automatic downloads support macOS x64/ARM64, Linux x64/ARM64, and Windows x64.
+Windows ARM64 has no native binary in this upstream release; unsupported systems
+can supply a compatible executable through `PM_CLOUDFLARED_BIN`. WSL uses Linux.
+
+Official release `2026.8.3` assets and SHA-256 digests are pinned in
+`lib/cloudflared-release.json`, from the Cloudflare GitHub release API. Downloads
+are bounded and verified before use, then cached under the user's home directory
+at `.glytch/bin/cloudflared/<version>/<platform>-<arch>/`. Cached content is
+verified and a changed executable is repaired from the verified asset. The
+`PM_CLOUDFLARED_BIN` override bypasses managed setup. Updating the pinned release
+requires a package update. Downloading it does not open a tunnel; startup still
+requires the board-member authorization configuration.
+
+Shared previews also require the deployed `preview-grant` authorization
+function and runner configuration: set its public verifier JWK in
+`PREVIEW_VERIFY_JWK` and the
+exact app origins in `PM_PREVIEW_APP_ORIGINS` (comma-separated HTTPS origins;
+localhost loopback is allowed for local development). The tunnel binary alone
+does not provide preview access, and missing configuration fails closed.
+
+### Reading setup and health checks
+
+`viewable init` and `viewable doctor` group output into Project, Runner, Coding agents,
+and System sections. OK, WARN and FAIL labels remain visible without color;
+interactive terminals add green, yellow and red. Piped output is plain by default.
+`NO_COLOR` disables styling, including when `FORCE_COLOR` is set. Failure summaries
+count the checks that need attention and include a separate Next steps section.
+
+Run project commands from the folder linked to your board. A prominent warning
+appears when the current directory is your home folder. A loaded daemon with no
+heartbeat may still be starting; doctor distinguishes that from an unloaded daemon.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+## Moving from Glytch
+
+If you already installed `glytch` globally, run
+`npm install -g viewable-one@latest --force`, then use `viewable` (or the
+compatible `glytch` command). The flag lets npm replace the old command aliases.
+For a clean install, use `npm install -g viewable-one@latest`.
+The last `glytch` package forwards to `viewable-one`. Saved settings, tokens,
+projects and runs stay in `~/.glytch` and each project’s `.glytch` folder;
+existing service and board connection names stay valid. No setup is lost.
+Every `VIEWABLE_*` environment variable takes precedence over its matching
+`GLYTCH_*` variable, which remains supported. New connections use
+`https://app.viewable.one/mcp`; existing saved addresses keep working.