modelroom 0.0.0-stage → 0.0.2

package/docs/02-convention.md

@@ -0,0 +1,109 @@
+# The convention
+
+A room is one screen. Everything in a room is a file with one job, and every file has one
+audience. That is the whole idea; the rest follows.
+
+## Files
+
+```
+rooms/<room>/
+├── BRIEF.md        why this room exists        → director, everyone
+├── SPEC.md         what the artifact cannot show → designer, agent, implementer
+├── BEHAVIOUR.md    what it promises             → tests, implementer
+└── index.html      the artifact (the screen)    → director, owner, implementer
+```
+
+The artifact is the visible spec. `SPEC.md` is the invisible one. They must not overlap.
+
+## Rules
+
+1. **The artifact owns what is visible.** If a statement can be shown in a screenshot, it
+   belongs to `index.html`, not to `SPEC.md`.
+2. **A statement lives in one file.** To reach another file, reference it by id
+   (`@sign-in-1`) instead of copying it.
+3. **The design layer never reads the application.** Rooms hold promises the room itself can
+   keep. Anything that needs the real system — records, timestamps, rounding, permissions —
+   belongs to the application and is handed over, not fetched.
+4. **Implementation reads the design layer, never the other way round.**
+
+This is enforceable rather than aspirational: an agent working in the design layer can be
+denied access outside it (for example, OpenCode `permissions` with
+`external_directory: deny` and write rules limited to `rooms/*`).
+
+## The artifact
+
+- Self-contained: no CDN, no web fonts, no framework, no build step. It is going to be handed
+  to implementation, so it has to stand on its own (and render with no network).
+- One file per state (`index-error.html` and so on). Steps in a flow are separate rooms.
+- Anything shared (a component, a token) is named in `SPEC.md`, not reinvented per room.
+
+## Frontmatter is the record
+
+The body is the content. The frontmatter is the record the dashboard reads: the title,
+the one-line summary, the tags, the state. Nothing else stores it, so nothing has to be
+kept in sync.
+
+```yaml
+---
+title: Sign in
+status: draft
+version: 1
+summary: A boring front door — the person is signed in, or told plainly why not.
+tags: [auth, form]
+---
+```
+
+Reserved keys — shape only, never a fixed vocabulary:
+
+| Key | Shape | Shown as |
+|---|---|---|
+| `title` | string | the card's heading |
+| `summary` | string | one line under the heading |
+| `key_points` | string[] | up to three bullets |
+| `tags` | string[] | chips, and a checkbox facet |
+| `status` | string | a badge, and a facet |
+| `version` | number or string | a `v3` badge |
+| `updated_at` | date string | sort order (falls back to file mtime) |
+| `deprecated` | boolean | hidden unless archived is on |
+| `superseded_by` | string | a pointer to the room that replaced this one |
+
+**Everything else is a facet.** Add `category: kiosk`, `platform: tablet`, or anything
+that helps you narrow the list; a string becomes a radio group or a select (built from
+the values that exist, with counts), a list becomes checkboxes. The dashboard never
+validates values — it shows what is there.
+
+`adopted` (or `accepted`, `approved`) is a human decision. An agent must never set it.
+
+## What an agent may do
+
+An agent adds. It does not delete.
+
+- new room, new key, new tag, new doc → fine
+- merge two spellings → add an alias, leave both values in place
+- retire a room → `deprecated: true` and `superseded_by: <room>`
+- remove a file or a key → a human does it
+
+That is what makes "the agent keeps the record tidy" safe: every move is additive and
+reversible in git.
+
+## The check
+
+```
+modelroom check
+```
+
+It reads the frontmatter — head of the file only — and reports what would stop the
+dashboard from deriving the record: malformed or nested frontmatter, a reserved key with
+the wrong shape, two spellings of the same value, a `title` that disagrees with the H1,
+a `superseded_by` that points nowhere. Errors are fixable by an agent; warnings are for a
+human. It never writes.
+
+## Naming
+
+- Files are named for **what they are**, not for who writes them and not for the tool:
+  `BRIEF`, `SPEC`, `BEHAVIOUR`, `DESIGN`, `principles`, `components`, `tokens`.
+- Avoid words that shift meaning with the reader (`context`, `system`, `ui`, `ux`) and words
+  that name a medium (`screen`, `page`) when the thing is not a medium.
+- **Scope is expressed by the directory, not by the filename.** One `BRIEF.md` per level —
+  product, flow, room — read top-down, written only at your own level.
+- Prefer one word that survives translation (see the list above) over a compound.

package/docs/03-cli.md

@@ -0,0 +1,103 @@
+# CLI
+
+```
+modelroom [serve] [--port 4321] [--host 127.0.0.1] [--open]
+modelroom init [<room>] [--dir rooms] [--force]
+modelroom check [--json] [--strict]
+modelroom doctor
+modelroom --version | --help
+```
+
+`modelroom` with no command is `serve`. `serve` needs Node 20+ and nothing else. `init` only
+copies templates. `check` reads the frontmatter of every room and reports convention problems.
+`doctor` checks the setup and exits non-zero when something is broken (optionally missing things
+do not count).
+
+## serve
+
+Starts the workspace on `127.0.0.1:4321` by default. `modelroom` alone does the same.
+
+- `/` — every room, side by side
+- `/room/<name>` — chat, the room's docs, the artifact
+- `/settings` — which agent to run
+- `/files/<path>` — your repository, served read-only and **unmodified** (no injection)
+
+`--open` tries to open a browser; on a headless machine it is ignored.
+
+## init
+
+Copies the room templates and, if missing, `modelroom.json`, `AGENTS.md` and a
+`.modelroom/` line in `.gitignore`.
+
+```
+modelroom init checkout            # creates rooms/checkout/
+modelroom init checkout --dir design/screens
+modelroom init checkout --force    # overwrite existing files
+```
+
+## check
+
+```
+modelroom check              # errors and warnings
+modelroom check --json       # machine-readable
+modelroom check --strict     # warnings fail too
+```
+
+It only reads the head of each doc (frontmatter lives there) and never writes:
+
+```
+FAIL  sign-in/BRIEF.md  reserved-type  tags must be array, got string
+warn  checkout/BRIEF.md  h1-title       H1 "Checkout" differs from title "check out"
+warn  sign-in/BRIEF.md   variant        status: draft / Draft — same value, different spelling
+
+2 room(s), 1 error(s), 2 warning(s)
+```
+
+Exit code is 1 on errors (or on warnings with `--strict`).
+
+## doctor
+
+```
+modelroom doctor
+ok   node 22.14.0 (needs >= 20)
+ok   root exists: /path/to/repo
+ok   rooms dir exists: rooms
+ok   rooms found: checkout, sign-in
+ok   config: modelroom.json
+ok   agent command on PATH: opencode
+ok   png rendering (playwright): not installed (optional)
+ok   room checkout: docs ok
+```
+
+## Config: `modelroom.json`
+
+```jsonc
+{
+  "root": ".",                                  // where your repository is
+  "rooms": "rooms",                             // rooms live here
+  "artifact": "index.html",                     // the file that is the screen
+  "docs": ["BRIEF.md", "SPEC.md", "BEHAVIOUR.md"], // the only files the UI may write
+  "port": 4321,
+  "agent": {
+    "adapter": "opencode",                      // "opencode" | "command"
+    "command": "opencode",
+    "agent": "build",
+    "model": null,                              // set this when your agent's default fails
+    "standalone": true,
+    "args": []                                  // adapter "command": e.g. ["-p", "{prompt}"]
+  }
+}
+```
+
+Anything you change from `/settings` is kept locally in `.modelroom/state.json`
+(git-ignore it) — committed configuration stays in `modelroom.json`.
+
+## Thumbnails
+
+Rendering the artifact to PNG is optional and needs Playwright:
+
+```
+npm i -D playwright && npx playwright install chromium
+```
+
+Without it, rooms simply show no thumbnail and the **make png** button reports why.

package/docs/04-agents.md

@@ -0,0 +1,88 @@
+# Agents
+
+modelroom does not bundle a model and does not own a chat product. It runs the agent you
+configure, one session per room, and shows you what changed.
+
+## Built-in adapters
+
+| Adapter | What it runs | Notes |
+|---|---|---|
+| `opencode` | [OpenCode](https://opencode.ai) CLI | sessions, model and agent selection |
+| `command` | any CLI | you provide `agent.args`; `{prompt}` and `{session}` are substituted |
+
+### opencode
+
+```jsonc
+{
+  "agent": {
+    "adapter": "opencode",
+    "command": "opencode",
+    "agent": "build",           // an agent defined in .opencode/agents/
+    "model": "openrouter/deepseek/deepseek-v4.1-flash",
+    "standalone": true
+  }
+}
+```
+
+modelroom runs, roughly:
+
+```
+opencode run --standalone --agent <agent> --model <model> --session <id> --auto "<prompt>"
+```
+
+Two things are worth knowing, both learned the hard way:
+
+- **Set `model`.** Many agents resolve to a free tier by default, and the CLI then refuses to
+  run outside its own app (`OpenCode's free tier can only be used from within OpenCode`).
+- **`standalone: true`** runs the agent against a private server that inherits this process's
+  environment, which is what makes provider keys visible to it. If your shared service already
+  has keys, either setting works.
+
+Agents that need to *write* only the room's files should be scoped on their side, for example
+with OpenCode `permissions`:
+
+```yaml
+# .opencode/agents/design.md
+permissions:
+  - { action: "*", resource: "*", effect: deny }
+  - { action: read, resource: "rooms/*", effect: allow }
+  - { action: edit, resource: "rooms/*", effect: allow }
+  - { action: glob, resource: "*", effect: allow }
+  - { action: grep, resource: "*", effect: allow }
+  - { action: external_directory, resource: "*", effect: deny }
+```
+
+### command
+
+For anything else — Claude Code, Codex, a local model, a shell script:
+
+```jsonc
+{
+  "agent": { "adapter": "command", "command": "claude", "args": ["-p", "{prompt}"] }
+}
+```
+
+`{session}` is substituted with the room's session id. Sessions are stored per room in
+`.modelroom/state.json`; **new session** in the room UI starts a fresh one.
+
+## Writing an adapter
+
+An adapter is one object:
+
+```js
+export const mine = {
+  name: 'mine',
+  newSessionId: () => `ses_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`,
+  run({ cfg, cwd, prompt, sessionId, onChunk, onExit }) {
+    // spawn your CLI; stream output with onChunk('stdout'|'stderr', text)
+    // call onExit(code, errorMessage?) once it finishes
+  },
+};
+```
+
+Add it to `lib/agents/index.mjs`. Two rules keep adapters honest:
+
+1. **Close stdin** (`stdio: ['ignore', 'pipe', 'pipe']`). A CLI that reads stdin will hang
+   forever if the pipe stays open.
+2. **Do not parse the output into meaning.** modelroom shows the agent's words as they are.
+   Interpretation belongs to the person reading the room.

package/examples/rooms/sign-in/BEHAVIOUR.md

@@ -0,0 +1,23 @@
+# sign-in — behaviour
+
+What this room promises.
+
+```gherkin
+Feature: sign in
+
+  @sign-in-1
+  Scenario: correct credentials
+    Given the sign-in screen is open
+    When the person submits a valid email and password
+    Then the screen reports success and leaves for the next room
+
+  @sign-in-2
+  Scenario: wrong credentials
+    Given the sign-in screen is open
+    When the person submits a password that does not match
+    Then the screen stays, and explains in one sentence that the details did not match
+```
+
+Notes
+- The room does not decide how credentials are checked — that belongs to the application.
+- `@sign-in-2` must not reveal whether the email exists.

package/examples/rooms/sign-in/BRIEF.md

@@ -0,0 +1,15 @@
+---
+title: Sign in
+status: draft
+version: 1
+summary: A boring front door — the person is signed in, or told plainly why not.
+tags: [auth, form]
+---
+# Sign in
+
+Why does this room exist?
+
+- **For:** someone who has an account and needs to get in, once, on a device they may not own
+- **Because:** we want a front door that is boring, quick and impossible to get wrong
+- **Matters most:** the person is signed in, or told plainly why not
+- **Not doing:** sign-up, password reset, "remember me", social login

package/examples/rooms/sign-in/SPEC.md

@@ -0,0 +1,14 @@
+# sign-in — spec
+
+Only what the artifact cannot show.
+
+- **Where it is used:** desktop and tablet browsers; keyboard and touch; works offline
+  (nothing on this screen fetches until submit)
+- **States:**
+  - default — `index.html`
+  - rejected credentials — `index-error.html` (same layout, one alert above the button)
+- **Constraints:**
+  - one purpose per screen: sign in, nothing else
+  - the submit button is reachable without scrolling at 1024×768
+  - errors are stated in one sentence, without blame
+- **Uses:** `components/field`, `components/button-primary`, tokens `--surface`, `--primary`

package/examples/rooms/sign-in/index.html

@@ -0,0 +1,56 @@
+<!doctype html>
+<!-- sign-in — example room artifact. Self-contained: no CDN, no framework, no build. -->
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>sign in</title>
+<style>
+  :root {
+    --bg: #faf9f7; --surface: #ffffff; --text: #1c1917; --muted: #78716c;
+    --line: #e7e5e4; --primary: #1c1917; --primary-text: #fafaf9;
+    --danger-bg: #fef2f2; --danger-line: #fecaca; --danger-text: #991b1b;
+    --radius: 14px;
+  }
+  * { box-sizing: border-box; }
+  html, body { height: 100%; }
+  body {
+    margin: 0; display: grid; place-items: center; padding: 32px 20px; background: var(--bg); color: var(--text);
+    font-family: "Hiragino Kaku Gothic ProN", "Hiragino Sans", "Noto Sans JP", system-ui, sans-serif; line-height: 1.7;
+  }
+  .card {
+    width: min(440px, 100%); background: var(--surface); border: 1px solid var(--line);
+    border-radius: var(--radius); padding: 32px; display: flex; flex-direction: column; gap: 20px;
+  }
+  .brand { font-size: 13px; letter-spacing: .12em; text-transform: uppercase; color: var(--muted); }
+  h1 { font-size: 22px; margin: 0; }
+  .field { display: flex; flex-direction: column; gap: 6px; }
+  label { font-size: 13px; color: var(--muted); }
+  input {
+    font: inherit; padding: 12px 14px; border: 1px solid var(--line); border-radius: 10px; background: var(--surface); color: var(--text);
+  }
+  input:focus-visible { outline: 2px solid var(--primary); outline-offset: 1px; }
+  button {
+    font: inherit; padding: 14px 20px; border-radius: 10px; border: 1px solid var(--primary);
+    background: var(--primary); color: var(--primary-text); cursor: pointer; min-height: 48px;
+  }
+  .hint { font-size: 13px; color: var(--muted); }
+</style>
+</head>
+<body>
+  <main class="card">
+    <div class="brand">modelroom · example</div>
+    <h1>Sign in</h1>
+    <div class="field">
+      <label for="email">Email</label>
+      <input id="email" type="email" autocomplete="username" placeholder="you@example.com">
+    </div>
+    <div class="field">
+      <label for="password">Password</label>
+      <input id="password" type="password" autocomplete="current-password" placeholder="••••••••">
+    </div>
+    <button>Sign in</button>
+    <p class="hint">This is a model room — nothing here is connected to anything.</p>
+  </main>
+</body>
+</html>

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "modelroom",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "A local workspace to design UI screens with any coding agent — one room per screen: BRIEF, SPEC, BEHAVIOUR and the artifact.",
+  "keywords": [
+    "agent-agnostic",
+    "ai-agents",
+    "claude-code",
+    "codex",
+    "coding-agents",
+    "design",
+    "design-system",
+    "design-workflow",
+    "live-preview",
+    "opencode",
+    "spec-driven",
+    "ui-design"
+  ],
+  "homepage": "https://github.com/modelroom/modelroom#readme",
+  "bugs": {
+    "url": "https://github.com/modelroom/modelroom/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modelroom/modelroom.git"
+  },
+  "bin": {
+    "modelroom": "dist/bin/modelroom.js"
+  },
+  "files": [
+    "dist",
+    "ui",
+    "templates",
+    "examples",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "types": "./dist/lib/server.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/lib/server.d.ts",
+      "default": "./dist/lib/server.js"
+    }
+  },
+  "scripts": {
+    "dev": "node --watch bin/modelroom.ts",
+    "modelroom": "node bin/modelroom.ts",
+    "start": "node bin/modelroom.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "build:css": "tailwindcss -i src/modelroom.css -o ui/modelroom.css --minify",
+    "dev:css": "tailwindcss -i src/modelroom.css -o ui/modelroom.css --watch",
+    "lint": "oxlint",
+    "lint:types": "oxlint --type-aware",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "verify": "npm run lint && npm run lint:types && npm run format:check && npm run typecheck && npm test && npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@tailwindcss/cli": "^4.3.3",
+    "@types/node": "^26.6.5",
+    "@vitest/coverage-v8": "^5.0.5",
+    "daisyui": "^5.7.50",
+    "lefthook": "^2.2.2",
+    "oxfmt": "^0.73.0",
+    "oxlint": "^1.88.0",
+    "oxlint-tsgolint": "^7.0.2004",
+    "playwright": "^1.64.1",
+    "publint": "^0.3.25",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  },
+  "engines": {
+    "node": ">=22.18"
+  }
+}

package/templates/AGENTS.md

@@ -0,0 +1,31 @@
+# AGENTS.md — design layer
+
+This repository uses [modelroom](https://github.com/modelroom/modelroom): one room per screen,
+with the reason, the invisible spec, the promises and the artifact kept apart.
+
+## Where you may write
+
+- `rooms/<room>/BRIEF.md` — why this room exists
+- `rooms/<room>/SPEC.md` — what the artifact cannot show (devices, states, constraints, what it may use)
+- `rooms/<room>/BEHAVIOUR.md` — what it promises (operations and results)
+- `rooms/<room>/index.html` — the artifact itself
+
+Nothing else. Do not touch the application code from here; the design layer never reads it.
+
+## How to work
+
+1. Read the room's `BRIEF.md` first, then `SPEC.md` and `BEHAVIOUR.md`.
+2. Change the artifact to match them. If they are wrong, say so — do not quietly reword them.
+3. Keep the artifact self-contained: no CDN, no web fonts, no framework, no build step.
+   It is going to be handed to implementation, so it must stand on its own.
+4. Never restate in `SPEC.md` what can be seen in the artifact. Never copy a promise into
+   two files; reference it by id (`@verb-1`) instead.
+5. Promises that need the real system (records, timestamps, permissions) do not belong in
+   this layer.
+
+## Conventions
+
+- Add `Status: draft|review|adopted` to `BRIEF.md` when you want the dashboard to show a state.
+  Changing it to `adopted` is a human decision, not yours.
+
+See `docs/02-convention.md` in the modelroom package for the reasoning.

package/templates/modelroom.json

@@ -0,0 +1,14 @@
+{
+  "root": ".",
+  "rooms": "rooms",
+  "artifact": "index.html",
+  "docs": ["BRIEF.md", "SPEC.md", "BEHAVIOUR.md"],
+  "port": 4321,
+  "agent": {
+    "adapter": "opencode",
+    "command": "opencode",
+    "agent": "build",
+    "model": null,
+    "standalone": true
+  }
+}

package/templates/room/BEHAVIOUR.md

@@ -0,0 +1,19 @@
+# {{room}} — behaviour
+
+What this room promises: operations and their results. Keep the wording in the language of
+the work, not of the code.
+
+```gherkin
+Feature: {{room}}
+
+  @first-1
+  Scenario: a first promise
+    Given some starting point
+    When the person does something
+    Then something observable happens
+```
+
+Notes
+- One id per promise (`@<verb>-<n>`), and one promise per scenario.
+- Promises that need the real system (records, timestamps, permissions) belong to the
+  application, not to this file.

package/templates/room/BRIEF.md

@@ -0,0 +1,16 @@
+---
+title: {{room}}
+status: draft
+version: 1
+summary: One sentence the next person can decide from.
+tags: []
+---
+# {{room}}
+
+Why does this room exist? Who is it for, and what has to be true for it to be worth
+building? Keep the priorities and the things you are deliberately not doing.
+
+- **For:**
+- **Because:**
+- **Matters most:**
+- **Not doing:**

package/templates/room/SPEC.md

@@ -0,0 +1,9 @@
+# {{room}} — spec
+
+Only what the artifact cannot show. If it can be seen in a screenshot, it belongs to the
+artifact, not here.
+
+- **Where it is used:** (device, input, environment)
+- **States:** (e.g. default, empty, error — and the file each one lives in)
+- **Constraints:** (what must stay true regardless of the layout)
+- **Uses:** (shared components and tokens this room is allowed to use)

package/templates/room/index.html

@@ -0,0 +1,53 @@
+<!doctype html>
+<!-- {{room}} — artifact (the thing you hand to implementation)
+     Self-contained on purpose: no CDN, no framework, no build. -->
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{{room}}</title>
+<style>
+  :root {
+    --bg: #faf9f7;
+    --surface: #ffffff;
+    --text: #1c1917;
+    --muted: #78716c;
+    --line: #e7e5e4;
+    --primary: #1c1917;
+    --primary-text: #fafaf9;
+    --radius: 16px;
+    --space: 24px;
+  }
+  * { box-sizing: border-box; }
+  html, body { height: 100%; }
+  body {
+    margin: 0; display: grid; place-items: center; padding: 40px 20px; background: var(--bg); color: var(--text);
+    font-family: "Hiragino Kaku Gothic ProN", "Hiragino Sans", "Noto Sans JP", system-ui, sans-serif;
+    line-height: 1.7;
+  }
+  .card {
+    width: min(520px, 100%); background: var(--surface); border: 1px solid var(--line);
+    border-radius: var(--radius); padding: var(--space); display: flex; flex-direction: column; gap: var(--space);
+  }
+  h1 { font-size: 22px; margin: 0; letter-spacing: .01em; }
+  p { margin: 0; color: var(--muted); font-size: 15px; }
+  .actions { display: flex; gap: 12px; flex-wrap: wrap; }
+  button {
+    font: inherit; padding: 14px 22px; border-radius: var(--radius); border: 1px solid var(--line);
+    background: var(--surface); color: var(--text); cursor: pointer;
+  }
+  button.primary { background: var(--primary); color: var(--primary-text); border-color: var(--primary); }
+</style>
+</head>
+<body>
+  <main class="card">
+    <h1>{{room}}</h1>
+    <p>This is the artifact for the room. Replace it from the chat, or write it by hand.
+       The spec and the promises live next to it in SPEC.md and BEHAVIOUR.md.</p>
+    <div class="actions">
+      <button class="primary">Primary action</button>
+      <button>Secondary</button>
+    </div>
+  </main>
+</body>
+</html>