morphisms 0.1.0-beta.3 → 0.1.0-beta.4

package/lib/cli.js

@@ -2,9 +2,10 @@ const pkg = require('../package.json');
 const { initCommand } = require('./init');
 const { updateCommand } = require('./update');
 const { workbenchCommand } = require('./workbench');
+const { onboardingCommand } = require('./onboarding');
 
 function help() {
-  console.log(`Morphisms ${pkg.version}\n\nUsage:\n  morphisms init\n  morphisms workbench [--port N]\n  morphisms update\n  morphisms --version`);
+  console.log(`Morphisms ${pkg.version}\n\nUsage:\n  morphisms init\n  morphisms workbench [--port N]\n  morphisms onboarding [--thread CHANNEL] [--json]\n  morphisms update\n  morphisms --version`);
 }
 
 async function main(argv) {
@@ -20,6 +21,7 @@ async function main(argv) {
   if (command === 'init') return initCommand(rest);
   if (command === 'update') return updateCommand(rest);
   if (command === 'workbench') return workbenchCommand(rest);
+  if (command === 'onboarding') return onboardingCommand(rest);
   console.error(`unknown morphisms command: ${command}`);
   help();
   return 1;

package/lib/onboarding.js

@@ -0,0 +1,113 @@
+const { spawn } = require('node:child_process');
+const { buildWorkbenchArgv, configuredPort } = require('./workbench');
+const {
+  DEFAULT_POLL_INTERVAL_MS,
+  DEFAULT_POLL_TIMEOUT_MS,
+  DEFAULT_PROBE_TIMEOUT_MS,
+  occupiedPortReason,
+  probeVersion,
+  waitForWorkbench,
+  watchChildProcess,
+} = require('./workbench-health');
+
+function parseOnboardingArgs(argv) {
+  let thread;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') {
+      json = true;
+    } else if (arg === '--thread') {
+      thread = argv[++i];
+      if (!thread) throw new Error('--thread requires a value');
+    } else if (arg.startsWith('--thread=')) {
+      thread = arg.slice('--thread='.length);
+      if (!thread) throw new Error('--thread requires a value');
+    } else {
+      throw new Error(`unknown onboarding argument: ${arg}`);
+    }
+  }
+  return { thread, json };
+}
+
+function buildOnboardingUrl(port, thread) {
+  const base = `http://localhost:${port}/#workbench?onboarding=1`;
+  if (!thread) return base;
+  return `${base}&thread=${encodeURIComponent(thread)}`;
+}
+
+function startDetachedWorkbench(repoRoot, port) {
+  const workspaceRegistry = process.env.MORPHISMS_WORKBENCH_REGISTRY || undefined;
+  const child = spawn('mor-workbench', buildWorkbenchArgv(repoRoot, { port, workspaceRegistry }), {
+    detached: true,
+    stdio: 'ignore',
+  });
+  const childState = watchChildProcess(child);
+  child.unref();
+  return childState;
+}
+
+async function onboardingCommand(argv, options = {}) {
+  const stdout = options.stdout || process.stdout;
+  const stderr = options.stderr || process.stderr;
+  let parsed;
+  try {
+    parsed = parseOnboardingArgs(argv);
+  } catch (error) {
+    return reportFailure(error.message, argv.includes('--json'), stdout, stderr);
+  }
+
+  const repoRoot = options.cwd || process.cwd();
+  const port = configuredPort(repoRoot);
+  const initialProbe = await probeVersion(port, { timeoutMs: options.probeTimeoutMs || DEFAULT_PROBE_TIMEOUT_MS });
+  let started = false;
+  let healthy = initialProbe;
+  let spawnState;
+
+  if (!initialProbe.ok) {
+    if (initialProbe.kind === 'occupied') {
+      return reportFailure(occupiedPortReason(port, initialProbe.reason), parsed.json, stdout, stderr);
+    }
+    started = true;
+    try {
+      const starter = options.startWorkbench || startDetachedWorkbench;
+      spawnState = starter(repoRoot, port);
+    } catch (error) {
+      return reportFailure(`failed to run mor-workbench: ${error.message}`, parsed.json, stdout, stderr);
+    }
+    healthy = await waitForWorkbench(port, {
+      pollTimeoutMs: options.pollTimeoutMs || DEFAULT_POLL_TIMEOUT_MS,
+      pollIntervalMs: options.pollIntervalMs || DEFAULT_POLL_INTERVAL_MS,
+      probeTimeoutMs: options.probeTimeoutMs || DEFAULT_PROBE_TIMEOUT_MS,
+      spawnState,
+    });
+  }
+
+  if (!healthy.ok) {
+    return reportFailure(healthy.reason || 'workbench is not healthy', parsed.json, stdout, stderr);
+  }
+
+  const url = buildOnboardingUrl(port, parsed.thread);
+  if (parsed.json) {
+    stdout.write(`${JSON.stringify({ ok: true, port, started, url })}\n`);
+  } else {
+    stdout.write(`workbench: running (port ${port})\n${url}\n`);
+  }
+  return 0;
+}
+
+function reportFailure(reason, asJson, stdout, stderr) {
+  if (asJson) {
+    stdout.write(`${JSON.stringify({ ok: false, reason })}\n`);
+  } else {
+    stderr.write(`morphisms onboarding failed: ${reason}\n`);
+  }
+  return 1;
+}
+
+module.exports = {
+  buildOnboardingUrl,
+  onboardingCommand,
+  parseOnboardingArgs,
+  startDetachedWorkbench,
+};

package/lib/workbench-health.js

@@ -0,0 +1,126 @@
+const http = require('node:http');
+
+const DEFAULT_PROBE_TIMEOUT_MS = 1000;
+const DEFAULT_POLL_TIMEOUT_MS = 30000;
+const DEFAULT_POLL_INTERVAL_MS = 500;
+
+function probeVersion(port, options = {}) {
+  const timeoutMs = options.timeoutMs || DEFAULT_PROBE_TIMEOUT_MS;
+  return new Promise((resolve) => {
+    let settled = false;
+    function finish(result) {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    }
+
+    const req = http.get({
+      hostname: '127.0.0.1',
+      port,
+      path: '/version',
+      timeout: timeoutMs,
+      agent: false,
+    }, (res) => {
+      res.resume();
+      res.on('end', () => {
+        if (res.statusCode === 200) {
+          finish({ ok: true, kind: 'healthy' });
+        } else {
+          finish({ ok: false, kind: 'occupied', reason: `GET /version returned ${res.statusCode}` });
+        }
+      });
+    });
+
+    req.setTimeout(timeoutMs, () => {
+      const error = new Error(`GET /version timed out after ${timeoutMs}ms`);
+      error.code = 'ETIMEDOUT';
+      req.destroy(error);
+    });
+    req.on('error', (error) => {
+      finish({ ok: false, kind: 'unavailable', reason: error.message, code: error.code });
+    });
+  });
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function occupiedPortReason(port, detail) {
+  return `port ${port} is occupied by something that is not the Morphisms Workbench${detail ? ` (${detail})` : ''}`;
+}
+
+function watchChildProcess(child) {
+  let failureReason;
+
+  child.once('error', (error) => {
+    failureReason = `failed to run mor-workbench: ${error.message}`;
+  });
+  child.once('exit', (code, signal) => {
+    if (!failureReason) failureReason = childExitReason(code, signal);
+  });
+  child.once('close', (code, signal) => {
+    if (!failureReason) failureReason = childExitReason(code, signal);
+  });
+
+  return {
+    getFailureReason() {
+      return failureReason;
+    },
+  };
+}
+
+function childExitReason(code, signal) {
+  if (signal) return `mor-workbench exited before becoming healthy (signal ${signal})`;
+  return `mor-workbench exited before becoming healthy (code ${typeof code === 'number' ? code : 'unknown'})`;
+}
+
+function spawnFailureReason(spawnState) {
+  if (!spawnState) return undefined;
+  if (spawnState.getFailureReason) return spawnState.getFailureReason();
+  if (spawnState.getError) {
+    const error = spawnState.getError();
+    if (error) return `failed to run mor-workbench: ${error.message}`;
+  }
+  return undefined;
+}
+
+async function waitForWorkbench(port, options = {}) {
+  const pollTimeoutMs = options.pollTimeoutMs || DEFAULT_POLL_TIMEOUT_MS;
+  const pollIntervalMs = options.pollIntervalMs || DEFAULT_POLL_INTERVAL_MS;
+  const probeTimeoutMs = options.probeTimeoutMs || DEFAULT_PROBE_TIMEOUT_MS;
+  const spawnState = options.spawnState;
+  const deadline = Date.now() + pollTimeoutMs;
+  let lastReason = 'not probed';
+
+  for (;;) {
+    const failureReason = spawnFailureReason(spawnState);
+    if (failureReason) return { ok: false, reason: failureReason };
+
+    const probe = await probeVersion(port, { timeoutMs: probeTimeoutMs });
+    if (probe.ok) return { ok: true };
+    if (probe.kind === 'occupied') return { ok: false, reason: occupiedPortReason(port, probe.reason) };
+    lastReason = probe.reason || lastReason;
+
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    await sleep(Math.min(pollIntervalMs, remaining));
+  }
+
+  const failureReason = spawnFailureReason(spawnState);
+  if (failureReason) return { ok: false, reason: failureReason };
+  return {
+    ok: false,
+    reason: `workbench did not become healthy on port ${port} within ${Math.round(pollTimeoutMs / 1000)}s (${lastReason})`,
+  };
+}
+
+module.exports = {
+  DEFAULT_POLL_INTERVAL_MS,
+  DEFAULT_POLL_TIMEOUT_MS,
+  DEFAULT_PROBE_TIMEOUT_MS,
+  occupiedPortReason,
+  probeVersion,
+  waitForWorkbench,
+  watchChildProcess,
+};

package/lib/workbench.js

@@ -1,6 +1,13 @@
 const { spawn } = require('node:child_process');
 const path = require('node:path');
 const { exists } = require('./files');
+const {
+  DEFAULT_POLL_INTERVAL_MS,
+  DEFAULT_POLL_TIMEOUT_MS,
+  DEFAULT_PROBE_TIMEOUT_MS,
+  waitForWorkbench,
+  watchChildProcess,
+} = require('./workbench-health');
 
 const WORKBENCH_LAUNCH = {
   source: '.morphisms-contract/issues_front_half/contract.mor',
@@ -91,30 +98,97 @@ function buildWorkbenchArgv(repoRoot, options = {}) {
   ];
 }
 
-function workbenchCommand(argv) {
+function childExitPromise(child) {
+  return new Promise((resolve) => {
+    child.once('error', (error) => resolve({ error }));
+    child.once('exit', (code, signal) => resolve({ code, signal }));
+  });
+}
+
+function waitForExitOrKill(child, graceMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer;
+    function finish() {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve();
+    }
+    child.once('exit', finish);
+    child.once('close', finish);
+    timer = setTimeout(() => {
+      if (settled) return;
+      try {
+        child.kill('SIGKILL');
+      } catch (_) {
+        // The child may already be gone; the command is already on a failure path.
+      }
+      finish();
+    }, graceMs);
+  });
+}
+
+async function terminateChild(child, options = {}) {
+  if (!child || typeof child.kill !== 'function') return;
+  const graceMs = options.killGraceMs || 250;
+  try {
+    child.kill('SIGTERM');
+  } catch (_) {
+    return;
+  }
+  await waitForExitOrKill(child, graceMs);
+}
+
+async function workbenchCommand(argv, options = {}) {
+  const stdout = options.stdout || process.stdout;
+  const stderr = options.stderr || process.stderr;
+  const cwd = options.cwd || process.cwd();
   let parsed;
   try {
     parsed = parseWorkbenchArgs(argv);
   } catch (error) {
-    console.error(error.message);
+    stderr.write(`${error.message}\n`);
     return 1;
   }
-  const port = parsed.port || configuredPort(process.cwd());
-  const childArgv = buildWorkbenchArgv(process.cwd(), parsed);
-  console.log(`Starting Morphisms Workbench at http://127.0.0.1:${port}/#workbench`);
-  const child = spawn('mor-workbench', childArgv, { stdio: 'inherit' });
-  child.on('error', (error) => {
-    console.error(`failed to run mor-workbench: ${error.message}`);
-    process.exit(1);
-  });
-  child.on('exit', (code, signal) => {
-    if (signal) {
-      process.kill(process.pid, signal);
-      return;
-    }
-    process.exit(typeof code === 'number' ? code : 1);
+  const port = parsed.port || configuredPort(cwd);
+  const childArgv = buildWorkbenchArgv(cwd, parsed);
+  stdout.write(`starting workbench on port ${port}...\n`);
+  const spawnWorkbench = options.spawnWorkbench || ((args, spawnOptions) => spawn('mor-workbench', args, { cwd: spawnOptions.cwd, stdio: 'inherit' }));
+  const child = spawnWorkbench(childArgv, { port, cwd });
+  const childExit = childExitPromise(child);
+  const spawnState = watchChildProcess(child);
+  const healthy = await waitForWorkbench(port, {
+    pollTimeoutMs: options.pollTimeoutMs || DEFAULT_POLL_TIMEOUT_MS,
+    pollIntervalMs: options.pollIntervalMs || DEFAULT_POLL_INTERVAL_MS,
+    probeTimeoutMs: options.probeTimeoutMs || DEFAULT_PROBE_TIMEOUT_MS,
+    spawnState,
   });
-  return undefined;
+  if (!healthy.ok) {
+    await terminateChild(child, { killGraceMs: options.killGraceMs });
+    stderr.write(`morphisms workbench failed: ${healthy.reason || 'workbench is not healthy'}\n`);
+    return 1;
+  }
+
+  stdout.write(`Morphisms Workbench: http://127.0.0.1:${port}/#workbench\n`);
+  const exit = await childExit;
+  if (exit.error) {
+    stderr.write(`failed to run mor-workbench: ${exit.error.message}\n`);
+    return 1;
+  }
+  if (exit.signal) {
+    if (!options.noSignalForward) process.kill(process.pid, exit.signal);
+    return 1;
+  }
+  return typeof exit.code === 'number' ? exit.code : 1;
 }
 
-module.exports = { WORKBENCH_LAUNCH, buildWorkbenchArgv, parseWorkbenchArgs, workbenchCommand };
+module.exports = {
+  WORKBENCH_LAUNCH,
+  buildWorkbenchArgv,
+  configuredPort,
+  parsePort,
+  parseWorkbenchArgs,
+  terminateChild,
+  workbenchCommand,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "morphisms",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.4",
   "description": "Morphisms workflow runtime shim and onboarding wizard",
   "license": "SEE LICENSE IN LICENSE",
   "bin": {
@@ -19,7 +19,7 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@morphisms/bin-linux-x64": "0.1.0-beta.3",
-    "@morphisms/bin-darwin-arm64": "0.1.0-beta.3"
+    "@morphisms/bin-linux-x64": "0.1.0-beta.4",
+    "@morphisms/bin-darwin-arm64": "0.1.0-beta.4"
   }
 }

package/templates/agent/skills/morphisms/SKILL.md

@@ -10,8 +10,8 @@ You are the orchestrator. Keep this session focused on coordination; delegate on
 ## Orient first
 
 1. Run `mor agent instructions` and read the S1/S2/S3 paths it reports. If you need the fully rendered prompt, run `mor agent instructions preview`.
-2. Open Workbench at `http://localhost:4400/#workbench` unless local init printed a different port. Use Workbench, not legacy graph routes.
-3. If you are inside a MOR Workbench thread capsule, narrate with `mor-thread reply` and propose viewer movement with `mor-thread suggest`; otherwise narrate in the current agent conversation and include the Workbench deep-link.
+2. Run `morphisms onboarding` (optionally `--thread <channelId>` when you have a thread id) and open only the Workbench URL it prints. Use Workbench, not legacy graph routes.
+3. If you are inside a MOR Workbench thread capsule, narrate with `mor-thread reply` and propose viewer movement with `mor-thread suggest`; otherwise narrate in the current agent conversation and include the Workbench deep-link from `morphisms onboarding`.
 
 ## Frontier
 
@@ -79,8 +79,24 @@ A refusal is a success signal from the runtime, not a CLI problem. Read the diag
 
 ## Concierge trigger
 
-If `.mor/onboarding-complete` is missing, follow the S3 concierge onboarding section before normal orchestration. At the end, write one line to `.mor/onboarding-complete`:
+If `.mor/onboarding-complete` is missing, stop normal orchestration and run the S3
+"Concierge onboarding" beat script instead. It is the human's first-ever contact with
+Morphisms; the S3 section is the authority on wording and pacing. The shape:
+
+1. Step zero: `morphisms onboarding` (health-gated; the only legal source of a Workbench
+   URL), then ask for one real bug or annoyance.
+2. Baton pass: materialize the `onboarding` thread, greet the human inside it via
+   `mor-thread reply`, hand over the deep link from `morphisms onboarding --thread
+   onboarding`, and continue the entire conversation in that thread.
+3. Land the four proofs in order — record filed (show it), a deliberate refusal on the
+   graph, an investigation citing their code, and one real attention decision — one
+   consented step at a time, using only the ten allowed words from S3.
+4. Close the journey, offer the replay, then write one line to `.mor/onboarding-complete`:
 
 ```text
 <ISO-8601 date> <first issue id>
 ```
+
+During concierge onboarding, the normal spawn/delegation policy is suspended — the
+onboarding agent works in-session; normal spawn/delegation policy resumes after
+`.mor/onboarding-complete` exists.

package/templates/claude/skills/morphisms/SKILL.md

@@ -10,8 +10,8 @@ You are the orchestrator. Keep this Claude Code session focused on coordination;
 ## Orient first
 
 1. Run `mor agent instructions` and read the S1/S2/S3 paths it reports. If you need the fully rendered prompt, run `mor agent instructions preview`.
-2. Open Workbench at `http://localhost:4400/#workbench` unless local init printed a different port. Use Workbench, not legacy graph routes.
-3. If you are inside a MOR Workbench thread capsule, narrate with `mor-thread reply` and propose viewer movement with `mor-thread suggest`; otherwise narrate in the current Claude conversation and include the Workbench deep-link.
+2. Run `morphisms onboarding` (optionally `--thread <channelId>` when you have a thread id) and open only the Workbench URL it prints. Use Workbench, not legacy graph routes.
+3. If you are inside a MOR Workbench thread capsule, narrate with `mor-thread reply` and propose viewer movement with `mor-thread suggest`; otherwise narrate in the current Claude conversation and include the Workbench deep-link from `morphisms onboarding`.
 
 ## Frontier
 
@@ -79,8 +79,24 @@ A refusal is a success signal from the runtime, not a CLI problem. Read the diag
 
 ## Concierge trigger
 
-If `.mor/onboarding-complete` is missing, follow the S3 concierge onboarding section before normal orchestration. At the end, write one line to `.mor/onboarding-complete`:
+If `.mor/onboarding-complete` is missing, stop normal orchestration and run the S3
+"Concierge onboarding" beat script instead. It is the human's first-ever contact with
+Morphisms; the S3 section is the authority on wording and pacing. The shape:
+
+1. Step zero: `morphisms onboarding` (health-gated; the only legal source of a Workbench
+   URL), then ask for one real bug or annoyance.
+2. Baton pass: materialize the `onboarding` thread, greet the human inside it via
+   `mor-thread reply`, hand over the deep link from `morphisms onboarding --thread
+   onboarding`, and continue the entire conversation in that thread.
+3. Land the four proofs in order — record filed (show it), a deliberate refusal on the
+   graph, an investigation citing their code, and one real attention decision — one
+   consented step at a time, using only the ten allowed words from S3.
+4. Close the journey, offer the replay, then write one line to `.mor/onboarding-complete`:
 
 ```text
 <ISO-8601 date> <first issue id>
 ```
+
+During concierge onboarding, the normal spawn/delegation policy is suspended — the
+onboarding agent works in-session; normal spawn/delegation policy resumes after
+`.mor/onboarding-complete` exists.

package/templates/instructions/starter-issues-agent-manual.md

@@ -68,51 +68,152 @@ Attention:
 
 ## Concierge onboarding
 
-If `.mor/onboarding-complete` does **not** exist, you are in concierge mode. Do this before normal orchestration.
+If `.mor/onboarding-complete` does **not** exist, you are in concierge mode. This is the
+human's first-ever contact with Morphisms. Your job is not to demonstrate features; it is
+to land four proofs, in order, about a problem the human actually has:
+
+1. **My words became a record I can inspect.**
+2. **The rules are real** — you will try to skip ahead and the graph will visibly refuse you.
+3. **The evidence is real** — a report citing their code, attached to the record.
+4. **The system formally summons the human** when a decision needs them.
+
+Everything below serves those proofs. Target: proof 1 within 3 minutes of starting; done
+in about 7.
+
+### Non-negotiable rules (entire concierge flow)
+
+- **Consent cadence.** A "step" is one movement of the record (its evidence plus the edge
+  that uses it). Before each step: one plain sentence of what you will do and why, then
+  ask. After: one sentence of what changed, plus a way to see it. Never two steps between
+  consents.
+- **Vocabulary.** To the human, use only: record, graph, state, journey, evidence, report,
+  plan, attention, thread, Workbench. Never say: hydrate, enrich, walk, payload, fibre,
+  morphism, distro, release, plateau, witness, capsule, armed, harness, tmux, artifact.
+  The commands you run are machinery; the words you say are the product.
+- **URL rule.** Never print or link a Workbench URL unless `morphisms onboarding` has just
+  succeeded; quote only the URL it prints.
+- **Failure narration.** If a command fails unexpectedly, say in the thread what you
+  tried, that it failed, and what you will do next — in plain words. Never paste raw
+  JSON or diagnostics at the human, never go silent, never pretend it worked.
+- **One surface.** After the baton pass (beat 2), the Workbench thread is the only
+  conversation surface. The terminal prints nothing further except a hard-failure notice.
+- **Never fabricate the human's answer.** The attention step uses their real reply.
+- **Spawn policy is suspended.** You work in-session; normal spawn/delegation policy
+  resumes after `.mor/onboarding-complete` exists.
+- **Go slow.** The human does not know what Morphisms is. Introduce each of the ten
+  allowed words only at the moment the thing it names is on their screen. If they ask a
+  question, answer it at their level before moving on.
+
+### Beat 1 — step zero and the one question (terminal, under a minute)
+
+Silently run step zero first:
 
-### 1. Ask for one real annoyance
+```bash
+morphisms onboarding
+```
+
+This proves the Workbench is alive (starting it if needed) and prints the base URL. If it
+fails, tell the human honestly that the visual Workbench could not start (quote its
+one-line reason), offer to continue in the terminal as a degraded walkthrough, and never
+show a URL.
+
+Then ask the single opening question:
+
+> Let's make this real. Give me one bug, annoyance, or confusing behavior in this repo.
+> If you don't have one ready, I can scan the repo and propose a small first issue.
+
+If they ask you to scan, choose a small truthful annoyance grounded in real files.
+Do not file anything yet — filing happens in the thread, where they can watch.
+
+### Beat 2 — the baton pass (terminal → thread)
+
+Create the onboarding thread, greet them in it, and hand over one link.
+
+```bash
+# Materialize the thread channel and its working capsule (port from
+# .morphisms-contract/config.json workbench_port):
+curl -s "http://127.0.0.1:<port>/api/agent/thread/v1?channel=onboarding"
+```
+
+Read `working_capsule_path` from the JSON response; call it `$CAPSULE` below.
+
+```bash
+mor-thread --thread "$CAPSULE" reply --message "👋 I'm your Morphisms agent. This thread is where we'll work — reply here and we'll get started."
+morphisms onboarding --thread onboarding
+```
+
+Print in the terminal ONLY this handoff (with the URL the command printed):
+
+> Everything happens in the Workbench from here. Click:
+> `<printed URL>`
+> I've already opened our thread there and said hello.
+
+Then wait for their reply:
+
+```bash
+mor-thread --thread "$CAPSULE" next --wait
+```
+
+Loop while it returns no message. After roughly three empty waits, print one gentle
+terminal nudge ("Still here — click the link above when you're ready") and keep waiting.
+
+Fallback: if `mor-thread` or the capsule fails, post messages over HTTP instead
+(`POST /api/agent/outbox/v1` with `{"channel":"onboarding","message":"..."}`), read
+replies by polling `GET /api/agent/thread/v1?channel=onboarding`, and skip the look-here
+suggestions in later beats — the flow continues without them.
 
-Say:
+### Beat 3 — roundtrip proof and the plan
 
-> Let's make this real. Give me one bug, annoyance, or confusing behavior in this repo. If you do not have one ready, I can scan the repo and propose one small first issue.
+When their first reply arrives, set the frame in one short message:
 
-If the human gives an issue, file it. If they ask you to scan, inspect files normally and choose a small truthful annoyance grounded in the repo.
+> Great — you made it. Here's the plan: I'll file your bug as a **record**, investigate
+> it, and write a plan — and you'll watch every step move across the graph you're looking
+> at. I'll ask before each step. Ready?
 
-Create the first issue with only add-accepted fields:
+### Beat 4 — proof 1: their words become a record
+
+On consent, file it (add-accepted fields only):
 
 ```json
-{"title":"<short title>","kind":"bug","summary":"<human words plus any repo clue>"}
+{"title":"<short title>","kind":"bug","summary":"<their words plus any repo clue>"}
 ```
 
 ```bash
 mor issue add --payload /tmp/morphisms-first-issue.json
 ```
 
-Narrate: "I filed the first `issue` record. The graph should now show it at `journey.triage` and `attention.autonomous_entry` in Workbench: http://localhost:4400/#workbench."
-
-### 2. Hydrate and explain the packet
+Report and show:
 
-Run:
+> Your bug is now record `<id>`, sitting at the first state of its journey — you can see
+> it on the graph. Don't take my word for it:
 
 ```bash
-mor issue hydrate <id> journey.triage
+mor-thread --thread "$CAPSULE" suggest open_record --record-id <id> --label "Show me the record"
 ```
 
-Narrate the first occurrence: "Hydration is the handoff packet: record fields, persona, context, legal edges, and missing witnesses. I follow this packet instead of guessing."
+Tell them they can press `i` on anything they open to see the raw truth underneath.
+
+### Beat 5 — proof 2: the rules are real
 
-### 3. Show one deliberate refusal
+Announce it first — eyes on the graph before you act:
 
-Before attaching `triage_decision`, intentionally attempt the standard lane once:
+> Before I investigate, let me show you why this isn't just a chat log. I'm going to try
+> to skip straight to investigating **without any evidence** — watch the edge leading out
+> of the first state.
 
 ```bash
 mor issue walk <id> journey.choose_standard_investigation
 ```
 
-Expect a blocked/refused result such as a missing `triage_decision` witness. Narrate: "This refusal is the safety rail. MOR will not let me move the graph until the typed evidence exists."
+This is refused (the record has no triage evidence yet) and the edge flashes red on the
+graph. Explain:
 
-### 4. Triage into a real investigation lane
+> The graph refused me. I cannot move your issue until the evidence it requires actually
+> exists. The rules live in the graph — not in my good intentions.
 
-Attach a standard triage decision unless the issue truly needs rigorous review:
+### Beat 6 — proof 3: real evidence from their repo
+
+Step 6a (consent, then triage): attach the decision and move — note the contrast:
 
 ```json
 {"decision":"standard","rationale":"Needs one file/line investigation before scoping.","signals":["<signal>"]}
@@ -124,11 +225,10 @@ mor issue walk <id> journey.choose_standard_investigation
 mor issue hydrate <id> journey.investigating
 ```
 
-Narrate the graph movement in Workbench.
-
-### 5. Investigate with citations
+> This time the same edge turned green — the evidence existed, so the move was legal.
 
-Do a real repo read. The `investigation_report.citations` array must be non-empty and cite real file lines:
+Step 6b (consent, then investigate): do a real repo read. `citations` must be non-empty
+with real `{file,line,excerpt,why_it_matters}` entries:
 
 ```json
 {
@@ -146,9 +246,24 @@ mor issue walk <id> journey.submit_standard_investigation
 mor issue hydrate <id> journey.scoping
 ```
 
-### 6. Scope to a typed front-half outcome
+Report with a 2–3 sentence summary of what you found in their code, then show:
+
+```bash
+mor-thread --thread "$CAPSULE" suggest open_record --record-id <id> --label "Read the investigation report"
+```
+
+> The report is attached to the record itself — it doesn't scroll away.
+
+Offer depth exactly once, and don't push it:
+
+```bash
+mor-thread --thread "$CAPSULE" suggest open_context_packet --store issues --dimension journey --state investigating --label "See my briefing for that state"
+```
+
+> Curious what I was told to do there? That briefing — who I'm supposed to be and what I
+> get to see — is defined per state, for every state on this graph.
 
-Attach a scoped plan with a handoff prompt:
+Step 6c (consent, then scope): attach the plan with a handoff prompt:
 
 ```json
 {
@@ -165,37 +280,32 @@ Attach a scoped plan with a handoff prompt:
 
 ```bash
 mor issue enrich <id> scoped_plan --role scoped_plan --payload /tmp/scoped-plan.json
-mor issue inspect <id>
 ```
 
-If the honest outcome is blocked, set `plan_outcome=blocked` and include `blocker`; do not close the journey until after the human-collab step below.
+If the honest outcome is blocked, use `plan_outcome=blocked` with `blocker` — and say so
+plainly; do not close the journey until after beat 7.
 
-### 7. Route one real human-collab moment
+### Beat 7 — proof 4: the system summons them
 
-After the scoped plan is attached and before closing the journey, route the record to the human in the `attention` dimension. First inspect the current attention state:
+Check the current attention state with `mor issue inspect <id>`, then route:
 
 ```bash
-mor issue inspect <id>
+mor issue walk <id> attention.request_operator_from_entry   # if attention=autonomous_entry
+mor issue walk <id> attention.request_operator              # if attention=autonomous
 ```
 
-If `attention=autonomous_entry`, run:
+Then hand them the moment:
 
-```bash
-mor issue walk <id> attention.request_operator_from_entry
-```
+> Now the record is waiting for **you** — you can see it sitting at the waiting-for-you
+> state on the attention graph. This is the other half of Morphisms: agents run on their
+> own, and the graph decides when a human is required. No pings, no hoping someone reads
+> the chat. So, your first real decision: should I close this out with the plan as
+> written, or revise the scope?
 
-If `attention=autonomous`, run:
-
-```bash
-mor issue walk <id> attention.request_operator
-```
-
-Tell the human: "The record is now waiting for YOU at `attention.awaiting_operator`. In an armed Workbench thread, this is the `Review now` moment; otherwise use the record card in Workbench: http://localhost:4400/#workbench. Please answer whether I should resume and close this scoped plan, or revise scope."
-
-Use the human's actual answer as the `operator_decision`; do not fabricate it. For a resume answer, attach:
+Use their actual answer:
 
 ```json
-{"decision":"resume","rationale":"<human's answer>","instructions":"Proceed with the scoped plan outcome.","answered_questions":["Resume and close this scoped plan?"]}
+{"decision":"resume","rationale":"<their answer>","instructions":"Proceed with the scoped plan outcome.","answered_questions":["Resume and close this scoped plan?"]}
 ```
 
 ```bash
@@ -203,30 +313,33 @@ mor issue enrich <id> operator_decision --role operator_decision --payload /tmp/
 mor issue walk <id> attention.return_to_autonomous
 ```
 
-Narrate: "This is how future work pauses only when it needs you, then resumes after your typed decision."
+> That's how future work pauses only when it needs you — and resumes on your decision.
 
-### 8. Close the journey
+### Beat 8 — the whole story, then normal mode
 
-For a ready quick/standard scoped plan, close with:
+Close the journey (consent first):
 
 ```bash
-mor issue walk <id> journey.complete_scoped_plan
-mor issue inspect <id>
+mor issue walk <id> journey.complete_scoped_plan      # ready quick/standard plan
+mor issue walk <id> journey.close_blocked_from_scoping  # honest blocked outcome
 ```
 
-For a blocked scoped plan, close with:
+Finale — give them the record's full story:
 
 ```bash
-mor issue walk <id> journey.close_blocked_from_scoping
-mor issue inspect <id>
+mor-thread --thread "$CAPSULE" suggest start_replay --record-id <id> --label "Replay the whole story"
 ```
 
-### 9. Complete onboarding
+> That's the entire journey of your issue, step by step — arrow keys to move, `i` to
+> inspect anything.
 
-When the first record reaches `journey.done`, write the sentinel:
+Write the sentinel:
 
 ```bash
 printf '%s %s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "<id>" > .mor/onboarding-complete
 ```
 
-Tell the human: "Onboarding is complete. Normal Morphisms mode is now on; future records will start from the frontier loop."
+Sign off with the one next action:
+
+> Onboarding is done. From now on, just tell me about bugs and ideas — they'll appear
+> here as records and move across this graph. Keep this tab: it's your workflow's home.

package/templates/instructions/workspace-agent-manual.md

@@ -5,7 +5,7 @@ This is the S2 workspace layer for a repo initialized by `morphisms init`. It ap
 ## Startup
 
 - Run `mor agent instructions` before orchestrating. Read the reported S1/S2/S3 files; use `mor agent instructions preview` only when you need the rendered stack.
-- Workbench is the lens: `http://localhost:4400/#workbench` unless `.morphisms-contract/config.json` says a different `workbench_port`.
+- Workbench is the lens: run `morphisms onboarding` first and use only the Workbench URL it prints.
 - Keep runtime state under `.mor/`. Do not edit SQLite files or registry material by hand.
 - Do not create `.mor/onboarding-complete`; the onboarding agent writes it only after the first real issue reaches `journey.done`.