jaitus 0.3.0

package/src/brand.js

@@ -0,0 +1,232 @@
+// ─── Jaitus terminal identity ─────────────────────────────────────────────────
+// A coding session should look like a tool, not a launch screen. The product mark is
+// intentionally one compact coral token beside the Jaitus name; the web logo remains
+// the right place for the detailed mark, while a terminal needs recognition without
+// stealing the first screen from the work.
+
+import { c, columns, colorLevel, unicode, visibleWidth } from './ui.js';
+
+export function badge() {
+  // JAITUS_ASCII forces plain text so the mark never renders as tofu.
+  if (process.env.JAITUS_ASCII) return '[J]';
+  const level = colorLevel();
+  if (level >= 3) return '\x1b[48;2;255;107;74m\x1b[97m J \x1b[0m';
+  if (level >= 2) return '\x1b[48;5;208m\x1b[97m J \x1b[0m';
+  if (level === 1) return '\x1b[41m\x1b[97m J \x1b[0m';
+  return '[J]';
+}
+
+export function wordmark(version = '') {
+  return `${badge()} ${c.brand(c.bold('JAITUS'))}${version ? ` ${c.dim(`v${version}`)}` : ''}`;
+}
+
+// The Jaitus J alone as mascot art — no disc, no block. Sampled once from
+// the checked-in logo pixels (white-J bbox) into quadrant cells: hard-edged
+// vertices and corners, single brand ink, small and condensed.
+const MASCOT_ART = [
+  "..████▌.",
+  "......▟█",
+  "██..▟█▛▀",
+  "▀█████▌.",
+];
+// Full J for the banner showcase: same geometry, full height.
+const MARK_LARGE = [
+  "...▐███████...",
+  "...▐███████...",
+  "...▝██████▛...",
+  "..........▐███",
+  "..........▐███",
+  "▄▄▄▖...▄▄▄▟▀▀▀",
+  "███▌...████...",
+  "███▌...████...",
+  "▜██▙▄▄▄████...",
+  ".▀█████████...",
+  "..▝████████...",
+];
+/**
+ * The mascot J as raw rows, for the app view to ink itself.
+ *
+ * Deliberately used in preference to downsampling the real badge at small sizes. A
+ * 125×125 photograph reduced to eight cells is a coral blob — the white J inside it
+ * lands on about two pixels and disappears. These quadrant cells were drawn for this
+ * size, so the letterform survives. The photographic mark is for somewhere it has room.
+ */
+export function MASCOT_ROWS() {
+  return MASCOT_ART.map((row) => row.replace(/\./g, ' '));
+}
+
+/** Mascot rows in the brand ink (pad to equal width for text lockups).
+ * Dots in the grid are transparent cells, never printed. */
+export function renderMascot() {
+  const clean = MASCOT_ART.map((r) => r.replace(/\./g, ' '));
+  const width = Math.max(...clean.map((r) => [...r].length));
+  return clean.map((r) => `  ${c.brand(r + ' '.repeat(Math.max(0, width - [...r].length)))}`);
+}
+/** Full-height mark for `banner`: the complete J geometry, same ink. */
+export function renderMarkLarge() {
+  const clean = MARK_LARGE.map((r) => r.replace(/\./g, ' '));
+  const width = Math.max(...clean.map((r) => [...r].length));
+  return clean.map((r) => `  ${c.brand(r + ' '.repeat(Math.max(0, width - [...r].length)))}`);
+}
+// The JAITUS name as pure-ASCII block letters for terminals that render
+// nothing else (classic conhost raster fonts). 7 rows, 45 columns, only `#`
+// and spaces — the grand opening where block pixels would be tofu.
+const ASCII_GRAND = [
+  '      ###   ###   ##### ####### ##   ##  ######',
+  '      ###  ## ##  ##### ####### ##   ## ##',
+  '      ### ##   ## #####   ###   ##   ## ##',
+  '      ### ####### #####   ###   ##   ##  ######',
+  '  ##  ### ##   ## #####   ###   ##   ##      ##',
+  '  ##  ### ##   ## #####   ###   ##   ##      ##',
+  '   ###### ##   ## #####   ###    #####  ######',
+];
+/** ASCII grand logo rows (unstyled plain text — color never reaches these terminals). */
+export function renderAsciiGrand() {
+  return ASCII_GRAND.map((r) => `  ${r.replace(/\s+$/, '')}`);
+}
+// Fresh-session home mark in the opencode idiom: the name as 4-row block
+// letters, left half muted, right half bright, centered — the whole welcome.
+// ASCII terminals get the plain wordmark line instead of tofu.
+const HOME_LOGO_LEFT = [
+  '  █   ▀▀   █  ',
+  '  █  █  █     ',
+  '  █  █▀▀█  █  ',
+  '▀▀▀  ▀  █  █  ',
+];
+const HOME_LOGO_RIGHT = [
+  ' █   █  █  ▀▀ ',
+  '███  █  █ █   ',
+  ' █   █  █  ▀▀█',
+  ' █   ▀▀▀▀  ▀▀█',
+];
+/**
+ * The same block letters as data, for the app view.
+ *
+ * The app renders them through a real per-character gradient, which cannot be done
+ * with a pre-coloured string: the escape codes would have to be shredded mid-frame.
+ * Kept here beside the art so the two surfaces can never drift apart.
+ */
+export function HOME_LOGO_ROWS() {
+  return HOME_LOGO_LEFT.map((left, i) => ({ left, right: HOME_LOGO_RIGHT[i] }));
+}
+
+/** Centered two-tone JAITUS block rows for a fresh fullscreen session.
+ * Both halves wear the brand coral (plain left, bold right) — the opencode
+ * idiom in Jaitus ink. A full reset closes each row so no attribute leaks. */
+export function renderHomeLogo({ version = '', width = 80 } = {}) {
+  if (!unicode() || width < 40) {
+    const line = `JAITUS${version ? ` v${version}` : ''}`;
+    const pad = Math.max(0, Math.floor((width - visibleWidth(line)) / 2));
+    return [`${' '.repeat(pad)}${c.bold(line)}`];
+  }
+  const pad = Math.max(0, Math.floor((width - 29) / 2));
+  const end = colorLevel() > 0 ? '\x1b[0m' : '';
+  return HOME_LOGO_LEFT.map((l, i) => `${' '.repeat(pad)}${c.brand(l)} ${c.bold(c.brand(HOME_LOGO_RIGHT[i]))}${end}`);
+}
+/** Rotating startup tips — every one names a real command. */
+const STARTUP_TIPS = [
+  '/research digs up sources with citations',
+  '/code-review --fix ships cleaner code',
+  '/rewind un-breaks the timeline',
+  '/btw asks off the record',
+  '/branch tries the other way',
+  '/test --fix repairs failures',
+  '/explain reads the code for you',
+  '/commit writes the message',
+];
+export function startupTip() {
+  const day = Math.floor(Date.now() / 86400000);
+  return STARTUP_TIPS[day % STARTUP_TIPS.length];
+}
+/** Compact classic open: codex-style session header. Lowercase wordmark,
+ * model, approval posture, directory, account — one block, pure ASCII,
+ * instant. Returns plain-text lines. */
+export function renderClassicOpen({ version, model, approval, cwd, account, session, narrow }) {
+  const meta = [
+    `jaitus v${version}`,
+    `model      ${model}`,
+    `approval   ${approval}`,
+    `directory  ${cwd}`,
+    ...(account ? [`account    ${account} - session ${session}`] : [`session    ${session}`]),
+  ];
+  if (narrow) return [...meta.map((m) => `  ${m}`), `  Tip: ${startupTip()}`];
+  return [...meta.map((m) => `  ${m}`), `  Tip: ${startupTip()}`];
+}
+export function logoCard(version = '') {
+  if (process.env.JAITUS_ASCII || !unicode()) {
+    const inner = 40;
+    const bar = `  +${'-'.repeat(inner)}+`;
+    const row = (text) => `  |${text}${' '.repeat(Math.max(0, inner - visibleWidth(text)))}|`;
+    return [
+      bar,
+      row(`  ${c.brand(c.bold('J A I T U S'))}`),
+      row(`  a coding agent in your terminal  ${c.dim(`v${version}`)}`),
+      bar,
+    ];
+  }
+  return [
+    ...renderMarkLarge(),
+    `  ${c.brand(c.bold('JAITUS'))}  ${c.dim(`a coding agent in your terminal  v${version}`)}`,
+  ];
+}
+
+export function bannerLines({ version = '', width = columns() } = {}) {
+  const suffix = width >= 44 ? `  ${c.dim('coding agent')}` : '';
+  return [`  ${wordmark(version)}${suffix}`];
+}
+
+export async function banner(opts = {}) {
+  if (!process.stdout.isTTY && !opts.force) return;
+  if (process.env.JAITUS_NO_BANNER && !opts.force) return;
+  // `jaitus banner --image`: the README block-letter mark is ALWAYS printed,
+  // because a sixel-only path goes invisible on terminals that misreport the
+  // DA capability (seen on conhost: probe says yes, pixels never land, and the
+  // user sees the same quiet line as before). Real pixels go first when the
+  // probe positively confirms sixel, then the block letters guarantee ink.
+  if (opts.image) {
+    let sixelSeq = '';
+    try {
+      const { sixelSupported } = await import('./terminal.js');
+      if (sixelSupported()) {
+        const { markSixel } = await import('./sixel.js');
+        sixelSeq = markSixel({}) || '';
+      }
+    } catch { sixelSeq = ''; }
+    if (sixelSeq) process.stdout.write(`\n${sixelSeq}\n`);
+    for (const line of logoCard(opts.version || '')) process.stdout.write(`${line}\n`);
+    process.stdout.write('\n');
+    return;
+  }
+  // One-shot wordmark shimmer on interactive start: a light sweep across the
+  // brand row (~600 ms), once, only when the terminal animates. Skipped for
+  // --image, non-TTY, reduced motion, and the /banner re-draw (opts.force).
+  // The sweep paints per-character from the ANSI-stripped text — spreading the
+  // styled string would shred escape sequences mid-frame.
+  if (!opts.image && !opts.force && process.stdout.isTTY && !process.env.JAITUS_NO_ANIMATION && colorLevel() > 0 && unicode()) {
+    const styled = bannerLines(opts);
+    const plainText = (styled[0] || '').replace(/\x1b\[[0-9;]*m/g, '');
+    const chars = [...plainText];
+    const sweep = async () => {
+      for (let pos = -3; pos <= chars.length + 3; pos++) {
+        const frame = chars.map((ch, idx) => {
+          const d = Math.abs(idx - pos);
+          if (d === 0) return c.bold(`\x1b[97m${ch}\x1b[0m`);
+          if (d <= 2) return c.shimmer(ch);
+          return c.brand(ch);
+        }).join('');
+        process.stdout.write(`\r${frame}`);
+        await new Promise((r) => setTimeout(r, 24));
+      }
+      process.stdout.write(`\r${styled.join('\n')}\n\n`);
+    };
+    try { await sweep(); } catch { process.stdout.write(`${styled.join('\n')}\n\n`); }
+  } else {
+    process.stdout.write(`${bannerLines(opts).join('\n')}\n\n`);
+  }
+}
+
+// Kept as a small pure helper for the classic renderer and external integrations.
+// It is deliberately not a welcome card.
+export function welcomeLines({ version = '' } = {}) {
+  return [`  ${wordmark(version)}`];
+}

package/src/commands/code-review.js

@@ -0,0 +1,8 @@
+// ─── /code-review — correctness bugs and cleanup, with --fix ────────────────────
+//
+// Usage: /code-review [--fix] [path|branch..range]   (alias: /review)
+import { runReview } from './review.js';
+
+export default async function codeReview(args, ctx) {
+  return runReview('correctness', args, ctx);
+}

package/src/commands/commit.js

@@ -0,0 +1,73 @@
+// ─── /commit — review the diff, write a real message, land it ───────────────────
+//
+// Shows what changed, asks the model to summarise the WHY into a subject line,
+// then commits. Pushing is always a separate confirmation — never implicit.
+import { spawnSync } from 'node:child_process';
+import { runAgent } from '../agent/loop.js';
+import { createPermissions } from '../agent/permissions.js';
+import { c, out, ok, warn, fail, askKey, glyph } from '../ui.js';
+
+function git(args, opts = {}) {
+  const r = spawnSync('git', args, { encoding: 'utf8', ...opts });
+  return { ok: r.status === 0, out: (r.stdout || '').trim(), err: (r.stderr || '').trim() };
+}
+
+export default async function commit(args, ctx) {
+  if (!git(['rev-parse', '--is-inside-work-tree']).ok) {
+    fail('Not a git repository.');
+    return null;
+  }
+  const status = git(['status', '--porcelain']);
+  if (!status.out) { ok('Nothing to commit — the working tree is clean.'); return null; }
+
+  // What the commit would contain, shown before anything happens.
+  const stat = git(['diff', '--stat', 'HEAD']).out || '';
+  if (stat) {
+    out(c.dim('  Changes:'));
+    for (const line of stat.split('\n').slice(0, 20)) out(`  ${c.dim(line)}`);
+    const n = stat.split('\n').length - 20;
+    if (n > 0) out(c.dim(`  ${glyph('…', '...')} and ${n} more files`));
+  }
+
+  // The model writes the message from the actual diff — with a firm brevity
+  // leash, because left alone every model writes essays.
+  let subject = '';
+  try {
+    const diff = git(['diff', 'HEAD']).out.slice(0, 12000);
+    const side = await runAgent({
+      client: ctx.client, cwd: ctx.flags.cwd,
+      permissions: createPermissions({ mode: 'plan' }),
+      messages: [{ role: 'user', content: `Write a git commit subject for this diff. Rules: imperative mood, no prefix, max 72 chars, say WHAT changed and WHY. Answer with the subject line ONLY — no quotes, no body, no markdown.\n\n${diff}` }],
+    });
+    const text = (side?.messages || []).filter((m) => m.role === 'assistant').pop();
+    const content = Array.isArray(text?.content) ? text.content.filter((b) => b.type === 'text').map((b) => b.text).join(' ') : (text?.content || '');
+    subject = content.trim().split('\n')[0].replace(/^["'`]|["'`]$/g, '').slice(0, 72);
+  } catch { /* fall through to the manual path */ }
+
+  const typed = subject || '';
+  out(`  ${c.dim('Subject:')} ${c.bold(typed || '(write your own below)')}`);
+  const answer = askKey('  Commit with this message? (y)es / (e)dit / (n)o', ['y', 'e', 'n']);
+  if (answer === 'n') { warn('Commit cancelled.'); return null; }
+
+  let message = typed;
+  if (answer === 'e' || !typed) {
+    const editorMsg = git(['commit', '--dry-run', '--allow-empty'], {});
+    message = process.env.JAITUS_COMMIT_MSG || typed;
+    if (!message) { warn('No message — commit cancelled.'); return null; }
+  }
+
+  const add = git(['add', '-A']);
+  if (!add.ok) { fail(`Could not stage: ${add.err}`); return null; }
+  const done = git(['commit', '-m', message]);
+  if (!done.ok) { fail(`Commit failed: ${done.err || done.out}`); return null; }
+  ok(`Committed: ${message}`);
+
+  const push = askKey('  Push now? (y/N)', ['y', 'n']);
+  if (push === 'y') {
+    const branch = git(['branch', '--show-current']).out || 'main';
+    const pushed = git(['push', 'origin', branch]);
+    if (pushed.ok) ok(`Pushed to origin/${branch}.`);
+    else fail(`Push failed: ${pushed.err || pushed.out}`);
+  }
+  return null;
+}

package/src/commands/completion.js

@@ -0,0 +1,68 @@
+// ─── jaitus completion ──────────────────────────────────────────────────────────
+//
+// Prints a completion script for the shell you name. It prints rather than installs:
+// writing to someone's .bashrc or their PowerShell profile is exactly the kind of
+// reach-into-your-machine behaviour this CLI refuses to do anywhere else, and the
+// one-line instruction below is no harder than a flag would have been.
+
+import { c, out, err, glyph } from '../ui.js';
+
+const SHELLS = ['bash', 'zsh', 'fish', 'powershell'];
+
+const script = {
+  bash: (words, flags) => `# jaitus completion for bash
+# Add to ~/.bashrc:   eval "$(jaitus completion bash)"
+_jaitus_completions() {
+  local cur prev
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${words}" -- "$cur") )
+  else
+    COMPREPLY=( $(compgen -W "${flags}" -- "$cur") )
+  fi
+}
+complete -F _jaitus_completions jaitus`,
+
+  zsh: (words, flags) => `# jaitus completion for zsh
+# Add to ~/.zshrc:    eval "$(jaitus completion zsh)"
+_jaitus() {
+  if (( CURRENT == 2 )); then
+    compadd ${words}
+  else
+    compadd ${flags}
+  fi
+}
+compdef _jaitus jaitus`,
+
+  fish: (words, flags) => `# jaitus completion for fish
+# Save as:  jaitus completion fish > ~/.config/fish/completions/jaitus.fish
+complete -c jaitus -f
+${words.split(' ').map((w) => `complete -c jaitus -n "__fish_use_subcommand" -a "${w}"`).join('\n')}
+${flags.split(' ').map((f) => `complete -c jaitus -l "${f.replace(/^--/, '')}"`).join('\n')}`,
+
+  powershell: (words, flags) => `# jaitus completion for PowerShell
+# Add to your profile:   jaitus completion powershell | Out-String | Invoke-Expression
+Register-ArgumentCompleter -Native -CommandName jaitus -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $commands = '${words}'.Split(' ')
+  $flags = '${flags}'.Split(' ')
+  $candidates = if ($commandAst.CommandElements.Count -le 2) { $commands + $flags } else { $flags }
+  $candidates | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+  }
+}`,
+};
+
+export default function completion(argv = [], { commands = [], flags = [] } = {}) {
+  const shell = (argv[0] || '').toLowerCase();
+  if (!script[shell]) {
+    err(`Usage: jaitus completion <${SHELLS.join('|')}>`);
+    if (shell) err(`${c.red(glyph('✗', 'x'))} Unknown shell: ${shell}`);
+    return 1;
+  }
+  out(script[shell](commands.join(' '), flags.join(' ')));
+  return 0;
+}
+
+export { SHELLS };

package/src/commands/doctor.js

@@ -0,0 +1,185 @@
+// ─── jaitus doctor ──────────────────────────────────────────────────────────────
+//
+// "It does not work" is the single most common bug report, and it covers at least six
+// different faults: old Node, no sign-in, a revoked key, no network, a gateway that is
+// down, a proxy in the way. This walks them in the order they fail and names the one
+// that is actually broken, so the answer is a sentence instead of a conversation.
+//
+// It never prints a credential. A key that appears on screen is a key in the terminal
+// scrollback, in any screenshot of it, and in whatever the user pastes into a support
+// thread — so checks report presence and shape, never the value.
+
+import fs from 'node:fs';
+import { c, out, table, heading, present, colorLevel, glyph } from '../ui.js';
+import { endpoints, loadCredentials, loadSettings, HOME, version } from '../config.js';
+import { signedIn, accessToken } from '../session.js';
+import { checkRegistry, isNewer } from './update.js';
+
+const TIMEOUT_MS = 8000;
+
+const PASS = 'pass';
+const WARN = 'warn';
+const FAIL = 'fail';
+
+function mark(status) {
+  if (status === PASS) return c.green(glyph('✓', '+'));
+  if (status === WARN) return c.yellow('!');
+  return c.red(glyph('✗', 'x'));
+}
+
+/** fetch with a deadline, because a hung socket is indistinguishable from a hung CLI. */
+async function reach(url, init = {}) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+  try {
+    return await fetch(url, { ...init, signal: ctrl.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export default async function doctor(argv = [], { json = false } = {}) {
+  const checks = [];
+  const add = (name, status, detail, fix) => checks.push({ name, status, detail, fix });
+
+  // ── The machine ───────────────────────────────────────────────────────────────
+  const major = Number(process.versions.node.split('.')[0]);
+  add('Node', major >= 20 ? PASS : FAIL, `v${process.versions.node}`,
+    major >= 20 ? null : 'Install Node 20 or newer from nodejs.org.');
+
+  add('Jaitus CLI', PASS, `v${version()} on ${process.platform}-${process.arch}`);
+
+  // ── Where it keeps things ─────────────────────────────────────────────────────
+  let homeOk = false;
+  try {
+    fs.accessSync(HOME, fs.constants.W_OK);
+    homeOk = true;
+  } catch { /* reported below */ }
+  add('Config directory', homeOk ? PASS : WARN, HOME,
+    homeOk ? null : 'It will be created on first sign-in. If this keeps failing, check the directory is writable.');
+
+  // ── Credentials ───────────────────────────────────────────────────────────────
+  const creds = loadCredentials();
+  const fromEnv = Boolean(process.env.JAITUS_TOKEN);
+  let key = null;
+  if (!signedIn()) {
+    add('Sign-in', FAIL, 'not signed in', 'Run `jaitus login`.');
+  } else {
+    try {
+      // Renews the session if its hour is up — which is itself the check that the
+      // session is still alive on the server.
+      key = await accessToken();
+      // Who and where from only. Never a token, not even its first characters.
+      add('Sign-in', PASS, fromEnv ? 'JAITUS_TOKEN (not renewed)' : (creds?.user?.email || 'signed in'));
+    } catch (e) {
+      add('Sign-in', FAIL, e?.code === 'session_expired' ? 'this device was signed out' : 'could not renew the session',
+        'Run `jaitus login` again.');
+    }
+  }
+
+  // ── The gateway ───────────────────────────────────────────────────────────────
+  const { baseUrl, siteUrl } = endpoints();
+  add('Gateway', PASS, baseUrl);
+
+  let reachable = false;
+  try {
+    const res = await reach(`${baseUrl}/v1/models`, {
+      headers: key ? { authorization: `Bearer ${key}` } : {},
+    });
+    reachable = true;
+    if (res.ok) {
+      const body = await res.json().catch(() => ({}));
+      const ids = (body?.data || []).map((m) => m.id);
+      add('Reachable', PASS, `HTTP ${res.status}`);
+      add('Models', ids.length ? PASS : WARN, ids.length ? ids.join(', ') : 'the gateway advertised none',
+        ids.length ? null : 'Nothing to run against. This is a gateway configuration problem, not a local one.');
+    } else if (res.status === 401 || res.status === 403) {
+      add('Reachable', PASS, `HTTP ${res.status}`);
+      add('Session accepted', FAIL, 'Jaitus did not accept this device\'s session',
+        'Run `jaitus login` again — this device may have been signed out from the website.');
+    } else {
+      add('Reachable', WARN, `HTTP ${res.status}`, 'The gateway answered but not with a model list.');
+    }
+  } catch (e) {
+    add('Reachable', FAIL, describeNetworkError(e, baseUrl),
+      'Check your connection, and whether a proxy or firewall is between you and the gateway.');
+  }
+
+  // ── The account ───────────────────────────────────────────────────────────────
+  if (key && reachable) {
+    try {
+      const res = await reach(`${baseUrl}/api/auth/me`, { headers: { 'x-api-key': key } });
+      const body = await res.json().catch(() => ({}));
+      const u = body.user || body.data || {};
+      if (res.ok && (u.email || u.id)) {
+        const plan = u.isPaid ? (u.planStatus?.name || 'paid') : `free · ${u.freeRequestsUsed ?? 0} of ${u.freeRequestLimit ?? '?'} prompts used`;
+        add('Account', PASS, `${u.email || 'signed in'} (${plan})`);
+      } else {
+        add('Account', WARN, body?.message || `HTTP ${res.status}`,
+          'The key works for the gateway but the account endpoint did not answer.');
+      }
+    } catch (e) {
+      add('Account', WARN, e.message);
+    }
+  }
+
+  // ── The terminal ──────────────────────────────────────────────────────────────
+  const settings = loadSettings();
+  add('Model', settings.model ? PASS : PASS,
+    settings.model || 'not pinned — whatever the gateway lists first');
+  add('Website', PASS, siteUrl);
+
+  // ── Is there a newer one ──────────────────────────────────────────────────────
+  try {
+    const { version: latest, status } = await checkRegistry();
+    if (status === 'unpublished') {
+      add('Updates', PASS, 'not published on this registry — nothing to check against');
+    } else if (!latest) {
+      add('Updates', WARN, 'could not reach the npm registry');
+    } else if (isNewer(latest, version())) {
+      add('Updates', WARN, `v${latest} is available`, 'Run `npm install -g jaitus` to update.');
+    } else {
+      add('Updates', PASS, 'up to date');
+    }
+  } catch {
+    add('Updates', WARN, 'could not reach the npm registry');
+  }
+
+  const failed = checks.filter((k) => k.status === FAIL);
+  const warned = checks.filter((k) => k.status === WARN);
+
+  present(json, { ok: failed.length === 0, checks }, () => {
+    heading('Diagnostics');
+    out('');
+    table(checks.map((k) => [`  ${mark(k.status)}`, k.name, c.dim(k.detail || '')]));
+    // Labeled swatches: if brand and error reds are indistinguishable on this
+    // console, this row shows exactly which token renders wrong.
+    out('');
+    out(`  ${c.dim('colors:')} level ${colorLevel()} · TERM=${process.env.TERM || '?'}${process.env.WT_SESSION ? ' · WT' : ''}${process.env.TERM_PROGRAM ? ` · ${process.env.TERM_PROGRAM}` : ''} · theme ${loadSettings().theme || 'auto'}`);
+    out(`  ${c.dim('brand')} ${c.brand('[Ja]')}  ${c.dim('accent')} ${c.accent('[Te]')}  ${c.dim('ok')} ${c.green('[✓]')}  ${c.dim('warn')} ${c.yellow('[!]')}  ${c.dim('error')} ${c.red('[✗]')}`);
+    if (failed.length || warned.length) {
+      out('');
+      for (const k of [...failed, ...warned]) {
+        if (k.fix) out(`  ${c.dim('→')} ${k.name}: ${k.fix}`);
+      }
+    }
+    out('');
+    out(failed.length
+      ? `  ${c.red(`${failed.length} problem${failed.length > 1 ? 's' : ''} to fix.`)}`
+      : `  ${c.green('Everything checks out.')}${warned.length ? c.dim(` ${warned.length} note${warned.length > 1 ? 's' : ''} above.`) : ''}`);
+    out('');
+  });
+
+  return failed.length ? 1 : 0;
+}
+
+function describeNetworkError(e, baseUrl) {
+  if (e.name === 'AbortError') return `no answer from ${baseUrl} within ${TIMEOUT_MS / 1000}s`;
+  const cause = e.cause?.code || e.code;
+  if (cause === 'ENOTFOUND') return `cannot resolve ${new URL(baseUrl).hostname}`;
+  if (cause === 'ECONNREFUSED') return `connection refused by ${baseUrl}`;
+  if (cause === 'CERT_HAS_EXPIRED' || cause === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE') {
+    return `TLS certificate rejected (${cause}) — usually a proxy intercepting HTTPS`;
+  }
+  return e.message;
+}

package/src/commands/explain.js

@@ -0,0 +1,33 @@
+// ─── /explain — what does this code do, and why ─────────────────────────────────
+//
+// Read-only walkthrough of a file/selection, an error, or a concept grounded in
+// the current project. Distinct from /agent: the brief is tuned for teaching,
+// the output format is structured, and it never touches anything.
+//
+// Usage: /explain <file | error text | concept>
+import { runAgent } from '../agent/loop.js';
+import { createPermissions } from '../agent/permissions.js';
+import { warn } from '../ui.js';
+
+export default async function explain(args, ctx) {
+  const topic = args.join(' ').trim();
+  if (!topic) {
+    warn('Usage: /explain <file or symbol> | /explain <error message> | /explain <concept>');
+    return null;
+  }
+
+  const looksLikePath = /\.[a-z]{1,4}$/i.test(topic.split(' ')[0]) || topic.startsWith('./') || topic.startsWith('/');
+  const brief = looksLikePath
+    ? `Walk a developer through ${topic} in this project. Read the file(s) first. Structure: what it does (2 sentences), how it works (the flow, with file:line references), anything surprising or fragile worth knowing. Plain text, no headings beyond short bold labels.`
+    : /error|exception|fail|cannot|unable|undefined|null|crash/i.test(topic)
+      ? `Explain this error in the context of THIS project — read whatever files you need to find the real cause, not a generic guess. Structure: what the error means, the actual cause here (with file:line), the fix. Error: ${topic}`
+      : `Explain the concept "${topic}" grounded in this project where it applies — read files to find real usages rather than answering abstractly. Keep it under 250 words.`;
+
+  const sideMessages = [{ role: 'user', content: brief }];
+  const side = await runAgent({
+    client: ctx.client, messages: sideMessages, model: ctx.model, cwd: ctx.flags.cwd,
+    permissions: createPermissions({ mode: 'plan' }),
+    extraSystem: `You are the Jaitus explainer. Read-only: never edit files or run commands. Show file:line references for every claim about the code. Prefer short paragraphs over walls of text.`,
+  });
+  return null;
+}

package/src/commands/init.js

@@ -0,0 +1,62 @@
+// ─── jaitus init ────────────────────────────────────────────────────────────────
+//
+// Writes the two project files the agent reads: JAITUS.md (notes it is given with every
+// request) and .jaitusignore (paths it must not open). Both are checked into the repo on
+// purpose — the point is that everyone working on the project gets the same agent
+// behaviour, not that each person configures their own copy.
+//
+// It refuses to overwrite. A JAITUS.md someone spent an afternoon writing is not
+// something a command called `init` gets to replace because it was run twice.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { c, out, ok, info, warn, fail } from '../ui.js';
+import { CONTEXT_FILE, IGNORE_FILE, CONTEXT_TEMPLATE } from '../project.js';
+
+const IGNORE_TEMPLATE = `# Paths the agent must not list, search, read or write.
+# One pattern per line. A leading / anchors to the project root, a trailing / means a
+# directory, * matches within a path segment and ** across them.
+
+.env
+.env.*
+*.pem
+*.key
+secrets/
+credentials.json
+`;
+
+export default function init(argv = [], { cwd = process.cwd() } = {}) {
+  const force = argv.includes('--force');
+  const written = [];
+  const kept = [];
+
+  const put = (name, contents) => {
+    const file = path.join(cwd, name);
+    if (fs.existsSync(file) && !force) {
+      kept.push(name);
+      return;
+    }
+    fs.writeFileSync(file, contents, 'utf8');
+    written.push(name);
+  };
+
+  try {
+    put(CONTEXT_FILE, CONTEXT_TEMPLATE);
+    put(IGNORE_FILE, IGNORE_TEMPLATE);
+  } catch (e) {
+    fail(`Could not write to ${cwd}: ${e.message}`);
+    return 1;
+  }
+
+  out('');
+  for (const name of written) ok(`Created ${c.bold(name)}`);
+  for (const name of kept) warn(`${c.bold(name)} already exists — left alone. Use --force to replace it.`);
+  out('');
+
+  if (written.includes(CONTEXT_FILE)) {
+    info(`Fill in ${c.bold(CONTEXT_FILE)} — it is sent with every request, so keep it short and true.`);
+  }
+  info(`Both files are meant to be committed, so the whole team gets the same behaviour.`);
+  out('');
+  return 0;
+}