@usenexus/cli 0.0.2 → 0.1.0

package/dist/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="referrer" content="no-referrer" />
+    <title>nexus</title>
+    <script type="module" crossorigin src="./assets/index-DycaEuDy.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-Bj0JERnz.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/package.json

@@ -1,13 +1,51 @@
 {
   "name": "@usenexus/cli",
-  "version": "0.0.2",
-  "description": "nexus: a repo that ships itself. npx @usenexus/cli launches the local GUI (coming soon).",
+  "version": "0.1.0",
+  "description": "nexus: a local GUI for Claude Code that runs the nexus loop on your repo. npx @usenexus/cli",
   "license": "MIT",
   "type": "module",
-  "bin": { "nexus": "bin/nexus.mjs" },
-  "files": ["bin", "README.md", "LICENSE"],
-  "engines": { "node": ">=20" },
-  "repository": { "type": "git", "url": "git+https://github.com/daretodave/nexus.git" },
+  "bin": {
+    "nexus": "bin/nexus.mjs"
+  },
+  "files": [
+    "bin",
+    "server",
+    "shared",
+    "dist",
+    "prompts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node scripts/bundle-prompts.mjs && vite build",
+    "test": "node --test \"test/*.test.mjs\"",
+    "start": "node bin/nexus.mjs",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.305"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "6.1.2",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "vite": "8.3.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daretodave/nexus.git",
+    "directory": "packages/cli"
+  },
   "homepage": "https://github.com/daretodave/nexus#readme",
-  "keywords": ["claude-code", "nexus", "autonomous", "agents", "methodology"]
+  "keywords": [
+    "claude-code",
+    "nexus",
+    "autonomous",
+    "agents",
+    "methodology",
+    "gui"
+  ]
 }

package/prompts/adopt.md

@@ -0,0 +1,119 @@
+# Adopt nexus — agent prompt
+
+> Clone nexus next to your repo, then paste the short version
+> from README.md's
+> [TL;DR — clone + delegate the adoption](../README.md#tldr--clone--delegate-the-adoption)
+> into your agent — it points here. This file is the full
+> instruction set the agent then follows; read it yourself
+> first if you want to know exactly what you're authorizing.
+>
+> Use this if you already have a `spec.md`. If you only have a
+> verbal pitch, use [`pitch.md`](./pitch.md) instead.
+
+---
+
+## The prompt
+
+```
+Adopt nexus.
+
+nexus is at ../nexus (or ./.nexus if submoduled). It is a
+methodology + template kit for turning this repo into an
+autonomous-loop project. Read the following, in order, before
+making a single change:
+
+  1. ../nexus/README.md            — entry point
+  2. ../nexus/concepts/architecture.md  — the whole system
+  3. ../nexus/concepts/skills-anatomy.md — how skills work
+  4. ../nexus/playbooks/new-project.md   AND
+     ../nexus/playbooks/existing-project.md
+                                   — pick the one that applies
+  4a. ../nexus/playbooks/polyrepo.md AND/OR
+      ../nexus/playbooks/workspace.md
+                                   — only if the topology check
+                                     under "Then:" below (in
+                                     this same prompt) lands on
+                                     either
+  5. ../nexus/playbooks/ci-providers.md  — for the deploy gate
+  6. ../nexus/intervention-spectrum.md   — how the loop scales
+  7. ../nexus/customization/*.md   — e.g. verify gate, hermetic
+                                     e2e, data layer, sub-agents;
+                                     skim the rest as needed
+
+Then:
+
+  - Decide whether this is greenfield or brownfield by reading
+    `git log --oneline | wc -l`, looking at the file tree, and
+    checking for an existing spec.md.
+  - Check the topology: is there already a sibling `plan/`
+    directory next to this repo, or multiple sibling repos
+    under one un-versioned root? Infer a default from that
+    (single-repo if neither), but always confirm it with the
+    user before proceeding — see the ask list below. Getting
+    this wrong reshapes file locations from phase 1 onward.
+  - Follow the matching playbook end-to-end. Do not skip steps.
+  - Copy templates from ../nexus/templates/ into this repo.
+  - Replace placeholders (<PROJECT>, <PROJECT_LOWER>,
+    <PROJECT_TAGLINE>, <HOSTING_URL>, <HOSTING_PROVIDER>,
+    <REPO_SLUG>, <DEFAULT_BRANCH>, <PROJECT_PKG_PREFIX>) with
+    values you derive from the existing repo state. If a value
+    is genuinely unknowable, surface it in plan/AUDIT.md as a
+    [needs-user-call] row and continue with a defensible
+    default.
+  - Ask the user ONLY for: (a) the hosting provider name and
+    auth token if not visibly configured, (b) the project's
+    canonical name + tagline if no spec exists, (c) the
+    URL/API/CLI contract if it cannot be inferred, (d)
+    confirmation of the topology guess above — single-repo,
+    polyrepo (`plan/` split into a sibling repo), or workspace
+    (3+ sibling repos under one un-versioned root). For
+    everything else, decide.
+  - Adapt bearings.md to reflect the actual stack present in
+    this repo. Do not assume Next.js, Tailwind, or any
+    specific framework — read package.json / Cargo.toml /
+    pyproject.toml / go.mod and adapt.
+  - Write the plan as specs and chunks (nexus/concepts/
+    plan-shape.md): a plan/README.md roadmap with one row per
+    spec drawn from the spec (or from CURRENT-STATE.md for
+    brownfield), the first spec or two chunked (S/M/L, every
+    acceptance ID covered), the rest `Not chunked yet.`.
+    Copy templates/plan/nexus.lock and run
+    scripts/plan-check.mjs until it is green.
+  - Wire the verify gate against this repo's actual test
+    setup. Wire the deploy gate against the chosen provider.
+  - At the end: produce a single commit titled
+    "chore: adopt nexus methodology" with a body listing every
+    file added/modified, every placeholder you resolved, and
+    every [needs-user-call] you logged. Push.
+  - Then stop. Do not invoke /ship-a-chunk yourself; let the
+    user do that as the first conscious step.
+
+Standing rules carried from agents.md:
+  - Commit and push as a single atomic act.
+  - No Co-Authored-By trailers, no emojis. If your harness
+    auto-appends one of these by default, strip it before every
+    commit — this rule overrides that convention here.
+  - No --no-verify, no force-push, no destructive resets.
+  - Tests alongside code.
+  - When in doubt: decide, document the call in the commit body,
+    proceed.
+
+Estimated time: well under an hour, agent-paced (no
+read-and-decide pauses) — new-project.md's own header quotes
+2–3 hours for a human working the same playbook manually and
+notes the delegated-agent case finishes faster; see its note
+on the difference. Begin.
+```
+
+---
+
+## See also
+
+- [`README.md`](../README.md) — the short paste that points
+  here, plus what to expect when the agent returns and when
+  this path is the wrong one.
+- [`playbooks/new-project.md`](../playbooks/new-project.md) /
+  [`playbooks/existing-project.md`](../playbooks/existing-project.md)
+  — the playbooks this prompt tells the agent to follow.
+- [`pitch.md`](./pitch.md) — the pre-spec variant, for when
+  there's no `spec.md` yet.

package/prompts/pitch.md

@@ -0,0 +1,93 @@
+# Pitch-to-adopted — agent prompt
+
+> Clone nexus next to your repo, then paste the short version
+> from README.md's
+> [TL;DR — I have a pitch, no spec yet](../README.md#tldr--i-have-a-pitch-no-spec-yet)
+> into your agent — it points here, with your pitch inline.
+> This file is the full instruction set the agent then
+> follows; read it yourself first if you want to know exactly
+> what you're authorizing.
+>
+> Use this if you have a working name and a one-paragraph
+> pitch, but no `spec.md` yet. If you already have a `spec.md`,
+> use [`adopt.md`](./adopt.md) instead.
+
+---
+
+## The prompt
+
+```
+Run nexus's pitch-to-adopted flow.
+
+nexus is at ../nexus (or ./.nexus if submoduled). The plan
+is: pre-spec interview → write spec.md → adopt nexus.
+
+Phase A — pre-spec interview (30-45 minutes)
+
+Read ../nexus/playbooks/pre-spec.md end-to-end. Read
+../nexus/concepts/asking-well.md for question shape. Then
+run the three question batches (foundation, spine, surface)
+per the playbook. AskUserQuestion is allowed during this
+phase — it's pre-spec, not in-skill. Once spec.md is
+committed at the end of Phase A, that rule reverts.
+
+Here's my pitch in my own words:
+
+  <ONE-PARAGRAPH PITCH — what the product is, who it's for,
+  what makes it interesting. Don't polish.>
+
+Phase A deliverables (committed before Phase B starts):
+  - spec.md (at least one page, persona named, v1 scope)
+  - plan/bearings.md stub (Surface, Auth, Stack, hosting,
+    voice, hard rules)
+  - (optional) claude-design.prompt.md if Batch 3 Q2 landed
+    on "commission a visual system" (see
+    ../nexus/customization/visual-system.md)
+  - (optional) NEXUS_LESSONS.md scratch — capture nexus gaps
+    you hit during the interview, for a later /lessons-pr
+    pass back to the nexus repo
+
+Phase B — adoption
+
+Once Phase A's commits land, switch to the standard adoption
+prompt: read and follow ../nexus/prompts/adopt.md exactly,
+including its own narrow four-item ask list (hosting
+provider/token, project name/tagline, URL/API/CLI contract,
+topology confirmation) — that list is adopt.md's own
+carve-out, the same class as /oversight's. Beyond those four
+items, AskUserQuestion is not allowed. Decide and document;
+don't ask.
+
+End-state:
+  - chore: adopt nexus methodology commit landed and pushed
+  - Day 1 checklist in new-project.md passes
+  - Ready for /ship-a-chunk as the first conscious step.
+  - Do NOT invoke /ship-a-chunk yourself; let the user do
+    that.
+
+Standing rules:
+  - Commit and push as a single atomic act per logical chunk.
+  - No Co-Authored-By trailers, no emojis.
+  - No --no-verify, no force-push.
+
+Estimated time: 60-90 minutes total, agent-paced for Phase B
+(Phase A is genuinely interactive, per pre-spec.md's own
+30-45 minute estimate; Phase B's 2-3 hour playbook estimate
+is the human-paced figure — see new-project.md's note).
+Begin with Phase A.
+```
+
+Pitch quality matters. If you can't describe the product in
+one paragraph in plain language, come back when you can. The
+agent will not invent product direction for you.
+
+---
+
+## See also
+
+- [`README.md`](../README.md) — the short paste that points
+  here.
+- [`adopt.md`](./adopt.md) — the Phase B prompt this one
+  hands off to.
+- [`playbooks/pre-spec.md`](../playbooks/pre-spec.md) — what
+  Phase A tells the agent to follow.

package/server/gh.mjs

@@ -0,0 +1,89 @@
+// GitHub Actions setup and live runs, through the person's own `gh` login.
+// Run state is observed only (gh run list / view); nothing here infers
+// progress from a clock. A run still queued after STALL_MS reads "stalled".
+import { run, json } from './sh.mjs';
+
+export const STALL_MS = 2 * 60 * 1000;
+export const POLL_MS = 8000;
+export const SECRET = 'CLAUDE_CODE_OAUTH_TOKEN';
+
+export async function actionsSetup(repo) {
+  const auth = await run('gh', ['auth', 'status'], { cwd: repo });
+  if (!auth.ok) return { gh: false, note: auth.missing ? 'gh is not installed.' : 'gh is not signed in. Run `gh auth login`.' };
+  const [secrets, workflows, perms, rulesets] = await Promise.all([
+    run('gh', ['secret', 'list', '--json', 'name'], { cwd: repo }),
+    run('gh', ['workflow', 'list', '--all', '--json', 'id,name,path,state'], { cwd: repo }),
+    run('gh', ['api', 'repos/{owner}/{repo}/actions/permissions/workflow'], { cwd: repo }),
+    run('gh', ['api', 'repos/{owner}/{repo}/rulesets'], { cwd: repo }),
+  ]);
+  const names = (json(secrets.stdout) || []).map((s) => s.name);
+  const p = json(perms.stdout) || {};
+  const rs = json(rulesets.stdout);
+  return {
+    gh: true,
+    steps: [
+      {
+        id: 'secret',
+        label: `${SECRET} repo secret`,
+        ok: names.includes(SECRET),
+        detail: secrets.ok ? (names.length ? `secrets: ${names.join(', ')}` : 'no repo secrets') : 'could not list secrets (needs admin on the repo)',
+        fix: `Run \`claude setup-token\`, then \`gh secret set ${SECRET}\` and paste the token.`,
+      },
+      {
+        id: 'permissions',
+        label: 'Workflow token can write',
+        ok: p.default_workflow_permissions === 'write',
+        detail: perms.ok ? `default: ${p.default_workflow_permissions || 'unknown'}; may approve PRs: ${p.can_approve_pull_request_reviews ? 'yes' : 'no'}` : 'could not read workflow permissions',
+        fix: 'Settings -> Actions -> General -> Workflow permissions: Read and write.',
+      },
+      {
+        id: 'rulesets',
+        label: 'Rulesets on main and claims',
+        ok: Array.isArray(rs) && rs.length > 0,
+        optional: true,
+        detail: Array.isArray(rs) ? (rs.length ? rs.map((r) => `${r.name} (${r.enforcement})`).join(', ') : 'none') : 'could not read rulesets',
+        fix: 'Optional in owner mode. In PR mode, protect main so only pull requests land.',
+      },
+    ],
+    workflows: (json(workflows.stdout) || []).map((w) => ({ id: w.id, name: w.name, path: w.path, enabled: w.state === 'active', state: w.state })),
+  };
+}
+
+export async function setWorkflow(repo, id, enabled) {
+  if (!/^[0-9]+$/.test(String(id))) return { ok: false, error: 'bad workflow id' };
+  const r = await run('gh', ['workflow', enabled ? 'enable' : 'disable', String(id)], { cwd: repo });
+  return { ok: r.ok, out: (r.stdout + r.stderr).trim() };
+}
+
+export async function listRuns(repo) {
+  const r = await run('gh', ['run', 'list', '-L', '20', '--json', 'databaseId,displayTitle,workflowName,status,conclusion,createdAt,updatedAt,url,event'], { cwd: repo });
+  if (!r.ok) return { ok: false, runs: [], error: (r.stderr || '').trim().slice(0, 300) };
+  return { ok: true, runs: (json(r.stdout) || []).map((x) => markStall(x, Date.now())) };
+}
+
+export function markStall(runRow, now) {
+  const queuedFor = now - Date.parse(runRow.createdAt || 0);
+  return { ...runRow, stalled: runRow.status === 'queued' && queuedFor > STALL_MS };
+}
+
+/**
+ * Turn a fresh run list into loop beats against what was seen before.
+ * `seen` maps run id -> last status. A run first seen already completed
+ * is history, not news: it is recorded without a beat.
+ */
+export function runBeats(runs, seen) {
+  const out = [];
+  for (const r of runs) {
+    const id = String(r.databaseId);
+    const before = seen.get(id);
+    const now = r.status;
+    seen.set(id, now);
+    if (before === now) continue;
+    if (before === undefined && now === 'completed') continue;
+    const name = r.workflowName || r.displayTitle || '';
+    if (now === 'queued' || now === 'waiting' || now === 'requested' || now === 'pending') out.push({ k: 'loop', p: 'dispatch', id, name });
+    else if (now === 'in_progress') out.push({ k: 'loop', p: 'run', id, name });
+    else if (now === 'completed') out.push({ k: 'loop', p: 'conclude', id, name, conclusion: r.conclusion || 'unknown' });
+  }
+  return out;
+}

package/server/hub.mjs

@@ -0,0 +1,104 @@
+// The event hub behind GET /api/events (one SSE stream per tab).
+//
+// - On connect: a `hello` with server time and the full replay (beats and
+//   transcript), so a late tab reduces to the same state as an early one.
+// - A `: ping` comment every 20 s keeps proxies and sleeping tabs honest.
+// - Writes are coalesced into 300 ms flushes; consecutive text deltas for
+//   the same transcript item merge into one event.
+
+export const PING_MS = 20000;
+export const FLUSH_MS = 300;
+const MAX_BEATS = 5000;
+const MAX_TRANSCRIPT = 2000;
+
+export function createHub({ pingMs = PING_MS, flushMs = FLUSH_MS } = {}) {
+  const clients = new Set();
+  const beats = [];
+  const transcript = [];
+  let queue = [];
+  let timer = null;
+  let status = { state: 'idle' };
+  const extras = {};
+
+  function frame(type, data) {
+    return `event: ${type}\ndata: ${JSON.stringify(data)}\n\n`;
+  }
+
+  function flush() {
+    timer = null;
+    if (!queue.length) return;
+    const out = coalesce(queue).map((e) => frame(e.type, e.data)).join('');
+    queue = [];
+    for (const res of clients) res.write(out);
+  }
+
+  function emit(type, data) {
+    queue.push({ type, data });
+    if (!timer) timer = setTimeout(flush, flushMs);
+  }
+
+  function beat(b) {
+    beats.push(b);
+    if (beats.length > MAX_BEATS) beats.splice(0, beats.length - MAX_BEATS);
+    emit('beat', b);
+  }
+
+  function tx(item) {
+    if (item.kind === 'delta') {
+      const last = transcript[transcript.length - 1];
+      if (last && last.kind === 'text' && last.id === item.id) last.text += item.text;
+      else transcript.push({ kind: 'text', id: item.id, agent: item.agent, text: item.text });
+    } else transcript.push(item);
+    if (transcript.length > MAX_TRANSCRIPT) transcript.splice(0, transcript.length - MAX_TRANSCRIPT);
+    emit('tx', item);
+  }
+
+  function setStatus(next) {
+    status = { ...status, ...next };
+    emit('status', status);
+  }
+
+  function set(key, value) {
+    extras[key] = value;
+    emit(key, value);
+  }
+
+  function attach(req, res) {
+    res.writeHead(200, {
+      'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'no-cache, no-transform',
+      connection: 'keep-alive',
+      'x-accel-buffering': 'no',
+    });
+    res.write(frame('hello', { time: Date.now(), beats, transcript, status, ...extras }));
+    clients.add(res);
+    const ping = setInterval(() => res.write(': ping\n\n'), pingMs);
+    req.on('close', () => { clearInterval(ping); clients.delete(res); });
+  }
+
+  function reset() {
+    beats.length = 0;
+    transcript.length = 0;
+    emit('reset', {});
+  }
+
+  function close() {
+    if (timer) { clearTimeout(timer); flush(); }
+    for (const res of clients) res.end();
+    clients.clear();
+  }
+
+  return { emit, beat, tx, setStatus, set, attach, reset, close, flush, get clients() { return clients.size; }, get beats() { return beats; }, get transcript() { return transcript; } };
+}
+
+/** Merge consecutive `tx` deltas for the same item; everything else passes in order. */
+export function coalesce(events) {
+  const out = [];
+  for (const e of events) {
+    const last = out[out.length - 1];
+    if (e.type === 'tx' && e.data.kind === 'delta' && last && last.type === 'tx' && last.data.kind === 'delta' && last.data.id === e.data.id) {
+      last.data = { ...last.data, text: last.data.text + e.data.text };
+    } else out.push({ type: e.type, data: e.data });
+  }
+  return out;
+}

package/server/normalize.mjs

@@ -0,0 +1,89 @@
+// SDK / stream-json messages -> transcript items for the prompt pane.
+// Pure apart from `ctx`, which remembers which assistant messages already
+// streamed as partials (so the full message that follows is not repeated).
+
+export function newTxContext() {
+  return { msgId: null, streamed: new Set() };
+}
+
+export function summarize(name, input = {}) {
+  const pick = input.command || input.file_path || input.pattern || input.url || input.description || input.prompt || input.query || '';
+  const s = String(pick).replace(/\s+/g, ' ').trim();
+  return s.length > 140 ? `${s.slice(0, 137)}...` : s;
+}
+
+/** Copy for account errors, keyed by the SDK's assistant error codes. */
+export function friendlyError(code, fallback) {
+  switch (code) {
+    case 'authentication_failed':
+      return 'Claude Code is not logged in. Run `claude` in a terminal, then /login, and try again.';
+    case 'billing_error':
+      return 'Your Claude account has a billing problem. Check your plan, then try again.';
+    case 'rate_limit':
+      return 'Rate limited. Wait a minute and send again.';
+    case 'overloaded':
+      return 'The service is overloaded right now. Try again shortly.';
+    default:
+      return fallback || `Claude Code reported: ${code}`;
+  }
+}
+
+export function txFromMessage(msg, ctx) {
+  const out = [];
+  if (!msg || typeof msg !== 'object') return out;
+  const agent = msg.parent_tool_use_id || 'main';
+  switch (msg.type) {
+    case 'system':
+      if (msg.subtype === 'init') out.push({ kind: 'system', text: `session ${String(msg.session_id || '').slice(0, 8)} · ${msg.model || 'model'} · ${(msg.slash_commands || []).length} commands`, session: msg.session_id });
+      if (msg.subtype === 'task_notification' && msg.summary) out.push({ kind: 'system', agent: msg.tool_use_id || agent, text: `task ${msg.status}: ${msg.summary}` });
+      break;
+    case 'stream_event': {
+      if (msg.parent_tool_use_id) break;
+      const ev = msg.event || {};
+      if (ev.type === 'message_start' && ev.message) ctx.msgId = ev.message.id;
+      if (ev.type === 'content_block_delta' && ev.delta && ev.delta.type === 'text_delta') {
+        if (ctx.msgId) ctx.streamed.add(ctx.msgId);
+        out.push({ kind: 'delta', id: `${ctx.msgId || 'm'}:${ev.index ?? 0}`, agent, text: ev.delta.text });
+      }
+      break;
+    }
+    case 'assistant': {
+      const m = msg.message || {};
+      if (msg.error) out.push({ kind: 'error', code: msg.error, text: friendlyError(msg.error) });
+      const content = Array.isArray(m.content) ? m.content : [];
+      content.forEach((block, i) => {
+        if (block.type === 'text' && !msg.parent_tool_use_id && !ctx.streamed.has(m.id) && block.text) {
+          out.push({ kind: 'text', id: `${m.id || 'm'}:${i}`, agent, text: block.text });
+        }
+        if (block.type === 'tool_use') out.push({ kind: 'tool', id: block.id, agent, name: block.name, summary: summarize(block.name, block.input) });
+      });
+      break;
+    }
+    case 'user': {
+      const content = msg.message && Array.isArray(msg.message.content) ? msg.message.content : [];
+      for (const block of content) {
+        if (block && block.type === 'tool_result' && block.is_error) out.push({ kind: 'tool-error', id: block.tool_use_id, agent, text: toText(block.content).slice(0, 400) });
+      }
+      break;
+    }
+    case 'result':
+      out.push({
+        kind: 'result',
+        ok: !msg.is_error,
+        subtype: msg.subtype,
+        cost: typeof msg.total_cost_usd === 'number' ? msg.total_cost_usd : null,
+        turns: msg.num_turns ?? null,
+        ms: msg.duration_ms ?? null,
+        session: msg.session_id,
+        text: msg.is_error ? toText(msg.result || msg.errors || msg.subtype) : '',
+      });
+      break;
+  }
+  return out;
+}
+
+function toText(c) {
+  if (typeof c === 'string') return c;
+  if (Array.isArray(c)) return c.map((x) => (typeof x === 'string' ? x : x && x.text ? x.text : '')).join(' ');
+  return c == null ? '' : JSON.stringify(c);
+}

package/server/preflight.mjs

@@ -0,0 +1,59 @@
+// Onboarding preflight: is this machine ready to drive Claude Code here?
+import { run, json } from './sh.mjs';
+import { repoInfo } from './repo.mjs';
+
+export async function preflight(repo) {
+  const [ver, auth, gh, info] = await Promise.all([
+    run('claude', ['--version']),
+    run('claude', ['auth', 'status', '--json'], { timeout: 15000 }),
+    run('gh', ['auth', 'status']),
+    repoInfo(repo),
+  ]);
+  const a = json(auth.stdout) || {};
+  const checks = [
+    {
+      id: 'claude',
+      label: 'Claude Code installed',
+      ok: ver.ok,
+      detail: ver.ok ? ver.stdout.trim() : 'Not found on PATH.',
+      fix: ver.ok ? null : 'Install Claude Code (https://claude.com/claude-code), then reopen this page.',
+    },
+    {
+      id: 'login',
+      label: 'Logged in',
+      ok: !!a.loggedIn,
+      detail: a.loggedIn ? [a.authMethod, a.subscriptionType].filter(Boolean).join(' · ') : 'Not logged in.',
+      fix: a.loggedIn ? null : 'Run `claude` in a terminal, then /login.',
+    },
+    {
+      id: 'gh',
+      label: 'GitHub CLI signed in',
+      ok: gh.ok,
+      optional: true,
+      detail: gh.ok ? firstLine(gh.stdout + gh.stderr, /Logged in to .*/) : gh.missing ? 'gh not installed.' : 'Not signed in.',
+      fix: gh.ok ? null : 'Optional, for the cloud loop and PRs: install gh, then `gh auth login`.',
+    },
+    {
+      id: 'remote',
+      label: 'Git remote',
+      ok: !!info.remote,
+      optional: true,
+      detail: info.remote || (info.isGit ? 'No origin remote.' : 'This folder is not a git repo.'),
+      fix: info.remote ? null : info.isGit ? 'Add one: `git remote add origin <url>`.' : 'Run the GUI from inside your project, or `git init` first.',
+    },
+    {
+      id: 'adopted',
+      label: 'nexus adopted',
+      ok: info.adopted,
+      optional: true,
+      detail: info.adopted ? 'agents.md, plan/ and .claude/commands present.' : 'Not yet.',
+      fix: info.adopted ? null : 'Use "Adopt nexus" below, or give the prompt to your agent.',
+    },
+  ];
+  return { checks, info, ready: checks.filter((c) => !c.optional).every((c) => c.ok) };
+}
+
+function firstLine(text, re) {
+  const m = re.exec(text);
+  return m ? m[0].trim() : text.trim().split(/\r?\n/)[0] || '';
+}