create-pmos 0.5.0 → 0.6.0

package/payload/skills-native/pmos-router/SKILL.md

@@ -23,7 +23,7 @@ router is the bug (fix it via the weekly harness scan).
 > **Format note:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)).
 > Sources of truth: the AGENTS.md lane list, `.github/scripts/initiative-gate.sh`, D56/D58/D60.
 
-## Step 0 — two checks before any route
+## Step 0 — three checks before any route
 
 1. **Sharpness (the fog/ticket test):** *can the PM state the question or idea precisely now — not
    answer it, state it?* If not, it is **fog**: not ready for intake. Name what would sharpen it
@@ -31,15 +31,37 @@ router is the bug (fix it via the weekly harness scan).
 2. **Prior rejection:** check [planning/out-of-scope/](/planning/out-of-scope/README.md) for the
    concept. If a file exists, **read it first** and surface it to the PM — the concept returns only
    if the PM overrides the recorded reasoning, and the file is updated either way.
+3. **The specimen test — ASK it, do not wait to be told** (D60 as amended 2026-07-24):
+
+   > **Can the PM judge this from a description, or do they need an instance of it in front of them?**
+
+   Put it to the PM in their own terms for this piece of work. If no description settles it, the
+   route is **prototype**, *whether or not the work has a user interface* — the lane is no longer
+   UI-gated. This check is asked here because the recorded failure is discoverability: a PM who does
+   not know the lane exists cannot ask for it, and a step left to memory decays to never.
+
+   **It must discriminate in both directions.** Most feature work — an MCP tool, a migration, a CI
+   gate — *is* judgeable from a description and routes straight to its PRD untaxed. Over-firing twice
+   running is a D41 tripwire on the test's wording.
+
+4. **Existing-surface check — does the PM understand what is already there?** Ask:
+
+   > **Would specifying this honestly require reading code that already exists?**
+
+   Yes → an [explain-surface](/build-skills/explain-surface.skill) pass runs **first**, before the
+   spike brief / prototype brief / PRD is authored, in a fresh context. Greenfield → skip it. This is
+   standard, not optional: the PRD skill's own rule ("look it up rather than asking") means the
+   *agent* acquires the understanding and the PM does not, and a spec built on facts the PM never saw
+   is a watermelon at the root.
 
 ## The routes
 
 | The PM says… | Route | Lane / artifacts / next skill | Gates to expect |
 |---|---|---|---|
-| "I have an idea" for something **user-facing, not yet seen** | **Prototype first — before any PRD** | `type: prototype`; quick brief at `prd_path` (**no rubric BY DESIGN** — grilled, never scored); [prototype skill](/skills/core/prototype.skill). **Design-system precondition is BLOCKING** — absent → the agent authors one from the same brief, PM approves, first. | Initiative Gate (brief exists); web-ci quarantine; PM disposition (promote/iterate/kill) |
+| "I have an idea" the PM **can't judge from a description** — they need an **instance** in front of them (a UI not yet seen; equally *does this skill's output teach?*, *does this API feel right to call?*) | **Prototype first — before any PRD** | `type: prototype`; quick brief at `prd_path` declaring **the judgement exercised + the specimen format** (**no rubric BY DESIGN** — grilled, never scored); [prototype skill](/skills/core/prototype.skill). Format fits the work: lookable UI, a worked sample output, call/response transcripts, a schema sketch. **The class's conventions are a BLOCKING precondition** (design system for UI; SKILL-FORMAT, D19 ACI, migration/RLS conventions elsewhere) — absent → the agent authors them from the same brief, PM approves, first. | Initiative Gate (brief exists); web-ci quarantine; PM disposition (promote/iterate/kill) |
 | A **new bet** — new product/capability/direction whose *whether* is unargued | **Offer the strategic brief** (recommended, skippable — D61) | [strategic-brief skill](/skills/core/strategic-brief.skill) → `planning/briefs/<id>-brief.md`; go → feature route below; no-go → file in out-of-scope/ | none (the brief is never a gate) |
 | A **validated direction or known feature** (incl. a promoted prototype) | **Feature lane** | `type: feature`; PRD + eval rubric ([prd](/skills/core/prd.skill) + [eval-rubric](/skills/core/eval-rubric.skill) skills), rubric authored alongside (D13); contract before build (D16). A promoted prototype's PRD is **derived from the validated option**. New surface → leg B: [design-brief](/skills/core/design-brief.skill) as the build's reference, held to the [design-reference rubric](/planning/evals/design-reference-eval-rubric.md) | Initiative Gate (PRD+rubric); full three-tier gate |
-| "**Is this feasible / should we / how would we…?**" — answerable by investigation | **Discovery lane** | `type: discovery`; spike brief at `prd_path` ([discovery skill](/skills/core/discovery.skill)); question + timebox + disposition. Deliverable is a **learning** — if the PM needs to *see* it, that is the prototype route instead | Initiative Gate (spike brief) |
+| "**Is this feasible / should we / how would we…?**" — a **question** with an unknown answer, findable by investigation | **Discovery lane** | `type: discovery`; spike brief at `prd_path` ([discovery skill](/skills/core/discovery.skill)); question + timebox + disposition. Deliverable is a **learning**, and it closes on the **timebox** ("inconclusive" is a recordable outcome). Contrast the row above: that one holds a **candidate** whose rightness no description settles, delivers a **validated direction**, and closes on a **disposition against a specimen**. Widening this lane to cover that was considered and **rejected** in D60 | Initiative Gate (spike brief) |
 | "**Production is broken**" | **Incident lane** | `type: incident`; fix now, record post-hoc within 48h at `prd_path` (the one sanctioned inversion; [incident template](/okf/core/templates/incident-record-template.md)) | Initiative Gate (record, post-hoc) |
 | A **text deliverable** (landing page, microcopy, release notes, campaign) | **Content lane** | `type: content`; content brief at `prd_path`, rubric recommended not required (D58); [copywriting skill](/skills/domains/copywriting.skill). Copy for a prototype rides the prototype instead (D60) | Initiative Gate (content brief) |
 | **Upkeep** — refactor/ops/security with no honest KR | **Chore lane, health-anchored** | `type: chore`; one-paragraph intent in `status`; anchor `health:<id>` from [health-budgets](/planning/okrs/health-budgets.md) (D59) — never a faked KR | Initiative Gate (intent + anchor) |

package/payload/skills-native/prd/SKILL.md

@@ -32,6 +32,13 @@ agreed.
 
 ## Procedure
 
+0a. **Existing surface? Understand it first — before grilling.** If specifying this honestly
+   requires reading code that already exists, an [explain-surface](/build-skills/explain-surface.skill)
+   pass runs on that region **first**, in a fresh context and **not by you**. Its *Open questions*
+   section is a declared input to the grilling below: those are the things that could not be
+   determined from the code, and they must be resolved with the PM or carried explicitly into the
+   PRD's risks — never silently answered by assumption. Greenfield → skip. This exists because step 0b's
+   boundary rule, on its own, gives the **agent** the understanding and the PM none.
 0. **Grill before you write.** Before any authoring, interrogate the PM's intent as a dialogue —
    **one question at a time, a recommended answer offered with each**, no authoring until shared
    understanding is confirmed. Stop when the intent is **unambiguous**, not at a count — there is
@@ -74,6 +81,7 @@ agreed.
 
 A complete PRD instance contains:
 
+- **Frontmatter** — the file opens with OKF YAML frontmatter: `type: PRD`, `title`, `timestamp` (the repo-wide convention, D63; [frontmatter-format](/okf/core/concepts/frontmatter-format.md)).
 - **Identity** — `initiative_id`, `product_slug`, `pm_slug`, parent `KR`.
 - **Problem** — who has it, why now, what it costs to leave unsolved.
 - **Goal & non-goals** — the change sought; explicit out-of-scope.

package/payload/skills-native/prototype/SKILL.md

@@ -1,68 +1,126 @@
 ---
 name: prototype
-description: Run a pre-PRD visual validation through the prototype lane (D60) — the PM gives a QUICK brief, a design agent produces divergent low-fidelity lookable options with real draft copy, a designer-grade grilling sharpens them (dialogue, never a score), and the PM disposes promote/iterate/kill. Use when a user-facing idea needs to be SEEN before a PRD can honestly be written; requires the product's design system (blocking — author it first if absent).
+description: Run a pre-PRD validation through the prototype lane (D60) — the PM gives a QUICK brief, an agent produces 2–3 divergent specimens in whatever format fits the work (lookable UI options, a worked sample output, call/response transcripts, a schema sketch with example rows), a grilling sharpens them (dialogue, never a score), and the PM disposes promote/iterate/kill. Use when an idea's rightness cannot be settled by a description and the PM needs an INSTANCE in front of them — whether or not the work has a user interface; requires the artifact class's conventions (blocking — author them first if absent).
 license: MIT
 metadata:
-  pmos-version: 1.0.0
+  pmos-version: 1.1.0
   pmos-owner: wawan
   pmos-risk: low
   pmos-category: design
   pmos-scope: read:okf, write:prototype, write:planning
 ---
 
-# prototype — Run a leg-A visual validation through the prototype lane
+# prototype — Run a leg-A validation through the prototype lane
 
 The [D60](/okf/products/pmos/adr/d60-prototype-loop.md) lane skill. The division of labour is the
-point: **the PM briefs; the agent designs.** The PM should never have to author a design system or
-build a prototype to validate an idea.
+point: **the PM briefs; the agent builds the specimen.** The PM should never have to author a design
+system, a convention set, or a prototype to validate an idea.
 
 > **Format note:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)).
 > Level 1 above is the trigger; this body is Level 2.
+> **Scope note (2026-07-24 amendment):** this lane is **no longer gated on the work being a user
+> interface**. D60's mechanism — *make it examinable, then grill it, before committing to a spec* —
+> is general; it was only ever *expressed* visually. The visual path below is unchanged and stays
+> first-class; it is now one shape among several.
 
 ## When to use vs. not
 
-- **Use** when a user-facing idea — new product, new feature, or an improvement to an existing
-  surface — needs visual confirmation **before** a PRD exists. The measured cost of skipping this is
-  the console-redesign series: four post-build rejections that a lookable artifact would have caught
-  pre-spec.
+**The entry rule is the specimen test:**
+
+> **Can the PM judge this from a description, or do they need an instance of it in front of them?**
+
+- **Use** when no description settles it. The measured cost of skipping this is the
+  console-redesign series: four post-build rejections that a lookable artifact would have caught
+  pre-spec — a *visual* judgement that could only be made once the thing existed. The class is wider
+  than the instance: *does this skill's output actually teach?*, *does this API feel right to call?*,
+  *does this rubric actually discriminate?*, *does this error message actually help?* are the same
+  judgement in a different medium.
+- **Do not use** when a description does settle it — which is most feature work. An MCP tool, a
+  migration, a CI gate: the PM can read what it will do and decide. Those go straight to their PRD.
+  **A lane that fires on everything has failed as surely as one that fires on nothing**; over-firing
+  twice running is a D41 tripwire on the test's wording.
 - **Do not use** for leg B (the post-PRD, high-fidelity design reference — that is the
-  [design loop](/okf/core/concepts/design-loop.md): design-brief → design → reconcile, now open to
-  new surfaces per D60's D48 amendment).
-- **Do not use** for non-visual questions ("is this feasible?") — that is the
-  [discovery lane](/skills/core/discovery.skill), whose deliverable is a learning, not a look.
+  [design loop](/okf/core/concepts/design-loop.md): design-brief → design → reconcile, open to new
+  surfaces per D60's D48 amendment).
+- **Do not use** when you hold a *question* rather than a *candidate* — that is the
+  [discovery lane](/skills/core/discovery.skill):
+
+  | | You hold | Deliverable | Closes on |
+  |---|---|---|---|
+  | **discovery** | a **question** with an unknown answer, findable by investigation | a **learning** | the timebox — "inconclusive" is a recordable outcome |
+  | **prototype** | a **candidate** whose rightness no description settles | a **validated direction** | a disposition against a specimen |
+
+  Widening `discovery` to cover this was considered and **rejected** in D60 and stays rejected:
+  "discovery" is not the word a PM reaches for when they want to *see* something, and
+  discoverability was the whole failure.
 
 ## Procedure
 
 1. **Open the lane.** `create_initiative({id, title, parent_kr, type:'prototype', stage:'intake'})` —
    anchored like all work (D21/D59). Branch `initiative/<id>`.
+1b. **Improving something that already exists? Understand it first.** If the specimen will replace
+   or alter an existing surface, run an [explain-surface](/build-skills/explain-surface.skill) pass on
+   it — fresh context, **before** the brief. Divergent options against a surface nobody has
+   characterised diverge from a guess, and the PM cannot grill them honestly. Brand-new → skip.
 2. **Take the quick brief.** The PM fills the
-   [prototype-brief template](/okf/core/templates/prototype-brief-template.md) — two required
-   sections, minutes not hours — into `prototype/<id>/brief.md`; set it as `prd_path`.
-   **`rubric_path` stays null by design** (grilled, never scored). If the PM starts writing
-   requirements, stop them: that detail belongs in the PRD that *follows*.
-3. **Design-system check — BLOCKING (D60).** Does this product have a design system (tokens,
-   type scale, components — PMOS's own app: D38)? **If not, author one first**: from the same brief,
-   propose a minimal system (palette + type scale + spacing unit + core component shapes), get the
-   PM's approval, record it in the product's namespace. Only then prototype. Never silently invent
-   per-prototype styling — that is how inconsistent products happen.
-4. **Retrieve the craft.** `get_okf_concepts({concept_ids:['core/concepts/design-craft']})` — the
-   perception/cognition evidence, craft moves, accessibility floors, and the recorded anti-patterns.
-   Reason from principles to THIS brief; two briefs must not produce the same design.
-5. **Produce divergent options** into `prototype/<id>/` — low-fidelity, self-contained, lookable
-   (static HTML is usually right; whatever renders fastest). **2–3 genuinely different directions**,
-   not one safe one with variants. **Real draft copy** (D60: copy rides the prototype —
-   [copywriting.skill](/skills/domains/copywriting.skill) craft applies in-loop; claim-sourcing waits
-   for the content lane at production). Respect the accessibility floors even at low fidelity.
-6. **Grill — dialogue, never a score.** A designer-grade critic (fresh context, default-to-refute
-   stance, [design-craft](/okf/core/concepts/design-craft.md) loaded) interrogates each option: *why
-   this structure? what job does the focal element serve? what would the best product designer say is
-   wrong? what was NOT tried?* One question at a time, a recommended answer with each, no action until
-   shared understanding is confirmed. Sharpen the options from it. **Produces no score, no verdict,
-   no threshold, no `evals` row** — re-introducing scoring here under any name is a D60 violation.
+   [prototype-brief template](/okf/core/templates/prototype-brief-template.md) — minutes not hours —
+   into `prototype/<id>/brief.md`; set it as `prd_path`. It declares **the judgement being
+   exercised** and **the specimen format chosen** (step 4), because those are what the grilling and
+   the disposition hang on. **`rubric_path` stays null by design** (grilled, never scored). If the PM
+   starts writing requirements, stop them: that detail belongs in the PRD that *follows*.
+3. **Precondition check — BLOCKING (D60(c), generalised).** A specimen built against no shared
+   vocabulary produces something nobody can consistently build from. Before producing anything, confirm
+   the artifact class has **conventions** and **craft knowledge** to reason from:
+
+   | Class | Its conventions live in |
+   |---|---|
+   | A user interface | the product's **design system** — tokens, type scale, components (PMOS's own app: [D38](/DECISIONS.md); tenants checked at onboarding) |
+   | A skill | [SKILL-FORMAT](/skills/core/SKILL-FORMAT.md) — three-level progressive disclosure |
+   | A tool or API | [D19](/okf/products/pmos/adr/d19-aci-design.md)'s ACI principle |
+   | A knowledge doc | the OKF spec + [frontmatter-format](/okf/core/concepts/frontmatter-format.md) |
+   | A schema | the repo's migration + RLS conventions |
+
+   In PMOS most already exist, so this usually passes on inspection. **Where a class has neither,
+   authoring them is the first initiative** — propose a minimal set, get the PM's approval, record it
+   in the product's namespace, and only then prototype. Never silently invent per-prototype
+   conventions; that is how inconsistent products happen.
+4. **Retrieve the craft, and choose the format.** `get_okf_concepts` the class's craft — for a user
+   interface, `core/concepts/design-craft` (perception/cognition evidence, craft moves, accessibility
+   floors, recorded anti-patterns); for other classes, the conventions named in step 3. **Reason from
+   principles to THIS brief; two briefs must not produce the same specimen.** D60(e) is explicit that
+   without a craft layer to reason from, an agent told to "apply practice" produces generic output —
+   if you cannot name what you are reasoning from, you are in the blocking case above.
+
+   Then choose the format by the principle — **the cheapest specimen that lets the PM exercise the
+   judgement in question**. A starting vocabulary, deliberately **not a closed enum**; an unlisted
+   shape takes whatever actually fits, named in the brief:
+
+   | Work shape | A specimen might be |
+   |---|---|
+   | A user interface | a low-fidelity lookable artifact (static HTML is usually right) |
+   | A skill / agent capability | a worked sample output on real input |
+   | A tool or API shape | sample call + response transcripts |
+   | A data model | a schema sketch with example rows |
+   | An eval rubric | the rubric scored against 2–3 real past artifacts |
+   | Error text, CLI, protocol | the actual strings, or a session transcript |
+
+5. **Produce divergent specimens** into `prototype/<id>/` — low-fidelity, self-contained, examinable
+   (whatever renders or reads fastest). **2–3 genuinely different directions, not one safe one with
+   variants** — divergence is the point in any medium. **Real draft content, never placeholder**
+   (D60: copy rides the prototype — [copywriting.skill](/skills/domains/copywriting.skill) craft
+   applies in-loop; claim-sourcing waits for the content lane at production). The non-visual analogue
+   is the same rule: real inputs and real outputs, because fake ones hide exactly the friction the
+   specimen exists to surface. Respect the accessibility floors even at low fidelity.
+6. **Grill — dialogue, never a score.** A craft-grade critic (fresh context, default-to-refute
+   stance, the class's craft loaded) interrogates each specimen: *why this structure? what job does
+   the focal element serve? what would the best practitioner in this class say is wrong? what was NOT
+   tried?* One question at a time, a recommended answer with each, no action until shared
+   understanding is confirmed. Sharpen the specimens from it. **Produces no score, no verdict, no
+   threshold, no `evals` row** — re-introducing scoring here under any name is a D60 violation.
 7. **PM disposition** (the only gate on leg A, and it is the PM's):
    - **promote** → open a **new feature-lane initiative**; its PRD and rubric are **derived from the
-     validated option** (what was seen and chosen becomes the spec's substance). Leg B then runs
-     inside that initiative's Build.
+     validated specimen** (what was seen and chosen becomes the spec's substance). Leg B, where the
+     work has a surface, then runs inside that initiative's Build.
    - **iterate** → back to step 5 with the PM's reaction folded in.
    - **kill** → record one honest line on the initiative, **file the concept into
      [planning/out-of-scope/](/planning/out-of-scope/README.md)** (decision, reasoning, what would
@@ -73,10 +131,17 @@ build a prototype to validate an idea.
 ## Hard rules
 
 - Artifacts live in **`prototype/<id>/` only** — never `web/`, never a tenant app. The `web-ci`
-  quarantine assertion enforces this; do not fight it.
+  quarantine assertion enforces this for the visual case; it is the *instance* of D01's general rule,
+  which binds every medium. Do not fight it, and do not read "the assertion only covers `web/`" as
+  permission to let a non-visual specimen leak into product code.
 - **A prototype never ships.** Promote produces a *spec*, not a deploy. Quality bars are suspended in
   `prototype/` precisely because nothing there can reach production (D01).
-- **No score on leg A, no skipped grilling on leg A.** Both PM rules bind; neither may be satisfied
-  by dropping the other.
+- **No score on leg A, no skipped grilling on leg A.** Both PM rules bind; **neither may be satisfied
+  by dropping the other**. This holds for non-visual specimens too, where the temptation is sharper:
+  a schema or an API *looks* like it has objective criteria, and that is exactly the argument that
+  produces safe, scoreable output — the criteria you can score are the ones you already know to look
+  for. A technically correct schema can still be the wrong one to live with, and *fit* is what leg A
+  is for. (The console log's twin: the evaluator graded *correct* design; the PM judged *desirable*
+  design.)
 - If the PM stops looking and promotes on autopilot, say so — an unreviewed disposition is the
   [meta-watermelon](/okf/core/concepts/watermelon-flag.md) in a new place.

package/payload/templates/agent-run-eval-rubric.md

@@ -1,3 +1,13 @@
+---
+type: Rubric
+title: "Eval Rubric: Agent-run capability baseline (kit seed — copy per initiative)"
+timestamp: 2026-07-19
+eval_type: capability
+initiative_id: (set per initiative)
+pass_threshold: 0.80
+canonical_path: pmos/planning/evals/agent-run-eval-rubric.md
+---
+
 # Eval Rubric: Agent-run capability baseline (kit seed — copy per initiative)
 
 > Kit-seeded generic rubric (D54). Two purposes: (1) it is the TEMPLATE to copy to
@@ -6,13 +16,6 @@
 > meaningful from day one. It scores a generic agent run outcome-only (D14) with weighted partial
 > credit (D15).
 
-## Frontmatter
-- type: Rubric
-- eval_type: capability
-- initiative_id: (set per initiative)
-- pass_threshold: 0.80
-- canonical_path: pmos/planning/evals/agent-run-eval-rubric.md
-
 ## Gate assignment
 - **Quality Gate (deterministic):** repo CI green; `pmos-gate` (anchored + rubrics) green.
 - **Review Gate (adversarial):** the weighted dimensions below — evaluator skill, default-to-refute,

package/payload/templates/ticket-template.md

@@ -1,4 +1,6 @@
 ---
+type: Template
+timestamp: 2026-07-23
 id: "001"
 title: short imperative title — one deliverable
 status: todo            # todo | doing | done

package/workspace/README.md

@@ -0,0 +1,112 @@
+---
+type: Reference
+title: "PMOS Terminal Workspace"
+timestamp: 2026-07-25
+---
+
+# PMOS Terminal Workspace
+
+The local companion that runs the PM's agent sessions as **real terminals**, with the PMOS
+workflow (library, gates, needs-you) around them. Built to D62 (as ratified + twice amended):
+a **persistent, localhost-only session server** owning real PTYs, with a **GUI client** attached
+over WebSocket. The native TUI is a deferred later client (D62 amendment 2).
+
+## Why it can't lose your harness
+Each session spawns your agent CLI (Claude Code / Codex / a shell) as a real PTY; xterm.js is a
+true terminal emulator on the other end. The CLI runs **untouched** — its own login (Claude
+subscription included), slash commands, keybindings. The workspace is the terminal, not a wrapper.
+
+## Everything survives a session
+The server holds PTYs in memory and mirrors each session's scrollback + metadata to `state/`.
+Close/reload the client → re-attach replays scrollback and the run continues (detach, not kill).
+Restart the server → prior sessions reload as `exited` with full history and one-click respawn.
+
+## Run it — just type `pmos`
+One-time setup (installs the `pmos` command on your machine):
+```bash
+cd workspace
+npm install -g .
+```
+Then, from any terminal, any folder:
+```bash
+pmos                 # starts the workspace (installs deps on first run) + opens the browser
+```
+That's it. The server keeps running after you close the terminal — sessions survive (R7).
+```bash
+pmos status          # is it running? which sessions?
+pmos stop            # shut it down (scrollback is preserved; sessions respawn next time)
+pmos doctor          # diagnose the environment (node-pty arch, PTY spawn test)
+```
+
+<details><summary>Without the global install (running from the repo)</summary>
+
+```bash
+cd workspace
+npm install          # node-pty (native), ws, @xterm/*
+npm start            # http://127.0.0.1:7433  (localhost only — never public, D62)
+npm test             # end-to-end checks: PTY round-trip, restart-persistence, gates, launcher
+npm run test:ui      # browser checks: terminal geometry, reader scroll, markdown (needs Chrome)
+```
+</details>
+
+## Layout (PM-directed, D62 R9 + round 2)
+Three columns. **Left = the workspace**: repos on top, running agents below, equal halves.
+**Middle = the terminal**, sessions as tabs. **Right rail = the library over the document
+reader** — either pane folds away (click its header), the whole rail hides (`rail`), and both
+the split and the rail width are draggable. The layout you choose survives a reload.
+
+- **Add a repo by picking a folder** — `＋` opens your machine's own folder chooser (typing a
+  path still works; where no chooser exists, an in-app folder browser stands in).
+- **Rename a session any time** — the ✎ on its row, a double-click on its tab, or `F2`. Live or
+  exited, and it survives a server restart.
+- **Documents read like documents** — the identity block becomes a card, tables are tables,
+  nested/ordered/task lists survive, and a relative `.md` link opens that document in the reader.
+- **Preview more than markdown** — `.skill` files render as markdown; text/config files open as
+  escaped source; `.html` opens as source with an opt-in **sandboxed** render (scripts + network
+  denied); markdown renders **repo-relative images inline**. A remote `![](https://…)` image is
+  never fetched (no zero-click beacon); a binary stays listed but inert (open it in your editor).
+
+## The gates are real, never automatic (R5)
+`approve` / `return` / `accept` write the PMOS file-mode vocabulary to `acceptances.jsonl` and
+clear the matching needs entry — only ever on your click.
+
+**The record lands in the repo that earned it.** Each workspace resolves its own state dir —
+`pmos/state/` (the kit's layout, D54), then `state/`, then `.pmos/`; the home workspace uses the
+server's own `state/`. A PMOS-shaped repo with no state dir yet gets the kit layout on first
+write. That path matters: `scripts/metrics.py` reads `pmos/state/acceptances.jsonl` for the north
+star and κ, so an acceptance recorded anywhere else is a green click over an empty record. A
+plain (non-PMOS) repo has no layout to invent — the gate records into the server's `state/` and
+the response says `fallback: true` rather than guessing.
+
+Records carry the kit's `accepted` field (`accept` → true, `return` → false) so file-mode metrics
+count them. `pm_label` is **never** derived from a click — κ labels are the PM's own word (D40).
+
+## Your own runs are searchable (the history lens)
+Every session's scrollback is already mirrored to disk, which makes it a record of what earlier
+runs actually **did** — the thing structured run rows don't carry. The rail's fourth lens,
+**history**, searches it; the filter box becomes the query. An agent working in a pane can ask
+the same question itself: `GET /api/search?q=…&ws=…`.
+
+Two guarantees. It is scoped to **one repo** — a workspace never searches another's history
+(R1/R3), and an unrecognised workspace id resolves to home, so it can only ever see less.
+And every returned line is **scrubbed** of ANSI and of anything credential-shaped (bearer
+tokens, JWTs, `Authorization:` values, api keys): scrollback holds whatever the agent printed,
+so D08's never-log-headers discipline applies to what this hands back. Matching runs against
+the *scrubbed* text, so the endpoint cannot be used to grep a secret out.
+
+## Boundaries (honest v1 seams)
+- **Server binds 127.0.0.1** — the D62 hosted-PTY-bridge rejection stands; a tailnet/phone client
+  attaches to the same local server, never a public endpoint.
+- **needs-you feed** — an explicit `needs.json` (written by the harness/MCP) is authoritative for
+  the entries it names; everything else is **derived** from the repo's own append-only state, so a
+  repo nobody has seeded still shows its real work. Derived: an eval with no acceptance for its run
+  (the Acceptance Gate is open, D12), and a declared outcome past its horizon with no disposition
+  (the D57 check is due — a *missing* horizon counts as due, mirroring `metrics.py`). Derivation
+  only reports: an overdue outcome carries **no** close button, because disposal is
+  `record_outcome_check` with evidence, and auto-disposal is prohibited (D57).
+- File reads are **path-guarded** to the repo. The reader serves previewable **text kinds**
+  (markdown incl. `.skill`, text/config, HTML source) and streams repo-relative **images** through
+  a MIME-allowlisted `/api/asset`; binaries and out-of-root/cross-workspace paths are refused.
+  Remote images are never fetched (no beacon). Request headers are never logged (D08).
+
+Screenshots: `docs/screenshot-dark.png`, `docs/screenshot-light.png`, `docs/screenshot-doc.png`.

package/workspace/REMOTE.md

@@ -0,0 +1,131 @@
+---
+type: Reference
+title: "Workspace remote access over a private tailnet (Tailscale)"
+timestamp: 2026-07-26
+---
+
+# Reaching the workspace from your phone — over a private tailnet, never the public internet
+
+The workspace server owns **real terminal sessions (PTYs)** running your `claude` on **your own
+subscription**. By default it binds `127.0.0.1` only, so it is reachable solely from the machine it
+runs on. This runbook enables reaching **the same local server** from another of your own devices —
+a phone, a laptop — over a **private Tailscale tailnet**. It never exposes a public endpoint.
+
+## Why a tailnet, and why no public endpoint (D62)
+
+A [Tailscale](https://tailscale.com) tailnet is a private [WireGuard](https://www.wireguard.com/)
+mesh between **your own devices**. Every device is authenticated and encrypted end-to-end; addresses
+live in the CGNAT range `100.64.0.0/10` and are routable **only** between devices on your tailnet —
+never from the public internet.
+
+PMOS's locked decision **D62** rejects, permanently:
+
+- **any public endpoint** for the workspace server, and
+- **any hosted PTY bridge** (proxying the terminal through a hosted, browser-reachable surface).
+
+A public server that owns a PTY running your Claude subscription is severe exposure. The tailnet path
+sidesteps that entirely: the phone attaches to the *same local server* across your own private
+network. Accordingly, this feature will **only ever** bind loopback plus your machine's own tailnet
+address. If you ask it to bind anything else (`0.0.0.0`, a LAN or public IP), it **refuses to start**.
+
+## Setup
+
+1. **Install Tailscale** on the machine running the workspace and on your phone:
+   - Machine: https://tailscale.com/download — then `tailscale up`.
+   - Phone: install the Tailscale app from your app store and sign in to the **same** tailnet.
+   - Confirm the machine's tailnet IPv4: `tailscale ip -4` (a `100.x.y.z` address).
+
+2. **Start the server in remote mode**, from `workspace/`:
+
+   ```sh
+   PMOS_REMOTE=tailnet npm start
+   ```
+
+   On startup it prints (once):
+
+   ```
+   pmos workspace server — REMOTE (tailnet) mode
+     local:   http://127.0.0.1:7433
+     tailnet: http://100.x.y.z:7433   (private WireGuard net, device-authenticated, never public — D62)
+     token (generated — shown ONCE, copy it now): <a long token>
+     attach with header  Authorization: Bearer <token>   or query  ?token=<token>
+     loopback requests are token-free; every tailnet request must present the token.
+   ```
+
+   **Copy the token now** — it is shown only once and never logged again.
+
+3. **Open it from your phone.** In the phone's browser (on the same tailnet), open:
+
+   ```
+   http://100.x.y.z:7433/?token=<token>
+   ```
+
+   The client attaches to the **same live sessions** the desktop sees; the token authorizes both the
+   page and its WebSocket. Requests from the machine itself (`127.0.0.1`) never need the token.
+
+## Configuration
+
+| Variable | Effect |
+|---|---|
+| `PMOS_REMOTE=tailnet` | Opt in. Bind loopback **+** the machine's tailnet IPv4, and require a token beyond loopback. |
+| `PMOS_BIND_TAILNET=1` | Equivalent to `PMOS_REMOTE=tailnet`. |
+| `PMOS_TOKEN=<t>` | Use your own token instead of a generated one. **Never printed** — supply it yourself on both ends. |
+| `PMOS_TAILNET_IP=<100.x.y.z>` | Pin the tailnet address (skips auto-detection). Must be within `100.64.0.0/10`. |
+| `PMOS_BIND_ADDR=<addr>` | Force a specific bind. Accepted **only** if loopback or within `100.64.0.0/10`; anything else refuses to start. |
+| *(none of the above)* | **Default:** loopback only, no token — unchanged local behavior. |
+
+## Security model (what is guaranteed)
+
+- **Never public.** The only addresses the server will ever bind are loopback and a
+  `100.64.0.0/10` tailnet address. `0.0.0.0`, `::`, LAN, and public IPs are refused — the server
+  exits with a clear error rather than binding them. There is no code path to a public bind.
+- **Token beyond loopback.** With remote mode on, every non-loopback HTTP request and WebSocket
+  upgrade must present the bearer token, or it is rejected (`401` / socket closed). Loopback requests
+  stay token-free for local development. The comparison is constant-time.
+- **Origin/Host allowlist (D64).** Both the HTTP guard and the WebSocket-upgrade handshake reject any
+  request whose `Origin` is foreign (not same-origin with the `Host` it arrived on) or whose `Host`
+  hostname is not loopback/localhost or your tailnet address. This closes the cross-origin-localhost /
+  DNS-rebinding vector: without it, **any website open in your browser** could open a WebSocket to
+  `ws://127.0.0.1:<port>` and spawn a shell + type into it, because loopback peers are token-exempt.
+  A same-origin page served by the workspace passes; a cross-site page is rejected `403`. Native
+  clients / `curl` (which send no `Origin`) still pass this check and are then gated by the token.
+- **No header/token logging (D08).** The request-guard path logs nothing about the request. The
+  token is printed at most once at startup (only when generated); a token you supply is never echoed.
+- **Rate-limited control channel (D64).** The WS messages that spawn shells (`new`/`respawn`) and
+  feed a PTY (`input`) are per-connection rate-limited, bounding abuse if the socket is ever reached.
+- **Independent layers.** The tailnet (WireGuard device auth), the bearer token, and the origin/host
+  allowlist all gate access — a device must be *on your tailnet*, *hold the token*, **and** present a
+  same-origin request from an allowed host.
+
+## Exposing to the internet — the required hardening (D64)
+
+The workspace is **tailnet-first**. The tailnet path above is the supported way to reach it from
+another of your own devices and needs no internet exposure. If you nonetheless expose an instance to
+the internet, D64 permits it **only after all three of the following are in place — never before, and
+never as a raw public bind**:
+
+1. **The bearer token for every non-loopback peer** (already enforced in remote mode).
+2. **The Origin/Host allowlist** (already enforced — see above).
+3. **TLS termination at the exposure boundary.** **The workspace server does not terminate TLS.** It
+   speaks plain HTTP/WS and must sit behind something that terminates TLS for it — Tailscale's own
+   HTTPS (`tailscale serve` / `tailscale funnel`) or a reverse proxy (Caddy, nginx, a tunnel) that
+   holds the certificate and forwards to the loopback/tailnet listener. Do **not** put the raw HTTP
+   port on a public interface — the server refuses non-loopback/non-tailnet binds precisely so this
+   stays a conscious proxy decision, not an accident.
+
+When a reverse proxy forwards to the workspace, keep the forwarded `Host` set to the loopback/tailnet
+host the server actually binds, so the Origin/Host allowlist still recognises same-origin requests.
+
+## Troubleshooting
+
+- **"refusing to bind … only loopback or a Tailscale tailnet address (100.64.0.0/10) is permitted"**
+  — you passed `PMOS_BIND_ADDR` (or `PMOS_TAILNET_IP`) that isn't loopback or tailnet. Use your real
+  `tailscale ip -4` value.
+- **"no Tailscale tailnet address … was found"** — Tailscale isn't up on this machine. Run
+  `tailscale up`, or set `PMOS_TAILNET_IP`.
+- **"cannot bind 100.x.y.z:PORT — that address is not present on this machine"** — the pinned
+  `PMOS_TAILNET_IP` isn't actually assigned to this machine. Check `tailscale ip -4`.
+- **Phone gets 401** — the token is missing or wrong. Re-open with `?token=<token>` (or send
+  `Authorization: Bearer <token>`). Restarting the server without `PMOS_TOKEN` mints a new token.
+- **Phone can't connect at all** — confirm both devices show each other in the Tailscale app, and
+  that you used the `100.x.y.z` address, not a LAN IP.