quoxcli 0.3.1 → 0.4.0

package/lib/commands/org.js

@@ -7,6 +7,7 @@ import { formatOutput, formatDetail, printSuccess, printWarning } from '../core/
 import { otherProfileUsers, listProcs } from '../core/profileUsers.js';
 import { resolveOrgId } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { numberedOrgLines, pickOrgByInput, sharedSwitchHint } from '../quoxon/orgSwitch.js';
 
 export function registerOrgCommands(program, ctx) {
   const { client, auth, config } = ctx;
@@ -90,9 +91,26 @@ export function registerOrgCommands(program, ctx) {
   org
     .command('switch')
     .description('Switch active organization context')
-    .argument('<orgId>', 'organization ID or slug')
-    .action(async (orgId) => {
+    .argument('[orgId]', 'organization ID, slug, or the number from the list (omit to pick from a numbered list)')
+    .action(async (orgIdArg) => {
       auth.requireAuth();
+      let orgId = orgIdArg;
+      if (!orgId || /^\d+$/.test(orgId)) {
+        const l = await client.get(resolveEndpoint('orgs.list').path, { service: resolveEndpoint('orgs.list').service });
+        const orgs = Array.isArray(l) ? l : (l?.organizations || l?.orgs || l?.data || []);
+        if (!orgs.length) throw new QuoxError('No organisations returned for this login.', 1);
+        if (!orgId) {
+          const curId = (() => { try { return auth.getOrgId(); } catch { return null; } })();
+          for (const line of numberedOrgLines(orgs, curId)) console.log(line);
+          if (!process.stdin.isTTY) throw new QuoxError('Pass a number, slug or ID: quox org switch <number>.', 1);
+          const rl = (await import('node:readline/promises')).createInterface({ input: process.stdin, output: process.stdout });
+          try { orgId = await rl.question('Switch to which? (number, slug, or Enter to cancel) '); } finally { rl.close(); }
+          if (!orgId.trim()) { console.log('Not switched.'); return; }
+        }
+        const pick = pickOrgByInput(orgId, orgs);
+        if (pick.org) orgId = pick.org.id;
+        else if (/^\d+$/.test(orgId)) throw new QuoxError(`No org numbered ${orgId}. Run \`quox org switch\` to see the list.`, 1);
+      }
       // The server matches memberships by org ID only. Accept a slug (or exact name) by
       // resolving it against the caller's org list first; a 26-char ULID passes through.
       let targetId = orgId;
@@ -126,8 +144,7 @@ export function registerOrgCommands(program, ctx) {
         const name = config.getActiveProfileName?.();
         const others = name ? otherProfileUsers({ profile: name, defaultProfile: config._data?.activeProfile, procs: listProcs(), selfPids: [process.pid, process.ppid] }) : [];
         if (others.length) {
-          printWarning(`${others.length} other quox session${others.length === 1 ? '' : 's'} use profile "${name}" (pid ${others.map(p => p.pid).join(', ')}). `
-            + 'They follow this org on their next token refresh or restart. To move one window only, use /org switch inside it.');
+          printWarning(sharedSwitchHint({ name, pids: others.map(p => p.pid) }));
         }
       } catch { /* best effort: never fail the switch over the warning */ }
     });

package/lib/commands/provider.js

@@ -17,6 +17,9 @@ import { createApi, isInteractiveHuman } from '../quoxon/api.js';
 import { PROVIDERS, providerFor, looksLikeKey, connectionLines, connectFlow, connectOllamaFlow, connectCompatFlow } from '../quoxon/connect.js';
 import { needsConsent, consentCovers, connectConsentNote, providerLabel } from '../quoxon/consent.js';
 import { readStdin } from '../quoxon/print.js';
+import { INSTALL_TOOLS, toolFor, planLine, offerQuestion, runInstall, isAgentCaller } from '../quoxon/installCli.js';
+import { YN_OPTIONS, waitForDecision } from '../core/askDecision.js';
+import { detectCallerSource } from '../core/callerSource.js';
 
 const KINDS = Object.keys(PROVIDERS);
 const SAFE_ROW = ['id', 'integration_type', 'label', 'is_default', 'test_status', 'last_tested_at', 'created_at'];
@@ -25,6 +28,8 @@ const CONTAINER_NOTE = 'Quox runs in containers: 127.0.0.1 or localhost means th
 function defaultIO() {
   return {
     isTTY: () => isInteractiveHuman(),
+    isAgent: () => isAgentCaller(process.env),
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
     readStdin: () => readStdin(),
     promptSecret: async (message) => {
       const { default: inquirer } = await import('inquirer');
@@ -129,6 +134,59 @@ export function registerProviderCommands(program, ctx) {
       await consentAfter(p.type);
     });
 
+  // ── provider install (LAZY-AI-CLI) ────────────────────────────────────────
+  // The user's own server downloads the vendor's npm package (never a binary Quox ships). A person decides: y/N on
+  // a terminal, a high-risk approval card when an agent runs it (an agent's --yes is not a person's yes).
+  provider
+    .command('install')
+    .description('Install Claude Code or Codex on this Quox server from npm (the vendor\'s own package), so Claude sign-in and Codex work. Instance admin only')
+    .argument('<tool>', `what to install: ${Object.keys(INSTALL_TOOLS).join(', ')}`)
+    .option('--yes', 'install without the y/N question (a script; an agent still gets an approval card)')
+    .action(async (toolArg, opts) => {
+      auth.requireAuth();
+      const tool = toolFor(toolArg);
+      if (!tool) throw new Error(`No installable CLI called "${toolArg}". Use one of: ${Object.keys(INSTALL_TOOLS).join(', ')}`);
+      const t = INSTALL_TOOLS[tool];
+      const a = api();
+      const st = await a.providerCliStatus();
+      const cur = st?.ok ? st.tools.find((x) => x.id === tool) : null;
+      if (cur?.installed) { printInfo(`✔ ${t.name} is already installed on this server (${cur.version || 'version unknown'}${cur.location ? `, ${cur.location}` : ''}). Nothing to do.`); return; }
+      const plan = await a.providerCliPlan(tool);
+      if (!plan?.ok) {
+        if (plan?.status === 404 || plan?.status === 405) throw new Error(`This Quox server is too old to install ${t.name} for you. Update it first: quox server update`);
+        throw new Error(plan?.status === 403 ? (plan.error || 'Only an instance admin can install software on this server.') : `Could not plan the install: ${plan?.error || 'no answer'}`);
+      }
+      printInfo(planLine(plan));
+      let approvalId = null;
+      if (io.isAgent()) {
+        const orgId = resolveOrgId(auth, program);
+        const src = (() => { try { return detectCallerSource(process.env); } catch { return {}; } })();
+        const session = process.env.QUOX_SESSION || src?.label || 'agent';
+        const ep = resolveEndpoint('inbox.decision.create', { orgId });
+        const filed = await client.post(ep.path, { service: ep.service, body: {
+          session, title: `Install ${t.name} on this server?`, why: planLine(plan), options: YN_OPTIONS, recommend: 'y', high_risk: true,
+          justification: `${session} asked to install ${t.vendor}'s ${plan.package} ${plan.version} from npm on this Quox server, so ${t.name} works. It runs as the Quox service user, never root, and every install is audited.`,
+          agent: process.env.QUOX_AGENT_ID || undefined,
+        } });
+        const id = filed?.decision?.id;
+        if (!id) throw new Error('Could not file the approval card. Nothing was installed.');
+        printInfo(`An agent is running this, so a person decides: approval card ${id} is in /approvals (needs the step-up PIN).`);
+        const r = await waitForDecision({
+          poll: (w) => { const g = resolveEndpoint('inbox.decision.get', { orgId, id }); return client.get(g.path, { service: g.service, query: { wait: w }, timeout: (w + 15) * 1000, retries: 0 }); },
+          log: (m) => process.stderr.write(`${m}\n`),
+        });
+        if (r.decision?.state !== 'answered' || r.decision?.answer?.option !== 'y') { printInfo(`Not installed: the card was not approved. Nothing was downloaded.`); process.exitCode = 2; return; }
+        approvalId = id;
+      } else if (!opts.yes) {
+        if (!io.isTTY()) throw new Error(`Run again with --yes to install ${t.name}, or run it in a terminal to be asked. Nothing was installed.`);
+        if (!(await io.confirm(offerQuestion(tool, plan)))) { printInfo('Not installed. Nothing was downloaded.'); return; }
+      }
+      printInfo(`◐ installing ${t.name} ${plan.version} on the server (this takes a minute or two)`);
+      const r = await runInstall(a, tool, { approvalId, onProgress: printInfo, sleep: io.sleep || undefined });
+      if (!r.ok) throw new Error(r.lines.join(' '));
+      for (const l of r.lines) printInfo(l);
+    });
+
   // ── provider test ──────────────────────────────────────────────────────────
   provider
     .command('test')

package/lib/commands/quoxseo.js

@@ -231,6 +231,37 @@ export function registerQuoxseoCommands(program, ctx) {
       } catch (err) { annotate(err); }
     });
 
+  s.command('queries')
+    .description('Ranked Search Console query rows: query, page, impressions, clicks, CTR, position')
+    .option('--sort <s>', 'impressions | clicks | position-opportunity (high impressions at position 5-20)', 'impressions')
+    .option('--limit <n>', 'max rows (default 25, max 100)', '25')
+    .option('--filter <text>', 'only queries containing this text, e.g. "conversation"')
+    .option('--gaps', 'topic-gap view: queries with impressions that no crawled page targets')
+    .action(async (opts) => {
+      try {
+        const qs = new URLSearchParams();
+        qs.set('sort', opts.sort);
+        qs.set('limit', opts.limit);
+        if (opts.filter) qs.set('filter', opts.filter);
+        if (opts.gaps) qs.set('gaps', '1');
+        const data = await get(client, 'quoxseo.queries.rows', { query: `?${qs}` });
+        if (jsonOut(data)) return;
+        if (!data.crawl_id) { console.log('No Search Console query data yet; the ingest with Search Console access has not run.'); return; }
+        const p = data.period;
+        const when = p && p.start ? `${p.start}..${p.end}` : 'period unknown';
+        const rows = data.rows || [];
+        if (data.view === 'topic-gaps') {
+          console.log(`topic gaps (impressions, no page targets the query) · ${when} · ${rows.length} of ${data.total_gaps}`);
+        } else {
+          console.log(`queries by ${data.sort}${opts.filter ? ` matching "${opts.filter}"` : ''} · ${when} · ${rows.length} of ${data.matched}`);
+        }
+        if (!rows.length) { console.log('No rows.'); return; }
+        for (const r of rows) {
+          console.log(`${r.query}  | ${r.page}  impr ${r.impressions}  clk ${r.clicks}  ctr ${(r.ctr * 100).toFixed(1)}%  pos ${r.position ?? '-'}`);
+        }
+      } catch (err) { annotate(err); }
+    });
+
   s.command('coverage')
     .description("Google index coverage: what's indexed, and where Google disagrees with the page")
     .option('--filter <f>', 'indexed | not-indexed')

package/lib/commands/research.js

@@ -0,0 +1,79 @@
+/**
+ * quox research domains list|add <domain>|remove <domain>
+ *
+ * The curated trusted research list: hosts the research agent may web_read after a web_search has run.
+ * Stored as the org setting RESEARCH_TRUSTED_DOMAINS through the SAME governed settings path as
+ * `quox settings set` (PATCH /api/v1/platform/settings/flags/:key, human org admin, witnessed there).
+ * Unset or empty means the built-in default list, which add/remove seed from so a first edit never drops it.
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+
+const KEY = 'RESEARCH_TRUSTED_DOMAINS';
+
+// Mirror of services/collector/lib/researchTrustedDefaults.js DEFAULT_TRUSTED_SETTING (a test keeps them identical).
+export const DEFAULT_DOMAINS = (`nist.gov,cisa.gov,cve.org,=cve.mitre.org,=cveawg.mitre.org,=www.kernel.org,=developers.cloudflare.com,=attack.mitre.org,=www.python.org,=docs.python.org,=peps.python.org,=go.dev,=tip.golang.org,` +
+  `=nginx.org/en/,=nginx.org/license,=www.postgresql.org/docs/,=www.postgresql.org/support/security/,=www.postgresql.org/about/news/,` +
+  `openssl-library.org,openssl.org,openssh.com,=kubernetes.io,msrc.microsoft.com,=www.rfc-editor.org,=datatracker.ietf.org/doc/,` +
+  `security-tracker.debian.org,ubuntu.com/security,github.com/advisories/ghsa-`).split(',');
+
+const tokens = (v) => String(v || '').split(/[\s,]+/).map((t) => t.trim().toLowerCase()).filter(Boolean);
+
+function cleanDomain(raw) {
+  const eq = String(raw || '').trim().startsWith('=') ? '=' : '';
+  const t = String(raw || '').trim().replace(/^=/, '').toLowerCase().replace(/^https?:\/\//, '').replace(/\/+$/, '');
+  const host = t.split('/')[0].replace(/\.+$/, '');
+  if (!/^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/.test(host)) return null; // IP literals and junk refused
+  return eq + (t.includes('/') ? host + t.slice(t.indexOf('/')) : host);
+}
+
+async function effective(client) {
+  const ep = resolveEndpoint('v1.settings.list');
+  const data = await client.get(ep.path, { service: ep.service });
+  const f = (data.flags || []).find((x) => x.key === KEY);
+  const list = tokens(f && f.value);
+  const isOrg = !!(f && f.source === 'setting' && list.length);
+  return { list: isOrg ? list : DEFAULT_DOMAINS.slice(), source: isOrg ? 'org setting' : 'built-in default' };
+}
+
+async function write(client, list) {
+  const ep = resolveEndpoint('v1.settings.set', { key: KEY });
+  return client.patch(ep.path, { service: ep.service, body: { value: list.join(',') } });
+}
+
+export function registerResearchCommands(program, ctx) {
+  const { client } = ctx;
+  const r = program.command('research').description('Governed web research settings');
+  const d = r.command('domains').description('Trusted research domains: hosts agents may read after a web search (org setting)');
+
+  d.command('list', { isDefault: true })
+    .description('Show the effective trusted research list and where it comes from')
+    .action(async () => {
+      const { list, source } = await effective(client);
+      process.stdout.write(`source: ${source}\n`);
+      for (const e of list) process.stdout.write(`  ${e}\n`);
+    });
+
+  d.command('add <domain>')
+    .description('Add a domain (or host/path-prefix; a leading = means exact host only) to the org list (human org admin)')
+    .action(async (domain) => {
+      const dom = cleanDomain(domain);
+      if (!dom) { process.stderr.write(`Not added: "${domain}" is not a domain name (IP literals are never trusted)\n`); process.exitCode = 1; return; }
+      const { list } = await effective(client);
+      if (list.includes(dom)) { process.stdout.write(`${dom} is already on the list\n`); return; }
+      await write(client, [...list, dom]);
+      process.stdout.write(`added ${dom} (${list.length + 1} entries, org setting)\n`);
+    });
+
+  d.command('remove <domain>')
+    .description('Remove a domain from the org list (human org admin)')
+    .action(async (domain) => {
+      const dom = cleanDomain(domain);
+      const { list } = await effective(client);
+      if (!dom || !list.includes(dom)) { process.stderr.write(`Not removed: ${domain} is not on the list\n`); process.exitCode = 1; return; }
+      const next = list.filter((e) => e !== dom);
+      if (!next.length) { process.stderr.write('Not removed: that would empty the list, which means the built-in default. Add another entry first.\n'); process.exitCode = 1; return; }
+      await write(client, next);
+      process.stdout.write(`removed ${dom} (${next.length} entries, org setting)\n`);
+    });
+}

package/lib/commands/rows.js

@@ -38,9 +38,16 @@ export const CONTRACT = {
     trend: 'optional. up, down, flat, or a number (the change: 3 shows ▲3, -2 shows ▼2).',
     link: 'optional. An http(s) URL to look at for more; shown by quox rows test and /row test.'
   },
+  // TUI-QPE 2026-10-19: additive v1.1 fields, kept apart so the v1 field list stays exactly as published.
+  fields_v1_1: {
+    cells: 'optional. [{parts: [{text, tone, bold, keep, group}], keep}]: one row in several colours. A narrow window drops the lowest keep first (a whole part, its group, or a cell; no keep = never dropped), never half a word.',
+    grid: 'optional. A short name; rows with the same grid line their cells up in columns (quox-qpe-row uses "qpe").',
+    min_cols: 'optional. A whole number; the row hides when the drawn width (the terminal width less one) is under it.'
+  },
   example: { label: 'Approvals', value: 3, text: 'waiting for you', tone: 'warn', trend: 1, link: 'https://quox.example/approvals' },
   rules: [
     'Plain text output counts as {"text": "<the text>"}.',
+    'One source can draw several lines: {"text": "<short line for older clients>", "grid": "...", "lines": [<status row>, ...]} (up to 4 lines in all above the status bar).',
     'Terminal escapes and control characters are removed before anything is drawn.',
     'A row definition never carries a secret: use a quox or plugin row (your session is used) or a local command that reads its own secret.',
     'Command rows run on the machine that holds them only. They are never synced, shared or imported without a person saying yes to the exact command.'
@@ -347,6 +354,8 @@ export function registerRowsCommands(program, ctx) {
       if (json()) return say(JSON.stringify(CONTRACT, null, 2));
       say(tint('heading').bold('Status-row contract v1'));
       for (const [k, v] of Object.entries(CONTRACT.fields)) say(`  ${tint('id').bold(k.padEnd(6))} ${v}`);
+      say(tint('label')('v1.1 (colours and narrow windows):'));
+      for (const [k, v] of Object.entries(CONTRACT.fields_v1_1)) say(`  ${tint('id').bold(k.padEnd(8))} ${v}`);
       say(tint('label')('Example:'));
       say('  ' + JSON.stringify(CONTRACT.example));
       say(tint('label')('Draws as:'));

package/lib/commands/run.js

@@ -90,7 +90,24 @@ export function registerRunCommands(program, ctx) {
         }
       }
 
-      formatDetail({ ...data, source }, { format: program.opts().output });
+      // RUNS: surface WHICH step failed and the retry hint at the top level, so a failed
+      // run no longer reads as a bare "fetch failed" with no step.
+      const detail = { ...data, source };
+      const d = data.error && typeof data.error.details === 'object' && data.error.details ? data.error.details : null;
+      if (data.status === 'failed' && d && d.nodeId) {
+        detail.failedStep = d.nodeName && d.nodeName !== d.nodeId ? `${d.nodeName} (${d.nodeId})` : String(d.nodeId);
+      }
+      if (data.status === 'failed' && data.error && data.error.message) {
+        // formatDetail truncates long nested values; show the full code + network detail here.
+        detail.failure = `${data.error.code || 'ERROR'}: ${data.error.message}`;
+      }
+      if (data.metadata && data.metadata.retryable) {
+        detail.retry = data.metadata.retryExecutionId
+          ? `auto-retried as ${data.metadata.retryExecutionId}`
+          : `retryable: ${data.metadata.retryHint || `quox run create --workflow ${data.workflowId}`}`;
+      }
+
+      formatDetail(detail, { format: program.opts().output, full: true });
     });
 
   run

package/lib/commands/scope.js

@@ -5,7 +5,7 @@
  *
  * Scopes are read-only projections of the org/division/department/team
  * hierarchy — there is no backend write route for scopes. To create,
- * update, or delete a scope, use `quox org`, `quox division`,
+ * update, or delete a scope, use `quox org`, `quox org divisions`,
  * `quox department`, or `quox team` instead.
  */
 
@@ -18,7 +18,7 @@ export function registerScopeCommands(program, ctx) {
 
   const scope = program
     .command('scope')
-    .description('View scopes (read-only — use `quox org`/`quox division`/`quox team` to manage)');
+    .description('View scopes (read-only — use `quox org`/`quox org divisions`/`quox department`/`quox team` to manage)');
 
   scope
     .command('list')

package/lib/commands/server.js

@@ -24,6 +24,7 @@ import { planUninstall, runUninstall } from '../server/uninstall.js';
 import { serverChecks } from '../server/doctor.js';
 import { writeDiagBundle } from '../server/diag.js';
 import { latestSnapshot, listSnapshots } from '../server/snapshot.js';
+import { loadRegistry, saveServer, buildRows, planGo, hereIdentity, registryPath } from '../server/devServers.js';
 
 const icon = (s) => (s === 'pass' ? chalk.green('✔') : s === 'warn' ? chalk.yellow('⚠') : s === 'skip' ? chalk.dim('·') : chalk.red('✖'));
 
@@ -288,5 +289,117 @@ export function registerServerCommands(program, ctx = {}) {
       console.log(`Private-network targets: ${r.enabled ? 'on' : 'off'} ${chalk.dim('(quox server config lan-targets on|off)')}`);
     });
 
+  // DEVFLEET CX-2: `quox server roles` — the server roles registry (role -> url). A role (brain today) can be pointed
+  // off-box so the service runs on another host without an env edit; resolveServiceUrl reads the registry before env.
+  // list is readable by any instance admin; set/unset mutate instance-wide state so are instance-OWNER (superadmin) only.
+  const roles = server.command('roles').description('Point a server role (e.g. brain) at a URL, so a service can run off-box without an env change');
+  roles.command('list')
+    .description('Show each role, its URL, and whether it comes from the registry or the environment (read-only)')
+    .action(async () => {
+      const { client, auth } = ctx;
+      auth?.requireAuth?.();
+      const ep = resolveEndpoint('server.roles.list');
+      const r = await client.get(ep.path, { service: ep.service });
+      if (json()) { console.log(JSON.stringify(r, null, 2)); return; }
+      if (r.corrupt) console.log(chalk.yellow(` ⚠ the roles store is unreadable (${r.error}); showing environment values only
+`));
+      for (const row of (r.roles || [])) {
+        const where = row.source === 'registry' ? chalk.green('registry') : (row.source === 'env' ? chalk.dim('environment') : chalk.dim('unset'));
+        console.log(` ${row.role.padEnd(10)} ${row.url || chalk.dim('(none)')}  ${chalk.dim(`[${where}]`)}`);
+      }
+      if (!(r.roles || []).length) console.log(chalk.dim(' no roles'));
+    });
+  roles.command('set')
+    .description('Point a role at a URL (instance owner only). Use --test to probe it for health and version first')
+    .argument('<role>', 'the role, e.g. brain')
+    .argument('<url>', 'the URL the role should resolve to, e.g. http://10.1.2.3:3106')
+    .option('--test', 'probe <url> for health and version before storing it; abort if it is unreachable')
+    .action(async (role, url, o) => {
+      const { client, auth } = ctx;
+      auth?.requireAuth?.();
+      if (o.test) {
+        const tp = resolveEndpoint('server.roles.test', { role });
+        const t = await client.post(tp.path, { service: tp.service, body: { url } });
+        if (!t.success) { const e = new Error(`--test failed: ${t.error || `status ${t.status}`}; not storing`); e.exitCode = 1; throw e; }
+        if (!json()) console.log(chalk.dim(` probe ok: status ${t.status}${t.version ? `, version ${t.version}` : ''}`));
+      }
+      const ep = resolveEndpoint('server.roles.set', { role });
+      const r = await client.put(ep.path, { service: ep.service, body: { url } });
+      if (json()) { console.log(JSON.stringify(r, null, 2)); return; }
+      console.log(chalk.green(` ✔ role ${r.role} -> ${r.url}`));
+    });
+  roles.command('unset')
+    .description('Remove a role from the registry so it falls back to the environment value (instance owner only)')
+    .argument('<role>', 'the role to remove')
+    .action(async (role) => {
+      const { client, auth } = ctx;
+      auth?.requireAuth?.();
+      const ep = resolveEndpoint('server.roles.unset', { role });
+      const r = await client.delete(ep.path, { service: ep.service });
+      if (json()) { console.log(JSON.stringify(r, null, 2)); return; }
+      console.log(chalk.green(r.removed ? ` ✔ role ${role} removed; falling back to the environment value` : ` role ${role} was not set`));
+    });
+
+  // DEVFLEET: the registered dev servers. Bastion supplies address + state, the org's dev-server registry supplies purpose/project/workdir.
+  const regPath = () => deps.registryPath || registryPath(env);
+  async function devRows() {
+    const { client, auth } = ctx;
+    auth?.requireAuth?.();
+    const ep = resolveEndpoint('v1.fleet.hosts.list');
+    const d = await client.get(ep.path, { service: ep.service, retries: 0, timeout: 5000 });
+    const hosts = d?.hosts || d;
+    if (!Array.isArray(hosts)) throw new Error('could not read the Bastion host registry (quox fleet hosts)');
+    { const reg = await loadRegistry({ client, path: regPath() }); return buildRows(hosts, { servers: reg.servers, defaults: reg.defaults }, deps.here || hereIdentity()); }
+  }
+  server.command('list')
+    .description('The registered dev servers: purpose, project, reachable, and which one this is (read-only)')
+    .action(async () => {
+      const rows = await devRows();
+      if (json()) { console.log(JSON.stringify(rows.map(({ ip, user, jump, ...r }) => r), null, 2)); return; }
+      if (!rows.length) { console.log(chalk.dim(` no dev servers registered. Add one: quox server mark <host> --purpose "main dev"`)); return; }
+      const showDeploy = rows.some(r => r.lastDeploy);
+      const cell = (v) => (v == null || v === '' ? '-' : String(v));
+      const w = (k) => Math.max(k.length, ...rows.map(r => cell(r[k]).length));
+      const cols = ['name', 'purpose', 'project', 'repo'];
+      const widths = Object.fromEntries(cols.map(k => [k, w(k)]));
+      console.log(chalk.bold(` ${cols.map(k => k.toUpperCase().padEnd(widths[k])).join('  ')}  REACHABLE${showDeploy ? '  LAST DEPLOY' : ''}`));
+      for (const r of rows) {
+        const line = `${cols.map(k => cell(r[k]).padEnd(widths[k])).join('  ')}  ${(r.reachable ? 'yes' : 'no').padEnd(9)}${showDeploy ? `  ${cell(r.lastDeploy)}` : ''}`;
+        console.log(` ${line}${r.current ? chalk.cyan('  <- this server') : ''}`);
+      }
+    });
+  server.command('mark')
+    .description('Record what a dev server is for (org registry on the Quox server, additive): purpose, project, repo, workdir, ci')
+    .argument('<name>', 'the Bastion host id, e.g. web01')
+    .option('--purpose <text>', 'what this server is for, e.g. "main dev"')
+    .option('--project <text>').option('--repo <text>').option('--workdir <path>', 'where go starts quox on that server')
+    .option('--ci <text>', 'CI or auto-deploy note or URL').option('--user <user>', 'ssh user (default control)').option('--jump <host>', 'ssh ProxyJump alias (default: the registry defaults.jump, else a direct ssh)')
+    .option('--last-deploy <text>', 'last deploy note (shown only if any server has one)')
+    .action(async (name, o) => {
+      ctx.auth?.requireAuth?.();
+      const e = await saveServer({ client: ctx.client, name, fields: { ...o, lastDeploy: o.lastDeploy }, path: regPath() });
+      if (json()) { console.log(JSON.stringify({ name, ...e }, null, 2)); return; }
+      console.log(chalk.green(` ✔ ${name} recorded${e.purpose ? ` as ${e.purpose}` : ''}`));
+    });
+  server.command('go')
+    .description('Open a Quox window on a registered dev server (ssh via your own config and the Bastion jump host, then quox in its workdir)')
+    .argument('<name>', 'a server from `quox server list`')
+    .option('--dry-run', 'print what would run and run nothing')
+    .action(async (name, o) => {
+      const rows = await devRows();
+      const plan = planGo(rows.find(r => r.name === name));
+      if (plan.error) {
+        const known = rows.map(r => r.name).join(', ') || 'none registered';
+        const e = new Error(plan.error === 'unknown server' ? `unknown server "${name}". Registered: ${known}` : plan.error);
+        e.exitCode = 1; throw e;
+      }
+      console.log(chalk.dim(` going to ${name}: ${plan.text}`));
+      if (dry(o)) return;
+      const spawnImpl = deps.spawnSync || (await import('node:child_process')).spawnSync;
+      const r = spawnImpl(plan.cmd, plan.args, { stdio: 'inherit', cwd: plan.cwd });
+      if (r?.error) { const e = new Error(`could not start ${plan.cmd}: ${r.error.message}`); e.exitCode = 1; throw e; }
+      if (r?.status) process.exitCode = r.status;
+    });
+
   return server;
 }

package/lib/commands/shortcut.js

@@ -0,0 +1,41 @@
+// `quox shortcut add|remove`: a short command (default `q`) for quox. Local only; never shadows an existing command.
+import chalk from 'chalk';
+import { createInterface } from 'node:readline/promises';
+import { addShortcut, removeShortcut, DEFAULT_NAME } from '../core/shortcut.js';
+import { askText } from '../quoxon/ask.js';
+
+async function askYes(line) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try { return /^y(es)?$/i.test((await rl.question(`${line} `)).trim()); } finally { rl.close(); }
+}
+
+export function registerShortcutCommand(program, ctx = {}) {
+  const d = ctx.shortcutDeps || {};
+  const out = d.log || ((l) => console.log(l));
+  const sc = program.command('shortcut')
+    .description('A short command for quox, like q (add / remove); refuses if the name already runs something else, never uses sudo');
+  sc.command('add')
+    .description('Make a "q" command that runs quox: a symlink in a directory you own that is on PATH. Refuses (and says what it found) if q already resolves to something else on PATH; never shadows an existing command, no sudo, no shell rc edits. Safe to repeat.')
+    .option('--name <name>', 'the short command name', DEFAULT_NAME)
+    .option('-y, --yes', 'create without asking (needed in a non-interactive shell)')
+    .action(async (o) => {
+      const name = o.name || DEFAULT_NAME;
+      const yes = o.yes || program.opts().yes;
+      if (!yes) {
+        const tty = d.isTTY ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+        if (!tty) { out('Not created: this needs a yes. Re-run with quox shortcut add --yes in a non-interactive shell.'); process.exitCode = 1; return; }
+        if (!(await (d.ask || askYes)(askText(`Make \`${name}\` run quox?`, { keys: 'y/N' })))) { out('Not created. Nothing was changed.'); return; }
+      }
+      const r = (d.add || addShortcut)({ name, ...(d.opts || {}) });
+      out(r.ok ? chalk.green(`✔ ${r.message}`) : chalk.red(`✖ ${r.message}`));
+      if (!r.ok) process.exitCode = 1;
+    });
+  sc.command('remove')
+    .description('Remove the short command, only if it is a link to this quox (anything else named q is left alone)')
+    .option('--name <name>', 'the short command name', DEFAULT_NAME)
+    .action(async (o) => {
+      const r = (d.remove || removeShortcut)({ name: o.name || DEFAULT_NAME, ...(d.opts || {}) });
+      out(r.ok ? r.message : chalk.red(`✖ ${r.message}`));
+      if (!r.ok) process.exitCode = 1;
+    });
+}

package/lib/commands/skills.js

@@ -585,11 +585,27 @@ export function registerSkillsCommands(program, ctx) {
   sealed
     .command('show')
     .description('Show a sealed skill\'s manifest (name, description, input contract, content hash). Manifest only.')
-    .argument('<sealedId>', 'sealed skill ID')
-    .action(async (sealedId) => {
+    .argument('<sealedId>', 'sealed skill ID or name')
+    .action(async (idOrName) => {
       auth.requireAuth();
-      const ep = resolveEndpoint('skills.sealed.get', { sealedId });
-      const data = await client.get(ep.path, { service: ep.service });
+      let sealedId = idOrName;
+      let data;
+      try {
+        const ep = resolveEndpoint('skills.sealed.get', { sealedId });
+        data = await client.get(ep.path, { service: ep.service });
+      } catch (err) {
+        // Coverage wave (ev_mvg4iwfp_d0b2e3): chat passed the skill's name. A 404 that matches exactly one sealed
+        // skill's name resolves to its id; anything else keeps the original error.
+        if (err.status !== 404) throw err;
+        const lep = resolveEndpoint('skills.sealed.list');
+        const list = await client.get(lep.path, { service: lep.service });
+        const rows = (list && (list.sealed ?? list)) || [];
+        const hits = (Array.isArray(rows) ? rows : []).filter((r) => r && r.name === idOrName);
+        if (hits.length !== 1) throw err;
+        sealedId = hits[0].sealedId;
+        const ep = resolveEndpoint('skills.sealed.get', { sealedId });
+        data = await client.get(ep.path, { service: ep.service });
+      }
       printInfo('Manifest only. The sealed content is never returned by the API.');
       formatDetail(data, { format: program.opts().output, title: `Sealed skill: ${sealedId}` });
     });

package/lib/commands/vm.js

@@ -19,7 +19,7 @@ import { resolveOrgId } from './helpers.js';
 import { formatOutput, printInfo, printWarning } from '../core/output.js';
 import {
   VM_ACTIONS, VmPendingError, pendingHint, makeExec, makePoolRest,
-  listVms, vmInfo, vmDoctor, doctorLines, vmAction, vmSnapshot, vmRehearse, waitRehearsal, poolStatus, poolLease, poolDone, poolConfig, poolHostKeyLines,
+  listVms, vmListRows, vmInfo, vmDoctor, doctorLines, vmAction, vmSnapshot, vmRehearse, waitRehearsal, poolStatus, poolLease, poolDone, poolConfig, poolHostKeyLines,
   readPubkey, textOf, payloadOf,
 } from '../core/vm.js';
 
@@ -92,7 +92,7 @@ export function registerVmCommands(program, ctx) {
       const vms = await listVms(exec, { node: options.node, type: options.type });
       if (json()) { console.log(JSON.stringify(vms.map((v) => v.raw), null, 2)); return; }
       formatOutput(
-        { columns: ['vmid', 'name', 'node', 'type', 'status'], rows: vms.map(({ raw, ...r }) => r) },
+        { columns: ['vmid', 'name', 'node', 'type', 'status', 'tags'], rows: vmListRows(vms) },
         { emptyMessage: 'No VMs found.' },
       );
     }));