quoxcli 0.2.0 → 0.4.0

package/lib/quoxon/slash/todoCmd.js

@@ -0,0 +1,122 @@
+/**
+ * /todo <text> adds an Action Tracker item; /todo alone and /todos list the board; /todo move do5 done moves one
+ * (owner typed /todo, 2026-10-20). The writes and reads are core/actionItems.js, the same core as `quox actions`.
+ * Items get per-listing short ids by column: td1.. (to do), do1.. (doing), dn1.. (done). They are positions in the
+ * last list, mapped to real item ids; a move re-reads the board and says so when the list has changed.
+ * Pure helpers here: parse, short ids, wording.
+ */
+export const DONE_SHOWN = 10;
+const PREFIX = { backlog: 'td', doing: 'do', done: 'dn' };
+const COLUMN_NAME = { backlog: 'To do', doing: 'Doing', done: 'Done' };
+const REF = /^(td|do|dn)(\d+)$/i;
+const STATUS_WORD = { todo: 'todo', 'to-do': 'todo', td: 'todo', doing: 'doing', do: 'doing', wip: 'doing', progress: 'doing', 'in-progress': 'doing', done: 'done', dn: 'done', complete: 'done', completed: 'done', finished: 'done' };
+const USAGE = 'Usage: /todo <text> adds. /todos lists. /todo move do5 done (or /todo do5 done, /todo mark do2 done, /todo td3 doing) moves one.';
+
+/** A column word -> 'todo' | 'doing' | 'done' | null. Accepts "to do" and "in progress" as two words. */
+export function statusWord(words) {
+  const w = (Array.isArray(words) ? words.join('-') : String(words || '')).trim().toLowerCase();
+  return STATUS_WORD[w] || null;
+}
+
+/** Leading short ids from words, comma and/or space separated ("td1,td2", "td1 td2", "td1, td2") -> { refs, used } (used = words consumed). */
+export function takeRefs(words) {
+  const refs = [];
+  let used = 0;
+  for (const w of words) {
+    const parts = String(w).split(',').filter(Boolean);
+    if (!parts.length || !parts.every((p) => REF.test(p))) break;
+    refs.push(...parts.map((p) => p.toLowerCase()));
+    used += 1;
+  }
+  return { refs: [...new Set(refs)], used };
+}
+
+/** "/done td1,td2" argument -> { kind: 'done', refs } | { kind: 'usage', text }. Nothing but short ids is accepted. */
+export function parseDone(arg) {
+  const words = String(arg || '').trim().split(/\s+/).filter(Boolean);
+  const { refs, used } = takeRefs(words);
+  if (!refs.length || used !== words.length) return { kind: 'usage', text: 'Usage: /done td1,td2 (or /done td1 td2) marks those items done. /todos lists the ids.' };
+  return { kind: 'done', refs };
+}
+
+export function todoDoneLine(title) {
+  return `\u2714 Done: ${title}`;
+}
+
+/**
+ * "/todo ..." or "/todos ..." + its argument ->
+ *   { kind: 'list' } | { kind: 'add', text } | { kind: 'move', ref, to } | { kind: 'usage', text }.
+ * Only /todo with free text adds. A short id plus a column word moves; an id with a bad column is a usage error, never an add.
+ */
+export function parseTodo(command, arg) {
+  const text = String(arg || '').trim();
+  if (String(command || '').toLowerCase() === '/todos' || !text) return { kind: 'list' };
+  const words = text.split(/\s+/);
+  const verb = /^(move|mv|mark|set)$/i.test(words[0]);
+  const rest = verb ? words.slice(1) : words;
+  const lead = takeRefs(rest);
+  if (lead.refs.length) {
+    const to = statusWord(rest.slice(lead.used));
+    if (to) return lead.refs.length > 1 ? { kind: 'move', ref: lead.refs[0], refs: lead.refs, to } : { kind: 'move', ref: lead.refs[0], to };
+    return { kind: 'usage', text: USAGE };
+  }
+  if (verb) return { kind: 'usage', text: USAGE };
+  return { kind: 'add', text };
+}
+
+/** board {backlog,doing,done} (backlog = the to-do column) -> { map: { td1: id, ... }, shown: { todo, doing, done } } (done is capped at DONE_SHOWN). */
+export function numberBoard(board, doneShown = DONE_SHOWN) {
+  const shown = { backlog: board.backlog || [], doing: board.doing || [], done: (board.done || []).slice(0, doneShown) };
+  const map = {};
+  for (const col of Object.keys(PREFIX)) shown[col].forEach((it, n) => { map[`${PREFIX[col]}${n + 1}`] = it.id; });
+  return { map, shown };
+}
+
+/** Confirmation after an add: the item id plus where to see the list. */
+export function todoAddedLine(item) {
+  return `Added to your Action Tracker: ${item.id}  ${item.title}. /todos lists them.`;
+}
+
+/** The board as short numbered lines, per column, with short ids. -> string. */
+export function todoBoardText(board, numbered = numberBoard(board)) {
+  const total = (board.backlog || []).length + (board.doing || []).length + (board.done || []).length;
+  if (!total) return 'Nothing in your Action Tracker. /todo <text> adds an item.';
+  const out = [`Your Action Tracker (${(board.backlog || []).length} to do, ${(board.doing || []).length} doing, ${(board.done || []).length} done). /todo <text> adds, /todo move do2 done moves:`];
+  for (const col of ['backlog', 'doing', 'done']) {
+    const items = numbered.shown[col];
+    const all = (board[col] || []).length;
+    if (!all) continue;
+    out.push(`${COLUMN_NAME[col]}:`);
+    items.forEach((i, n) => out.push(`  ${PREFIX[col]}${n + 1}  ${i.title}${i.due_date ? `  due ${String(i.due_date).slice(0, 10)}` : ''}`));
+    if (all > items.length) out.push(`  ... and ${all - items.length} more ${col === 'done' ? 'done (quox actions list --status done)' : ''}`.trimEnd());
+  }
+  return out.join('\n');
+}
+
+/**
+ * Resolve a short id for a move. oldMap is the map from the last /todos (or null if none yet); fresh is the board
+ * read just now. The item is found by its REAL id from the old list, so a list that shifted still moves the item
+ * you saw. -> { id, title, note? } | { error }.
+ */
+export function resolveRef(ref, oldMap, board) {
+  const fresh = numberBoard(board, Infinity);
+  const byId = {};
+  for (const [short, id] of Object.entries(fresh.map)) byId[id] = short;
+  const titleOf = (id) => [...(board.backlog || []), ...(board.doing || []), ...(board.done || [])].find((i) => i.id === id)?.title || '';
+  if (!oldMap || !oldMap[ref]) {
+    const id = fresh.map[ref];
+    if (!id) return { error: `No ${ref} on your board. /todos lists the current ids.` };
+    return { id, title: titleOf(id), note: oldMap ? undefined : `No list shown yet in this window, so ${ref} is read from the board as it is now.` };
+  }
+  const id = oldMap[ref];
+  if (!byId[id]) return { error: `${ref} is gone from your board (done elsewhere or deleted). /todos lists the current ids.` };
+  const nowRef = byId[id];
+  const shownNow = numberBoard(board).map[nowRef] === id; // the id is one the user could see in a fresh listing
+  return nowRef === ref
+    ? { id, title: titleOf(id) }
+    : { id, title: titleOf(id), note: `The list changed since /todos: "${titleOf(id)}" is ${nowRef} now${shownNow ? '' : ' (beyond the short list)'}. Moving that one.` };
+}
+
+export function todoMovedLine(item) {
+  return `Moved ${item.title} to ${item.status}.`;
+}

package/lib/quoxon/slash/undoApi.js

@@ -0,0 +1,38 @@
+/** Server calls behind /undo. Each throws on a non-2xx (never reads an error body as data). */
+import { resolveEndpoint } from '../../api/endpoints.js';
+
+const listOf = (d, ...keys) => { for (const k of keys) if (Array.isArray(d?.[k])) return d[k]; return Array.isArray(d) ? d : []; };
+const receiptOf = (d) => d?.envelope_id || d?.envelopeId || d?.receipt?.envelope_id || d?.receipt?.id || null;
+
+export function createUndoOps({ client, orgId = () => null }) {
+  return {
+    /** The call's envelope, read back: { ok, env } | { ok:false, error }. */
+    async envelope(id) {
+      try { const d = await client.get(`/aee/${encodeURIComponent(id)}`, { service: 'collector', retries: 0, timeout: 10000 }); return { ok: true, env: d?.envelope || d }; }
+      catch (e) { return { ok: false, error: e?.status ? `HTTP ${e.status}` : (e?.message || 'failed') }; }
+    },
+    async recentMoves() {
+      const ep = resolveEndpoint('inboxq.moves.recent');
+      return listOf(await client.get(ep.path, { service: ep.service, retries: 0, query: { limit: 20 } }), 'moves');
+    },
+    async undoMove(moveId) {
+      const ep = resolveEndpoint('inboxq.moves.undo');
+      return { receipt: receiptOf(await client.post(ep.path, { service: ep.service, retries: 0, body: { moveId } })) };
+    },
+    async releaseSlot(name) {
+      const ep = resolveEndpoint('v1.slots.release', { name });
+      const data = await client.post(ep.path, { service: ep.service, retries: 0, body: { force: false, org_id: orgId() || undefined } });
+      const after = data?.slot;
+      if (after && after.state !== 'free' && !data.promoted) throw new Error(`slot ${name} was not released: the server still shows it ${after.state}${after.holder_session ? ` by ${after.holder_session}` : ''}`);
+      return { receipt: receiptOf(data) };
+    },
+    async listNotes() {
+      const ep = resolveEndpoint('notesq.notes.list');
+      return listOf(await client.get(ep.path, { service: ep.service, retries: 0 }), 'notes', 'items', 'data');
+    },
+    async deleteNote(id) {
+      const ep = resolveEndpoint('notesq.notes.delete', { id });
+      return { receipt: receiptOf(await client.delete(ep.path, { service: ep.service, retries: 0 })) };
+    }
+  };
+}

package/lib/quoxon/slash/undoCmd.js

@@ -0,0 +1,49 @@
+/** /undo last: find the last receipt-backed state change, explain it, and (when a known inverse binds) reverse it on y. */
+import { lastStateChange, INVERSES, BY_HAND } from './inverses.js';
+
+const ago = (ms) => { const s = Math.max(0, Math.round(ms / 1000)); return s < 60 ? `${s}s ago` : s < 3600 ? `${Math.round(s / 60)}m ago` : `${Math.round(s / 3600)}h ago`; };
+const clip = (s, n) => { const t = String(s || '').replace(/\s+/g, ' ').trim(); return t.length > n ? `${t.slice(0, n - 1)}…` : t; };
+
+export function createUndoCmd({ api, say, getItems, card, now = () => Date.now() }) {
+  return async function undo(arg) {
+    const a = String(arg || '').trim().toLowerCase();
+    if (a && a !== 'last') return say('Usage: /undo last   (bare /undo does the same; Ctrl+_ undoes composer typing)', 'warn');
+    const ops = api.undoOps;
+    if (!ops) return say('/undo is not available in this mode.', 'warn');
+    const call = lastStateChange(getItems());
+    if (!call) return say('No Quox action in this conversation has a receipt to reverse yet.', 'dim');
+    const when = Number.isFinite(call.startedAt) ? ago(now() - call.startedAt) : 'earlier';
+    // The receipt is the evidence of what ran: read it back before offering to reverse anything.
+    const rec = await ops.envelope(call.envelopeId);
+    if (rec.ok) {
+      const p = rec.env?.payload || {};
+      if (p.tool_name && p.tool_name !== call.tool) return say(`The receipt ${call.envelopeId} is for ${p.tool_name}, not ${call.tool}, so nothing was offered.`, 'warn');
+      if (p.success === false) return say(`The receipt says ${call.tool} did not succeed, so there is nothing to undo.`, 'warn');
+    }
+    const head = `undo │ ${call.tool} · ${when} · receipt ${call.envelopeId}${rec.ok ? '' : ` (receipt not read (${rec.error}))`}`;
+    const inv = INVERSES[call.tool];
+    if (!inv) {
+      say(head);
+      say(`Quox can't reverse ${call.tool} automatically.`, 'warn');
+      say(`It did: ${clip(call.resultSummary || call.summary || call.tool, 100)}. By hand: ${BY_HAND[call.tool] || 'check what it changed with /proof and undo that yourself'}.`, 'dim');
+      return undefined;
+    }
+    let bound;
+    try { bound = await inv.bind(call, ops); } catch (e) { return say(`Could not work out what to reverse: ${e?.message || e}. Nothing ran.`, 'warn'); }
+    if (!bound.ok) {
+      say(head);
+      say(`Quox can't reverse ${call.tool} automatically here: ${bound.why}.`, 'warn');
+      say(`By hand: ${bound.byHand}.`, 'dim');
+      return undefined;
+    }
+    card.ask([head, `It ${inv.did}: ${clip(call.resultSummary || call.summary, 100)}.`, `Undoing it will ${bound.reverse}.`],
+      async () => {
+        let r;
+        try { r = await bound.run(ops); } catch (e) { return say(`NOT undone: ${e?.message || e}`, 'warn'); }
+        say(`Undone: ${bound.reverse}.`, 'ok');
+        say(r?.receipt ? `new receipt ${r.receipt}  (/proof ${r.receipt})` : 'The server returned no receipt id for this reversal, so there is nothing to /proof for it.', 'dim');
+        return undefined;
+      }, 'Cancelled; nothing was undone.', { question: 'Undo it?' });
+    return undefined;
+  };
+}

package/lib/quoxon/slash/undoWish.js

@@ -0,0 +1,15 @@
+/** /undo and /wish factory app.js wires: switch cases plus one answer hook. They share one card (one y/n at a time). */
+import { createCard } from './card.js';
+import { createUndoCmd } from './undoCmd.js';
+import { createWishCmd } from './wishCmd.js';
+
+export function createUndoWish({ api, say, getItems, runTurn, draft, now }) {
+  const card = createCard({ say, now });
+  return {
+    undo: createUndoCmd({ api, say, getItems, card, now }),
+    wish: createWishCmd({ api, say, card, runTurn, draft }),
+    answer: (text) => card.answer(text),
+    pending: () => card.pending(),
+    touch: () => card.touch()
+  };
+}

package/lib/quoxon/slash/watch.js

@@ -0,0 +1,164 @@
+/**
+ * /watch <anything>: turn a site, repo, server, competitor page, metric or condition into an ongoing observer.
+ * Backend (real): an agent schedule on the tasks service (POST /api/agent-schedules). Each tick the scheduler runs
+ * the watch prompt as an objective and escalates to the owner's Approvals inbox per the escalation policy.
+ */
+const DAY = 1440;
+const PAGE_WORDS = /\b(competitor|competitors|pricing|price|prices|plans?|changelog|blog|docs|landing)\b/i;
+const SERVER_WORDS = /\b(server|host|box|vm|node|gitea|nginx|postgres|redis|db|database|service|container|docker|disk|cpu|memory|ram|load|health|healthy|status)\b/i;
+const METRIC_WORDS = /\b(metric|signups?|sign-ups?|revenue|mrr|arr|traffic|errors?|latency|conversion|sales|users?|churn|orders?|visits?)\b/i;
+const URL_RE = /\bhttps?:\/\/[^\s]+/i;
+const GITHUB_RE = /\b(?:https?:\/\/)?github\.com\/[\w.-]+\/[\w.-]+/i;
+const DOMAIN_RE = /\b(?:[a-z0-9-]+\.)+[a-z]{2,}(?:\/[^\s]*)?/i;
+
+const DEFAULT_CONDITION = {
+  site: 'it is down, returns an error status, or responds very slowly',
+  server: 'it is unhealthy or unreachable',
+  page: 'the page changes in a way that matters (prices, plans, wording, new sections)',
+  repo: 'something needs attention: failing CI, new issues or security alerts'
+};
+const unitMin = (n, u) => { const x = u.toLowerCase(); return x.startsWith('h') ? n * 60 : x.startsWith('d') ? n * DAY : n; };
+const strip = (s) => s.replace(/[),.;]+$/, '');
+
+/** "quox.ai for downtime every 5 minutes" -> { kind, target, condition, everyMin|null } */
+export function parseWatch(text) {
+  let t = String(text || '').trim();
+  let everyMin = null;
+  const ev = t.match(/\b(?:every|each)\s+(\d+)\s*(minutes?|mins?|m|hours?|hrs?|h|days?|d)\b/i);
+  if (ev) { everyMin = unitMin(Number(ev[1]), ev[2]); t = t.replace(ev[0], ' '); }
+  else {
+    const w = t.match(/\b(hourly|daily)\b/i);
+    if (w) { everyMin = w[1].toLowerCase() === 'hourly' ? 60 : DAY; t = t.replace(w[0], ' '); }
+  }
+  t = t.replace(/\s+/g, ' ').trim();
+  if (!t) return { kind: 'none', target: '', condition: '', everyMin };
+
+  let left = t, cond = '';
+  const m = t.match(/^(.*?)\s+(?:for|when|whenever|if)\s+(.+)$/i);
+  if (m && m[1].trim()) { left = m[1].trim(); cond = m[2].trim(); }
+
+  const url = left.match(URL_RE)?.[0];
+  const gh = left.match(GITHUB_RE)?.[0];
+  const dom = !url && !gh ? left.match(DOMAIN_RE)?.[0] : null;
+  const out = (kind, target, condition) => ({ kind, target, condition, everyMin });
+
+  if (gh || /\brepo(sitory)?\b/i.test(left)) {
+    return out('repo', gh ? strip(gh).replace(/^https?:\/\//, '') : (left.replace(/\brepo(sitory)?\b/i, '').trim() || left), cond || DEFAULT_CONDITION.repo);
+  }
+  if (url || dom) {
+    const target = strip(url || dom);
+    const pageish = PAGE_WORDS.test(left) && !/\b(down|downtime|uptime|outage)\b/i.test(cond);
+    return pageish ? out('page', target, cond || DEFAULT_CONDITION.page) : out('site', target, cond || DEFAULT_CONDITION.site);
+  }
+  if (PAGE_WORDS.test(left) && !METRIC_WORDS.test(left)) return out('page', left, cond || DEFAULT_CONDITION.page);
+  if (METRIC_WORDS.test(left)) return out('metric', left, cond || left);
+  if (SERVER_WORDS.test(left) && left.split(' ').length <= 3) {
+    const target = left.replace(/\b(health|healthy|status)\b/gi, '').replace(/\s+/g, ' ').trim() || left;
+    return out('server', target, cond || DEFAULT_CONDITION.server);
+  }
+  return out('condition', cond ? left : t, cond || t);
+}
+
+/** Cron-friendly interval in minutes (floor 5, whole hours above an hour, cap one day). */
+export function normalizeEvery(min) {
+  const n = Number(min);
+  if (!Number.isFinite(n) || n <= 0) return 15;
+  if (n >= DAY) return DAY;
+  if (n < 5) return 5;
+  if (n < 60) return [5, 10, 15, 20, 30, 60].reduce((a, b) => (Math.abs(b - n) < Math.abs(a - n) ? b : a));
+  return Math.min(23, Math.max(1, Math.round(n / 60))) * 60;
+}
+export function everyToCron(min) {
+  const n = normalizeEvery(min);
+  if (n >= DAY) return '0 9 * * *';
+  if (n === 60) return '0 * * * *';
+  if (n > 60) return `0 */${n / 60} * * *`;
+  return `*/${n} * * * *`;
+}
+export const everyLabel = (min) => { const n = normalizeEvery(min); return n >= DAY ? 'day' : n === 60 ? 'hour' : n > 60 ? `${n / 60} h` : `${n} min`; };
+
+const KIND = { site: 'website', server: 'server', page: 'web page', repo: 'repository', metric: 'metric', condition: 'condition' };
+const slug = (s) => { const x = String(s).replace(/^https?:\/\//i, '').replace(/\/+$/, ''); return x.length > 60 ? `${x.slice(0, 59)}…` : x; };
+
+const watchPrompt = (name, w) => [
+  `You are running a scheduled watch named "${name}".`,
+  `Target (${KIND[w.kind] || w.kind}): ${w.target}.`,
+  `Condition to detect: ${w.condition}.`,
+  'Check the target now using the read-only tools you have. Change nothing.',
+  'If the condition is NOT met, finish with the single line "ok" and raise nothing: stay quiet.',
+  'If it IS met, raise it to the owner as a notification or inbox item: what you saw, when, and the evidence, in 3 lines or fewer.',
+  'If you cannot check it at all (no tool, no access), say exactly that once; do not pretend it is fine.'
+].join('\n');
+
+/** -> { body (POST /api/agent-schedules), card[] , every } */
+export function buildWatchPlan(w) {
+  const every = normalizeEvery(w.everyMin ?? 15);
+  const cron = everyToCron(every);
+  const name = `watch:${slug(w.target)}`;
+  const budget = { maxTokensPerRun: 20000, maxToolCallsPerRun: 10, maxDurationMs: 120000 };
+  const body = {
+    agentId: 'quox', name, cronExpression: cron, timezone: 'UTC',
+    taskTemplate: { title: name, prompt: watchPrompt(name, w) },
+    escalationPolicy: { onFailure: 'ESCALATE', escalateTo: null },
+    budget, maxConsecutiveFailures: 5
+  };
+  const card = [
+    ['Watch preview (nothing is created until you answer):', 'accent'],
+    `  Watching   ${w.target}  (${KIND[w.kind] || w.kind})`,
+    `  Triggers   ${w.condition}`,
+    `  Checks     every ${everyLabel(every)} (cron ${cron}, UTC)`,
+    '  Notifies   you, in your Approvals inbox, only when it triggers or the watch keeps failing',
+    `  Runs as    agent quox, read-only by instruction, ${budget.maxToolCallsPerRun} tool calls per check`
+  ];
+  return { body, card, every };
+}
+
+const USAGE = 'Usage: /watch <what> [for <condition>] [every 5 min]   e.g. /watch quox.ai for downtime, /watch gitea health. Also /watch list, /watch stop <id>.';
+const why = (e) => `${e?.status ? `HTTP ${e.status}: ` : ''}${e?.message || 'failed'}`;
+
+export function createWatchCmd({ api, say, confirm }) {
+  const listed = async () => {
+    const rows = await api.watchList();
+    return (Array.isArray(rows) ? rows : rows?.schedules || []).filter((s) => String(s.name || '').startsWith('watch:'));
+  };
+  async function list() {
+    let rows;
+    try { rows = await listed(); } catch (e) { return say(`Could not list watches: ${why(e)}`, 'warn'); }
+    if (!rows.length) return say('No watches yet. /watch quox.ai for downtime sets one up.');
+    say(`Watches (${rows.length}):`);
+    for (const s of rows) say(`  ${s.id}  ${s.name.slice(6)}  cron ${s.cron_expression}  ${Number(s.enabled) === 0 ? 'stopped' : (s.last_status || 'no check yet')}`);
+    return say('Stop one with /watch stop <id>.', 'dim');
+  }
+  async function stop(idArg) {
+    if (!idArg) return say('Usage: /watch stop <id>  (/watch list shows ids)', 'warn');
+    let rows;
+    try { rows = await listed(); } catch (e) { return say(`Could not read watches: ${why(e)}`, 'warn'); }
+    const hits = rows.filter((s) => s.id === idArg || s.id.toLowerCase().startsWith(idArg.toLowerCase()));
+    if (hits.length !== 1) return say(hits.length ? `"${idArg}" matches ${hits.length} watches; use more of the id.` : `No watch "${idArg}". /watch list shows them.`, 'warn');
+    try { await api.watchStop(hits[0].id); } catch (e) { return say(`Could not stop ${hits[0].id}: ${why(e)}`, 'warn'); }
+    return say(`✔ Stopped watch ${hits[0].id} (${hits[0].name.slice(6)}).`, 'ok');
+  }
+  function create(text) {
+    const w = parseWatch(text);
+    if (!w.target) return say(USAGE, 'warn');
+    const plan = buildWatchPlan(w);
+    confirm.ask(plan.card, async () => {
+      let r;
+      try { r = await api.watchCreate(plan.body); } catch (e) { return say(`Could not create the watch: ${why(e)}. Nothing is watching.`, 'warn'); }
+      if (!r?.id) return say('The server returned no watch id, so I cannot confirm it exists. /watch list shows what is there.', 'warn');
+      say(`✔ Watching ${w.target} (id ${r.id}). First check within ${everyLabel(plan.every)}.`, 'ok');
+      say(`  Stop it: /watch stop ${r.id}    See all: /watch list`);
+    }, { prompt: 'Create this watch?' });
+    return undefined;
+  }
+  return {
+    handle(arg) {
+      const a = String(arg || '').trim();
+      if (!a) return say(USAGE);
+      if (!api.watchCreate) return say('Watches are not available in this mode.', 'warn');
+      if (/^list$/i.test(a)) return list();
+      const s = a.match(/^(?:stop|rm)\b\s*(.*)$/i);
+      return s ? stop(s[1].trim()) : create(a);
+    }
+  };
+}

package/lib/quoxon/slash/wish.js

@@ -0,0 +1,23 @@
+/** /wish: the prompt that makes Quox draft a spec, reading its shape back, and the follow-up prompts. */
+export const SHAPE_LABEL = { skill: 'a skill', workflow: 'a workflow', power: 'a power from a repo', code: 'needs code' };
+
+export const wishPrompt = (wish) => 'The user wishes Quox could do something it cannot do today. Do NOT build or install anything and do not call any state-changing tool. '
+  + 'Reply with a SHORT design spec, plain lines, no preamble, using exactly these labels:\n'
+  + 'What it does: one or two sentences.\n'
+  + 'Uses: which existing Quox tools, CLI commands or APIs it would call.\n'
+  + 'Hat: which hat and permissions it needs.\n'
+  + 'Tests: what would prove it works.\n'
+  + 'Shape: exactly one of skill | workflow | power | code  (skill = a procedure an agent follows; workflow = a scheduled or triggered sequence of existing steps; power = packaged from a repo; code = needs new code).\n\n'
+  + `Wish: ${String(wish).trim().slice(0, 1500)}`;
+
+/** -> 'skill' | 'workflow' | 'power' | 'code' | null (no readable Shape line). */
+export function parseShape(spec) {
+  const m = /^\s*shape\s*:\s*(skill|workflow|power|code)\b/im.exec(String(spec || ''));
+  return m ? m[1].toLowerCase() : null;
+}
+
+export const creationPrompt = (shape, wish, spec) => (shape === 'skill'
+  ? `The user approved this spec. Create it now as a skill with skill_manage (op=create; it lands experimental and queued for review, which is expected). Use only what the spec says.\n\nWish: ${wish}\n\n${spec}`
+  : `The user approved this spec. Create it now as a workflow with your workflow tool, left inactive: do not activate it or deploy it, and do not schedule it. Use only what the spec says.\n\nWish: ${wish}\n\n${spec}`);
+
+export const requestText = (wish, spec) => `Feature request from /wish: ${wish}\n\nDrafted spec:\n${String(spec).trim()}\n\nNo shape of skill or workflow fit, so this needs the normal build and review path.`;

package/lib/quoxon/slash/wishCmd.js

@@ -0,0 +1,32 @@
+/** /wish: draft a governed spec, show it as one card, and on y create (skill, workflow) or file (power, code). Never installs code. */
+import { wishPrompt, parseShape, creationPrompt, requestText, SHAPE_LABEL } from './wish.js';
+
+const clip = (s, n) => { const t = String(s || '').replace(/\s+/g, ' ').trim(); return t.length > n ? `${t.slice(0, n - 1)}…` : t; };
+
+export function createWishCmd({ api, say, card, runTurn, draft }) {
+  return async function wish(arg) {
+    const text = String(arg || '').trim();
+    if (!text) return say('Usage: /wish <what you wish Quox could do>', 'warn');
+    if (!draft) return say('/wish is not available in this mode.', 'warn');
+    say('Drafting a spec for that…', 'dim');
+    let spec;
+    try { spec = await draft(wishPrompt(text)); } catch (e) { spec = null; say(`Draft failed: ${e?.message || e}`, 'warn'); }
+    if (!spec || !String(spec).trim()) return say('Quox could not draft a spec for that, so nothing was proposed. Try /wish again.', 'warn');
+    const shape = parseShape(spec);
+    const body = String(spec).trim().split('\n').slice(0, 14).map(l => clip(l, 110));
+    const plan = shape === 'skill' || shape === 'workflow'
+      ? `On y: Quox creates it as ${shape === 'skill' ? 'an experimental skill queued for human review' : 'an inactive workflow'} through the normal governed path (you will see its tool call and receipt).`
+      : `On y: the spec is filed as a feature request (${shape ? SHAPE_LABEL[shape] : 'shape unclear, treated as needing code'}). Nothing is installed; code goes through the normal build and review path.`;
+    card.ask([`wish │ ${clip(text, 80)}`, ...body], // the plan is the card's "do" row
+      async () => {
+        if (shape === 'skill' || shape === 'workflow') { say(`Creating the ${shape}…`, 'dim'); return runTurn(creationPrompt(shape, text, spec)); }
+        if (!api.gripe) return say('Filing is not available in this mode; the spec is above.', 'warn');
+        const g = await api.gripe(requestText(text, spec).slice(0, 4000), { yes: true });
+        if (!g.ok) return say(`Not filed: ${g.message}`, 'warn');
+        const url = (g.notes || []).find(n => n.kind === 'created')?.url;
+        say(url ? `Filed as a feature request: ${url}. Nothing was installed.` : 'Filed as a feature request. Nothing was installed.', 'ok');
+        return undefined;
+      }, 'Cancelled; nothing was created or filed.', { who: 'Quox', question: shape === 'skill' || shape === 'workflow' ? `Create the ${shape}?` : 'File it as a governed spec?', action: plan.replace(/^On y: /, '') });
+    return undefined;
+  };
+}