cueline 0.1.0

package/dist/src/state/paths.d.ts

@@ -0,0 +1,9 @@
+export interface RunPaths {
+    home: string;
+    runsDir: string;
+    runDir: string;
+    events: string;
+    snapshot: string;
+}
+export declare function defaultCueLineHome(environment?: NodeJS.ProcessEnv): string;
+export declare function runPaths(home: string, runId: string): RunPaths;

package/dist/src/state/paths.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { homedir } from "node:os";
+import { runtimeEnvironment } from "../core/runtime.js";
+const RUN_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export function defaultCueLineHome(environment = runtimeEnvironment()) {
+    const configured = environment.CUELINE_HOME;
+    const userHome = environment.HOME ?? homedir();
+    if (!configured || configured.trim() === "") {
+        return path.resolve(userHome, ".cueline");
+    }
+    if (configured === "~") {
+        return path.resolve(userHome);
+    }
+    if (/^~[/\\]/.test(configured)) {
+        return path.resolve(userHome, configured.slice(2));
+    }
+    return path.resolve(configured);
+}
+export function runPaths(home, runId) {
+    if (!RUN_ID_PATTERN.test(runId)) {
+        throw new Error(`RUN_ID_INVALID: '${runId}'`);
+    }
+    const resolvedHome = path.resolve(home);
+    const runsDir = path.join(resolvedHome, "runs");
+    const runDir = path.join(runsDir, runId);
+    if (!runDir.startsWith(runsDir + path.sep)) {
+        throw new Error(`RUN_ID_INVALID: '${runId}'`);
+    }
+    return {
+        home: resolvedHome,
+        runsDir,
+        runDir,
+        events: path.join(runDir, "events.jsonl"),
+        snapshot: path.join(runDir, "snapshot.json"),
+    };
+}
+//# sourceMappingURL=paths.js.map

package/dist/src/state/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/state/paths.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,cAAc,GAAG,oCAAoC,CAAC;AAU5D,MAAM,UAAU,kBAAkB,CAAC,WAAW,GAAsB,kBAAkB,EAAE;IACtF,MAAM,UAAU,GAAG,WAAW,CAAC,YAAY,CAAC;IAC5C,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,IAAI,OAAO,EAAE,CAAC;IAC/C,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC5C,CAAC;IACD,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IACD,IAAI,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,KAAa;IAClD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,GAAG,CAAC,CAAC;IAChD,CAAC;IACD,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACzC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,GAAG,CAAC,CAAC;IAChD,CAAC;IACD,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,OAAO;QACP,MAAM;QACN,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC;QACzC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC;KAC7C,CAAC;AACJ,CAAC"}

package/dist/src/state/store.d.ts

@@ -0,0 +1,23 @@
+import { type RunEvent } from "./event-log.js";
+import { type RunPaths } from "./paths.js";
+export type RunReducer<State> = (state: State, event: RunEvent) => State;
+export interface RunStoreOptions<State> {
+    home: string;
+    runId: string;
+    initialState: State;
+    reducer: RunReducer<State>;
+    now?: () => Date;
+}
+export declare class RunStore<State> {
+    #private;
+    readonly paths: RunPaths;
+    readonly runId: string;
+    private constructor();
+    static create<State>(options: RunStoreOptions<State>): Promise<RunStore<State>>;
+    static load<State>(options: RunStoreOptions<State>): Promise<RunStore<State>>;
+    get state(): State;
+    get lastSequence(): number;
+    append(type: string, payload: unknown): Promise<RunEvent>;
+    snapshot(): Promise<void>;
+    replay(): Promise<State>;
+}

package/dist/src/state/store.js

@@ -0,0 +1,108 @@
+import { mkdir, readFile } from "node:fs/promises";
+import { atomicWriteJson } from "./atomic-write.js";
+import { appendEvent, readEvents } from "./event-log.js";
+import { runPaths } from "./paths.js";
+const STATE_PROTOCOL = "cueline/state/0.1";
+function clone(value) {
+    return structuredClone(value);
+}
+function parseSnapshot(contents, runId) {
+    const parsed = JSON.parse(contents);
+    if (parsed.protocol !== STATE_PROTOCOL ||
+        parsed.run_id !== runId ||
+        !Number.isSafeInteger(parsed.last_sequence) ||
+        parsed.last_sequence < 0 ||
+        parsed.state === undefined) {
+        throw new Error("STATE_SNAPSHOT_INVALID");
+    }
+    return parsed;
+}
+export class RunStore {
+    paths;
+    runId;
+    #initialState;
+    #reducer;
+    #now;
+    #state;
+    #lastSequence;
+    constructor(options, state, lastSequence) {
+        this.runId = options.runId;
+        this.paths = runPaths(options.home, options.runId);
+        this.#initialState = clone(options.initialState);
+        this.#reducer = options.reducer;
+        this.#now = options.now ?? (() => new Date());
+        this.#state = clone(state);
+        this.#lastSequence = lastSequence;
+    }
+    static async create(options) {
+        const paths = runPaths(options.home, options.runId);
+        await mkdir(paths.runDir, { recursive: true });
+        const existing = await readEvents(paths.events);
+        if (existing.length > 0) {
+            throw new Error(`RUN_ALREADY_EXISTS: '${options.runId}'`);
+        }
+        return new RunStore(options, options.initialState, 0);
+    }
+    static async load(options) {
+        const paths = runPaths(options.home, options.runId);
+        const events = await readEvents(paths.events);
+        let state = clone(options.initialState);
+        let lastSequence = 0;
+        try {
+            const snapshot = parseSnapshot(await readFile(paths.snapshot, "utf8"), options.runId);
+            if (snapshot.last_sequence <= events.length) {
+                state = clone(snapshot.state);
+                lastSequence = snapshot.last_sequence;
+            }
+        }
+        catch {
+            state = clone(options.initialState);
+            lastSequence = 0;
+        }
+        for (const event of events) {
+            if (event.sequence > lastSequence) {
+                state = options.reducer(state, event);
+                lastSequence = event.sequence;
+            }
+        }
+        return new RunStore(options, state, lastSequence);
+    }
+    get state() {
+        return clone(this.#state);
+    }
+    get lastSequence() {
+        return this.#lastSequence;
+    }
+    async append(type, payload) {
+        if (type.trim() === "") {
+            throw new Error("EVENT_TYPE_INVALID");
+        }
+        const event = {
+            sequence: this.#lastSequence + 1,
+            timestamp: this.#now().toISOString(),
+            type,
+            payload,
+        };
+        await appendEvent(this.paths.events, event);
+        this.#state = this.#reducer(this.#state, event);
+        this.#lastSequence = event.sequence;
+        return event;
+    }
+    async snapshot() {
+        const snapshot = {
+            protocol: STATE_PROTOCOL,
+            run_id: this.runId,
+            last_sequence: this.#lastSequence,
+            state: this.#state,
+        };
+        await atomicWriteJson(this.paths.snapshot, snapshot);
+    }
+    async replay() {
+        let state = clone(this.#initialState);
+        for (const event of await readEvents(this.paths.events)) {
+            state = this.#reducer(state, event);
+        }
+        return state;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/src/state/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/state/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAiB,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAiB,MAAM,YAAY,CAAC;AAErD,MAAM,cAAc,GAAG,mBAAmB,CAAC;AAmB3C,SAAS,KAAK,CAAQ,KAAY;IAChC,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,aAAa,CAAQ,QAAgB,EAAE,KAAa;IAC3D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAmC,CAAC;IACtE,IACE,MAAM,CAAC,QAAQ,KAAK,cAAc;QAClC,MAAM,CAAC,MAAM,KAAK,KAAK;QACvB,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,aAAa,CAAC;QAC1C,MAAM,CAAC,aAAwB,GAAG,CAAC;QACpC,MAAM,CAAC,KAAK,KAAK,SAAS,EAC1B,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,MAA+B,CAAC;AACzC,CAAC;AAED,MAAM,OAAO,QAAQ;IACV,KAAK,CAAW;IAChB,KAAK,CAAS;IACd,aAAa,CAAQ;IACrB,QAAQ,CAAoB;IAC5B,IAAI,CAAa;IAC1B,MAAM,CAAQ;IACd,aAAa,CAAS;IAEtB,YACE,OAA+B,EAC/B,KAAY,EACZ,YAAoB;QAEpB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACnD,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QACjD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;QAC9C,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,CAAC,aAAa,GAAG,YAAY,CAAC;IACpC,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,MAAM,CAAQ,OAA+B;QACxD,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACpD,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/C,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAChD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,wBAAwB,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC;QAC5D,CAAC;QACD,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,IAAI,CAAQ,OAA+B;QACtD,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACpD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC9C,IAAI,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QACxC,IAAI,YAAY,GAAG,CAAC,CAAC;QAErB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,aAAa,CAAQ,MAAM,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;YAC7F,IAAI,QAAQ,CAAC,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAC5C,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAC9B,YAAY,GAAG,QAAQ,CAAC,aAAa,CAAC;YACxC,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;YACpC,YAAY,GAAG,CAAC,CAAC;QACnB,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,KAAK,CAAC,QAAQ,GAAG,YAAY,EAAE,CAAC;gBAClC,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;gBACtC,YAAY,GAAG,KAAK,CAAC,QAAQ,CAAC;YAChC,CAAC;QACH,CAAC;QACD,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;IACpD,CAAC;IAED,IAAI,KAAK;QACP,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAED,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,OAAgB;QACzC,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;QACxC,CAAC;QACD,MAAM,KAAK,GAAa;YACtB,QAAQ,EAAE,IAAI,CAAC,aAAa,GAAG,CAAC;YAChC,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE;YACpC,IAAI;YACJ,OAAO;SACR,CAAC;QACF,MAAM,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAChD,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC,QAAQ,CAAC;QACpC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,MAAM,QAAQ,GAA0B;YACtC,QAAQ,EAAE,cAAc;YACxB,MAAM,EAAE,IAAI,CAAC,KAAK;YAClB,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,KAAK,EAAE,IAAI,CAAC,MAAM;SACnB,CAAC;QACF,MAAM,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACvD,CAAC;IAED,KAAK,CAAC,MAAM;QACV,IAAI,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QACtC,KAAK,MAAM,KAAK,IAAI,MAAM,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;YACxD,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/src/version.d.ts

@@ -0,0 +1 @@
+export declare const CUELINE_VERSION = "0.1.0";

package/dist/src/version.js

@@ -0,0 +1,2 @@
+export const CUELINE_VERSION = "0.1.0";
+//# sourceMappingURL=version.js.map

package/dist/src/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC"}

package/docs/architecture.md

@@ -0,0 +1,83 @@
+# Architecture
+
+## System boundary
+
+CueLine splits decision authority from local execution:
+
+```text
+ChatGPT web conversation (controller)
+              ^  |
+   observation|  |<CueLineControl>
+              |  v
+Codex + CueLine (intermediary and policy enforcement)
+              |
+              v
+registered local workers and filesystem state
+```
+
+The ChatGPT web page is the top-level controller. It decides whether the run should dispatch work, wait, inspect evidence, complete, or stop as blocked. It has no direct local tools or filesystem access. Codex supplies the built-in in-app Browser (IAB); CueLine converts persisted local evidence into controller observations and converts a validated controller command into a local action.
+
+CueLine is standalone. Its runtime does not import Omnilane or GPT Relay, and it does not read either project's state or configuration.
+
+## Components
+
+### Browser adapter
+
+`src/browser/codex-iab/` implements a text-only adapter over Codex's IAB client. It claims an existing ChatGPT tab when possible, otherwise opens the requested ChatGPT URL. It fills the composer, sends one turn, waits for a stable completed assistant message, and records the resulting conversation URL.
+
+The adapter can receive an injected browser or resolve `globalThis.iab` / `agent.browsers.get("iab")` from Codex's runtime. Plain Node does not provide these globals.
+
+### Controller protocol
+
+`src/protocol/` extracts the last complete `<CueLineControl>` envelope and validates it against the exact pending `run_id`, `round`, and `request_id`. Invalid output is returned to the same controller for a bounded repair attempt. This rejects stale replies and unrelated JSON from earlier parts of a conversation.
+
+### Controller loop
+
+`src/core/controller-loop.ts` owns the run:
+
+1. Persist the intended controller turn.
+2. Send an observation through the browser adapter.
+3. Persist the assistant response.
+4. Validate and persist the accepted command.
+5. Execute the command through the local supervisor.
+6. Snapshot the derived state.
+7. Repeat until `complete`, `blocked`, or the round limit is reached.
+
+The default limits are 12 controller rounds and two repair attempts per pending command.
+
+### Routing and runners
+
+`src/router/` chooses an enabled, available candidate before any process starts. `src/runners/` requires an explicitly registered `argv[0]`, uses `spawn` with `shell: false`, and never performs post-spawn fallback. `src/jobs/` coordinates foreground/background execution and persists job status.
+
+### Durable state
+
+`src/state/` writes a per-run JSONL event log and an atomic materialized snapshot. The event log is authoritative; a snapshot is a replay optimization. Job status files are atomically replaced.
+
+## Authority and trust
+
+The controller can request local work, but a request is not equivalent to process access. CueLine applies these gates:
+
+- exact run/round/request identity
+- structurally valid command and unique `job_key`
+- configured lane and pre-spawn candidate availability
+- config-derived registered executable allow-list
+- no shell interpolation
+- deterministic job identity and duplicate-dispatch suppression
+- no nested CueLine routing (`CUELINE_DEPTH`)
+- no retry after a worker has started
+
+These gates reduce accidental execution ambiguity; they do not make an allowed worker harmless. The local Codex/operator environment remains responsible for filesystem, network, credential, and side-effect permissions granted to each registered executable.
+
+## Data flow
+
+1. The original user request becomes part of every controller observation.
+2. Job outputs and errors are stored locally and included in later observations (individual fields are bounded before browser submission).
+3. ChatGPT returns a command; only the control envelope is machine-executed.
+4. On `complete`, CueLine returns `final_delivery_text` to Codex.
+5. On `blocked`, CueLine preserves the controller's reason and optional delivery text.
+
+CueLine does not intentionally inspect or export cookies, tokens, environment secrets, or browser session material. The IAB uses the user's already authenticated page.
+
+## Dependency model
+
+The published JavaScript has zero runtime npm dependencies and uses Node built-ins. TypeScript and Node type definitions are development dependencies only. Live ChatGPT orchestration additionally depends on Codex's IAB runtime and ChatGPT's current web UI; the bundled default local route also expects the `codex` CLI on `PATH`. The core state, protocol, router, and fake tests run in plain Node.

package/docs/assets/README.md

@@ -0,0 +1,51 @@
+# Brand assets
+
+Original CueLine artwork. Plain SVG, no external fonts, no embedded raster images, no third-party material.
+
+| File | Use |
+|---|---|
+| `cueline-mark-{light,dark}.svg` | Square mark, 48×48 grid. Readable down to 16 px. |
+| `cueline-wordmark-{light,dark}.svg` | Wordmark alone, for headers and docs. |
+| `cueline-banner-{light,dark}.svg` | README banner, 1280×320. |
+| `cueline-loop-{en,zh-TW,zh-CN,ja,ko}.svg` | The run figure, 1000×590, one per README language. |
+
+The mark, wordmark, and banner ship as a light/dark pair; pick one with a `<picture>` block so GitHub serves the right file:
+
+```html
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/cueline-banner-dark.svg">
+  <img alt="CueLine" src="docs/assets/cueline-banner-light.svg">
+</picture>
+```
+
+The run figure is a single file per language instead: it carries its own `@media (prefers-color-scheme: dark)` block and a transparent ground, so one `<img>` serves both themes and sits directly on the reader's canvas.
+
+## The mark
+
+A stage manager marks a cue in the margin of the promptbook: a vertical rule down the page, a caret at the exact line where the cue lands. That is the whole product in one drawing — the controller calls the cue, the line it points at is the work, and everything around it stays quiet.
+
+The vertical rule is the control loop. The caret is the accepted command. Three horizontal lines are the run; only the cued one is at full weight.
+
+## The run figure
+
+The figure is not a flowchart. It is the promptbook itself: two columns with the cue line down the middle, the controller speaking on the left, the machine working on the right, and one round per group of lines. Commands enter the line as a cue caret; observations leave it. Everything is monospaced, because the whole exchange is a printed log.
+
+## Geometry
+
+Everything sits on a 48-unit grid with a 3-unit stroke and butt caps. The wordmark is monoline geometric — drawn as paths, so it renders identically without a font. Cap height 32, stroke 3, uniform 10-unit letter gaps. Do not re-set the wordmark in a system font.
+
+## Palette
+
+| Role | Light | Dark |
+|---|---|---|
+| Ink | `#0F1720` | `#E6EDF3` |
+| Muted | `#5B6672` | `#8B949E` |
+| Rule | `#D5DBE2` | `#262C34` |
+| Ground | `#FBFBFC` | `#0D1117` |
+| Cue | `#C8553D` | `#E0674C` |
+
+The cue colour is the only accent, and it is only ever applied to the caret and the single cue tick. It is a tally-light red held back to a print vermilion. If a second accent is ever needed, the answer is no.
+
+## Not this
+
+Gradients, glow, glass, neon, circuitry, brains, robots, isometric clouds, decorative emoji. CueLine is a control surface, not a launch page.

package/docs/assets/cueline-banner-dark.svg

@@ -0,0 +1,41 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 320" width="1280" height="320" role="img" aria-label="CueLine — ChatGPT directs. Your machine executes.">
+  <title>CueLine — ChatGPT directs. Your machine executes.</title>
+  <rect width="1280" height="320" fill="#0D1117"/>
+
+  <g transform="translate(96 92) scale(1.5)">
+    <g fill="none" stroke-linecap="butt">
+      <path d="M12 8V40" stroke="#E6EDF3" stroke-width="3"/>
+      <path d="M26 15H40" stroke="#8B949E" stroke-width="3"/>
+      <path d="M26 24H40" stroke="#E6EDF3" stroke-width="3"/>
+      <path d="M26 33H40" stroke="#8B949E" stroke-width="3"/>
+    </g>
+    <path d="M14 18.5 23 24l-9 5.5z" fill="#E0674C"/>
+  </g>
+
+  <g transform="translate(200 110) scale(0.75)">
+    <g fill="none" stroke="#E6EDF3" stroke-width="3" stroke-linecap="butt" stroke-linejoin="miter">
+      <path d="M21.81 14.68A11.5 14.5 0 1 0 21.81 33.32"/>
+      <path d="M31.5 8V24A11.5 14.5 0 0 0 54.5 24V8"/>
+      <path d="M64.5 8V40"/>
+      <path d="M63 9.5H83"/>
+      <path d="M63 24H79"/>
+      <path d="M63 38.5H83"/>
+      <path d="M93.5 8V38.5"/>
+      <path d="M92 38.5H112"/>
+      <path d="M120.5 8V40"/>
+      <path d="M132.5 40V8L155.5 40V8"/>
+      <path d="M167.5 8V40"/>
+      <path d="M166 9.5H186"/>
+      <path d="M166 24H182"/>
+      <path d="M166 38.5H186"/>
+    </g>
+  </g>
+
+  <text x="96" y="214" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="19" fill="#8B949E" textLength="434" lengthAdjust="spacingAndGlyphs">ChatGPT directs. Your machine executes.</text>
+
+  <g stroke="#262C34" stroke-width="1">
+    <path d="M96 252.5H1184"/>
+    <path d="M96 253v6M160 253v6M224 253v6M288 253v6M416 253v6M480 253v6M544 253v6M608 253v6M672 253v6M736 253v6M800 253v6M864 253v6M928 253v6M992 253v6M1056 253v6M1120 253v6M1184 253v6"/>
+  </g>
+  <path d="M352 253v13" stroke="#E0674C" stroke-width="2"/>
+</svg>

package/docs/assets/cueline-banner-light.svg

@@ -0,0 +1,41 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 320" width="1280" height="320" role="img" aria-label="CueLine — ChatGPT directs. Your machine executes.">
+  <title>CueLine — ChatGPT directs. Your machine executes.</title>
+  <rect width="1280" height="320" fill="#FFFFFF"/>
+
+  <g transform="translate(96 92) scale(1.5)">
+    <g fill="none" stroke-linecap="butt">
+      <path d="M12 8V40" stroke="#0F1720" stroke-width="3"/>
+      <path d="M26 15H40" stroke="#5B6672" stroke-width="3"/>
+      <path d="M26 24H40" stroke="#0F1720" stroke-width="3"/>
+      <path d="M26 33H40" stroke="#5B6672" stroke-width="3"/>
+    </g>
+    <path d="M14 18.5 23 24l-9 5.5z" fill="#C8553D"/>
+  </g>
+
+  <g transform="translate(200 110) scale(0.75)">
+    <g fill="none" stroke="#0F1720" stroke-width="3" stroke-linecap="butt" stroke-linejoin="miter">
+      <path d="M21.81 14.68A11.5 14.5 0 1 0 21.81 33.32"/>
+      <path d="M31.5 8V24A11.5 14.5 0 0 0 54.5 24V8"/>
+      <path d="M64.5 8V40"/>
+      <path d="M63 9.5H83"/>
+      <path d="M63 24H79"/>
+      <path d="M63 38.5H83"/>
+      <path d="M93.5 8V38.5"/>
+      <path d="M92 38.5H112"/>
+      <path d="M120.5 8V40"/>
+      <path d="M132.5 40V8L155.5 40V8"/>
+      <path d="M167.5 8V40"/>
+      <path d="M166 9.5H186"/>
+      <path d="M166 24H182"/>
+      <path d="M166 38.5H186"/>
+    </g>
+  </g>
+
+  <text x="96" y="214" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="19" fill="#5B6672" textLength="434" lengthAdjust="spacingAndGlyphs">ChatGPT directs. Your machine executes.</text>
+
+  <g stroke="#D5DBE2" stroke-width="1">
+    <path d="M96 252.5H1184"/>
+    <path d="M96 253v6M160 253v6M224 253v6M288 253v6M416 253v6M480 253v6M544 253v6M608 253v6M672 253v6M736 253v6M800 253v6M864 253v6M928 253v6M992 253v6M1056 253v6M1120 253v6M1184 253v6"/>
+  </g>
+  <path d="M352 253v13" stroke="#C8553D" stroke-width="2"/>
+</svg>

package/docs/assets/cueline-loop-en.svg

@@ -0,0 +1,77 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 590" width="1000" height="590" role="img" aria-label="A CueLine run read as a promptbook: the machine reports an observation, the controller calls one command, the registered runner executes it, until the controller calls complete.">
+  <title>A CueLine run, read as a promptbook</title>
+  <style>
+    text { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace }
+    .hd   { fill: #0F1720; font-size: 17px; letter-spacing: .02em }
+    .sub  { fill: #8B949E; font-size: 13.5px }
+    .rule { stroke: #E4E8EC; stroke-width: 1 }
+    .spine{ stroke: #0F1720; stroke-width: 2 }
+    .tick { stroke: #C3CAD2; stroke-width: 1 }
+    .say  { fill: #C8553D; font-size: 15px }
+    .obs  { fill: #4A5561; font-size: 15px }
+    .note { fill: #8B949E; font-size: 13.5px }
+    .rnd  { fill: #B6BEC7; font-size: 12px; letter-spacing: .14em }
+    .foot { fill: #8B949E; font-size: 13.5px }
+    .cue  { fill: #C8553D }
+    @media (prefers-color-scheme: dark) {
+      .hd { fill: #E6EDF3 }
+      .sub, .note, .foot { fill: #7D8590 }
+      .rule { stroke: #21262D }
+      .spine { stroke: #C9D1D9 }
+      .tick { stroke: #30363D }
+      .say { fill: #E0674C }
+      .obs { fill: #ADBAC7 }
+      .rnd { fill: #484F58 }
+      .cue { fill: #E0674C }
+    }
+  </style>
+
+  <text x="505" y="44" class="hd" text-anchor="end">ChatGPT web conversation</text>
+  <text x="505" y="64" class="sub" text-anchor="end">the controller — plans, calls, judges</text>
+  <text x="555" y="44" class="hd">your machine</text>
+  <text x="555" y="64" class="sub">CueLine — validates, routes, executes, records</text>
+
+  <path d="M40 84H505" class="rule"/>
+  <path d="M555 84H960" class="rule"/>
+  <path d="M530 84V520" class="spine"/>
+
+  <text x="40" y="126" class="rnd">ROUND 1</text>
+  <path d="M505 122H524" class="tick"/>
+  <text x="555" y="126" class="obs">observation · your request, no jobs yet</text>
+  <path d="M524 118 517 122 524 126z" class="cue"/>
+
+  <path d="M536 158 545 162 536 166z" class="cue"/>
+  <text x="505" y="166" class="say" text-anchor="end">dispatch · review · lane default · advise</text>
+  <path d="M545 162H565" class="tick"/>
+  <text x="575" y="166" class="note">routed before anything starts</text>
+
+  <text x="555" y="200" class="note">codex exec (read-only) → succeeded</text>
+
+  <text x="40" y="264" class="rnd">ROUND 2</text>
+  <path d="M505 260H524" class="tick"/>
+  <text x="555" y="264" class="obs">observation · the evidence, verbatim</text>
+  <path d="M524 256 517 260 524 264z" class="cue"/>
+
+  <path d="M536 296 545 300 536 304z" class="cue"/>
+  <text x="505" y="304" class="say" text-anchor="end">dispatch · patch · mode work</text>
+  <path d="M545 300H565" class="tick"/>
+  <text x="575" y="304" class="note">argv[0] must already be allowed</text>
+
+  <text x="555" y="338" class="note">codex exec (workspace-write) → succeeded</text>
+
+  <text x="40" y="402" class="rnd">ROUND 3</text>
+  <path d="M505 398H524" class="tick"/>
+  <text x="555" y="402" class="obs">observation · updated evidence</text>
+  <path d="M524 394 517 398 524 402z" class="cue"/>
+
+  <path d="M536 434 545 438 536 442z" class="cue"/>
+  <text x="505" y="442" class="say" text-anchor="end">complete · final_delivery_text</text>
+  <path d="M545 438H565" class="tick"/>
+  <text x="575" y="442" class="note">returned to you, verbatim</text>
+
+  <text x="555" y="476" class="note">run sealed · events.jsonl is the record</text>
+
+  <path d="M40 520H960" class="rule"/>
+  <text x="40" y="546" class="foot">Five actions only — dispatch · wait · inspect · complete · blocked.</text>
+  <text x="40" y="568" class="foot">Nothing outside the envelope is executed. No worker is retried once it has started.</text>
+</svg>

package/docs/assets/cueline-loop-ja.svg

@@ -0,0 +1,77 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 590" width="1000" height="590" role="img" aria-label="CueLine の 1 回の実行をプロンプトブックとして読む：マシンが観測を送り、コントローラーがコマンドを 1 つ出し、登録済みの runner が実行し、complete が出るまで続く。">
+  <title>CueLine の実行を、プロンプトブックとして読む</title>
+  <style>
+    text { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, "Hiragino Sans", "Noto Sans CJK JP", "Yu Gothic", monospace }
+    .hd   { fill: #0F1720; font-size: 17px; letter-spacing: .02em }
+    .sub  { fill: #8B949E; font-size: 13.5px }
+    .rule { stroke: #E4E8EC; stroke-width: 1 }
+    .spine{ stroke: #0F1720; stroke-width: 2 }
+    .tick { stroke: #C3CAD2; stroke-width: 1 }
+    .say  { fill: #C8553D; font-size: 15px }
+    .obs  { fill: #4A5561; font-size: 15px }
+    .note { fill: #8B949E; font-size: 13.5px }
+    .rnd  { fill: #B6BEC7; font-size: 12px; letter-spacing: .14em }
+    .foot { fill: #8B949E; font-size: 13.5px }
+    .cue  { fill: #C8553D }
+    @media (prefers-color-scheme: dark) {
+      .hd { fill: #E6EDF3 }
+      .sub, .note, .foot { fill: #7D8590 }
+      .rule { stroke: #21262D }
+      .spine { stroke: #C9D1D9 }
+      .tick { stroke: #30363D }
+      .say { fill: #E0674C }
+      .obs { fill: #ADBAC7 }
+      .rnd { fill: #484F58 }
+      .cue { fill: #E0674C }
+    }
+  </style>
+
+  <text x="505" y="44" class="hd" text-anchor="end">ChatGPT ウェブ会話</text>
+  <text x="505" y="64" class="sub" text-anchor="end">コントローラー — 計画し、指示し、判断する</text>
+  <text x="555" y="44" class="hd">あなたのマシン</text>
+  <text x="555" y="64" class="sub">CueLine — 検証・ルーティング・実行・記録</text>
+
+  <path d="M40 84H505" class="rule"/>
+  <path d="M555 84H960" class="rule"/>
+  <path d="M530 84V520" class="spine"/>
+
+  <text x="40" y="126" class="rnd">ラウンド 1</text>
+  <path d="M505 122H524" class="tick"/>
+  <text x="555" y="126" class="obs">observation · あなたの依頼、ジョブはまだない</text>
+  <path d="M524 118 517 122 524 126z" class="cue"/>
+
+  <path d="M536 158 545 162 536 166z" class="cue"/>
+  <text x="505" y="166" class="say" text-anchor="end">dispatch · review · lane default · advise</text>
+  <path d="M545 162H565" class="tick"/>
+  <text x="575" y="166" class="note">プロセス起動の前にルートが決まる</text>
+
+  <text x="555" y="200" class="note">codex exec（読み取り専用）→ 成功 · 出力を保存</text>
+
+  <text x="40" y="264" class="rnd">ラウンド 2</text>
+  <path d="M505 260H524" class="tick"/>
+  <text x="555" y="264" class="obs">observation · 証拠をそのまま</text>
+  <path d="M524 256 517 260 524 264z" class="cue"/>
+
+  <path d="M536 296 545 300 536 304z" class="cue"/>
+  <text x="505" y="304" class="say" text-anchor="end">dispatch · patch · mode work</text>
+  <path d="M545 300H565" class="tick"/>
+  <text x="575" y="304" class="note">argv[0] は事前の許可が必要</text>
+
+  <text x="555" y="338" class="note">codex exec（workspace-write）→ 成功</text>
+
+  <text x="40" y="402" class="rnd">ラウンド 3</text>
+  <path d="M505 398H524" class="tick"/>
+  <text x="555" y="402" class="obs">observation · 更新された証拠</text>
+  <path d="M524 394 517 398 524 402z" class="cue"/>
+
+  <path d="M536 434 545 438 536 442z" class="cue"/>
+  <text x="505" y="442" class="say" text-anchor="end">complete · final_delivery_text</text>
+  <path d="M545 438H565" class="tick"/>
+  <text x="575" y="442" class="note">そのままあなたに返す</text>
+
+  <text x="555" y="476" class="note">ラン確定 · events.jsonl が記録そのもの</text>
+
+  <path d="M40 520H960" class="rule"/>
+  <text x="40" y="546" class="foot">アクションは 5 つだけ — dispatch · wait · inspect · complete · blocked。</text>
+  <text x="40" y="568" class="foot">エンベロープの外は実行されない。起動後のワーカーは再試行しない。</text>
+</svg>