@asrunjs/asrun 0.2.0 → 0.5.3

package/dist/ui/shared/ai-commands.js

@@ -68,10 +68,25 @@ const STREAM_ARGS = {
     claude: ['--output-format', 'stream-json', '--verbose'],
     opencode: ['--format', 'json'],
 };
-function invocation(tool, prompt, writes, session) {
+function invocation(tool, prompt, writes, session, model, thinking) {
     // OpenCode creates the session when the id does not exist yet, and continues it when it does.
+    // A model is named on every run: without one OpenCode falls back to its built-in free model, which has a daily
+    // usage limit, and nothing in the CLI's own state (the TUI's last-used model) applies to a one-shot run.
     if (tool === 'opencode')
-        return { file: 'opencode', args: ['run', '--auto', ...STREAM_ARGS.opencode, ...(session ? ['-s', session.id] : []), prompt] };
+        return {
+            file: 'opencode',
+            args: [
+                'run',
+                '--auto',
+                ...STREAM_ARGS.opencode,
+                ...(session ? ['-s', session.id] : []),
+                ...(model ? ['--model', model] : []),
+                // Without it OpenCode does not ask the model to think, so the reasoning it does would never reach the log.
+                // Claude Code has no such flag: it shows thinking when the model and its settings have it on.
+                ...(thinking ? ['--thinking'] : []),
+                prompt,
+            ],
+        };
     return {
         file: 'claude',
         args: [
@@ -81,6 +96,7 @@ function invocation(tool, prompt, writes, session) {
             ...(session ? [session.resume ? '--resume' : '--session-id', session.id] : []),
             // `acceptEdits` approves edits anywhere in the folder, which would void the narrow Edit rules below.
             ...(writes === 'files' || writes === 'spec' ? ['--permission-mode', 'acceptEdits'] : []),
+            ...(model ? ['--model', model] : []),
             '--allowedTools',
             ...claudeAllowedTools(writes),
             '--disallowedTools',
@@ -100,7 +116,10 @@ const NON_INTERACTIVE = 'Non-interactive run: nobody can answer questions, so do
  * browser window, so the agent hands them the steps that write data and waits, as user-handoff.md describes.
  */
 const ATTENDED = 'Attended run: a person is at the machine and the browser window is visible, so hand steps that write data or ' +
-    'need a choice to them and wait, as the skill describes. Nobody can answer questions in the chat, so write open ' +
+    'need a choice to them and wait, as the skill describes. Start every handoff (also a second one in the same run) ' +
+    'with its own call that sets __handoffCfg, before the call that runs handoff-card.js, and never change those options ' +
+    'inside the call that runs the card: the web UI sees that a person is needed only from that call, so without it ' +
+    'there is no "Your turn" badge and no notification. Nobody can answer questions in the chat, so write open ' +
     'questions into the case file as the skill describes and end with the RESULT: line.';
 /** The prompt of a one-shot run. `heal-spec` has no questions of its own, so it keeps the plain slash command. */
 export function headlessPrompt(command, caseId, options) {
@@ -113,7 +132,7 @@ export function headlessPrompt(command, caseId, options) {
 }
 /** Executable and arguments of the one-shot (non-interactive) run. */
 export function headlessInvocation(tool, command, caseId, options, session) {
-    return invocation(tool, headlessPrompt(command, caseId, options), AI_COMMAND_WRITES[command], session);
+    return invocation(tool, headlessPrompt(command, caseId, options), AI_COMMAND_WRITES[command], session, options.model, options.thinking);
 }
 /** The one-shot command as it is typed in a shell. */
 export function headlessCommandLine(tool, command, caseId, options, session) {
@@ -122,23 +141,27 @@ export function headlessCommandLine(tool, command, caseId, options, session) {
 /** Folder (relative to the AsRun root, git-ignored) where the clues typed into the Heal dialog are stored. */
 export const HINTS_DIR = '.tmp/hints';
 export const HINTS_MAX_CHARS = 8000;
+/** Folder (relative to the AsRun root, git-ignored) where the answers typed into the Continue box are stored. */
+export const REPLY_DIR = '.tmp/replies';
 export const REPLY_MAX_CHARS = 4000;
 export const USE_DEFAULTS_REPLY = 'Accept the suggestion of every open question: delete its TODO block and keep the sentence above it as confirmed text.';
 /**
  * The next turn of a run that ended with `RESULT: needs-input`: the user's answers. They go into the case file, which
- * stays the record of truth, and the task of the original command is finished.
+ * stays the record of truth, and the task of the original command is finished. The answers come from a file
+ * (`.tmp/replies/…md`) rather than from the prompt, so a line break or a quote in them cannot break the command line.
  */
-export function replyPrompt(command, reply) {
-    return (`The user answers your open questions (still nobody to ask, so do not stop to ask again):\n${reply.trim()}\n` +
+export function replyPrompt(command, replyFile) {
+    return (`The user answers your open questions (still nobody to ask, so do not stop to ask again). ` +
+        `Their answers are in ${replyFile}, relative to the project root: read that file first.\n` +
         'Fold every answer into the case file as the skill describes: write the answer into the sentence above the ' +
         'TODO block and remove the block, and keep a TODO block (with an empty Answer: line, emoji prefixes included) for what is still unknown. ' +
         `Then finish the task of /${command} and end with the RESULT: line.`);
 }
 /** The next turn of an earlier run, in its session and with exactly the permissions of the first turn. */
-export function continueInvocation(tool, command, reply, sessionId) {
-    return invocation(tool, replyPrompt(command, reply), AI_COMMAND_WRITES[command], { id: sessionId, resume: true });
+export function continueInvocation(tool, command, replyFile, sessionId, model, thinking) {
+    return invocation(tool, replyPrompt(command, replyFile), AI_COMMAND_WRITES[command], { id: sessionId, resume: true }, model, thinking);
 }
-export const continueCommandLine = (tool, command, reply, sessionId) => commandLine(continueInvocation(tool, command, reply, sessionId));
+export const continueCommandLine = (tool, command, replyFile, sessionId, model, thinking) => commandLine(continueInvocation(tool, command, replyFile, sessionId, model, thinking));
 /** Folder (relative to the AsRun root, git-ignored) where memos from the Cases page are stored. */
 export const MEMO_DIR = '.tmp/memos';
 export const MEMO_MAX_CHARS = 100_000;
@@ -150,5 +173,5 @@ export const makeCasePrompt = (memoPath) => `/make-case ${memoPath} ` +
     'Never overwrite an existing case: choose a new id instead. ' +
     'Put the cases of one area in a group folder (cases/<group>/<name>.md, id <group>/<name>), reusing an existing folder when it fits. ' +
     'Write the cases, run pnpm case:check, and list the open questions in your final report.';
-export const makeCaseInvocation = (tool, memoPath) => invocation(tool, makeCasePrompt(memoPath), 'cases-new');
-export const makeCaseCommandLine = (tool, memoPath) => commandLine(makeCaseInvocation(tool, memoPath));
+export const makeCaseInvocation = (tool, memoPath, model, thinking) => invocation(tool, makeCasePrompt(memoPath), 'cases-new', undefined, model, thinking);
+export const makeCaseCommandLine = (tool, memoPath, model, thinking) => commandLine(makeCaseInvocation(tool, memoPath, model, thinking));

package/dist/ui/shared/types.d.ts

@@ -33,6 +33,8 @@ export interface JobInfo {
     aiCommand?: AiCommand;
     /** The conversation of an AI run; a later job can resume it. */
     sessionId?: string;
+    /** The model the AI run was started with; omitted = the CLI's own choice. */
+    aiModel?: string;
     /** What the agent said in its last `RESULT:` line; null when it did not say or the run did not succeed. */
     resultState?: ResultState | null;
     /** The earlier job whose conversation this job continues. */
@@ -47,10 +49,33 @@ export interface AwaitingUserInfo {
 }
 /** `needs-input`: the agent wrote open questions into the case file and cannot go on without answers. */
 export type ResultState = 'ready' | 'needs-input';
+/**
+ * How one block of an AI job's log is presented. Absent for the plain output of every other job, which stays raw.
+ * `markdown`: what the agent said; `reasoning`: what it was thinking (not a result); `tool`: one call, started or
+ * finished; `result`: the first lines of a call's output; `error` / `hint`: what failed and what to do about it;
+ * `meta`: anything else a person should read (the waiting line, noise the CLI printed).
+ */
+export type JobChunkKind = 'tool' | 'result' | 'reasoning' | 'markdown' | 'error' | 'hint' | 'meta';
+/** A tool call of an AI job, so the log can color its name, its outcome and the time it took. */
+export interface JobChunkTool {
+    name: string;
+    /** What the call is about (the file, the command, the intent); empty when the CLI gave nothing telling. */
+    detail: string;
+    ok: boolean;
+    /** Still running: Claude reports the start of a call, OpenCode only its end. */
+    pending?: boolean;
+    /** How long it ran, as a person reads it (`0.4 s`); absent when the CLI did not report a start time. */
+    took?: string;
+}
 export interface JobChunk {
     seq: number;
     stream: 'stdout' | 'stderr' | 'system';
     data: string;
+    /** Set for the blocks of an AI job (see `JobChunkKind`); absent for a plain command's output. */
+    kind?: JobChunkKind;
+    /** When the block was produced, for AI jobs: shown as its own styled timestamp, not as part of the text. */
+    at?: string;
+    tool?: JobChunkTool;
 }
 export type StartJobRequest = {
     action: 'signin';
@@ -68,6 +93,16 @@ export type StartJobRequest = {
     env: string;
     force?: boolean;
     attended?: boolean;
+    /**
+     * Show the agent's reasoning in the log (`--thinking` for OpenCode; Claude shows it when its model has it on).
+     * Off by default: it costs tokens and time.
+     */
+    thinking?: boolean;
+    /**
+     * The model to run the agent with (as the CLI names it). Omitted = the CLI's own choice, which for OpenCode is
+     * its built-in free model. `heal-spec` keeps the model of the run it continues.
+     */
+    model?: string;
     /** `heal-spec` only: the profiles to heal; omitted = every profile that is logged in. */
     profiles?: string[];
     /** `heal-spec` only: what the user knows (optional). The server stores it as a file for the agent. */
@@ -82,6 +117,8 @@ export type StartJobRequest = {
     action: 'make-cases';
     tool: AiTool;
     memo: string;
+    model?: string;
+    thinking?: boolean;
 } | {
     action: 'run';
     env: string;
@@ -163,6 +200,16 @@ export interface RunPlan {
 }
 export type ProfileStatus = 'missing' | 'unverified' | 'ok' | 'expired' | 'error';
 /** One profile: a row of the Profiles page. */
+export interface SessionCheckInfo {
+    /** Where a visitor without a valid session is sent: a path on the site (`/login`) or a full URL (single sign-on). */
+    loggedOutUrl: string;
+    /** A selector that only exists while signed in; null when the profile does not name one. */
+    loggedInSelector: string | null;
+    /** A selector that proves the visitor is signed out, e.g. the password field of a login form. */
+    loggedOutSelector: string | null;
+    /** How long to wait for one of those signals, in milliseconds. */
+    timeoutMs: number;
+}
 export interface ProfileInfo {
     id: string;
     name: string;
@@ -170,6 +217,14 @@ export interface ProfileInfo {
     baseURL: string;
     account: string | null;
     tags: string[];
+    /** The page "Visit" opens after a login, e.g. `/app/home`; empty = the site root. */
+    startPath: string;
+    /** A page only a signed-in visitor sees; `/account/` unless set in profiles.yaml. */
+    sessionCheckPath: string;
+    /** How that page shows a missing login. */
+    sessionCheck: SessionCheckInfo;
+    /** Tests may send real email in this environment. Always false for production. */
+    email: boolean;
     status: ProfileStatus;
     verifying: boolean;
     /** When the session file was last written. */
@@ -186,11 +241,41 @@ export interface AddProfileRequest {
     /** A label for humans (a mailbox or username). Never a password. */
     account?: string;
     tags?: string[];
+    /** The page "Visit" opens after a login. Defaults to the site root. */
+    startPath?: string;
     /** Page that redirects to /login when logged out. Defaults to /account/. */
     sessionCheckPath?: string;
+    /** How that page shows a missing login. Omitted keys keep their default. */
+    sessionCheck?: Partial<SessionCheckInfo>;
     /** Only for environments other than production. Defaults to false. */
     email?: boolean;
 }
+/** Changes to one existing profile. The id itself cannot change: commands, session files and baselines use it. */
+export interface EditProfileRequest {
+    name: string;
+    /** The environment this profile points at, e.g. `production`, `staging`. */
+    env: string;
+    baseURL: string;
+    /** A label for humans (a mailbox or username). Never a password. */
+    account?: string;
+    tags?: string[];
+    /** The page "Visit" opens after a login. Defaults to the site root. */
+    startPath?: string;
+    /** Page that redirects to /login when logged out. Defaults to /account/. */
+    sessionCheckPath?: string;
+    /** How that page shows a missing login. Omitted keys keep their default. */
+    sessionCheck?: Partial<SessionCheckInfo>;
+    /** Only for environments other than production. Defaults to false. */
+    email?: boolean;
+}
+export interface EditProfileResult {
+    profile: ProfileInfo;
+    /**
+     * True when the site address changed: the saved login belonged to the old site, was deleted, and the
+     * profile has to log in again.
+     */
+    sessionCleared: boolean;
+}
 export interface ProfilesResponse {
     profiles: ProfileInfo[];
     /** Every environment used in profiles.yaml, `production` first. */
@@ -255,3 +340,32 @@ export interface CaseImpact {
     snapshotDir: string | null;
     snapshotCount: number;
 }
+/** One model an AI CLI can be run with, as the CLI itself names it. */
+export interface AiModelOption {
+    /** Exactly what `--model` takes: `provider/model` or `provider/model#variant` (OpenCode), an alias or an id (Claude). */
+    id: string;
+    label: string;
+    /** Where the row comes from: a provider id, or `alias` / `settings` / `gateway` for a Claude CLI. */
+    group: string;
+    /** A second line: what the model is, or what an alias resolves to. */
+    detail?: string;
+}
+/** The models one AI CLI offers on this machine, read from the CLI itself or from its configuration. */
+export interface AiModelsResponse {
+    tool: AiTool;
+    models: AiModelOption[];
+    /**
+     * What the CLI would run when asrun passes no `--model`; null when it cannot be known (OpenCode picks a built-in
+     * free model, which is not stored anywhere).
+     */
+    clientDefault: string | null;
+    /**
+     * What to preselect while the user has not chosen: the CLI's default (Claude), or the model the CLI's own last
+     * session used (OpenCode). Null when neither is known.
+     */
+    suggested: string | null;
+    /** Parts of the list that could not be read, in the words of the CLI: shown above the list, never fatal. */
+    notes: string[];
+    /** Set when there is no list at all (the CLI is not installed, or its answer could not be read). */
+    error: string | null;
+}

package/docs/agents/case-format.md

@@ -0,0 +1,193 @@
+# Case document contract (for AI agents)
+
+This file describes the shape that `lib/case-doc.ts`, `lib/values.ts` and `lib/targets.ts` read, and how a generated
+spec consumes it. It holds no rules of its own: the rules are in the framework `AGENTS.md`, in the skill, and in the
+references listed at the end.
+
+Read `AGENTS.md` first. If a project has `.claude/skills/<skill>.md`, that override comes after the skill; the
+project's `AGENTS.md` §2 comes last and wins over both. `F1`–`F6` always win.
+
+## Identity and paths
+
+- A case id is its path below `cases/` without `.md`: `header-logo`, or `documents/landing-page` with **one** group
+  folder (`^[a-z0-9]+(-[a-z0-9]+)*(/[a-z0-9]+(-[a-z0-9]+)*)?$`).
+- The spec is at the same path below `tests/` (`tests/documents/landing-page.spec.ts`), with its `*-snapshots/`
+  folder next to it.
+- `cases/_template.md` and names starting with `_` are not cases.
+- Specs import the framework by package name (`@asrunjs/asrun/*`), so a group folder changes no import.
+
+## Fixed tokens
+
+The parser and the web panel match these literals. A project language never translates them:
+
+- Section headings: `## Goal`, `## Steps`, `## Expected`, `## Values`, `## Visual checks`, `## Targets`, `## Notes`,
+  and `## Source` when the case was made from notes.
+- Front matter keys: `id`, `title`, `login`, `suites`, `writes`, `writes-note`, `envs`.
+- Step tags at the end of a step line: `[input]`, `[writes]`, `[email]`.
+- Under a step: `- Ready when:` lines and `- Recipe (phase):` lines.
+- Target cards: `### T<n> <name>` and their references `[T<n>]`.
+- Questions: `🚫 TODO [blocking]`, `❓ TODO [non-blocking]`, `✍️ Answer:`, and the markers
+  `🔍 to be confirmed by QA` / `👁️ not observed`.
+- The last line of a run: `RESULT: ready` or `RESULT: needs-input`.
+
+## Front matter
+
+`---` on the first line, YAML, `---` to close. `pnpm case:check` calls `parseCaseMeta`, which refuses the file when
+`suites`, `writes` or `envs` break the rules below. `id`, `title` and `login` are required by convention: keep them
+present (the editor shows them, and the generator reads the title and the login mode), but `case:check` does not
+enforce them.
+
+| Key | Required | Rule |
+|---|---|---|
+| `id` | yes | The case id; the editor keeps it in step with the path. |
+| `title` | yes | One line. |
+| `login` | no | `required` (default) or `none`. `none` → the spec sets `test.use({mustLogin: false})`. |
+| `suites` | yes | Non-empty list of lowercase words. Missing `suites` is an error. |
+| `writes` | no | List of environments. Omit for read-only. Any value other than a known environment is refused; the old `writes: test-data` is refused with a hint. |
+| `writes-note` | with `writes` | Non-empty text: what the case creates or changes. |
+| `envs` | no | List of environments; every environment in `writes` must also be in `envs`. |
+
+`priority: <level>` is the old name of `suites`: it is read as `suites: [<level>]`, and naming both is an error.
+Unknown environments are refused against the environments of `profiles.yaml`.
+
+`caseTags(id)` (`@asrunjs/asrun/cases`) turns the front matter into Playwright tags: one `@<suite>` per suite, plus
+`@writes` for a case that writes. The spec passes `{tag: caseTags('<id>')}` to the top-level `test.describe`; it never
+hard-codes tags.
+
+## Sections
+
+### Steps
+
+- Numbered Markdown lines (`1.`, `2.`, ...). The spec wraps each one in `test.step('<n>. <text>', ...)` with the text
+  verbatim, including the number. Do not paraphrase it.
+- A step's tags are the last tokens of its line: `[input]` (a person makes a choice), `[writes]` (it changes data),
+  `[email]` (it sends email). All may appear.
+- `- Ready when:` is a sub-line of the step: the positive signal that what the step loads is there. The spec waits
+  for it before reading; it is not an assertion.
+- `- Recipe (phase):` is a sub-line of an `[input]`/`[writes]` step: what a person did in the browser during an
+  attended exploration (positions, `[asrun]` names, control labels; no selectors). A tagged step with no recipe is a
+  `needs-input` stop for `/gen-spec`.
+- A question block is indented under the sentence it belongs to: 4 spaces under a numbered step, 2 under a bullet.
+  The parent line is the suggestion, written as a finished sentence; the `TODO` line holds one question and optional
+  `(evidence)`; the block ends with `- ✍️ Answer:` at one level deeper and that line is the last line of the block.
+  Details: `.claude/skills/exploring-cases/references/open-questions.md`.
+
+### Expected
+
+A bullet list of behaviour that must hold for every profile. Profile differences are values, not prose.
+
+### Values
+
+One fenced `yaml` block, and nothing else in `## Values`:
+
+```yaml
+default:
+  createButton: Create New
+example-staging:
+  previewLogoAlt: Example
+```
+
+- The top level is a map of profile id (or `default`) to a map of keys. Any other shape, an unknown profile id, or
+  a value that is not a map is an error.
+- `requireValues('<id>', profile)` deep-merges `default` under the profile's own entry.
+- A profile with no entry and no `default` fails with "Missing values ...". An empty value or one that starts with
+  `TODO` fails with "Incomplete values ...". Fill them before running; never make a spec read the YAML itself.
+- Values hold literals only: names, labels, options, test-data names. The checks themselves stay in `## Steps` and
+  `## Expected`, and selectors come from `## Targets`.
+
+### Visual checks
+
+Bullets naming what must match a screenshot baseline. A check on a logo, image, icon, file, PDF, screenshot or
+repeated text needs a `[T<n>]` card.
+
+### Targets
+
+One card per distinct thing a check looks at:
+
+```markdown
+### T1 Header logo
+- What: <the thing itself, and what it is not when a look-alike exists>
+- Where: <region of the page, dialog, tab or file page>
+- Identified by: <role and name, test id, alt text or title; never a position>
+- Not: <look-alikes that must not be matched>
+- Ready when: <what shows that the content has loaded>
+- Reference <profile-id>: .explore/targets/<case-id>/T1-<profile-id>.png
+```
+
+- `What`, `Where` and `Identified by` are required for a card that is not blocking.
+- `Reference <profile-id>:` must point under `.explore/targets/<case-id>/` (git-ignored), or be `none: <reason>`.
+  A missing file on this machine is a warning, not a failure: a fresh checkout has the card but not the screenshot.
+- A card may hold a `🚫 TODO [blocking]` block. Such a card is not complete; `pnpm case:check` does not fail on it,
+  and the check that uses it is not generated yet.
+- Every `[T<n>]` in a step, a ready signal or a check resolves to a card. `pnpm case:check` fails on a reference with
+  no card.
+- The binding rules for choosing a target (never guess, list candidates) are in
+  `.claude/skills/exploring-cases/references/assertion-targets.md`.
+
+### Notes and Source
+
+`## Notes` is free prose for a reviewer. `## Source` holds the original lines of a memo, written by `/make-case`.
+The panel shows both read-only.
+
+## How a spec consumes the case
+
+```ts
+// case: cases/<id>.md
+import {caseTags} from '@asrunjs/asrun/cases';
+import {configureCase, expect, test} from '@asrunjs/asrun/fixtures';
+import {requireValues} from '@asrunjs/asrun/values';
+
+test.describe('<Case title>', {tag: caseTags('<id>')}, () => {
+  configureCase('<id>'); // no retries and a longer timeout for a case that writes data
+  test('<single outcome>', async ({page, profile}) => {
+    const expected = requireValues<{/* keys */}>('<id>', profile);
+
+    await test.step('1. <step text, verbatim>', async () => {
+      // an action that loads content: actAndWait(page, () => click(), {responses, ready})
+      // a confirmation that may appear: clickOptionalUntilHidden(confirm, target, {message})
+      // a download: verifyDownload(page, trigger, {kind})
+    });
+  });
+});
+```
+
+- The first line `// case: cases/<id>.md` is what `pnpm spec:lint` uses to find the case and its targets.
+- `// target: T<n>` goes on the line before an image/screenshot/PDF check. `// ready: <signal>` goes before a check
+  for absence ("missing", "empty", "hidden") and needs a positive wait before it. `// pages: <the case's words>` goes
+  before an `expectPdf` that follows a case limit written in strong words ("only", "exactly", "must").
+- Import `test`/`expect` from `@asrunjs/asrun/fixtures`, never from `@playwright/test`. Locators:
+  `getByTestId` > `getByRole` > `getByLabel` > text.
+- No branching on `profile.id` or `profile.env`: differences go into `## Values`, selectors into `## Targets`.
+- Paths are relative (`page.goto('/account/')`); the Playwright project sets `baseURL`.
+
+## Profiles, values and the write gate
+
+- Each entry in `profiles.yaml` is one Playwright project named after its `id`. A spec runs once per profile.
+- The `profile` fixture exposes `id`, `env`, `baseURL`, `account`, `tags`, `email`.
+- The `caseGate` fixture enforces `envs` and `writes` at run time, also when `playwright test` is called directly:
+  a case limited to some environments is skipped elsewhere; a case that writes elsewhere only is skipped with a
+  notice; a write in a non-staging environment needs the confirmation the CLI sets, never an environment variable
+  that was merely present.
+- Write cases: name everything `[asrun] ...`, register it with `records.track` right after creating it, remove it
+  newest first (also after a failure), turn retries off with `configureCase`, and keep email steps behind
+  `emailStepAllowed(profile, '<step title>')`.
+
+## Checks to run before reporting
+
+| Command | Must |
+|---|---|
+| `pnpm case:check [<id>]` | no `FAIL` |
+| `pnpm typecheck` | no errors |
+| `pnpm spec:lint <id>` | no `FAIL` |
+| `pnpm baselines:review <id>` | every new image is looked at (a person's job) |
+
+## Related references
+
+In the framework package:
+
+- `.claude/skills/exploring-cases/references/assertion-targets.md` — what a check looks at, and when to ask.
+- `.claude/skills/exploring-cases/references/readiness.md` — wait for the content, optional confirmations, downloads.
+- `.claude/skills/exploring-cases/references/open-questions.md` — question blocks and how answers are folded in.
+- `.claude/skills/exploring-cases/references/user-handoff.md` — attended exploration and the handoff card.
+- `.claude/skills/generating-specs/references/conventions.md` — spec shape, assertion layers, readable failures.
+- `docs/cases.md` — the same format for people writing a case by hand.

package/docs/agents/framework-dev.md

@@ -0,0 +1,167 @@
+# Working on AsRun itself
+
+Read `AGENTS.md` first: it is the product baseline, and this file only adds how to change the framework. Nothing here
+is relevant to a project that uses asrun as a dependency.
+
+## Framework layout
+
+`<framework>` for a project is `node_modules/@asrunjs/asrun`. In this repository it is the root folder:
+
+- `lib/`              fixtures (`profile`, session guard, write gate) and helpers; specs import them as
+                      `@asrunjs/asrun/<module>` (for example `@asrunjs/asrun/fixtures`, `@asrunjs/asrun/values`)
+- `scripts/`          the user-facing commands; every command and flag is documented in `docs/commands.md`
+- `templates/`        the files `pnpm asrun init` writes into a workspace
+- `ui/`               local web UI (`pnpm ui`). It may only run the fixed actions in `ui/server/actions.ts`
+                      and must never serve anything under `.auth/`.
+- `docs/`             user documentation (`install.md`, `profiles.md`, `cases.md`, `ai-workflow.md`,
+                      `commands.md`, `web-ui.md`, `troubleshooting.md`) and `docs/theme-guide.html`
+- `docs/agents/`      documents for AI agents: this file, and `case-format.md` (the case document contract)
+- `examples/demo/`    a workspace for developing the framework itself against a local Docker stack (Conduit);
+                      it is committed (`.auth/` and `reports/` never are), see its README
+- `.claude/`          skills + slash commands for Claude Code; the skills are shared with OpenCode
+- `.opencode/commands/` the same commands for OpenCode (it does not read `.claude/commands`)
+- `AGENTS.md`         the product baseline rules (OpenCode reads it); `CLAUDE.md` imports it for Claude Code
+- `README.md`         the user-facing overview: what it does, install, first test, cookbook, links to `docs/`
+
+`package.json` `files` ships `README.md`, `AGENTS.md`, `CLAUDE.md`, `docs/`, `templates/`, `.claude/`, `bin/`,
+`dist/` and `ui/dist/`, so a project can read the same documentation from
+`node_modules/@asrunjs/asrun/docs/`.
+
+## Working on the framework itself
+
+- The framework repository holds no workspace content at the root: no `profiles.yaml`, `cases/`, `tests/` or
+  reports there. The one workspace is `examples/demo`, which is committed because it runs its own local site; its
+  `.auth/`, `reports/` and other run output are not.
+- Develop against the demo:
+
+  ```bash
+  pnpm demo:up                                  # build and start the local stack
+  pnpm demo:seed                                # accounts, articles, follows, favorites
+  pnpm asrun init --root examples/demo          # also writes the framework's .env (ASRUN_ROOT=examples/demo)
+  pnpm build                                    # the demo's specs import the package, which resolves to dist/
+  pnpm asrun --env staging --read-only
+  ```
+
+  `pnpm demo:reset` deletes the database and seeds it again; logins must be redone afterwards. Demo accounts are in
+  `examples/demo/README.md`.
+- Everything the framework reads for a project goes through `ROOT` in `lib/paths.ts` (the workspace root); its own
+  assets (templates, docs, skills, its `node_modules`) go through `FRAMEWORK_ROOT`. Never write into
+  `FRAMEWORK_ROOT` at run time.
+- After changing `lib/`, run `pnpm build` before exercising the demo's specs.
+- `templates/` is the source of the files a workspace gets. When a template changes, bump `version` in
+  `package.json` so `pnpm asrun doctor` in a project shows that it is behind.
+- `init` owns two lists: `GENERATED` (rewritten by `--update`; the commands and the Playwright files) and `ONCE`
+  (written only when missing; `AGENTS.md`, `CLAUDE.md`, the configs). `AGENTS.md`, `CLAUDE.md` and
+  `.claude/skills/**` belong to the project: `init --force` refuses them unless `--reset-rules` is given, so a
+  framework update can never overwrite a project's rules.
+- A project's rules never flow back here. The framework reads a workspace only through `ROOT` at run time; nothing
+  under `templates/` or `.claude/skills/` is generated from a project.
+
+### Installing this repository as a Git dependency (private)
+
+The npm package is the public channel for users. This repository is private, so a Git dependency works only on a
+machine that can clone it:
+
+```bash
+pnpm add -D github:wizcas/asrun#<tag>
+```
+
+pnpm 12 resolves a GitHub spec through the canonical HTTPS URL, not SSH. That machine therefore needs HTTPS
+credentials (a credential helper or a token), or a rewrite to SSH:
+
+```bash
+git config --global url."git@github.com:".insteadOf https://github.com/
+```
+
+On CI, give the runner a `GITHUB_TOKEN`, for example:
+
+```bash
+git config --global \
+  url."https://x-access-token:${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"
+```
+
+or a deploy key with the SSH rewrite above. A Git install also runs the package's `prepare` (it builds `dist/` and
+`ui/dist/`), so it is slower than the registry: use it only to pin a commit, a branch or a tag that is not published
+yet. For a one-off change, `pnpm patch @asrunjs/asrun` and commit the patch instead.
+
+## Documentation
+
+The split is intentional; keep it:
+
+- `README.md` — the user's first page: what AsRun does, requirements, install, the first test, customizing the
+  prompts, the every-day cookbook, safety in short, a documentation index, maintainer notes. It should stay readable
+  in one sitting; a section that grows past a screen belongs in `docs/`.
+- `docs/*.md` — the user reference. `docs/commands.md` is the only place that lists every command and flag.
+- `docs/agents/*.md` — for AI agents. `case-format.md` is the contract of the case document (fixed tokens, values,
+  targets); `AGENTS.md` references it, and the template `AGENTS.md` does too.
+
+When behavior changes, update the matching document in the same change. A command or flag goes into
+`docs/commands.md` and, if it is a daily one, into the README cookbook. A change to the case format goes into
+`docs/agents/case-format.md` and `docs/cases.md` together. Keep the relative links working and the fixed tokens
+spelled exactly as the parser reads them.
+
+## The commands and the two agent CLIs
+
+- Claude Code reads `.claude/commands/*` and `.claude/skills/<name>/SKILL.md`.
+- OpenCode reads `.opencode/commands/*`, `.claude/skills/<name>/SKILL.md`, `.opencode/skills/<name>/SKILL.md` and
+  `.agents/skills/<name>/SKILL.md`. It does **not** read `.claude/commands`, and it does **not** read a flat
+  `.claude/skills/<skill>.md` as a skill (that file is a project override, read by the command and by the skill).
+- `GENERATED` renders the same four command texts into both `.claude/commands/` and `.opencode/commands/`, so edit
+  `templates/.claude/commands/*.md` once. In this repository the eight command files are written by hand: keep
+  `.claude/commands/` and `.opencode/commands/` identical (`diff -r .claude/commands .opencode/commands`).
+- OpenCode discovers skills by walking up from the working directory to the git worktree, so a workspace sees only
+  its own skills, not the framework ones under `node_modules`: the command's `Load the framework skill <path>` is a
+  plain file read. That is why the skill itself must read the project override (`.claude/skills/<skill>.md`).
+
+## Web UI (`ui/web`)
+
+Before adding or changing any UI element, read `docs/theme-guide.html` (open the file; it is static HTML) and follow it.
+Its rules are binding, in particular:
+
+- Icons: Feather via the `react-feather` package only (`import {ChevronDown} from 'react-feather'`). Never draw, paste
+  or hand-write SVGs, and never add another icon library. Size 14 in buttons, 16-20 elsewhere; decorative icons get
+  `aria-hidden="true"`, icon-only buttons get an `aria-label`. Do not use Unicode symbols (`▲ ▼ ◀ ▶ ⤢`) as icons.
+- Colors: only the tokens in `ui/web/src/index.css` (the default Tailwind palette is removed). Pick the color by impact.
+- Buttons and badges: use `buttonClass()` and `Badge` from `ui/web/src/components/status.tsx`, never hand-style them.
+- Dropdowns: use `Select` from the same file, never a bare `<select>` or hand-copied classes (native arrow and height
+  differ). A required dropdown that is empty gets `invalid` (red). See the "Dropdowns" section of the theme guide.
+- A list the user has to search in (a case id, a file name) is `SearchSelect` from
+  `ui/web/src/components/search-select.tsx`: an input with a filtered list below it, which a native `<select>` cannot
+  do. It keeps `Select`'s height, border and focus ring, so the two look like one family; do not build a third variant.
+- If a change adds or alters a token, update `ui/web/src/index.css` and `docs/theme-guide.html` together.
+- The Help page ("How to start") shows screenshots from `ui/web/public/help/`: retake one when the page it shows
+  changes.
+
+Before reaching for a new dependency or writing a helper component, grep `package.json` and `ui/web/src` for what the
+project already uses.
+
+### Copy (`ui/web/src`)
+
+Every lead, label and tooltip is written for the person using the UI, never for the person who built it. Four rules:
+
+- **What → what you do → next.** A page, panel or section explains three things, in that order: what it does, what the
+  user has to do, and what comes next (state it only when something does). A run that needs nothing from the user says so.
+- **Short.** A lead is at most three sentences. A longer explanation becomes labeled paragraphs (`<b>While it runs</b> — …`)
+  or a bullet list, never one dense block. A tooltip is `# Title`, then at most three lines of one sentence each: it
+  wraps inside 320px (`ui/web/src/lib/tooltip.ts`).
+- **No implementation in the copy.** File paths, directory names, CLI flags, skill or command names, and the agent's
+  internal syntax (`TODO`, `Answer:`, `RESULT: needs-input`, `- Recipe:`) never appear in a lead, a label or a tooltip.
+  They belong where the file, the command or the syntax is the object itself: the Spec view, the Jobs drawer, a
+  `CopyBlock`, or a folded `<details>` block titled "For the command line".
+- **Say what the user sees.** "The run appears in the Jobs bar", not "the command runs in a one-shot session"; "the
+  browser shows a small card", not "the agent pauses on a `writes` step".
+
+## Before you open a pull request
+
+```bash
+pnpm typecheck
+pnpm build          # dist/ must match lib/ and scripts/
+pnpm case:check     # examples/demo cases
+pnpm spec:lint      # examples/demo specs
+pnpm ui:build       # ui/dist/ must match ui/web and ui/server
+```
+
+- `pnpm build` and `pnpm ui:build` also run from `prepare` and `prepack`, so a published package is complete.
+- Bump `version` when `templates/` or the shipped docs change; `pnpm asrun doctor` in a project compares it.
+- Keep the demo's committed expectations (`profiles.yaml`, `cases/`, `tests/`, baselines) in step with the demo site.
+  Baselines are a person's decision: never let an agent regenerate them.