@workser/cli 0.2.2 → 0.2.4

package/dist/index.js

@@ -3709,6 +3709,67 @@ workflow produces a result the app needs, its final node has to POST back to a
 webhook route in the app. Build only the trigger and the workflow runs perfectly
 while nothing ever appears in the product. The app-side receiver is covered in the
 \`workser-sdk\` skill under workflows.
+`
+  },
+  {
+    topic: "brand",
+    title: "The project's brand",
+    summary: "Read the owner's colours, fonts and logo before writing UI, and wire the generated design tokens into the app's theme.",
+    commands: ["design"],
+    source: "skills/workser/reference/brand.md",
+    body: `# The project's brand
+
+\`\`\`
+workser design show [--raw]
+\`\`\`
+
+The owner sets their brand once in Workser (logo, colours, fonts). Everything
+you build should follow it. Read it **before writing any UI**:
+
+\`\`\`bash
+workser design show --json
+\`\`\`
+
+\`\`\`json
+{"ok":true,"data":{"hasBrand":true,
+  "colors":{"primary":"#1f7a4d","accent":"#f5a623"},
+  "fonts":{"heading":"Inter","body":"Inter"},
+  "brand":{"name":"Green Grocer"},
+  "files":["design/tokens.json","design/tokens.css"]}}
+\`\`\`
+
+This asks the server, which derives the answer from the brand record itself \u2014 so
+it is correct even if nothing has been written into the working tree yet. That's
+the reason to use it instead of looking for a file and guessing when it's absent.
+
+\`"hasBrand": false\` is an ordinary state \u2014 most projects have no brand set.
+Choose sensible styling yourself; **don't** stop and ask the user to define a
+brand first.
+
+## Using it in the code
+
+The same values are generated into the working tree as two files:
+
+- \`design/tokens.json\` \u2014 the tokens in DTCG form
+- \`design/tokens.css\` \u2014 plain CSS custom properties (\`--ws-color-*\`, \`--ws-font-*\`)
+
+Wire \`design/tokens.css\` into the app's theme the way this app's setup expects \u2014
+it assumes no particular Tailwind version, so map it rather than pasting it.
+
+**Both files are generated and overwritten wholesale.** Never hand-edit them;
+your edit disappears on the next sync. \`workser design show --raw\` prints them
+verbatim if you need to see exactly what's in them.
+
+## Changing the brand is the owner's job
+
+There is no \`workser design set\` \u2014 the brand is one record the owner controls in
+the Workser app, and it drives everything generated from it. If the user asks you
+to change their brand colour, tell them where it lives (Design \u2192 Brand in Orbit)
+rather than writing the colour into the app by hand, which would drift from every
+other surface the brand feeds.
+
+For generating artwork *in* the brand's palette, see \`workser help images\` \u2014
+put the colours from \`design show\` into the prompt.
 `
   },
   {
@@ -4090,26 +4151,194 @@ The user can configure **roles** \u2014 named specialists each backed by a local
 (e.g. \`qa\` \u2192 codex, \`designer\` \u2192 claude_code).
 
 \`\`\`
-workser agent list                  # main agent + configured roles (+ which are runnable)
-workser agent run <role> "<task>"   # delegate a focused subtask (runs isolated)
+workser agent list                  # main agent + configured roles + which agents are connected
+workser agent run <role> "<task>"   # delegate to a CONFIGURED role (runs isolated)
+workser agent spawn <agent> "<task>" [--role <label>] [--instructions <text>] [--model <model>]
+                                     # spin up a TEMPORARY teammate on any connected agent CLI
 workser agent main                  # show the configured main agent
 \`\`\`
 
 ## How to use it
 
-Run \`workser agent list --json\` first \u2014 it tells you which roles exist **and** which
-are actually runnable on this machine. Delegating to a role that isn't installed just
-fails.
+Run \`workser agent list --json\` first \u2014 it tells you which roles exist, which are
+actually runnable on this machine, and which agent CLIs are connected at all
+(\`spawnable\`). Delegating to a role that isn't installed, or spawning an agent that
+isn't connected, just fails.
+
+\`workser agent run <role> "<task>" --json\` runs a **configured** role as an isolated
+local subagent and returns \`{role, agent, output, exitCode}\`.
+
+\`workser agent spawn <agent> "<task>" --json\` does the same thing without a
+pre-configured role \u2014 \`<agent>\` is one of \`claude_code|codex|kimi|opencode|grok\`, any
+of which can be connected on this machine. Use it to fan work out in parallel for
+one-off work with no matching role: e.g. spawn \`codex\` to research a topic while you
+keep working, or run a second \`claude_code\` instance on a different part of the same
+task. \`--instructions\` sets that teammate's system prompt for this one run \u2014 give it
+real scope, not just a repeat of the task.
+
+- Hand off focused subtasks \u2014 review this diff, design this screen, research this API \u2014
+  to keep your own context lean and get a specialized second perspective.
+- **A non-zero \`exitCode\` means the run failed.** Surface that; don't quietly treat
+  empty output as success.
+- The subagent doesn't share your context, configured role or spawned. Put everything
+  it needs in the task string (and \`--instructions\` for a spawn); it cannot see the
+  conversation you're in.
+- Never give a subagent \u2014 configured or spawned \u2014 a task that tells it to delegate or
+  spawn further. It has no supervision loop to stop a runaway chain.
+`
+  },
+  {
+    topic: "sdlc-entities",
+    title: "Board cards, decisions, requirements, and docs",
+    summary: "Read what this project already tracks and decided, keep the Board honest as you work, and record what a future maintainer will need.",
+    commands: ["board", "decision", "requirement", "doc"],
+    source: "skills/workser/reference/sdlc-entities.md",
+    body: `# Board cards, decisions, requirements, and docs
+
+These are the project's memory across sessions. They write to the **same tables**
+the Orbit desktop's Board, Project Memory, and Docs panels use, so anything here
+appears there too \u2014 and (when this CLI runs inside an Orbit-spawned agent run)
+as an inline card in the conversation you're working in.
+
+\`\`\`
+workser board list [--status <value>] [--label <value>] [--limit <n>]
+workser board show <id>
+workser board create <title> [--description <text>] [--status <value>]
+                              [--priority <value>] [--label <value>]
+                              [--owner <name>] [--milestone <id>]
+workser board update <id> [--title|--description|--status|--priority
+                           |--label|--owner|--milestone ...]
+workser board move <id> <backlog|in-progress|in-review|done>
+workser board close <id>
+
+workser decision list [--limit <n>]
+workser decision show <id>
+workser decision create <title> --context <text> --decision <text>
+                                 [--consequences <text>]
+
+workser requirement list [--status <value>] [--limit <n>]
+workser requirement show <id>
+workser requirement create <title> --body <text> [--status <text>]
+workser requirement update <id> [--title <text>] [--body <text>] [--status <text>]
+
+workser doc list [--work-item <id>]
+workser doc show <id> [--markdown]
+workser doc create <title> [--work-item <id>] [--markdown <text>]
+                            [--content-json <json>]
+workser doc update <id> [--title <text>] [--markdown <text>]
+\`\`\`
+
+## Read first \u2014 this is the part that matters
+
+Before starting anything beyond a trivial edit:
 
-\`workser agent run <role> "<task>" --json\` runs the role as an **isolated local
-subagent** with its own context and returns \`{role, agent, output, exitCode}\`.
+\`\`\`
+workser board list --json          # what's already tracked (don't re-file it)
+workser decision list --json       # what was already decided (don't reverse it)
+\`\`\`
+
+The project outlives your session. A decision recorded three weeks ago is the
+only thing standing between you and quietly undoing a choice someone made on
+purpose \u2014 \`workser decision show <id>\` gives you the context and consequences,
+not just the title. Reach for \`workser doc list\` / \`workser requirement list\`
+the same way when the task touches documented behaviour.
+
+## Keep the Board honest while you work
+
+A Board still reading \`backlog\` after the feature shipped tells the user the
+opposite of the truth. Moving the card is part of finishing the work:
 
-- Hand off focused subtasks \u2014 review this diff, design this screen \u2014 to keep your own
-  context lean and get a specialized second perspective.
-- **A non-zero \`exitCode\` means the role's run failed.** Surface that; don't quietly
-  treat empty output as success.
-- The subagent doesn't share your context. Put everything it needs in the task
-  string; it cannot see the conversation you're in.
+\`\`\`
+workser board move <id> in-progress   # you picked it up
+workser board move <id> in-review     # ready for the user to look at
+workser board close <id>              # done and verified
+\`\`\`
+
+\`--status\` is one of \`backlog | in-progress | in-review | done\` (default
+\`backlog\`). \`--priority\` is one of \`low | normal | high | urgent\` (default
+\`normal\`). \`--label\` repeats for more than one label:
+
+\`\`\`
+workser board create "Fix the login bug" --status in-progress --priority high \\
+  --label bug --label auth
+\`\`\`
+
+\`board update\` replaces the labels you pass rather than merging them, and
+touches only the fields you name. There is no \`board delete\` \u2014 \`done\` is the
+terminal state for finished work, and removing a card the user filed is theirs
+to do in Orbit.
+
+## Decisions are append-only
+
+\`decision create\` is for something with real tradeoffs worth a paper trail:
+\`--context\` is why it came up, \`--decision\` is what was decided,
+\`--consequences\` is the follow-on effects. There is deliberately **no
+\`decision update\`** \u2014 a decision record states what was decided at a point in
+time. When it stops being right, record a new decision that supersedes it and
+say so in its \`--context\`. Editing the history is how a decision log stops
+being worth reading.
+
+Requirements are different: they legitimately move along, so they do have
+\`update\`.
+
+\`\`\`
+workser requirement create "Support SSO" --body "Enterprise customers need SAML." \\
+  --status proposed
+workser requirement update <id> --status done
+\`\`\`
+
+## Docs
+
+\`--markdown\` is the normal way to write one. The body is stored both as the
+rich-text content the Docs panel renders and as a git-tracked markdown mirror
+at \`.workser/docs/<id>.md\` \u2014 \`workser doc show <id> --markdown\` reports that
+path so you can read the file with your normal tools.
+
+Revise the page that exists rather than creating a second copy of it:
+
+\`\`\`
+workser doc list --json                       # is there already a page for this?
+workser doc update <id> --markdown "$(cat updated.md)"
+\`\`\`
+
+\`--work-item <id>\` links a document to a Board card (a card has at most one).
+
+## When to record, and when not to
+
+Record what a future maintainer would need: follow-up work you found but didn't
+do, a choice between real alternatives, a behaviour worth writing down. Don't
+narrate every small step \u2014 and never treat filing a card as a substitute for
+the work. Creating a Board card that says "fix the bug" is not fixing the bug.
+`
+  },
+  {
+    topic: "search",
+    title: "Web search",
+    summary: "Google-grounded web search, run server-side \u2014 the API key never reaches you.",
+    commands: ["search"],
+    source: "skills/workser/reference/search.md",
+    body: `# Web search \u2014 ask the internet, not just the model
+
+\`\`\`
+workser search "<query>" [-n, --max-results <n>]   # Google-grounded web search
+\`\`\`
+
+## Why this exists
+
+A local agent can drive a browser, but it can't "search the web" without a URL
+already in hand \u2014 \`browser\` automation needs somewhere to point. This runs a
+real, grounded Google search server-side (core-api holds the API key; it never
+reaches the daemon, the CLI, or you) and returns a synthesized answer plus the
+source links behind it.
+
+## Using it well
+
+- Prefer this over guessing or asking the user when you need current facts,
+  prices, docs for a library, or anything time-sensitive.
+- The \`answer\` is a synthesized summary \u2014 the \`results\` list is the sources it
+  drew from. Cite or open one of those links if the user needs to verify the
+  claim themselves.
+- Not project-scoped: it's a general research tool, not tied to a project's data.
 `
   },
   {
@@ -4308,7 +4537,8 @@ function buildContext(opts) {
   const link = readProjectLink(cwd);
   const projectId = opts.project || process.env.WORKSER_PROJECT_ID || link?.projectId || session.defaultProjectId;
   const runId = process.env.WORKSER_RUN_ID || void 0;
-  return { endpoint, socketPath, token, mode: mode2, cwd, projectId, runId };
+  const conversationId = process.env.WORKSER_CONVERSATION_ID || void 0;
+  return { endpoint, socketPath, token, mode: mode2, cwd, projectId, runId, conversationId };
 }
 function runTarget(ctx) {
   return ctx.runId || "current";
@@ -5432,6 +5662,7 @@ function maskToken(token) {
 
 // src/commands/agent.ts
 var import_picocolors14 = __toESM(require_picocolors(), 1);
+var SPAWNABLE_AGENTS = ["claude_code", "codex", "kimi", "opencode", "grok"];
 function registerAgent(program3) {
   const agent = program3.command("agent").description("Delegate focused subtasks to your configured agent roles (each runs isolated)");
   agent.command("list").description("List the main agent (+ backup) and the configured subagents").action(
@@ -5448,9 +5679,19 @@ function registerAgent(program3) {
           );
         }
         const roles = cfg?.roles ?? [];
-        if (!roles.length) return line(import_picocolors14.default.dim("No subagents configured. Add them in the Workser Orbit Agents screen."));
-        line(import_picocolors14.default.bold("subagents:"));
-        for (const r of roles) line("  " + formatRole(r));
+        if (!roles.length) {
+          line(import_picocolors14.default.dim("No subagents configured. Add them in the Workser Orbit Agents screen."));
+        } else {
+          line(import_picocolors14.default.bold("subagents:"));
+          for (const r of roles) line("  " + formatRole(r));
+        }
+        const detected = cfg?.detected ?? [];
+        const spawnable = detected.filter(
+          (d) => d?.installed && d?.authed !== false
+        );
+        line(
+          import_picocolors14.default.bold("spawnable (workser agent spawn <agent>):") + " " + (spawnable.length ? spawnable.map((d) => toContractId(d.id)).join(", ") : import_picocolors14.default.dim("none connected"))
+        );
       });
     })
   );
@@ -5484,6 +5725,38 @@ function registerAgent(program3) {
       if (exitCode !== 0) process.exitCode = exitCode;
     })
   );
+  agent.command("spawn <agent> <task...>").description(
+    `Spin up a TEMPORARY teammate on any connected agent CLI (not a saved role) for a one-off task. <agent>: ${SPAWNABLE_AGENTS.join("|")}`
+  ).option("--role <label>", "display label for this run (default: <agent>)").option(
+    "--instructions <text>",
+    "system prompt for this one run \u2014 this teammate's expertise/scope"
+  ).option("--model <model>", "model override for the backing CLI").option("--effort <level>", "reasoning effort, where the backing CLI supports it").action(
+    action(async ({ ctx, args, opts }) => {
+      const spawnAgent = args[0];
+      const task = args[1].join(" ");
+      const res = await api(ctx, "/v1/agents/run", {
+        body: {
+          agent: spawnAgent,
+          task,
+          role: opts.role,
+          instructions: opts.instructions,
+          model: opts.model,
+          effort: opts.effort
+        }
+      });
+      const exitCode = res?.exitCode ?? 0;
+      ok(res, () => {
+        if (res?.output) line(res.output);
+        if (exitCode !== 0) {
+          warn(`Spawned ${spawnAgent} exited with code ${exitCode}.`);
+        }
+      });
+      if (exitCode !== 0) process.exitCode = exitCode;
+    })
+  );
+}
+function toContractId(id) {
+  return id === "claude" ? "claude_code" : id;
 }
 function formatRole(r) {
   const label = import_picocolors14.default.yellow(r.role);
@@ -6118,9 +6391,588 @@ function extract(response) {
   return String(response);
 }
 
+// src/commands/search.ts
+var import_picocolors23 = __toESM(require_picocolors(), 1);
+function registerSearch(program3) {
+  program3.command("search <query>").description("Search the web (Google-grounded, server-side)").option("-n, --max-results <n>", "max results", "5").action(
+    action(async ({ ctx, args, opts }) => {
+      const res = await api(ctx, "/v1/search", {
+        query: { q: args[0], maxResults: opts.maxResults }
+      });
+      ok(res, () => {
+        if (res?.answer) {
+          line(res.answer);
+          line("");
+        }
+        const results = res?.results ?? [];
+        if (!results.length) return line(import_picocolors23.default.dim("No results."));
+        for (const r of results) {
+          line(`${r.title || import_picocolors23.default.dim("(untitled)")}  ${import_picocolors23.default.dim(r.url)}`);
+        }
+      });
+    })
+  );
+}
+
+// src/commands/board.ts
+var import_picocolors24 = __toESM(require_picocolors(), 1);
+
+// src/commands/record-step.ts
+async function recordEntityStep(ctx, opts) {
+  if (!ctx.runId) return;
+  await api(ctx, `/v1/runs/${ctx.runId}/steps`, {
+    body: {
+      title: opts.title,
+      refType: opts.refType,
+      refId: opts.refId,
+      output: opts.output
+    }
+  }).catch(() => void 0);
+}
+
+// src/commands/board.ts
+var STATUSES = ["backlog", "in-progress", "in-review", "done"];
+var PRIORITIES = ["low", "normal", "high", "urgent"];
+function registerBoard(program3) {
+  const board = program3.command("board").description("Read and update the project's Board (work items)");
+  board.command("list").description("List the Board's cards \u2014 run this before starting work").option("--status <value>", `only cards in this status (${STATUSES.join(" | ")})`).option("--label <value>", "only cards carrying this label").option("--limit <n>", "cap the number of cards returned").action(
+    action(async ({ ctx, opts }) => {
+      const projectId = requireProject(ctx);
+      if (opts.status !== void 0) assertStatus(opts.status);
+      const all = await api(ctx, `/v1/projects/${projectId}/work-items`) ?? [];
+      let rows = all;
+      if (opts.status) rows = rows.filter((r) => r.status === opts.status);
+      if (opts.label) rows = rows.filter((r) => (r.labels ?? []).includes(opts.label));
+      if (opts.limit) {
+        const n = Number(opts.limit);
+        if (!Number.isFinite(n) || n < 1) {
+          throw new WorkserError(`--limit must be a positive number, got "${opts.limit}".`, {
+            code: "bad_request"
+          });
+        }
+        rows = rows.slice(0, n);
+      }
+      ok(rows, () => {
+        if (!rows.length) {
+          line(import_picocolors24.default.dim("No cards on the Board yet."));
+          return;
+        }
+        for (const r of rows) line(formatRow(r));
+      });
+    })
+  );
+  board.command("show <id>").description("Show one card in full, e.g. `workser board show <id>`").action(
+    action(async ({ ctx, args }) => {
+      const projectId = requireProject(ctx);
+      const row = await api(
+        ctx,
+        `/v1/projects/${projectId}/work-items/${args[0]}`
+      );
+      ok(row, () => {
+        line(`${import_picocolors24.default.bold(row.title)}  ${import_picocolors24.default.dim(row.id)}`);
+        line(`${statusTag(row.status)}  priority ${row.priority}`);
+        if (row.ownerHuman) line(`owner: ${row.ownerHuman}`);
+        if (row.labels?.length) line(`labels: ${row.labels.join(", ")}`);
+        if (row.description) line(`
+${row.description}`);
+      });
+    })
+  );
+  board.command("create <title>").description('Create a work item, e.g. `workser board create "Fix the login bug"`').option("--description <text>", "longer description").option("--status <value>", `${STATUSES.join(" | ")} (default: backlog)`).option("--priority <value>", `${PRIORITIES.join(" | ")} (default: normal)`).option(
+    "--label <value>",
+    "a label to attach (repeat for more)",
+    collect2,
+    []
+  ).option("--owner <name>", "the human who owns this card").option("--milestone <id>", "milestone id to attach this card to").action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const title = String(args[0] ?? "").trim();
+      if (!title) {
+        throw new WorkserError("A work item needs a title.", { code: "bad_request" });
+      }
+      if (opts.status !== void 0) assertStatus(opts.status);
+      if (opts.priority !== void 0) assertPriority(opts.priority);
+      const labels = opts.label;
+      const row = await api(ctx, `/v1/projects/${projectId}/work-items`, {
+        body: {
+          title,
+          description: opts.description,
+          status: opts.status,
+          priority: opts.priority,
+          labels: labels.length ? labels : void 0,
+          ownerHuman: opts.owner,
+          milestoneId: opts.milestone
+        }
+      });
+      await recordEntityStep(ctx, {
+        title: `Created work item: ${title}`,
+        refType: "agent_created_work_item",
+        refId: row?.id,
+        output: { workItem: row }
+      });
+      ok(row, () => line(`Created work item ${import_picocolors24.default.bold(row?.id ?? "")} \u2014 ${title}`));
+    })
+  );
+  board.command("update <id>").description("Change fields on a card \u2014 pass only what changes").option("--title <text>", "new title").option("--description <text>", "new description").option("--status <value>", STATUSES.join(" | ")).option("--priority <value>", PRIORITIES.join(" | ")).option(
+    "--label <value>",
+    "replace the card's labels with these (repeat for more)",
+    collect2,
+    []
+  ).option("--owner <name>", "the human who owns this card").option("--milestone <id>", "milestone id to attach this card to").action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      if (opts.status !== void 0) assertStatus(opts.status);
+      if (opts.priority !== void 0) assertPriority(opts.priority);
+      const labels = opts.label;
+      const body = {
+        title: opts.title,
+        description: opts.description,
+        status: opts.status,
+        priority: opts.priority,
+        // Commander's default `[]` is indistinguishable from "the user asked
+        // for zero labels", so an empty array means "not specified" here.
+        // Clearing labels is a rare enough intent to leave to the UI rather
+        // than overload a flag that cannot express it unambiguously.
+        labels: labels.length ? labels : void 0,
+        ownerHuman: opts.owner,
+        milestoneId: opts.milestone
+      };
+      if (Object.values(body).every((v) => v === void 0)) {
+        throw new WorkserError(
+          "Nothing to update \u2014 pass at least one of --title, --description, --status, --priority, --label, --owner, --milestone.",
+          { code: "bad_request" }
+        );
+      }
+      const row = await patchItem(ctx, projectId, String(args[0]), body);
+      ok(row, () => line(`Updated ${import_picocolors24.default.bold(row.id)} \u2014 ${row.title} ${statusTag(row.status)}`));
+    })
+  );
+  board.command("move <id> <status>").description(
+    `Move a card to ${STATUSES.join(" | ")} \u2014 the one-liner for keeping the Board honest`
+  ).action(
+    action(async ({ ctx, args }) => {
+      const projectId = requireProject(ctx);
+      const status = String(args[1]);
+      assertStatus(status);
+      const row = await patchItem(ctx, projectId, String(args[0]), { status });
+      ok(row, () => line(`Moved ${import_picocolors24.default.bold(row.title)} \u2192 ${statusTag(row.status)}`));
+    })
+  );
+  board.command("close <id>").description("Shorthand for `board move <id> done`").action(
+    action(async ({ ctx, args }) => {
+      const projectId = requireProject(ctx);
+      const row = await patchItem(ctx, projectId, String(args[0]), { status: "done" });
+      ok(row, () => line(`Closed ${import_picocolors24.default.bold(row.title)} ${statusTag(row.status)}`));
+    })
+  );
+}
+async function patchItem(ctx, projectId, id, body) {
+  const row = await api(ctx, `/v1/projects/${projectId}/work-items/${id}`, {
+    method: "PATCH",
+    body
+  });
+  if (!row) {
+    throw new WorkserError(`No work item with id "${id}" on this project.`, {
+      code: "bad_request"
+    });
+  }
+  return row;
+}
+function assertStatus(value) {
+  if (!STATUSES.includes(value)) {
+    throw new WorkserError(
+      `Unknown status "${value}". Use one of: ${STATUSES.join(", ")}.`,
+      { code: "bad_request" }
+    );
+  }
+}
+function assertPriority(value) {
+  if (!PRIORITIES.includes(value)) {
+    throw new WorkserError(
+      `Unknown priority "${value}". Use one of: ${PRIORITIES.join(", ")}.`,
+      { code: "bad_request" }
+    );
+  }
+}
+function formatRow(r) {
+  const labels = r.labels?.length ? import_picocolors24.default.dim(` [${r.labels.join(", ")}]`) : "";
+  const owner = r.ownerHuman ? import_picocolors24.default.dim(` @${r.ownerHuman}`) : "";
+  return `${import_picocolors24.default.dim(r.id)}  ${statusTag(r.status)}  ${r.title}${labels}${owner}`;
+}
+function statusTag(status) {
+  const label = status.padEnd(11);
+  if (status === "done") return import_picocolors24.default.green(label);
+  if (status === "in-progress") return import_picocolors24.default.yellow(label);
+  if (status === "in-review") return import_picocolors24.default.cyan(label);
+  return import_picocolors24.default.dim(label);
+}
+function collect2(value, previous) {
+  return [...previous, value];
+}
+
+// src/commands/decision.ts
+var import_picocolors25 = __toESM(require_picocolors(), 1);
+function registerDecision(program3) {
+  const decision = program3.command("decision").description("Read and record the project's architecture decisions");
+  decision.command("list").description("Every decision on record \u2014 read this before changing how something works").option("--limit <n>", "cap the number returned (newest first)").action(
+    action(async ({ ctx, opts }) => {
+      const projectId = requireProject(ctx);
+      let rows = await api(
+        ctx,
+        `/v1/projects/${projectId}/architecture-decisions`
+      ) ?? [];
+      rows = applyLimit(rows, opts.limit);
+      ok(rows, () => {
+        if (!rows.length) {
+          line(import_picocolors25.default.dim("No decisions recorded yet."));
+          return;
+        }
+        for (const r of rows) {
+          line(`${import_picocolors25.default.dim(r.id)}  ${import_picocolors25.default.dim(shortDate(r.createdAt))}  ${r.title}`);
+          line(`    ${truncate(r.decision, 100)}`);
+        }
+      });
+    })
+  );
+  decision.command("show <id>").description("The full record \u2014 context, decision, and consequences").action(
+    action(async ({ ctx, args }) => {
+      const projectId = requireProject(ctx);
+      const row = await api(
+        ctx,
+        `/v1/projects/${projectId}/architecture-decisions/${args[0]}`
+      );
+      ok(row, () => {
+        line(`${import_picocolors25.default.bold(row.title)}  ${import_picocolors25.default.dim(row.id)}`);
+        line(import_picocolors25.default.dim(`${row.status} \xB7 ${shortDate(row.createdAt)}`));
+        line(`
+${import_picocolors25.default.bold("Context")}
+${row.context}`);
+        line(`
+${import_picocolors25.default.bold("Decision")}
+${row.decision}`);
+        if (row.consequences) line(`
+${import_picocolors25.default.bold("Consequences")}
+${row.consequences}`);
+      });
+    })
+  );
+  decision.command("create <title>").description(
+    'workser decision create "Use Postgres" --context ... --decision ... [--consequences ...]'
+  ).requiredOption("--context <text>", "why this decision was needed").requiredOption("--decision <text>", "what was decided").option("--consequences <text>", "tradeoffs / follow-on effects").action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const title = String(args[0] ?? "").trim();
+      if (!title) {
+        throw new WorkserError("A decision needs a title.", { code: "bad_request" });
+      }
+      const row = await api(ctx, `/v1/projects/${projectId}/architecture-decisions`, {
+        body: {
+          title,
+          context: opts.context,
+          decision: opts.decision,
+          consequences: opts.consequences,
+          conversationId: ctx.conversationId
+        }
+      });
+      await recordEntityStep(ctx, {
+        title: `Recorded decision: ${title}`,
+        refType: "agent_created_decision",
+        refId: row?.id,
+        output: { decision: row }
+      });
+      ok(row, () => line(`Recorded decision ${import_picocolors25.default.bold(row?.id ?? "")} \u2014 ${title}`));
+    })
+  );
+  const requirement = program3.command("requirement").description("Read and record the project's requirements");
+  requirement.command("list").description("Every requirement on record \u2014 read this before deciding what to build").option("--status <value>", "only requirements in this status, e.g. accepted").option("--limit <n>", "cap the number returned (newest first)").action(
+    action(async ({ ctx, opts }) => {
+      const projectId = requireProject(ctx);
+      let rows = await api(ctx, `/v1/projects/${projectId}/requirements`) ?? [];
+      if (opts.status) rows = rows.filter((r) => r.status === opts.status);
+      rows = applyLimit(rows, opts.limit);
+      ok(rows, () => {
+        if (!rows.length) {
+          line(import_picocolors25.default.dim("No requirements recorded yet."));
+          return;
+        }
+        for (const r of rows) {
+          line(`${import_picocolors25.default.dim(r.id)}  ${r.status.padEnd(9)}  ${r.title}`);
+        }
+      });
+    })
+  );
+  requirement.command("show <id>").description("The full requirement text").action(
+    action(async ({ ctx, args }) => {
+      const projectId = requireProject(ctx);
+      const row = await api(
+        ctx,
+        `/v1/projects/${projectId}/requirements/${args[0]}`
+      );
+      ok(row, () => {
+        line(`${import_picocolors25.default.bold(row.title)}  ${import_picocolors25.default.dim(row.id)}`);
+        line(import_picocolors25.default.dim(`${row.status} \xB7 ${shortDate(row.createdAt)}`));
+        line(`
+${row.body}`);
+      });
+    })
+  );
+  requirement.command("create <title>").description('workser requirement create "Support SSO" --body ... [--status ...]').requiredOption("--body <text>", "the requirement's text").option("--status <text>", "e.g. proposed | accepted | done").action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const title = String(args[0] ?? "").trim();
+      if (!title) {
+        throw new WorkserError("A requirement needs a title.", { code: "bad_request" });
+      }
+      const row = await api(ctx, `/v1/projects/${projectId}/requirements`, {
+        body: {
+          title,
+          body: opts.body,
+          status: opts.status
+        }
+      });
+      await recordEntityStep(ctx, {
+        title: `Recorded requirement: ${title}`,
+        refType: "agent_created_requirement",
+        refId: row?.id,
+        output: { requirement: row }
+      });
+      ok(row, () => line(`Recorded requirement ${import_picocolors25.default.bold(row?.id ?? "")} \u2014 ${title}`));
+    })
+  );
+  requirement.command("update <id>").description(
+    "Move a requirement along, e.g. `workser requirement update <id> --status done`"
+  ).option("--title <text>", "new title").option("--body <text>", "new requirement text").option("--status <text>", "e.g. proposed | accepted | done").action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const body = {
+        title: opts.title,
+        body: opts.body,
+        status: opts.status
+      };
+      if (Object.values(body).every((v) => v === void 0)) {
+        throw new WorkserError(
+          "Nothing to update \u2014 pass at least one of --title, --body, --status.",
+          { code: "bad_request" }
+        );
+      }
+      const row = await api(
+        ctx,
+        `/v1/projects/${projectId}/requirements/${args[0]}`,
+        { method: "PATCH", body }
+      );
+      if (!row) {
+        throw new WorkserError(`No requirement with id "${args[0]}" on this project.`, {
+          code: "bad_request"
+        });
+      }
+      ok(row, () => line(`Updated requirement ${import_picocolors25.default.bold(row.id)} \u2014 ${row.title} (${row.status})`));
+    })
+  );
+}
+function applyLimit(rows, limit) {
+  if (limit === void 0) return rows;
+  const n = Number(limit);
+  if (!Number.isFinite(n) || n < 1) {
+    throw new WorkserError(`--limit must be a positive number, got "${limit}".`, {
+      code: "bad_request"
+    });
+  }
+  return rows.slice(0, n);
+}
+function truncate(text, max) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}\u2026` : flat;
+}
+function shortDate(iso) {
+  return iso ? iso.slice(0, 10) : "";
+}
+
+// src/commands/doc.ts
+var import_picocolors26 = __toESM(require_picocolors(), 1);
+function registerDoc(program3) {
+  const doc = program3.command("doc").description("Read and write project documents");
+  doc.command("list").description("List the project's documents \u2014 check here before writing a new one").option("--work-item <id>", "the document linked to this card, if there is one").action(
+    action(async ({ ctx, opts }) => {
+      const projectId = requireProject(ctx);
+      const rows = await api(ctx, `/v1/projects/${projectId}/documents`, {
+        query: { workItemId: opts.workItem }
+      }) ?? [];
+      ok(rows, () => {
+        if (!rows.length) {
+          line(import_picocolors26.default.dim("No documents yet."));
+          return;
+        }
+        for (const r of rows) {
+          const link = r.workItemId ? import_picocolors26.default.dim(` \u21B3 ${r.workItemId}`) : "";
+          const file = r.filePath ? import_picocolors26.default.dim(`  ${r.filePath}`) : "";
+          line(`${import_picocolors26.default.dim(r.id)}  ${r.title}${link}${file}`);
+        }
+      });
+    })
+  );
+  doc.command("show <id>").description("Show a document \u2014 `--markdown` prints the file mirror's path to read").option("--markdown", "report the repo-relative markdown mirror instead of the block content").action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const row = await api(
+        ctx,
+        `/v1/projects/${projectId}/documents/${args[0]}`
+      );
+      if (opts.markdown) {
+        ok({ id: row.id, title: row.title, filePath: row.filePath }, () => {
+          line(`${import_picocolors26.default.bold(row.title)}  ${import_picocolors26.default.dim(row.id)}`);
+          line(
+            row.filePath ? `Read it at ${import_picocolors26.default.bold(row.filePath)} (relative to the project folder).` : import_picocolors26.default.dim("This document has no markdown mirror on disk yet.")
+          );
+        });
+        return;
+      }
+      ok(row, () => {
+        line(`${import_picocolors26.default.bold(row.title)}  ${import_picocolors26.default.dim(row.id)}`);
+        if (row.workItemId) line(import_picocolors26.default.dim(`linked to work item ${row.workItemId}`));
+        if (row.filePath) line(import_picocolors26.default.dim(`markdown mirror: ${row.filePath}`));
+        line("");
+        line(row.contentJson);
+      });
+    })
+  );
+  doc.command("create <title>").description(
+    'workser doc create "Onboarding" [--work-item <id>] [--markdown ...] [--content-json ...]'
+  ).option("--work-item <id>", "link this document to a work item").option("--markdown <text>", "document body as markdown").option("--content-json <json>", "document body as rich-text content JSON").action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const title = String(args[0] ?? "").trim();
+      if (!title) {
+        throw new WorkserError("A document needs a title.", { code: "bad_request" });
+      }
+      const row = await api(ctx, `/v1/projects/${projectId}/documents`, {
+        body: {
+          title,
+          workItemId: opts.workItem,
+          markdown: opts.markdown,
+          contentJson: opts.contentJson
+        }
+      });
+      await recordEntityStep(ctx, {
+        title: `Created document: ${title}`,
+        refType: "agent_created_document",
+        refId: row?.id,
+        output: { document: row }
+      });
+      ok(row, () => line(`Created document ${import_picocolors26.default.bold(row?.id ?? "")} \u2014 ${title}`));
+    })
+  );
+  doc.command("update <id>").description("Revise an existing document rather than creating a second copy of it").option("--title <text>", "new title").option("--markdown <text>", "replace the body with this markdown").option("--content-json <json>", "replace the body with this rich-text content JSON").action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const body = {
+        title: opts.title,
+        markdown: opts.markdown,
+        contentJson: opts.contentJson
+      };
+      if (Object.values(body).every((v) => v === void 0)) {
+        throw new WorkserError(
+          "Nothing to update \u2014 pass at least one of --title, --markdown, --content-json.",
+          { code: "bad_request" }
+        );
+      }
+      const row = await api(
+        ctx,
+        `/v1/projects/${projectId}/documents/${args[0]}`,
+        { method: "PATCH", body }
+      );
+      if (!row) {
+        throw new WorkserError(`No document with id "${args[0]}" on this project.`, {
+          code: "bad_request"
+        });
+      }
+      ok(row, () => line(`Updated document ${import_picocolors26.default.bold(row.id)} \u2014 ${row.title}`));
+    })
+  );
+}
+
+// src/commands/design.ts
+var import_picocolors27 = __toESM(require_picocolors(), 1);
+function registerDesign(program3) {
+  const design = program3.command("design").description("Read the project's brand (colours, fonts, logo)");
+  design.command("show").description("Show this project's brand \u2014 read it before writing any UI").option("--raw", "print the generated token files verbatim instead of a summary").action(
+    action(async ({ ctx, opts }) => {
+      const projectId = requireProject(ctx);
+      const res = await api(
+        ctx,
+        `/v1/projects/${projectId}/design/files`
+      );
+      const files = res?.files ?? [];
+      if (opts.raw) {
+        ok(files, () => {
+          if (!files.length) {
+            line(import_picocolors27.default.dim("No brand set for this project."));
+            return;
+          }
+          for (const f of files) {
+            line(import_picocolors27.default.bold(f.path));
+            line(f.contents);
+            line("");
+          }
+        });
+        return;
+      }
+      const tokens = parseTokens(files);
+      const summary = tokens ? {
+        hasBrand: true,
+        colors: tokens.color,
+        fonts: tokens.font,
+        brand: tokens.brand,
+        files: files.map((f) => f.path)
+      } : { hasBrand: false, colors: {}, fonts: {}, brand: {}, files: [] };
+      ok(summary, () => {
+        if (!tokens) {
+          line(import_picocolors27.default.dim("No brand set for this project \u2014 choose sensible styling yourself."));
+          return;
+        }
+        for (const [name, value] of Object.entries(tokens.brand)) {
+          line(`${import_picocolors27.default.dim(name.padEnd(12))} ${value}`);
+        }
+        for (const [name, value] of Object.entries(tokens.color)) {
+          line(`${import_picocolors27.default.dim(`color.${name}`.padEnd(12))} ${value}`);
+        }
+        for (const [name, value] of Object.entries(tokens.font)) {
+          line(`${import_picocolors27.default.dim(`font.${name}`.padEnd(12))} ${value}`);
+        }
+        line("");
+        line(
+          import_picocolors27.default.dim(
+            `Generated into the working tree as ${files.map((f) => f.path).join(", ")} \u2014 wire those in, never edit them.`
+          )
+        );
+      });
+    })
+  );
+}
+function parseTokens(files) {
+  const doc = files.find((f) => f.path.endsWith("tokens.json"));
+  if (!doc) return null;
+  try {
+    const parsed = JSON.parse(doc.contents);
+    return {
+      color: unwrap(parsed.color),
+      font: unwrap(parsed.font),
+      brand: Object.fromEntries(
+        Object.entries(parsed.brand ?? {}).map(([k, v]) => [k, String(v)])
+      )
+    };
+  } catch {
+    return null;
+  }
+}
+function unwrap(group) {
+  return Object.fromEntries(
+    Object.entries(group ?? {}).map(([k, v]) => [k, v?.$value ?? ""])
+  );
+}
+
 // src/index.ts
 var pkg = {
-  version: true ? "0.2.2" : "0.0.0-dev"
+  version: true ? "0.2.4" : "0.0.0-dev"
 };
 var program2 = new Command();
 program2.name("workser").description(
@@ -6161,4 +7013,9 @@ registerBusiness(program2);
 registerArtifact(program2);
 registerImage(program2);
 registerAsk(program2);
+registerSearch(program2);
+registerBoard(program2);
+registerDecision(program2);
+registerDoc(program2);
+registerDesign(program2);
 program2.parseAsync(process.argv).catch((e) => fail(e));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workser/cli",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Workser CLI — give your local AI agent native DevOps & infrastructure on Workser. The agent runs `workser …` to provision, deploy, and manage real apps.",
   "license": "MIT",
   "type": "module",

package/skills/workser/SKILL.md

@@ -21,6 +21,8 @@ command. Don't print them all; you are paying for every line you load.
 
 | You need to… | Commands | Run |
 | --- | --- | --- |
+| See what's tracked, decided, or written down for this project | `board …`, `decision …`, `requirement …`, `doc …` | `workser help sdlc-entities` |
+| Follow the project's brand — colours, fonts, logo | `design …` | `workser help brand` |
 | Provision or query Postgres; list end users | `db …`, `auth …` | `workser help database` |
 | Deploy, set env vars, read logs, check a domain | `deploy`, `env …`, `logs`, `versions`, `domain`, `open` | `workser help deploy` |
 | Put files in the project's bucket | `storage …` | `workser help storage` |
@@ -73,6 +75,11 @@ Owner-only, for reference: `project create` · `project use` · `env rm` · `dom
    `{"ok":true,"data":...}` or `{"ok":false,"error":{"code","message",...}}`. Parse it.
 2. **Orient first.** Run `workser status --json` to see the connection, the pinned
    project, and the latest deploy before acting. You don't pick or switch projects.
+   For anything beyond a trivial edit, also read what the project already knows:
+   `workser board list --json` (what's tracked), `workser decision list --json`
+   (what was already decided, so you don't quietly reverse it), and
+   `workser design show --json` before writing UI. This project outlives your
+   session; that context is how you don't start from zero.
 3. **Stay in your lane.** `error.code = "owner_only"` (exit 6) means the action is
    reserved for the owner in Orbit. Don't retry or look for a workaround — tell the
    user, then continue. Provisioning the *pinned project's own* db / bucket / auth is
@@ -93,10 +100,15 @@ Owner-only, for reference: `project create` · `project use` · `env rm` · `dom
 
 ```bash
 workser status --json                       # 1. orient (project is already pinned)
-workser db create --json                    # 2. provision infra the app needs (idempotent)
-workser env set STRIPE_KEY=sk_live_… --json # 3. configure it
+workser board list --json                   # 2. what's already tracked
+workser decision list --json                #    …and already decided
+workser board move <id> in-progress --json  # 3. claim the card you're doing
+workser db create --json                    # 4. provision infra the app needs (idempotent)
+workser env set STRIPE_KEY=sk_live_… --json # 5. configure it
 # … you write the app code with your normal tools …
-workser deploy --prod --watch --json        # 4. ship; returns the live URL
+workser verify --json                       # 6. green build is the bar for "done"
+workser deploy --prod --watch --json        # 7. ship; returns the live URL
+workser board close <id> --json             # 8. the Board now matches reality
 ```
 
 Provisioning the pinned project's own database / bucket / auth is yours to do

package/skills/workser/reference/brand.md

@@ -0,0 +1,60 @@
+---
+topic: brand
+title: The project's brand
+summary: Read the owner's colours, fonts and logo before writing UI, and wire the generated design tokens into the app's theme.
+commands: [design]
+---
+
+# The project's brand
+
+```
+workser design show [--raw]
+```
+
+The owner sets their brand once in Workser (logo, colours, fonts). Everything
+you build should follow it. Read it **before writing any UI**:
+
+```bash
+workser design show --json
+```
+
+```json
+{"ok":true,"data":{"hasBrand":true,
+  "colors":{"primary":"#1f7a4d","accent":"#f5a623"},
+  "fonts":{"heading":"Inter","body":"Inter"},
+  "brand":{"name":"Green Grocer"},
+  "files":["design/tokens.json","design/tokens.css"]}}
+```
+
+This asks the server, which derives the answer from the brand record itself — so
+it is correct even if nothing has been written into the working tree yet. That's
+the reason to use it instead of looking for a file and guessing when it's absent.
+
+`"hasBrand": false` is an ordinary state — most projects have no brand set.
+Choose sensible styling yourself; **don't** stop and ask the user to define a
+brand first.
+
+## Using it in the code
+
+The same values are generated into the working tree as two files:
+
+- `design/tokens.json` — the tokens in DTCG form
+- `design/tokens.css` — plain CSS custom properties (`--ws-color-*`, `--ws-font-*`)
+
+Wire `design/tokens.css` into the app's theme the way this app's setup expects —
+it assumes no particular Tailwind version, so map it rather than pasting it.
+
+**Both files are generated and overwritten wholesale.** Never hand-edit them;
+your edit disappears on the next sync. `workser design show --raw` prints them
+verbatim if you need to see exactly what's in them.
+
+## Changing the brand is the owner's job
+
+There is no `workser design set` — the brand is one record the owner controls in
+the Workser app, and it drives everything generated from it. If the user asks you
+to change their brand colour, tell them where it lives (Design → Brand in Orbit)
+rather than writing the colour into the app by hand, which would drift from every
+other surface the brand feeds.
+
+For generating artwork *in* the brand's palette, see `workser help images` —
+put the colours from `design show` into the prompt.

package/skills/workser/reference/roles.md

@@ -11,23 +11,37 @@ The user can configure **roles** — named specialists each backed by a local CL
 (e.g. `qa` → codex, `designer` → claude_code).
 
 ```
-workser agent list                  # main agent + configured roles (+ which are runnable)
-workser agent run <role> "<task>"   # delegate a focused subtask (runs isolated)
+workser agent list                  # main agent + configured roles + which agents are connected
+workser agent run <role> "<task>"   # delegate to a CONFIGURED role (runs isolated)
+workser agent spawn <agent> "<task>" [--role <label>] [--instructions <text>] [--model <model>]
+                                     # spin up a TEMPORARY teammate on any connected agent CLI
 workser agent main                  # show the configured main agent
 ```
 
 ## How to use it
 
-Run `workser agent list --json` first — it tells you which roles exist **and** which
-are actually runnable on this machine. Delegating to a role that isn't installed just
-fails.
+Run `workser agent list --json` first — it tells you which roles exist, which are
+actually runnable on this machine, and which agent CLIs are connected at all
+(`spawnable`). Delegating to a role that isn't installed, or spawning an agent that
+isn't connected, just fails.
 
-`workser agent run <role> "<task>" --json` runs the role as an **isolated local
-subagent** with its own context and returns `{role, agent, output, exitCode}`.
+`workser agent run <role> "<task>" --json` runs a **configured** role as an isolated
+local subagent and returns `{role, agent, output, exitCode}`.
 
-- Hand off focused subtasks — review this diff, design this screen — to keep your own
-  context lean and get a specialized second perspective.
-- **A non-zero `exitCode` means the role's run failed.** Surface that; don't quietly
-  treat empty output as success.
-- The subagent doesn't share your context. Put everything it needs in the task
-  string; it cannot see the conversation you're in.
+`workser agent spawn <agent> "<task>" --json` does the same thing without a
+pre-configured role — `<agent>` is one of `claude_code|codex|kimi|opencode|grok`, any
+of which can be connected on this machine. Use it to fan work out in parallel for
+one-off work with no matching role: e.g. spawn `codex` to research a topic while you
+keep working, or run a second `claude_code` instance on a different part of the same
+task. `--instructions` sets that teammate's system prompt for this one run — give it
+real scope, not just a repeat of the task.
+
+- Hand off focused subtasks — review this diff, design this screen, research this API —
+  to keep your own context lean and get a specialized second perspective.
+- **A non-zero `exitCode` means the run failed.** Surface that; don't quietly treat
+  empty output as success.
+- The subagent doesn't share your context, configured role or spawned. Put everything
+  it needs in the task string (and `--instructions` for a spawn); it cannot see the
+  conversation you're in.
+- Never give a subagent — configured or spawned — a task that tells it to delegate or
+  spawn further. It has no supervision loop to stop a runaway chain.

package/skills/workser/reference/sdlc-entities.md

@@ -0,0 +1,123 @@
+---
+topic: sdlc-entities
+title: Board cards, decisions, requirements, and docs
+summary: Read what this project already tracks and decided, keep the Board honest as you work, and record what a future maintainer will need.
+commands: [board, decision, requirement, doc]
+---
+
+# Board cards, decisions, requirements, and docs
+
+These are the project's memory across sessions. They write to the **same tables**
+the Orbit desktop's Board, Project Memory, and Docs panels use, so anything here
+appears there too — and (when this CLI runs inside an Orbit-spawned agent run)
+as an inline card in the conversation you're working in.
+
+```
+workser board list [--status <value>] [--label <value>] [--limit <n>]
+workser board show <id>
+workser board create <title> [--description <text>] [--status <value>]
+                              [--priority <value>] [--label <value>]
+                              [--owner <name>] [--milestone <id>]
+workser board update <id> [--title|--description|--status|--priority
+                           |--label|--owner|--milestone ...]
+workser board move <id> <backlog|in-progress|in-review|done>
+workser board close <id>
+
+workser decision list [--limit <n>]
+workser decision show <id>
+workser decision create <title> --context <text> --decision <text>
+                                 [--consequences <text>]
+
+workser requirement list [--status <value>] [--limit <n>]
+workser requirement show <id>
+workser requirement create <title> --body <text> [--status <text>]
+workser requirement update <id> [--title <text>] [--body <text>] [--status <text>]
+
+workser doc list [--work-item <id>]
+workser doc show <id> [--markdown]
+workser doc create <title> [--work-item <id>] [--markdown <text>]
+                            [--content-json <json>]
+workser doc update <id> [--title <text>] [--markdown <text>]
+```
+
+## Read first — this is the part that matters
+
+Before starting anything beyond a trivial edit:
+
+```
+workser board list --json          # what's already tracked (don't re-file it)
+workser decision list --json       # what was already decided (don't reverse it)
+```
+
+The project outlives your session. A decision recorded three weeks ago is the
+only thing standing between you and quietly undoing a choice someone made on
+purpose — `workser decision show <id>` gives you the context and consequences,
+not just the title. Reach for `workser doc list` / `workser requirement list`
+the same way when the task touches documented behaviour.
+
+## Keep the Board honest while you work
+
+A Board still reading `backlog` after the feature shipped tells the user the
+opposite of the truth. Moving the card is part of finishing the work:
+
+```
+workser board move <id> in-progress   # you picked it up
+workser board move <id> in-review     # ready for the user to look at
+workser board close <id>              # done and verified
+```
+
+`--status` is one of `backlog | in-progress | in-review | done` (default
+`backlog`). `--priority` is one of `low | normal | high | urgent` (default
+`normal`). `--label` repeats for more than one label:
+
+```
+workser board create "Fix the login bug" --status in-progress --priority high \
+  --label bug --label auth
+```
+
+`board update` replaces the labels you pass rather than merging them, and
+touches only the fields you name. There is no `board delete` — `done` is the
+terminal state for finished work, and removing a card the user filed is theirs
+to do in Orbit.
+
+## Decisions are append-only
+
+`decision create` is for something with real tradeoffs worth a paper trail:
+`--context` is why it came up, `--decision` is what was decided,
+`--consequences` is the follow-on effects. There is deliberately **no
+`decision update`** — a decision record states what was decided at a point in
+time. When it stops being right, record a new decision that supersedes it and
+say so in its `--context`. Editing the history is how a decision log stops
+being worth reading.
+
+Requirements are different: they legitimately move along, so they do have
+`update`.
+
+```
+workser requirement create "Support SSO" --body "Enterprise customers need SAML." \
+  --status proposed
+workser requirement update <id> --status done
+```
+
+## Docs
+
+`--markdown` is the normal way to write one. The body is stored both as the
+rich-text content the Docs panel renders and as a git-tracked markdown mirror
+at `.workser/docs/<id>.md` — `workser doc show <id> --markdown` reports that
+path so you can read the file with your normal tools.
+
+Revise the page that exists rather than creating a second copy of it:
+
+```
+workser doc list --json                       # is there already a page for this?
+workser doc update <id> --markdown "$(cat updated.md)"
+```
+
+`--work-item <id>` links a document to a Board card (a card has at most one).
+
+## When to record, and when not to
+
+Record what a future maintainer would need: follow-up work you found but didn't
+do, a choice between real alternatives, a behaviour worth writing down. Don't
+narrate every small step — and never treat filing a card as a substitute for
+the work. Creating a Board card that says "fix the bug" is not fixing the bug.

package/skills/workser/reference/search.md

@@ -0,0 +1,29 @@
+---
+topic: search
+title: Web search
+summary: Google-grounded web search, run server-side — the API key never reaches you.
+commands: [search]
+---
+
+# Web search — ask the internet, not just the model
+
+```
+workser search "<query>" [-n, --max-results <n>]   # Google-grounded web search
+```
+
+## Why this exists
+
+A local agent can drive a browser, but it can't "search the web" without a URL
+already in hand — `browser` automation needs somewhere to point. This runs a
+real, grounded Google search server-side (core-api holds the API key; it never
+reaches the daemon, the CLI, or you) and returns a synthesized answer plus the
+source links behind it.
+
+## Using it well
+
+- Prefer this over guessing or asking the user when you need current facts,
+  prices, docs for a library, or anything time-sensitive.
+- The `answer` is a synthesized summary — the `results` list is the sources it
+  drew from. Cite or open one of those links if the user needs to verify the
+  claim themselves.
+- Not project-scoped: it's a general research tool, not tied to a project's data.