quoxcli 0.4.0 → 0.6.0

package/lib/server/installFlow.js

@@ -0,0 +1,168 @@
+/**
+ * `quox server install`: the existing guided installer behind a CLI verb (ONBOARD-P1).
+ *
+ * Not a second installer. Preflight (onboarding/preflight.js), the real runner (installRunner.js: get.quox.ai ->
+ * setup.sh) and the finisher (finish.js: owner account, sign-in, one-time link) are the same modules the Getting
+ * started screen uses; this file only sequences them and turns their events into stage events:
+ *
+ *   preflight  docker  download  compose-up  health  owner  vault  link
+ *
+ * The runner's own stages fold in as: fetch + configure + build -> download, start -> compose-up, health -> health.
+ * `vault` is skipped here (no AI key is taken on argv); the next step is printed.
+ * Nothing is claimed ok that did not answer: health is the runner's own 2xx probe of the auth service.
+ */
+import { resolve } from 'node:path';
+import { QuoxUserError } from '../core/errors.js';
+import { confirmInteractive } from '../core/confirm.js';
+import { runPreflight, preflightPassed, defaultDeps as preflightDeps } from '../quoxon/onboarding/preflight.js';
+import { defaultInstallDir } from '../quoxon/onboarding/installRunner.js';
+import { passwordProblem, emailOk } from '../quoxon/onboarding/finish.js';
+
+export const INSTALL_STAGES = ['preflight', 'docker', 'download', 'compose-up', 'health', 'owner', 'vault', 'link'];
+const FOLD = { fetch: 'download', configure: 'download', build: 'download', start: 'compose-up', health: 'health' };
+export const PLAN_STEPS = [
+  'check Docker, Compose, git, openssl, disk, RAM and ports (read-only)',
+  'download the installer from get.quox.ai and show its SHA256',
+  'clone the Quox source into the install directory',
+  'write secrets (.env) and a self-signed certificate',
+  'download the Quox images',
+  'start the services with docker compose up -d',
+  'wait until the auth service answers /health with a 2xx',
+  'create your owner account and sign in',
+  'print a one-time dashboard sign-in link (10 minutes)'
+];
+const AGAIN = 'quox server install';
+const LINK_HOW = 'quox -p <profile> dashboard (mints a fresh one-time sign-in link), or re-run with --print-login-link';
+
+/** The preflight copy is shared with the TUI ("press r"); the CLI/JSON path speaks CLI. */
+const cliWords = (t) => String(t == null ? t : t).replace(/,? then press r to check again\.?/gi, ` Then run: ${AGAIN}`).replace(/,? then press r( to try again)?\.?/gi, '.').replace(/\s+\./g, '.').replace(/\.\s*\./g, '.');
+/** This verb never installs Docker: the honest offer is a manual one with the doc link. */
+const cliRow = (r) => ({
+  ...r,
+  ...(r.fix ? { fix: cliWords(r.fix) } : {}),
+  ...(r.offer === 'install' ? { offer: 'manual' } : {})
+});
+
+/** First line of stdin, no trailing newline. */
+export async function readPasswordStdin(readStdin) {
+  const first = String(await readStdin()).split(/\r?\n/)[0];
+  if (!first) throw new QuoxUserError('--password-stdin got an empty first line. Pipe the password in, for example: printf %s "$PW" | quox server install --password-stdin', { exitCode: 2, code: 'empty_password' });
+  return first;
+}
+
+export async function defaultReadStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function defaultPrompt(message, type) {
+  const { default: inquirer } = await import('inquirer');
+  const a = await inquirer.prompt([{ type, name: 'v', message, ...(type === 'password' ? { mask: '*' } : {}) }]);
+  return a.v;
+}
+
+export async function defaultMakeInstall({ dir, env = process.env } = {}) {
+  const { realInstall } = await import('../quoxon/onboarding/index.js');
+  return realInstall({ env, installDir: dir });
+}
+
+/**
+ * -> { ok, ... }. Throws QuoxUserError (exit 2) for refusals made before anything changes.
+ * opts: { dir, dryRun, yes, email, passwordStdin }; deps: see defaults; emit(event).
+ */
+export async function runInstallFlow(opts = {}, deps = {}, emit = () => {}) {
+  const d = {
+    runChecks: runPreflight, makeInstall: defaultMakeInstall, confirm: confirmInteractive,
+    isTTY: () => Boolean(process.stdin.isTTY), readStdin: defaultReadStdin,
+    promptEmail: () => defaultPrompt('Owner email', 'input'), promptPassword: () => defaultPrompt('Owner password (hidden)', 'password'),
+    ...deps
+  };
+  const { dryRun = false, yes = false, passwordStdin = false } = opts;
+  const dir = resolve(opts.dir || defaultInstallDir());
+  const printLink = Boolean(opts.printLink);
+  const stage = (s, status, extra = {}) => emit({ type: 'stage', stage: s, status, ...extra });
+  const fail = (failedStage, error, next, extra = {}) => {
+    stage(failedStage, 'fail', { error, next });
+    const res = { ok: false, failedStage, error, next, ...extra };
+    emit({ type: 'result', ...res });
+    return res;
+  };
+
+  // ---- refusals first: nothing has been touched --------------------------------------------------------------
+  if (!dryRun) {
+    if (!yes && !d.isTTY()) throw new QuoxUserError('No terminal to answer y/N here. Read the plan with --dry-run, then re-run with --yes to install.', { exitCode: 2, code: 'no_terminal' });
+    if (!d.isTTY() && !passwordStdin) throw new QuoxUserError('No terminal for the owner password prompt. Pipe it in with --password-stdin (the password is never taken as an argument).', { exitCode: 2, code: 'no_terminal' });
+  }
+
+  // ---- preflight (read-only, also in a dry run) --------------------------------------------------------------
+  stage('preflight', 'running');
+  const rows = (await d.runChecks(preflightDeps(), () => {})).map(cliRow);
+  const dockerRows = rows.filter(r => r.id === 'docker' || r.id === 'compose');
+  const otherRows = rows.filter(r => r.id !== 'docker' && r.id !== 'compose');
+  const nextFor = (rs) => rs.filter(r => r.status === 'fail').map(r => `${r.fix || r.body}`).join(' ');
+  const bad = rows.filter(r => r.status === 'fail');
+  const otherBad = bad.filter(r => r.id !== 'docker' && r.id !== 'compose');
+  if (otherBad.length) return fail('preflight', bad.map(r => r.body).join('; '), `${nextFor(bad)} Then run: ${AGAIN}`, { checks: rows });
+  stage('preflight', 'ok', { detail: otherRows.map(r => r.body).join('; ') });
+  if (bad.length) return fail('docker', bad.map(r => r.body).join('; '), `${nextFor(bad)} Then run: ${AGAIN}`, { checks: rows });
+  stage('docker', 'ok', { detail: dockerRows.map(r => r.body).join('; ') });
+
+  if (dryRun) {
+    emit({ type: 'plan', dir, installerUrl: 'https://get.quox.ai', checks: rows.map(r => ({ id: r.id, status: r.status, body: r.body })), steps: PLAN_STEPS, changed: 'nothing' });
+    const res = { ok: true, dryRun: true };
+    emit({ type: 'result', ...res });
+    return res;
+  }
+
+  // ---- confirm, then collect the owner credentials BEFORE the long install -----------------------------------
+  if (!yes && !(await d.confirm(`Install Quox into ${dir} now?`, { flag: '--yes', purpose: 'install' }))) {
+    const res = { ok: false, declined: true, error: 'not confirmed', next: `Nothing was changed. Run ${AGAIN} --dry-run to see the plan.` };
+    emit({ type: 'result', ...res });
+    return res;
+  }
+  let email = opts.email ? String(opts.email).trim() : null;
+  if (!email && d.isTTY()) email = String(await d.promptEmail()).trim();
+  if (!emailOk(email)) throw new QuoxUserError('A valid owner email is needed: pass --email <address>.', { exitCode: 2, code: 'bad_email' });
+  const password = passwordStdin ? await readPasswordStdin(d.readStdin) : await d.promptPassword();
+  const weak = passwordProblem(password);
+  if (weak) throw new QuoxUserError(`The owner password is not accepted: ${weak}`, { exitCode: 2, code: 'weak_password' });
+
+  // ---- the install itself (the same runner Getting started uses) ----------------------------------------------
+  const { runner, finisher } = await d.makeInstall({ dir });
+  const open = {};
+  const res = await runner.run({
+    onEvent: (e) => {
+      if (e.type === 'log') { emit({ type: 'log', line: e.line }); return; }
+      if (e.type !== 'stage') return;
+      const s = FOLD[e.id]; if (!s) return;
+      if (e.status === 'running') { if (!open[s]) { open[s] = true; stage(s, 'running'); } return; }
+      if (e.status === 'ok' && (e.id === 'build' || e.id === 'start' || e.id === 'health')) { stage(s, 'ok', e.ms != null ? { ms: e.ms } : {}); open[s] = false; }
+    }
+  });
+  if (!res.ok) {
+    const failed = FOLD[res.failedStage] || res.failedStage || 'download';
+    if (res.interrupted) return fail(failed, 'interrupted', `Run ${AGAIN} again; finished steps are kept.`);
+    const next = [res.cause?.next || res.cause?.fix, res.hint || 'Finished steps are kept.', `Then run: ${AGAIN}`].filter(Boolean).join(' ');
+    return fail(failed, res.error || 'the installer failed', next, { logPath: res.logPath, ...(res.dashboardUrl ? { dashboardUrl: res.dashboardUrl } : {}) });
+  }
+
+  // ---- owner account, sign-in, vault, link ---------------------------------------------------------------------
+  stage('owner', 'running');
+  const made = await finisher.createOwner({ email, password });
+  if (!made.ok) {
+    return fail('owner', made.error || 'the owner account was not created',
+      made.existed ? 'An owner already exists on this server. Sign in with: quox login' : `The server is running. Create the owner with: quox setup`, { dashboardUrl: res.dashboardUrl, logPath: res.logPath });
+  }
+  const signed = await finisher.signIn({ email, password });
+  if (!signed.ok) return fail('owner', `owner created, but sign-in failed: ${signed.error}`, 'Sign in with: quox login', { dashboardUrl: res.dashboardUrl, logPath: res.logPath });
+  stage('owner', 'ok', { detail: email });
+  stage('vault', 'skip', { detail: 'no AI key was given here', next: 'Add one with: quox provider connect' });
+  const link = await finisher.loginLink(res.dashboardUrl);
+  if (!link.ok) return fail('link', link.error || 'could not create the sign-in link', `Open ${res.dashboardUrl || 'https://localhost:3000'} and sign in with ${email}.`, { dashboardUrl: res.dashboardUrl, logPath: res.logPath });
+  stage('link', 'ok', { ttlSeconds: link.ttlSeconds, linkIssued: true, ...(printLink ? {} : { linkHow: LINK_HOW }) });
+  const done = { ok: true, dashboardUrl: res.dashboardUrl, link: link.url, installDir: runner.installDir, logPath: res.logPath };
+  const { link: liveLink, ...safe } = done;
+  emit({ type: 'result', ...(printLink ? done : { ...safe, linkIssued: true, linkHow: LINK_HOW }) });
+  return done;
+}

package/lib/server/status.js

@@ -4,6 +4,7 @@
  */
 import { readFileSync, writeFileSync, mkdirSync, appendFileSync, renameSync } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { X509Certificate } from 'node:crypto';
 import { readInstalled } from './install.js';
 
 const STATE_FILE = 'lifecycle-state.json';
@@ -67,6 +68,18 @@ async function getJson(url, fetchImpl, timeout = 3000) {
   } catch (e) { return { ok: false, error: e?.cause?.code || e?.message || 'no answer' }; }
 }
 
+/**
+ * H3: the SHA256 fingerprint of the certificate the edge serves (ssl/quox.crt in the checkout), in the same format
+ * as the `quox connect` card, so the two can be compared by eye or by script. Never throws.
+ */
+export function certFingerprint(repoDir, { read = readFileSync } = {}) {
+  const file = join(repoDir || '', 'ssl', 'quox.crt');
+  try {
+    const c = new X509Certificate(read(file));
+    return { ok: true, file, fingerprint256: c.fingerprint256, validTo: c.validTo };
+  } catch (e) { return { ok: false, file, error: e?.code === 'ENOENT' ? 'no certificate file' : 'could not read the certificate' }; }
+}
+
 /** The running build, from the collector's public /version. */
 export async function runningVersion(collectorUrl, fetchImpl = globalThis.fetch) {
   const r = await getJson(`${collectorUrl.replace(/\/+$/, '')}/version`, fetchImpl);
@@ -99,7 +112,7 @@ export async function gatherStatus({ install, sys, fetchImpl = globalThis.fetch,
   const hist = backups ? readHistory(backups) : [];
   const lastUpdate = [...hist].reverse().find((e) => e.op === 'update' || e.op === 'rollback') || null;
   const state = backups ? readState(backups) : null;
-  return { install, installed, running, services: svc, disk, http, lastUpdate, inFlight: state && state.status === 'running' ? state : null };
+  return { install, installed, running, services: svc, disk, http, cert: certFingerprint(install.repoDir), lastUpdate, inFlight: state && state.status === 'running' ? state : null };
 }
 
 const svcIcon = (s) => (s.state === 'running' ? (s.health && s.health !== 'healthy' ? '⚠' : '✔') : '✖');
@@ -113,6 +126,7 @@ export function statusRows(st) {
   out.push(row('Version', `${i.release || '? no VERSION file'}${i.tag ? ` (${i.tag})` : ''} · checkout ${i.commit || '?'}${i.dirty ? ' · local changes' : ''}`));
   const rv = st.running;
   out.push(row('Running', rv.ok ? `${rv.commit || '?'}${rv.stamped === false ? ' (unstamped build)' : ''}${rv.commit && i.commit && !String(rv.commit).startsWith(i.commit) && !String(i.commit).startsWith(rv.commit) ? ' · differs from the checkout' : ''}` : `? ${rv.error}`));
+  if (st.cert) out.push(row('Certificate', st.cert.ok ? `SHA256 ${st.cert.fingerprint256} · valid to ${st.cert.validTo} (compare with the card \`quox connect\` shows)` : `? ${st.cert.error} (${st.cert.file})`));
   for (const h of st.http) out.push(row(`${h.ok ? '✔' : '✖'} ${h.name}`, `${h.url} · ${h.detail} · ${h.ms}ms`));
   if (!st.services.ok) out.push(row('✖ Services', `? ${st.services.error}`));
   else {

package/lib/toolOutputShape.js

@@ -16,7 +16,7 @@
 import { parsePath } from './quoxon/rows.js';
 
 const BLOCKED = new Set(['__proto__', 'constructor', 'prototype']);
-const GRAMMAR = 'use a.b, a[0], list[field=value] (exact), list[field~text] (contains, any case), list[*].field (that field of every item), list[*].{a,b} (several fields of every item, one call), list[field=value].name, count(list), or several paths at once: total,count(list)';
+const GRAMMAR = 'use . (the whole result), a.b, a[0], list[field=value] (exact), list[field~text] (contains, any case), list[*].field (that field of every item), list[*].{a,b} (several fields of every item, one call), list[field=value].name, count(list), or several paths at once: total,count(list)';
 export const DEFAULT_SAMPLE = 10;
 const COUNT_KEY_RE = /^(status|state|type|kind|level|severity|health|healthy|enabled|active|category|source|platform|os|role|priority|result|outcome|connected|online)$/i;
 
@@ -36,6 +36,9 @@ function splitTopLevel(e) {
   return parts;
 }
 
+// "." is the whole result, as in jq (SEER 2026-11-07: a model wrote --select . and was refused).
+const selectSteps = (x) => (x.trim() === '.' ? [] : parsePath(x));
+
 function parseSelect(expr) {
   const e = String(expr ?? '').trim();
   // GUIDES-FIX: several paths in one call ("total,active_total"): each must be a valid path on its own.
@@ -53,10 +56,10 @@ function parseSelect(expr) {
   const fn = /^([A-Za-z_]+)\s*\(([\s\S]*)\)$/.exec(e);
   if (fn) {
     if (fn[1] !== 'count') return { error: `--select: unknown function ${fn[1]}() (only count); ${GRAMMAR}` };
-    const steps = parsePath(fn[2]);
+    const steps = selectSteps(fn[2]);
     return steps ? { fn: 'count', steps } : { error: `--select: count() needs a path; ${GRAMMAR}` };
   }
-  const steps = parsePath(e);
+  const steps = selectSteps(e);
   return steps ? { steps } : { error: `--select: bad path ${JSON.stringify(e)}; ${GRAMMAR}` };
 }
 
@@ -270,6 +273,59 @@ function smallTopFields(body, found) {
   return Object.keys(out).length ? out : null;
 }
 
+
+/**
+ * OVERSIZED-IDS: the oversized summary used to carry only a sample of whole rows, which a big row (logs, blobs)
+ * pushes out entirely, so the model lost every id/name and answered from another tool (keeper_backup_list,
+ * bob_log_tail). id_index keeps the first ID_INDEX_ROWS rows of every list (top level, or under a top key) reduced
+ * to identifier/status fields, inside ID_INDEX_BUDGET chars in total, and says how many rows were left out.
+ */
+export const ID_INDEX_ROWS = 20;
+export const ID_INDEX_BUDGET = 6000;
+const ID_FIELD_RE = /^(id|name|title|status|state|created_at|started_at|key|host|host_id|hostname|slug|label|kind|type)$|_id$/i;
+const ID_VALUE_MAX = 80;
+
+function idRow(row) {
+  if (!isObj(row)) return (row === null || typeof row === 'object') ? null : (typeof row === 'string' ? row.slice(0, ID_VALUE_MAX) : row);
+  const r = {};
+  for (const [k, v] of Object.entries(row)) {
+    if (BLOCKED.has(k) || !ID_FIELD_RE.test(k)) continue;
+    if (v === null || typeof v === 'object') continue;
+    r[k] = typeof v === 'string' && v.length > ID_VALUE_MAX ? `${v.slice(0, ID_VALUE_MAX)}...` : v;
+  }
+  return r;
+}
+
+function idIndex(body, found) {
+  const lists = [];
+  if (Array.isArray(body)) lists.push(['(root)', body]);
+  else if (isObj(body)) {
+    for (const [k, v] of Object.entries(body)) if (!BLOCKED.has(k) && Array.isArray(v) && v.length) lists.push([k, v]);
+    if (!lists.length && found && found.path) lists.push([found.path, found.list]);
+  }
+  if (!lists.length) return null;
+  // the main list first, then the rest by size
+  const mainPath = found && found.path;
+  lists.sort((a, b) => ((b[0] === mainPath) - (a[0] === mainPath)) || b[1].length - a[1].length);
+  const out = {};
+  let used = 0;
+  for (const [path, list] of lists.slice(0, 8)) {
+    const rows = [];
+    for (const it of list.slice(0, ID_INDEX_ROWS)) {
+      const r = idRow(it);
+      if (r === null || (isObj(r) && !Object.keys(r).length)) continue;
+      const n = jsonLen(r) + 2;
+      if (used + n + 120 > ID_INDEX_BUDGET) break;
+      rows.push(r);
+      used += n;
+    }
+    if (!rows.length) continue;
+    used += 120;
+    out[path] = { total: list.length, shown: rows.length, omitted: list.length - rows.length, rows };
+  }
+  return Object.keys(out).length ? out : null;
+}
+
 export function capInline(value, { maxChars = INLINE_MAX_CHARS } = {}) {
   const size = jsonLen(value);
   if (size <= maxChars) return { value, capped: false };
@@ -299,6 +355,8 @@ export function capInline(value, { maxChars = INLINE_MAX_CHARS } = {}) {
     : `--select '${lp ? `${lp}[field=value].name` : '[0]'}', --select 'count(${lp || ''})' or --select '${lp ? `${lp}[*].field` : '[*].field'}'`;
   const next = `Result is ${fullKb} KB, too large to show whole, so this is the --summary view. For the exact part you need, run the same quox tool exec again with ${example} (or --summary --limit N for a bigger sample)${via ? `; the list is inside ${via}` : ''}. Never read or post-process a saved output with a shell.`;
   const head = { oversized: true, full_size_kb: fullKb, next, top_keys: isObj(body) ? Object.keys(body).slice(0, 40) : undefined };
+  const idx = idIndex(body, found);
+  if (idx) head.id_index = idx;
   const extra = smallTopFields(body, found);
   for (const limit of [DEFAULT_SAMPLE, 5, 3, 1, 0]) {
     const s = summarize(body, { limit });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quoxcli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Quox: the conversational front door to your self-hosted AI agent control plane",
   "type": "module",
   "bin": {
@@ -61,6 +61,7 @@
     "!lib/core/websiteSession.js",
     "!lib/quoxon/whatsnew.md",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "repository": {
@@ -68,7 +69,7 @@
     "url": "git+https://github.com/quoxai/quoxcore.git",
     "directory": "cli"
   },
-  "homepage": "https://cli.quox.ai",
+  "homepage": "https://quox.ai/cli",
   "bugs": {
     "url": "https://github.com/quoxai/quoxcore/issues"
   },

package/vendor/dragonlab/SOURCE

@@ -1,4 +1,4 @@
 repo: quoxai/dragonlab
-commit: 5b478a813554eb80793b848d14da1468ea3bdcef
-branch: HEAD
-files: 52
+commit: a4dda5ef12c417689768664022b8de1245794c56
+branch: integration/companions-vulcan-quoxperticus
+files: 66

package/vendor/dragonlab/design/quoxperticus/v2/quoxperticus-master.svg

@@ -0,0 +1,59 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 480">
+<title>Quoxperticus — the white, crimson and obsidian skill keeper</title>
+<g id="wings">
+<path id="left-wing" fill="#a92339" d="M 322 298 Q 252 207 137 92 L 161 209 L 114 182 L 148 279 L 112 291 L 243 337 Z"/>
+<path id="right-wing" fill="#c12b42" d="M 444 296 Q 510 133 621 78 L 608 192 L 666 170 L 634 269 L 677 277 L 533 338 Z"/>
+<path id="wing-ribs" fill="none" stroke="#666777" stroke-width="12" d="M 322 298 L 137 92 L 161 209 L 148 279 M 322 298 L 161 209 M 444 296 L 621 78 L 608 192 L 634 269 M 444 296 L 608 192"/>
+<path id="wing-tips" fill="#f6f0f2" d="M 126 105 L 137 76 L 165 103 L 145 98 Z M 600 91 L 629 66 L 642 99 L 622 86 Z"/>
+</g>
+<g id="tail">
+<path id="tail-coil" fill="#555763" d="M 447 353 C 521 330 611 352 631 391 C 655 437 576 454 521 432 C 578 438 610 413 593 395 Q 566 368 461 387 Z"/>
+<path id="tail-edge" fill="none" stroke="#eeecef" stroke-width="10" d="M 468 367 C 537 346 611 376 619 404 Q 617 428 563 433"/>
+<path id="tail-blade" fill="#e8374d" d="M 523 431 L 494 406 L 504 443 L 543 447 Z"/>
+</g>
+<g id="body">
+<path id="obsidian-body" fill="#55545f" d="M 315 237 Q 393 210 448 257 L 479 347 Q 475 403 431 418 L 311 413 Q 272 378 292 312 Z"/>
+<path id="chest-armour" fill="#e9e4ea" d="M 340 231 L 407 237 L 436 304 L 415 369 L 367 395 L 324 350 L 319 287 Z"/>
+<path id="chest-joints" fill="none" stroke="#8d8696" stroke-width="7" d="M 325 275 L 417 280 M 324 305 L 430 312 M 336 339 L 419 344 M 351 367 L 399 374"/>
+<path id="legs" fill="#666370" d="M 301 341 L 340 367 L 325 407 L 350 435 L 271 435 L 261 414 Z M 425 360 L 465 345 L 483 410 L 500 434 L 420 434 L 405 413 Z"/>
+<path id="feet-armour" fill="#f1edf1" d="M 273 409 L 319 407 L 342 429 L 271 429 Z M 424 408 L 475 408 L 493 428 L 420 429 Z"/>
+<path id="talons" fill="#161923" d="M 282 416 L 278 432 L 290 427 L 300 415 L 300 432 L 312 428 L 318 417 L 325 433 L 337 428 M 433 416 L 430 432 L 442 428 L 451 415 L 453 432 L 465 428 L 472 417 L 480 432 L 490 428"/>
+</g>
+<g id="neck">
+<path id="neck-black" fill="#53515d" d="M 334 166 L 400 160 Q 437 211 433 267 L 389 292 L 335 261 L 348 214 Z"/>
+<path id="neck-white" fill="#f5eef2" d="M 344 186 L 371 187 Q 384 227 409 261 L 386 281 L 353 252 L 360 216 Z"/>
+<path id="neck-spines" fill="#ede6ef" d="M 399 178 L 442 177 L 423 196 L 450 211 L 428 221 L 457 241 L 432 247 L 449 268 L 416 265 Z"/>
+</g>
+<g id="head">
+<path id="horn-far" fill="#faf4f4" d="M 324 117 L 297 76 L 300 26 L 315 65 L 346 105 Z"/>
+<path id="horn-near" fill="#ffffff" d="M 380 108 L 401 59 L 446 22 L 425 71 L 411 124 Z"/>
+<path id="horn-bands" fill="none" stroke="#292b35" stroke-width="9" d="M 300 65 L 321 69 M 312 91 L 334 89 M 408 66 L 430 61 M 397 90 L 417 91"/>
+<path id="face-armour" fill="#e9e5ed" d="M 304 128 L 339 99 L 384 100 L 419 127 L 409 173 L 381 201 L 326 193 L 293 165 Z"/>
+<path id="crown" fill="#e8334e" d="M 337 113 L 341 73 L 358 96 L 376 60 L 379 101 L 397 85 L 392 125 L 365 116 Z"/>
+<path id="cheek-fins" fill="#faf5f7" d="M 393 143 L 455 114 L 427 151 L 457 148 L 426 174 L 438 186 L 399 190 Z"/>
+<path id="muzzle" fill="#ffffff" d="M 313 163 Q 286 153 271 170 L 280 192 L 323 204 L 358 188 L 352 174 Z"/>
+<path id="nostril" fill="#20212b" d="M 282 172 L 293 168 L 290 180 Z"/>
+<path id="mouth" fill="none" stroke="#6a5265" stroke-width="5" d="M 281 187 Q 314 204 347 184"/>
+</g>
+<g id="panel">
+<path id="panel-shell" fill="#6d626f" d="M 186 309 L 416 309 L 442 367 L 211 367 Z"/>
+<path id="panel-screen" fill="#242333" d="M 199 317 L 406 317 L 425 354 L 218 354 Z"/>
+<path id="panel-rim" fill="none" stroke="#ff6475" stroke-width="7" d="M 186 309 L 416 309 L 442 367 L 211 367 Z"/>
+<path id="skill-cards" fill="#f0e9ee" d="M 224 326 L 258 326 L 264 344 L 230 344 Z M 281 326 L 315 326 L 321 344 L 287 344 Z"/>
+<path id="selected-skill" fill="#ff344f" d="M 341 326 L 379 326 L 385 344 L 347 344 Z"/>
+</g>
+<g id="arms">
+<path id="far-arm" fill="#e5dfe8" d="M 319 248 Q 288 235 267 263 L 251 290 L 228 294 L 223 312 L 272 315 L 287 284 L 325 277 Z"/>
+<path id="near-arm" fill="#f7eff2" d="M 412 250 Q 448 247 451 276 L 417 304 L 382 311 L 369 299 L 389 282 L 411 277 Z"/>
+<path id="finger-claws" fill="#20212b" d="M 232 297 L 225 316 L 240 308 L 249 298 L 245 317 L 260 309 M 377 296 L 367 313 L 385 308 L 393 295 L 390 312 L 407 303"/>
+<path id="arm-scales" fill="none" stroke="#a699ac" stroke-width="6" d="M 281 259 L 298 275 M 421 261 L 438 277"/>
+</g>
+<g id="eyes">
+<path id="far-eye-socket" fill="#080d19" d="M 304 147 C 304 137.0588745 312.0588745 129 322 129 C 331.9411255 129 340 137.0588745 340 147 C 340 156.9411255 331.9411255 165 322 165 C 312.0588745 165 304 156.9411255 304 147 Z"/>
+<path id="far-eye-white" fill="#ffffff" d="M 310 147 C 310 140.372583 315.372583 135 322 135 C 328.627417 135 334 140.372583 334 147 C 334 153.627417 328.627417 159 322 159 C 315.372583 159 310 153.627417 310 147 Z"/>
+<path id="far-pupil" fill="#080d19" d="M 318 145 C 318 138 326 138 326 145 C 326 153 318 153 318 145 Z"/>
+<path id="near-eye-socket" fill="#080d19" d="M 349 147 C 349 134.8497355 358.8497355 125 371 125 C 383.1502645 125 393 134.8497355 393 147 C 393 159.1502645 383.1502645 169 371 169 C 358.8497355 169 349 159.1502645 349 147 Z"/>
+<path id="near-eye-white" fill="#ffffff" d="M 356 147 C 356 138.71572875 362.71572875 132 371 132 C 379.28427125 132 386 138.71572875 386 147 C 386 155.28427125 379.28427125 162 371 162 C 362.71572875 162 356 155.28427125 356 147 Z"/>
+<path id="near-pupil" fill="#080d19" d="M 364 145 C 364 137 373 137 373 145 C 373 154 364 154 364 145 Z"/>
+</g>
+</svg>

package/vendor/dragonlab/design/quoxperticus/v3/character.mjs

@@ -0,0 +1,43 @@
+import {renderSvgRig} from '../../../factory/svg-rig-contour.mjs';
+export const QUOXPERTICUS_CLIPS=Object.freeze([{id:'idle',title:'Quiet Expertise',duration:12000},{id:'attach',title:'At Your Command',duration:3000},{id:'skill',title:'Select a Skill',duration:6000}]);
+export const STORY_DURATION=12000;
+const pulse=(t,a,b)=>t<=a||t>=b?0:Math.sin(Math.PI*(t-a)/(b-a))**2;
+const ease=x=>{x=Math.max(0,Math.min(1,x));return x*x*(3-2*x);};
+export function poseRig(rig,scene,ms){
+ const t=scene==='attach'?ms:ms%(scene==='skill'?6000:12000);
+ const look=scene==='skill'?pulse(t,0,3000):scene==='attach'?pulse(t,200,1900):.25*pulse(t,2000,5500);
+ const tap=scene==='skill'?(t<1800?ease((t-800)/1000):1-ease((t-2200)/1000)):0;
+ const follow=scene==='attach'?pulse(t,700,2800):scene==='idle'?.4*pulse(t,3000,8500):.25*pulse(t,3000,5800);
+ const paths=rig.paths.map(p=>({...p,polygons:p.polygons.map(poly=>poly.map(([x,y])=>{
+  if(p.group==='head'||p.group==='eyes')return [x-2*look,y+7*look];
+  if(p.group==='neck'){const w=Math.max(0,Math.min(1,(285-y)/75));return [x-2*look*w,y+7*look*w];}
+  if(p.id==='near-arm'||p.id==='finger-claws'&&x>350||p.id==='arm-scales'&&x>350){const w=Math.max(0,Math.min(1,(y-250)/45));return [x-12*tap*w,y+20*tap*w];}
+  if(p.group==='wings'){const w=Math.max(0,Math.min(1,(330-y)/240));return [x+(x<380?4:-4)*follow*w,y+5*follow*w];}
+  if(p.group==='tail'){const w=Math.max(0,Math.min(1,(x-460)/150));return [x,y-6*follow*w];}
+  return [x,y];
+ }))}));
+ const active=scene==='skill'&&t>=1800&&t<5000;
+ for(const p of paths)if(p.id==='selected-skill')p.rgb=active?[255,Math.round(70+100*pulse(t,1800,5000)),105]:[145,35,55];
+ if(active){
+  // Trace along the panel's own lower edge, clear of face and claws.
+  const u=Math.min(1,(t-1800)/1800),x=222+204*u,y=359;
+  paths.push({id:'skill-pulse',group:'effect',rgb:[255,230,240],stroke:0,erase:false,polygons:[[[x-4,y],[x,y-4],[x+4,y],[x,y+4]]]});
+ }
+ const map=new Map(paths.map(p=>[p.id,p]));
+ return {...rig,paths,eyes:rig.eyes.map(e=>({...e,socket:map.get(e.socket.id),white:map.get(e.white.id),pupil:map.get(e.pupil.id)}))};
+}
+export function renderQuoxperticus(rig,scene='idle',ms=0,options={}){
+ if(!QUOXPERTICUS_CLIPS.some(c=>c.id===scene))return {ok:false,code:'UNKNOWN_CLIP'};
+ if(!Number.isFinite(ms)||ms<0)return {ok:false,code:'INVALID_TIME'};
+ if(scene==='attach'&&ms>=3000&&!options.still)return renderQuoxperticus(rig,'idle',ms-3000,options);
+ const t=options.still?({idle:4000,attach:1200,skill:2200}[scene]):ms;
+ const caption=scene==='attach'?'Skills at your command.':scene==='skill'?'Select. Illuminate. Connect.':'Ready when you are.';
+ return {...renderSvgRig(poseRig(rig,scene,t),options),clip:scene,scene,caption};
+}
+export function renderStory(rig,ms,options={}){
+ if(!Number.isFinite(ms)||ms<0)return {ok:false,code:'INVALID_TIME'};
+ if(options.still)return renderQuoxperticus(rig,'skill',2200,options);
+ if(ms<3000)return renderQuoxperticus(rig,'attach',ms,options);
+ if(ms<9000)return renderQuoxperticus(rig,'skill',ms-3000,options);
+ return renderQuoxperticus(rig,'idle',ms-9000,options);
+}

package/vendor/dragonlab/design/quoxperticus/v4/character.mjs

@@ -0,0 +1,57 @@
+import {renderSvgRig} from '../../../factory/svg-rig-contour.mjs';
+import {poseRig as previousPose,renderQuoxperticus as previous,QUOXPERTICUS_CLIPS as clips} from '../v3/character.mjs';
+export const QUOXPERTICUS_CLIPS=Object.freeze([...clips,{id:'orchestrate',title:'Fleet Conductor',duration:10000}]);
+export const STORY_DURATION=13000;
+const clamp=x=>Math.max(0,Math.min(1,x));
+const ease=x=>{x=clamp(x);return x*x*(3-2*x);};
+const fit=rig=>({...rig,bounds:{left:12,top:0,right:790,bottom:460}});
+export function poseRig(rig,ms,{deck=false}={}){
+ const t=ms%10000,energy=ease(t/1400)*(1-ease((t-7800)/2200));
+ const base=previousPose(fit(rig),'idle',t);
+ const beat=energy*(.75+.25*Math.sin(t/380));
+ const paths=base.paths.map(p=>({...p,polygons:p.polygons.map(poly=>poly.map(([x,y])=>{
+  if(p.id==='near-arm'||p.id==='finger-claws'&&x>350||p.id==='arm-scales'&&x>350){const w=clamp((450-x)/70);return [x+14*energy*w,y-65*beat*w];}
+  return [x,y];
+ }))}));
+ const back=[],front=[];
+ const shape=(list,id,rgb,points,stroke=0)=>list.push({id,group:'orchestration',rgb,polygons:[points],stroke,erase:false});
+ const light=(v)=>[Math.round(160+95*v),Math.round(36+170*v),Math.round(65+170*v)];
+ const anchor=[390,288-50*beat];
+ if(energy>.01){
+  const count=deck?6:3;
+  for(let i=0;i<count;i++){
+   const left=i<3,x=left?55:742,y=110+(i%3)*100;
+   const phase=((t-1400-i*230)/2200%1+1)%1;
+   const bright=energy*(phase>.78?1:.3);
+   shape(back,'rack-'+i,light(bright),[[x-28,y-20],[x+28,y-20],[x+28,y+20],[x-28,y+20],[x-28,y-20]],4);
+   shape(back,'rack-divider-'+i,light(bright),[[x-26,y],[x+26,y]],3);
+   for(let j=0;j<2;j++)shape(back,'rack-led-'+i+'-'+j,[255,Math.round(130*energy),Math.round(150*energy)],[[x-17,y-12+j*20],[x-11,y-12+j*20],[x-11,y-7+j*20],[x-17,y-7+j*20]]);
+   // Curved command threads arch through the space above the wings.
+   const control=[left?170:600,25+i%3*22];
+   const point=u=>[(1-u)**2*anchor[0]+2*(1-u)*u*control[0]+u*u*x,(1-u)**2*anchor[1]+2*(1-u)*u*control[1]+u*u*y];
+   const thread=Array.from({length:31},(_,j)=>point(j/30));
+   shape(back,'thread-'+i,[Math.round(180*energy),Math.round(38*energy),Math.round(65*energy)],thread,3);
+   if(t>1400+i*230&&t<8500){
+    const [wx,wy]=point(phase),r=deck?6:7;
+    shape(front,'worker-'+i,light(energy),[[wx-r,wy],[wx,wy-r],[wx+r,wy],[wx,wy+r]]);
+    // Short comet tail makes outbound travel readable.
+    shape(front,'worker-tail-'+i,[240,65,105],[point(Math.max(0,phase-.055)),[wx,wy]],3);
+   }
+  }
+  // A ring at the conducting claw keeps the origin visible.
+  shape(front,'command-halo',light(energy),Array.from({length:33},(_,i)=>[anchor[0]+17*Math.cos(i*Math.PI/16),anchor[1]+9*Math.sin(i*Math.PI/16)]),3);
+ }
+ return {...base,paths:[...back,...paths,...front]};
+}
+export function renderQuoxperticus(rig,scene='idle',ms=0,options={}){
+ if(scene!=='orchestrate')return previous(fit(rig),scene,ms,options);
+ if(!Number.isFinite(ms)||ms<0)return {ok:false,code:'INVALID_TIME'};
+ const t=options.still?4600:ms%10000;
+ return {...renderSvgRig(poseRig(rig,t,options),options),clip:scene,scene,caption:t<1400?'Raise the command.':t<7800?'Dispatch workers. Conduct the fleet.':'Workers settle. The mission continues.',visualOnly:true,demo:true};
+}
+export function renderStory(rig,ms,options={}){
+ if(!Number.isFinite(ms)||ms<0)return {ok:false,code:'INVALID_TIME'};
+ if(options.still)return renderQuoxperticus(rig,'orchestrate',4600,options);
+ if(ms<3000)return renderQuoxperticus(rig,'attach',ms,options);
+ return renderQuoxperticus(rig,'orchestrate',ms-3000,options);
+}

package/vendor/dragonlab/design/quoxperticus/v4/review.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import {parseSvgRig} from '../../../factory/svg-rig.mjs';
+import {renderQuoxperticus,QUOXPERTICUS_CLIPS} from './character.mjs';
+import {artSlot,composeMessage} from '../../lucid/recovery/layout.mjs';
+import {cellsToAnsi} from '../../../vendor/quox-dragon/qart.js';
+const args=process.argv.slice(2),values=new Set(['--cols','--rows','--terminal-cols','--terminal-rows','--message','--scene','--at']);
+for(let i=0;i<args.length;i++){
+ if(values.has(args[i])){if(!args[i+1]||args[i+1].startsWith('--'))throw Error('Missing option value');i++;}
+ else if(!['--large','--mono','--help','--watch','--attach','--intro','--still','--list'].includes(args[i]))throw Error('Unknown option: '+args[i]);
+}
+const value=(name,fallback)=>args.includes(name)?args[args.indexOf(name)+1]:fallback;
+if(args.includes('--help')){console.log('Quoxperticus V4 forge studio. --watch --attach --intro --still --scene ID --at MS --list --large --mono --message TEXT --cols N --rows N --terminal-cols N --terminal-rows N');process.exit(0);}
+if(args.includes('--list')){console.log(QUOXPERTICUS_CLIPS.map(c=>c.id+' · '+c.title).join('\n'));process.exit(0);}
+const w=Number(value('--terminal-cols',process.stdout.columns||80)),h=Number(value('--terminal-rows',process.stdout.rows||24));
+if(!Number.isSafeInteger(w)||!Number.isSafeInteger(h)||w<1||h<1)throw Error('Invalid terminal size');
+const slot=artSlot(w,h),large=args.includes('--large')||args.includes('--intro'),explicit=large||args.includes('--cols')||args.includes('--rows');
+const cols=Number(value('--cols',large?Math.min(120,w-4):Math.min(39,slot.cols))),rows=Number(value('--rows',large?Math.min(36,h-4):Math.min(11,slot.rows)));
+const message=value('--message','QUOXPERTICUS\nSkills at your command.');
+if(!slot.showArt&&!explicit){console.log(composeMessage(null,message,{terminalCols:w}).join('\n'));}
+else{
+ if(cols>w-4||rows>h-2)throw Error('Requested art exceeds terminal margins');
+ const rig=parseSvgRig(await fs.readFile(new URL('../v2/quoxperticus-master.svg',import.meta.url),'utf8'));
+ const opts={cols,rows,mono:args.includes('--mono'),still:args.includes('--still'),deck:large};
+ const scene=value('--scene',args.includes('--attach')?'attach':'idle');
+ const r=renderQuoxperticus(rig,scene,Number(value('--at',0)),opts);
+ if(!r.ok)throw Error(r.code);
+ if(args.includes('--watch')||args.includes('--attach')||args.includes('--intro')){
+  const {watch}=await import('./watch.mjs');
+  await watch(rig,opts,{terminalCols:w,terminalRows:h,large,scene:args.includes('--scene')||args.includes('--attach')?scene:null,arrival:args.includes('--attach'),message:args.includes('--message')?message:null});
+ }else{
+ const shownMessage=args.includes('--message')?message:'QUOXPERTICUS\n'+r.caption;
+ console.log((large?[...cellsToAnsi(r.frame),...composeMessage(null,shownMessage,{terminalCols:w})]:composeMessage(r.frame,shownMessage,{terminalCols:w})).join('\n'));
+}
+}

package/vendor/dragonlab/design/quoxperticus/v4/watch.mjs

@@ -0,0 +1,56 @@
+import {performance} from 'node:perf_hooks';
+import {QUOXPERTICUS_CLIPS,renderQuoxperticus,renderStory,STORY_DURATION} from './character.mjs';
+import {composeMessage} from '../../lucid/recovery/layout.mjs';
+import {cellsToAnsi} from '../../../vendor/quox-dragon/qart.js';
+
+/** One bounded performance. No alternate screen or full-screen clearing. */
+export async function watch(paths,options,config){
+  if(!process.stdout.isTTY||!process.stdin.isTTY)throw new Error('--watch/--intro needs an interactive terminal. Use --scene and --at for snapshots.');
+  const {terminalCols,terminalRows,scene,large,message}=config;
+  const clip=scene?QUOXPERTICUS_CLIPS.find(c=>c.id===scene):null;
+  const duration=(clip?.duration??STORY_DURATION)+(config.arrival?6000:0);
+  const realCols=process.stdout.columns,realRows=process.stdout.rows;
+  const start=performance.now();
+  const render=t=>{
+    const r=scene?renderQuoxperticus(paths,scene,t,options):renderStory(paths,t,options);
+    if(!r?.ok)throw new Error(r?.code??'Invalid story frame');
+    const caption=message??'QUOXPERTICUS · '+r.clip+'\n'+r.caption;
+    return large?[...cellsToAnsi(r.frame),...caption.split('\n')]:composeMessage(r.frame,caption,{terminalCols});
+  };
+  // Reserve enough lines for captions too; keep within the real terminal.
+  const height=options.rows+3;
+  if(height>=terminalRows)throw new Error('Animation needs room for its caption; reduce --rows.');
+  let ended=false,drawn=false,timer,resolveDone,rejectDone;
+  const wasRaw=Boolean(process.stdin.isRaw);
+  const done=new Promise((resolve,reject)=>{resolveDone=resolve;rejectDone=reject;});
+  const cleanup=(error)=>{
+    if(ended)return;ended=true;clearInterval(timer);
+    process.stdin.off('data',key);process.stdout.off('resize',resized);
+    process.off('SIGINT',sigint);process.off('SIGTERM',sigterm);
+    process.stdin.setRawMode(wasRaw);process.stdin.pause();
+    if(drawn)process.stdout.write(`\x1b[${height}B\r`);
+    process.stdout.write('\x1b[0m\x1b[?25h');
+    error?rejectDone(error):resolveDone();
+  };
+  const key=data=>{if(data.includes(3)||data.toString().includes('q'))cleanup();};
+  const sigint=()=>cleanup(),sigterm=()=>cleanup();
+  const resized=()=>cleanup(new Error('Terminal resized; rerun for the new art slot.'));
+  try{
+    process.stdin.setRawMode(true);process.stdin.resume();process.stdin.on('data',key);
+    process.stdout.on('resize',resized);process.on('SIGINT',sigint);process.on('SIGTERM',sigterm);
+    process.stdout.write('\x1b[?25l');
+    // Allocate the block once; each frame replaces only these lines.
+    process.stdout.write('\n'.repeat(height)+`\x1b[${height}A`);drawn=true;
+    const tick=()=>{
+      try{
+        if(process.stdout.columns!==realCols||process.stdout.rows!==realRows)return resized();
+        const t=Math.min(performance.now()-start,duration-1),lines=render(t);
+        if(lines.length>height)throw new Error('Message exceeds the animation block; use a shorter message or a static preview.');
+        process.stdout.write(Array.from({length:height},(_,i)=>'\r\x1b[2K'+(lines[i]??'')+'\n').join('')+`\x1b[${height}A`);
+        if(performance.now()-start>=duration)cleanup();
+      }catch(e){cleanup(e);}
+    };
+    tick();if(!ended)timer=setInterval(tick,1000/6);
+    await done;
+  }catch(e){cleanup(e);await done;}
+}