@workser/cli 0.2.3 → 0.2.5

package/AGENTS.md

@@ -42,6 +42,7 @@ what you *can* do.
 workser status | whoami                       # orient (read)
 workser project show | list                   # your pinned project + the workspace
 workser env set KEY=VALUE… | list | get KEY   # env vars
+workser env pull [--out .env.local]           # write cloud env vars into a local file
 workser db create                             # provision the Neon Postgres database
 workser db url | list                         # DB connection string + status
 workser db tables                             # list tables in the database
@@ -92,6 +93,33 @@ workser ask "<question>" [--type <t>] [--option <o>] # ask the user, WAIT for th
 #   project create, project use, env rm, domain set
 ```
 
+## Project tracking (the Board, Docs and Memory the user sees in Orbit)
+```
+workser board list | show <id>                       # what's already tracked
+workser board create "<title>" [--description <t>] [--status <s>] [--priority <p>]
+workser board move <id> <backlog|in-progress|in-review|done> | close <id>
+workser decision list | show <id>                    # what was already decided
+workser decision create "<title>" --context <t> --decision <t> [--consequences <t>]
+workser requirement list | show <id> | create "<title>" --body <t> | update <id> --status <s>
+workser doc list | show <id> [--markdown]
+workser doc create "<title>" --markdown <text> | doc update <id> --markdown <text>
+```
+**Read before you plan** — `board list` and `decision list` tell you what someone is
+already doing and what this project chose on purpose, so you don't re-file work or
+quietly reverse a decision.
+
+**A plan with phases goes on the Board before you build it.** The moment you split a
+task into more than one phase: one `board create` card per phase (only the one you're
+doing goes to `in-progress`), the plan itself as one `doc create --markdown` — with
+**no `--work-item`**, because a linked doc is shown on its card and hidden from the
+Docs panel — and a `decision create` if the plan settled a real tradeoff. A plan that
+lives only in your reply is gone as soon as the conversation scrolls.
+
+**Keep it true as you work.** `board move <id> in-progress` when you pick it up,
+`in-review` when it's ready to look at, `board close <id>` when it's done and
+verified. A Board still reading `backlog` after you shipped is worse than no Board.
+Decisions are append-only: supersede an old one with a new record, never edit it.
+
 ## Memory (remember across conversations, not just this one)
 Every conversation you run is otherwise a fresh start — no memory of what you or the
 user decided last time. `workser memory add "<content>"` fixes that: it stores durable,
@@ -205,8 +233,12 @@ keep your own context lean and get a specialized second perspective; a non-zero
 ## Example
 ```bash
 workser status --json                  # orient: which project, last deploy
+workser board list --json              # what's tracked; decision list for what's decided
+workser board create "Phase 1 — …" --status in-progress --json   # phased plan -> cards
+workser doc create "Plan" --markdown "…" --json                  # …plus the plan doc
 workser env set STRIPE_KEY=sk_live_… --json
 # … you write the app code with your normal tools …
 workser deploy --prod --watch --json   # -> .data.url is the live URL
+workser board close <id> --json        # the Board now matches reality
 ```
 Report results to the user in plain language, not raw JSON.

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.
 `
   },
   {
@@ -4124,6 +4185,157 @@ real scope, not just a repeat of the task.
   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 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.
+
+## Work with phases \u2192 cards + a plan doc, before you build
+
+The moment you split a task into more than one phase, file it \u2014 not afterwards,
+and not only in your reply, which is gone once the conversation scrolls.
+
+\`\`\`bash
+# one card per phase; only the one you're doing goes to in-progress
+workser board create "Phase 1 \u2014 schema + migration" \\
+  --description "Add orders/line_items tables and the migration." \\
+  --status in-progress --json
+workser board create "Phase 2 \u2014 checkout API" --description "\u2026" --json
+workser board create "Phase 3 \u2014 cart UI"      --description "\u2026" --json
+
+# the plan itself, ONE doc, deliberately NOT linked to a card
+workser doc create "Checkout \u2014 implementation plan" --markdown "$(cat plan.md)" --json
+
+# the approach, if the plan settled something with real alternatives
+workser decision create "Carts live server-side" --context "\u2026" --decision "\u2026" --json
+\`\`\`
+
+**Don't pass \`--work-item\` for a multi-phase plan.** A linked document renders on
+its card and is *hidden* from the Docs panel; a plan spanning three phases belongs
+to the project, not to phase 1.
+
+The bar: if the user closed this conversation now, the Board should still show
+what's left and the doc should still explain the plan to whoever continues it.
+
+## 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\` \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. A card saying "fix the bug" is not fixing the bug.
 `
   },
   {
@@ -4352,7 +4564,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";
@@ -5187,6 +5400,7 @@ async function presign(ctx, projectId, bucket, key, operation, expiresInSeconds)
 
 // src/commands/env.ts
 var import_picocolors9 = __toESM(require_picocolors(), 1);
+import { readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
 function appQuery(opts) {
   const app = typeof opts?.app === "string" ? opts.app : "";
   return app ? `?webAppId=${encodeURIComponent(app)}` : "";
@@ -5243,6 +5457,59 @@ function registerEnv(program3) {
       })
     )
   );
+  env.command("pull").description("Write this app's cloud env vars into a local file (default .env.local)").option("--app <webAppId>", APP_FLAG_HELP).option("--out <file>", "Local file to write", ".env.local").action(
+    action(async ({ ctx, opts }) => {
+      const projectId = requireProject(ctx);
+      const items = await api(
+        ctx,
+        `/v1/projects/${projectId}/env${appQuery(opts)}`
+      );
+      const outPath = typeof opts?.out === "string" ? opts.out : ".env.local";
+      if (!items?.length) {
+        return ok(
+          { file: outPath, pulled: [] },
+          () => line(import_picocolors9.default.dim("No cloud variables to pull."))
+        );
+      }
+      const pulled = [];
+      for (const item of items) {
+        const res = await api(
+          ctx,
+          `/v1/projects/${projectId}/env/${encodeURIComponent(item.key)}${appQuery(opts)}`
+        );
+        pulled.push({ key: item.key, value: res?.value ?? "" });
+      }
+      await mergeEnvFile(outPath, pulled);
+      ok(
+        { file: outPath, pulled: pulled.map((p) => p.key) },
+        () => success(
+          `Pulled ${pulled.length} variable(s) into ${import_picocolors9.default.bold(outPath)}.`
+        )
+      );
+    })
+  );
+}
+var ENV_KEY_LINE = /^([A-Za-z_][A-Za-z0-9_]*)=/;
+async function mergeEnvFile(path, vars) {
+  const existing = await readFile3(path, "utf8").catch(() => "");
+  const lines = existing.length ? existing.split(/\r?\n/) : [];
+  const remaining = new Map(vars.map((v) => [v.key, v.value]));
+  const merged = lines.map((rawLine) => {
+    const match = ENV_KEY_LINE.exec(rawLine);
+    if (!match || !remaining.has(match[1])) return rawLine;
+    const key = match[1];
+    const value = remaining.get(key);
+    remaining.delete(key);
+    return `${key}=${formatEnvValue(value)}`;
+  });
+  while (merged.length && merged[merged.length - 1] === "") merged.pop();
+  for (const [key, value] of remaining) {
+    merged.push(`${key}=${formatEnvValue(value)}`);
+  }
+  await writeFile3(path, merged.join("\n") + "\n", "utf8");
+}
+function formatEnvValue(value) {
+  return /[\s"'#]/.test(value) ? JSON.stringify(value) : value;
 }
 
 // src/commands/deploy.ts
@@ -6035,7 +6302,7 @@ function printRun(run) {
 }
 
 // src/commands/image.ts
-import { writeFile as writeFile3, mkdir } from "fs/promises";
+import { writeFile as writeFile4, mkdir } from "fs/promises";
 import { dirname as dirname2, resolve as resolve3 } from "path";
 function registerImage(program3) {
   const image = program3.command("image").description("Generate images from a text prompt");
@@ -6100,7 +6367,7 @@ async function download(url, output) {
     );
   }
   await mkdir(dirname2(target), { recursive: true });
-  await writeFile3(target, Buffer.from(await res.arrayBuffer()));
+  await writeFile4(target, Buffer.from(await res.arrayBuffer()));
   return target;
 }
 
@@ -6228,9 +6495,565 @@ function registerSearch(program3) {
   );
 }
 
+// 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.3" : "0.0.0-dev"
+  version: true ? "0.2.5" : "0.0.0-dev"
 };
 var program2 = new Command();
 program2.name("workser").description(
@@ -6272,4 +7095,8 @@ 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.3",
+  "version": "0.2.5",
   "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` |
@@ -33,10 +35,9 @@ command. Don't print them all; you are paying for every line you load.
 | Record finished output, or ask the user a question | `artifact …`, `ask` | `workser help deliverables` |
 | Control this machine — files, shell, screen, browser | `tool …` | `workser help computer-use` |
 
-`workser help` with no topic lists them. **The CLI is the source of truth**: it ships
-these guides with itself, so they match the version you are running. For exact flags
-on any command, `workser <command> --help` is generated from the implementation and
-cannot be out of date.
+`workser help` with no topic lists them. **The CLI is the source of truth** — it
+ships these guides itself, so they match the version you are running, and
+`workser <command> --help` is generated from the implementation.
 
 ## Orientation (no guide needed)
 
@@ -59,13 +60,11 @@ SQL, provision the bucket + auth, deploy, set env vars, manage files. Sensitive
 actions are **gated** — the daemon may return `error.code = "awaiting_approval"`
 (exit 5) and wait for the user to approve in Orbit; ask them to approve, then retry.
 
-What you **cannot** do is administer the project set or destroy config: creating or
-switching which project is pinned, deleting env vars, or attaching a custom domain.
-Those return `error.code = "owner_only"` (exit 6) — tell the user it's an owner
-action to do in Orbit, then continue with what you can do. The project is already
-selected; you don't pick or switch it.
-
-Owner-only, for reference: `project create` · `project use` · `env rm` · `domain set`.
+What you **cannot** do is administer the project set or destroy config:
+`project create` · `project use` · `env rm` · `domain set` return
+`error.code = "owner_only"` (exit 6). Tell the user it's an owner action to do in
+Orbit, then continue with what you can. The project is already selected; you don't
+pick or switch it.
 
 ## Golden rules
 
@@ -73,19 +72,29 @@ 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.
-3. **Stay in your lane.** `error.code = "owner_only"` (exit 6) means the action is
+   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. **A phased plan goes on the Board before you build it.** One `board create`
+   card per phase, the plan itself as one `doc create` (no `--work-item`, or it's
+   hidden from the Docs panel), and a `decision create` if it settled a real
+   tradeoff. A plan that lives only in your reply is gone when the conversation
+   scrolls. Details: `workser help sdlc-entities`.
+4. **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
    allowed (it may be approval-gated, not owner-only).
-4. **Approvals are normal.** Some allowed actions may return
+5. **Approvals are normal.** Some allowed actions may return
    `{"error":{"code":"awaiting_approval"}}` (exit 5) while the user approves in the
    Orbit UI. Tell the user to approve, then retry — do **not** try to bypass it.
-5. **Never ask for or store credentials.** Auth is handled by Orbit; you never see keys.
-6. **Verify before "done".** Before telling the user a task is complete, run
+6. **Never ask for or store credentials.** Auth is handled by Orbit; you never see keys.
+7. **Verify before "done".** Before telling the user a task is complete, run
    `workser verify --json` (runs the project's typecheck/lint/build). If it
    reports `"ok": false`, fix the errors it lists and re-run until it passes —
    a green build is the bar for "done", not your own judgement.
-7. **Destructive shell actions are blocked.** Irreversible commands (`rm -rf /`,
+8. **Destructive shell actions are blocked.** Irreversible commands (`rm -rf /`,
    `git reset --hard`, `DROP`/`TRUNCATE`, `curl | sh`, …) are refused by Workser's
    safety policy — don't attempt them; use migrations + scoped changes instead.
 
@@ -93,16 +102,18 @@ 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 create "Phase 2 — …" --json   # 3. phases? file them + the plan doc
+workser board move <id> in-progress --json  # 4. claim the card you're doing
+workser db create --json                    # 5. provision infra the app needs (idempotent)
+workser env set STRIPE_KEY=sk_live_… --json # 6. 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                       # 7. green build is the bar for "done"
+workser deploy --prod --watch --json        # 8. ship; returns the live URL
+workser board close <id> --json             # 9. the Board now matches reality
 ```
 
-Provisioning the pinned project's own database / bucket / auth is yours to do
-(`db create`, `storage create`, `auth enable`) — the user may need to approve it in
-Orbit (`awaiting_approval`). Only a **custom domain** is an owner action.
-
 ## Reading results
 
 - Success: use `.data` (e.g. `.data.url` after deploy, `.data` array after `list`).

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/sdlc-entities.md

@@ -0,0 +1,150 @@
+---
+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.
+
+## Work with phases → cards + a plan doc, before you build
+
+The moment you split a task into more than one phase, file it — not afterwards,
+and not only in your reply, which is gone once the conversation scrolls.
+
+```bash
+# one card per phase; only the one you're doing goes to in-progress
+workser board create "Phase 1 — schema + migration" \
+  --description "Add orders/line_items tables and the migration." \
+  --status in-progress --json
+workser board create "Phase 2 — checkout API" --description "…" --json
+workser board create "Phase 3 — cart UI"      --description "…" --json
+
+# the plan itself, ONE doc, deliberately NOT linked to a card
+workser doc create "Checkout — implementation plan" --markdown "$(cat plan.md)" --json
+
+# the approach, if the plan settled something with real alternatives
+workser decision create "Carts live server-side" --context "…" --decision "…" --json
+```
+
+**Don't pass `--work-item` for a multi-phase plan.** A linked document renders on
+its card and is *hidden* from the Docs panel; a plan spanning three phases belongs
+to the project, not to phase 1.
+
+The bar: if the user closed this conversation now, the Board should still show
+what's left and the doc should still explain the plan to whoever continues it.
+
+## 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. A card saying "fix the bug" is not fixing the bug.