@workser/cli 0.6.22 → 0.6.26

package/AGENTS.md

@@ -133,16 +133,18 @@ workser requirement list | show <id> | create "<title>" --body <t> | update <id>
 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 this task's Subtasks list, not the Board.** Use one
-`task subtask add` per phase. If you spot a bad title, role, note, or file scope after
-creation, correct that existing row with `task subtask update <id>`; do not say it is
-locked, create a replacement, or duplicate the plan. Write the plan narrative once
-as `doc create --markdown` with no `--work-item`, and record a real tradeoff with
-`decision create`.
+**Read before you plan** — `goal list`, `task list`, and `decision list` tell you
+what the team is delivering, what someone is already doing, and what this project
+chose on purpose, so you don't re-file work or quietly reverse a decision.
+
+**Choose the planning level before creating work.** A business outcome with two or
+more owner-visible deliveries is a goal: `goal create` proposes its ordered phases,
+then you stop until the owner agrees the shape. A task is one delivery; `task subtask
+add` records the specialist steps inside it. Do not call subtasks phases, and do not
+create the goal's tasks in the proposal turn. If you spot a bad title, role, note, or
+file scope after creation, correct that existing row with `task subtask update <id>`;
+do not create a replacement or duplicate the plan. The legacy Board is not a planning
+surface for agents.
 
 **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
@@ -265,12 +267,13 @@ 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 goal list --json               # long-running outcomes and their phases
+workser task list --json               # the work already filed
+workser decision list --json           # what the project chose on purpose
+# For a big outcome: goal create ... --phase ... --json, then STOP for agreement.
+# For one delivery: task create ..., then task subtask add ... for its steps.
 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

@@ -3584,6 +3584,7 @@ function ownerOnly(opts) {
 
 // src/output.ts
 var OUT_OF_SCOPE_EXIT = 7;
+var BILLING_EXIT = 8;
 var mode = "text";
 var quiet = false;
 function configureOutput(opts) {
@@ -3645,6 +3646,18 @@ function fail(err) {
       process.stderr.write(import_picocolors.default.dim("  Approve the action in Workser Orbit, then retry.\n"));
     } else if (e.code === "owner_only") {
       process.stderr.write(import_picocolors.default.dim("  This is an owner action \u2014 do it in the Workser Orbit app.\n"));
+    } else if (e.code === "insufficient_credits") {
+      process.stderr.write(
+        import_picocolors.default.dim(
+          "  The organization is out of AI credits. Top up in Workser Orbit (Billing) \u2014 retrying will not help.\n"
+        )
+      );
+    } else if (e.code === "image_quota_reached") {
+      process.stderr.write(
+        import_picocolors.default.dim(
+          "  This month's plan allowance is spent. Upgrade the plan, or wait for the month to roll over \u2014 retrying will not help.\n"
+        )
+      );
     }
   }
   process.exit(exitCodeFor(e));
@@ -3655,6 +3668,9 @@ function exitCodeFor(e) {
   if (e.code === "awaiting_approval") return 5;
   if (e.code === "owner_only") return OWNER_ONLY_EXIT;
   if (e.code === "out_of_scope") return OUT_OF_SCOPE_EXIT;
+  if (e.code === "insufficient_credits" || e.code === "image_quota_reached") {
+    return BILLING_EXIT;
+  }
   return 1;
 }
 
@@ -4575,7 +4591,7 @@ forever; if it does, carry on and state clearly what you assumed.
 ## Asking for an app that does not exist yet
 
 The project needs a kind of app it does not have \u2014 a backend for the phone app, a
-desktop build of the website. **You cannot create one yourself**, by design: apps
+phone version of the website. **You cannot create one yourself**, by design: apps
 are real infrastructure on the owner's account. Ask, and their click creates it.
 The answer gives you the new app's id.
 
@@ -4590,15 +4606,19 @@ workser ask "The phone app needs an API to hold its data. Add one?" \\
 |---|---|
 | \`web\` | Next.js site on Workser hosting |
 | \`mobile\` | Expo / React Native phone app |
-| \`desktop\` | Next.js + Electron, installs on a Mac or PC |
 | \`api\` | backend service \u2014 \`api-hono\` (TypeScript) or \`api-python\` (FastAPI) |
 
 **Name the kind you actually mean.** Asking for \`web\` because you are unsure is
-how a desktop app gets created as a website: the card shows the owner the kind
+how a phone app gets created as a website: the card shows the owner the kind
 you named, they approve THAT, and the wrong app is provisioned under your own
 sentence asking for the right one. An unknown kind is refused with the list
 above rather than guessed at \u2014 read it and ask again.
 
+**There is no desktop app type.** Workser builds websites, phone apps and
+backend services. If the owner asks for a Mac or Windows app, say plainly that
+Workser cannot make one yet \u2014 do not offer a web app dressed as a window, and
+do not build a "desktop-style" page instead. That is not what they asked for.
+
 **Never ask for a secret value this way** \u2014 the answer is stored and displayed. Ask
 *where* a key should go, then have the user set it (\`workser env set\` writes it
 without you ever seeing it).
@@ -4674,105 +4694,6 @@ workser artifact add --url https://acme.workser.app --kind app -t "Storefront"
 \`\`\`
 
 See \`reference/deliverables.md\`.
-`
-  },
-  {
-    topic: "desktop",
-    title: "Desktop apps \u2014 one codebase, a window, and an installer",
-    summary: "How a Workser desktop app is built, what breaks only after it is installed, and how to produce and publish a signed installer.",
-    commands: ["project", "env", "deploy"],
-    source: "skills/workser/reference/desktop.md",
-    body: `# Desktop apps
-
-A Workser desktop app is **one Next.js codebase with two ways to run**: a normal
-web build for development and preview, and an Electron shell that loads the
-static export from disk and gets packaged into an installer.
-
-There is no deploy. A desktop app has no Vercel project and no URL \u2014 its
-preview is the app running locally, and its deliverable is a file someone
-double-clicks.
-
-## The rule that breaks everything, and only after install
-
-**The app must stay statically exportable.** A packaged Electron app loads from
-\`file://\` and has **no Node server**. So none of this exists once it is
-installed:
-
-- server components that fetch at request time
-- server actions (\`"use server"\`)
-- route handlers under \`app/api/*\`
-- \`next/image\` optimisation
-
-Every one of them works in \`npm run dev\` **and** in the local preview, and fails
-only on the owner's machine. That is the one direction of error nobody catches,
-so \`next.config.mjs\` keeps \`output: "export"\` to make the build fail loudly
-instead. Do not remove it to "fix" an import.
-
-Need a server? Use the project's api app \u2014 \`workser project apps\` to find it,
-then read its URL and set \`NEXT_PUBLIC_API_URL\`. See \`workser help apps\`.
-
-## Secrets: this is a public client
-
-Anyone who installs the app can read every string inside it. So:
-
-- \`NEXT_PUBLIC_*\` only, and nothing behind that prefix is private
-- never a database URL, an API key, or a \`wsgw_\` gateway key
-- anything privileged lives in the api app and is reached over HTTP
-
-The manifest deliberately does not declare \`AI_GATEWAY_API_KEY\` for this type,
-which is what stops Workser seeding one. Do not add it.
-
-## The two processes
-
-| File | Runs where | May do |
-| --- | --- | --- |
-| \`electron/main.js\` | Node, on the machine | files, tray, windows, updates |
-| \`app/**\` | the renderer, sandboxed | ordinary web code, no Node |
-| \`electron/preload.js\` | the bridge | expose **named functions** only |
-
-\`contextIsolation: true\` and \`nodeIntegration: false\` are not defaults to tidy
-up \u2014 turning either off hands full filesystem and process access to page code.
-Add a capability by exporting one named function from preload, never by handing
-the renderer \`ipcRenderer\`.
-
-## Building and shipping
-
-\`\`\`bash
-npm run dev            # browser only, fastest loop
-npm run dev:desktop    # the same app inside a real Electron window
-npm run build          # static export -> out/
-npm run dist:desktop   # the installer -> release/
-\`\`\`
-
-In the app, **Publish \u2192 Your installer** does the same thing with a target
-picker, progress, and a download link at the end.
-
-## Signing \u2014 the owner's certificate, never Workser's
-
-An unsigned build runs perfectly on the machine that made it and tells every
-other machine the app is damaged (macOS) or trips SmartScreen (Windows). That
-is the failure an owner cannot diagnose, so say it before they send the file.
-
-\`electron-builder\` reads these from the environment; set them with
-\`workser env set --app <id>\`:
-
-| Platform | Keys |
-| --- | --- |
-| macOS | \`CSC_LINK\`, \`CSC_KEY_PASSWORD\` |
-| macOS notarize | \`APPLE_ID\`, \`APPLE_APP_SPECIFIC_PASSWORD\`, \`APPLE_TEAM_ID\` |
-| Windows | \`WIN_CSC_LINK\`, \`WIN_CSC_KEY_PASSWORD\` |
-
-A Mac app can only be built on a Mac \u2014 \`codesign\` and \`hdiutil\` are Apple's and
-have no substitute.
-
-## Auto-update
-
-Publishing uploads the installer **and** the update metadata
-(\`latest-mac.yml\` / \`latest.yml\`) beside it. \`electron-updater\` reads only that
-metadata, so an installer published alone gives you a download that works once
-and an app that can never update itself \u2014 and nobody notices until release two.
-Keep \`publish.url\` in \`electron-builder.yml\` pointed at the prefix the publish
-step reports back.
 `
   },
   {
@@ -5071,6 +4992,7 @@ up front \u2014 most of the apps a goal will touch don't exist when it's propose
 workser image generate "<prompt>"            # alias: workser image gen
   -r, --reference <url...>                   # condition on existing images (up to 4)
   -o, --output <path>                        # also download the first image locally
+workser image usage                          # can I generate right now, and what would stop me
 \`\`\`
 
 Returns the generated image's public URL, so the usual move is to generate, then use
@@ -5094,6 +5016,32 @@ workser image gen "same van, from the side" -r https://\u2026 -o ./public/van.pn
 - **Placeholder art is not a deliverable.** Generating a hero image to unblock a
   layout is fine; shipping it as the user's brand asset without asking is not.
 
+## This is metered, and it can be refused
+
+Every image is billed to the organization's credit wallet, and each plan includes
+a monthly number of them. Three gates run server-side before anything is drawn \u2014
+the plan tier, the monthly allowance, then the wallet \u2014 so a call can come back
+refused having spent nothing.
+
+\`\`\`bash
+workser image usage --json    # {"limit":10,"used":3,"remaining":7,
+                              #  "credits":{"available":41.2,"requiredPerImage":4.12,"sufficient":true},
+                              #  "canGenerate":true,"blockedBy":null}
+\`\`\`
+
+- **Check before a batch, not after.** Planning six images is a plan that needs
+  six times \`requiredPerImage\` in the wallet. \`workser image usage\` answers that
+  before any of them cost anything; \`blockedBy\` names which gate would stop you
+  (\`plan\`, \`quota\`, \`credits\`), and it exits non-zero when generation is blocked.
+- **A refusal is final, not a hiccup \u2014 do NOT retry it.** \`insufficient_credits\`
+  (HTTP 402) and \`image_quota_reached\` (403) come back as those exact codes in
+  \`--json\`, and the CLI exits 8 for both. Retrying cannot succeed and every
+  attempt is another paid call the owner did not ask for. Stop, and tell the
+  owner what to do: top up credits, or upgrade the plan.
+- **You cannot see their balance any other way**, so do not guess at it from how
+  many images you have already made \u2014 a refusal at image four of six leaves the
+  work half-done and looks like a bug.
+
 ## Understanding media you can't natively see or hear
 
 The fallback for a text-only model, or media you have no other way to reach: describe
@@ -5420,14 +5368,17 @@ the same way when the task touches documented behaviour.
 \`--infra\` match on the server, so the answer covers the whole project rather
 than the first page of it. \`decision tag <id>\` files one that already exists.
 
-## Work with phases \u2192 subtasks + a plan doc, before you build
+## Work with one task's steps \u2192 subtasks + 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.
+Do not confuse two levels of planning. A **goal phase** is an owner-visible
+delivery across tasks; create it with \`workser goal create\` and wait for agreement
+before filing work. A **subtask** is one teammate's implementation step inside a
+single approved task. File those steps before building \u2014 not afterwards, and not
+only in your reply, which is gone once the conversation scrolls.
 
 \`\`\`bash
-# the phases \u2014 this task's own subtask list, not the Board
-workser task subtask add "Phase 1 \u2014 schema + migration" --role api --note "\u2026"
+# the implementation steps \u2014 this task's own subtask list, not the Board
+workser task subtask add "Create schema + migration" --role api --note "\u2026"
 
 # the plan's narrative, ONE doc, deliberately NOT linked to a subtask
 workser doc create "Checkout \u2014 plan" --kind plan --markdown "$(cat plan.md)" --json
@@ -5447,9 +5398,9 @@ Never tell the user a subtask is locked, and never file a second one alongside
 the wrong one \u2014 a plan with a duplicate phase in it is a plan nobody can read
 the progress of.
 
-**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.
+**Don't pass \`--work-item\` for a goal-wide plan.** A linked document renders on
+its card and is *hidden* from the Docs panel; a plan spanning several goal phases
+belongs to the project, not to the first task.
 
 The bar: if the user closed this conversation now, the subtask list should still
 show what's left and the doc should still explain the plan to whoever continues
@@ -9208,6 +9159,32 @@ function registerImage(program3) {
       ok(res, () => line(res?.answer ?? ""));
     })
   );
+  image.command("usage").description(
+    "Whether an image can be generated right now \u2014 monthly allowance, credit balance, and what would block it"
+  ).action(
+    action(async ({ ctx }) => {
+      const projectId = requireProject(ctx);
+      const status = await api(
+        ctx,
+        `/v1/projects/${projectId}/images/usage`
+      );
+      ok(status, () => {
+        const monthly = status.limit === null ? "no monthly limit on this plan" : `${status.used} of ${status.limit} used this month, ${status.remaining} left`;
+        line(`This month:  ${monthly}`);
+        line(
+          `Credits:     ${status.credits.available.toFixed(2)} available, about ${status.credits.requiredPerImage.toFixed(2)} per image`
+        );
+        if (status.canGenerate) {
+          success("Can generate now");
+        } else {
+          warn(
+            status.blockedBy === "credits" ? "Blocked: not enough organization credits. Top up in Workser Orbit (Billing)." : status.blockedBy === "quota" ? "Blocked: this month's plan allowance is spent. Upgrade, or wait for the month to roll over." : "Blocked: this plan cannot generate images. Upgrade to Spark or higher."
+          );
+        }
+      });
+      if (!status.canGenerate) process.exitCode = BILLING_EXIT;
+    })
+  );
 }
 async function download(url, output) {
   const target = resolve4(output);
@@ -9291,7 +9268,10 @@ var TYPES = [
 var APP_TYPES = [
   "web",
   "mobile",
-  "desktop",
+  // NOT OFFERED AT FIRST LAUNCH (2026-09-05) — `desktop` is `creatable: false`
+  // in core-api, so the card would error on the owner's click. Re-enable
+  // together with that flag; grep the marker.
+  // "desktop",
   // `api` is the shorthand; the two concrete spellings pick the runtime and
   // are accepted at this boundary for an agent that knows which one it wants.
   "api",
@@ -10594,153 +10574,18 @@ function paceLine(pace) {
 }
 
 // src/role-guard.ts
-var READS = [
-  // `requirement` sits beside `doc` and `decision` because it is the same kind
-  // of thing and was simply forgotten: the verb shipped, no role could run it,
-  // and on 2026-08-23 a channel PM reported to the owner that "requirements are
-  // not readable by this PM role" — which was exactly true, for every role.
-  "task",
-  "board",
-  "doc",
-  "decision",
-  "requirement",
-  "memory",
-  "search",
-  "verify",
-  "logs",
-  "status",
-  "help",
-  "whoami",
-  "login",
-  "auth",
-  "project",
-  "open",
-  "doctor",
-  // Both READ and report. `scan` reads files and shells out to npm; `health`
-  // makes a GET request to an address that is already public. Neither can
-  // change anything, which is why the roles that exist to look — qa, security,
-  // sre, analyst — get them without getting anything else.
-  "scan",
-  "health",
-  // Read-only views of what is running. Added with Phase 6a: an SRE that can
-  // read logs but cannot list deployments or read the app's address is being
-  // asked to diagnose an outage with one eye shut.
-  "urls",
-  "deployments",
-  // Reading the plan and what is used against it. An agent proposing "add
-  // another project" can only sensibly propose it if it can find out the plan
-  // allows two and two already exist.
-  "usage",
-  // RECORDING WHAT YOU PRODUCED IS NOT CHANGING THE PROJECT.
-  // Every dispatched role is told, in its own preamble, to run `workser
-  // artifact list` before non-trivial work and `workser artifact add` when it
-  // finishes something the owner should get. Five roles — pm, qa, security,
-  // analyst, sre — were then refused the verb here, so the instruction and the
-  // guard contradicted each other: the agent kept trying to obey an order this
-  // file would not let it obey, and burned its run doing it. It belongs beside
-  // `doc`, `decision` and `board`, which are already in this list and also
-  // have `create` subcommands — these write the project's RECORD, not the
-  // project. What stops a reviewer editing code is its filesystem mode, and
-  // that is untouched.
-  "artifact",
-  // LEAVING A FACT FOR THE TEAM IS NOT CHANGING THE PROJECT — the same
-  // argument as `artifact` directly above, and it belongs in READS rather than
-  // BUILDS on purpose. The roles that DISCOVER things are the reading ones: a
-  // tester that found the real cause, an analyst that found the actual column
-  // name, a security engineer that found where a key is read from. A shared
-  // memory only builders could write to would be missing most of what is worth
-  // sharing. See the daemon's `team-memory.ts`.
-  "note"
-];
-var BUILDS = [
-  ...READS,
-  "app",
-  "env",
-  "db",
-  "storage",
-  "checkpoint",
-  "image",
-  "design",
-  "ask",
-  "sync",
-  "tool",
-  "workflow",
-  "neon",
-  "business"
-];
-var ROLE_VERBS = {
-  pm: [...READS, "ask", "app"],
-  // `note` reaches this via READS.
-  architect: [...BUILDS, "versions"],
-  web: BUILDS,
-  api: BUILDS,
-  mobile: BUILDS,
-  python: BUILDS,
-  automation: BUILDS,
-  designer: BUILDS,
-  qa: READS,
-  security: READS,
-  analyst: READS,
-  sre: [...READS, "deploy", "domain", "versions"],
-  devops: [...BUILDS, "deploy", "domain", "versions"]
-  // NOTE: `deployments` reaches READS above, so every role can LIST and
-  // INSPECT. That is correct — history is a read. The two verbs that change
-  // production (`promote`, `rollback`) are not gated here at all, and must not
-  // be: they are gated in the DAEMON, as `deploy.prod`, which is a door "just
-  // do it" cannot open. A second, verb-name-based rule here would be a weaker
-  // copy of a control that already works.
-};
 var NEVER = {
-  // Approving is the owner's, full stop. An agent that can approve the plan it
-  // proposed has removed the only gate this product has.
   "task approval": "Only the owner can approve a plan."
 };
-var READ_PAIRS = /* @__PURE__ */ new Set([
-  // The project's own brand and design notes.
-  "design show",
-  // What exists, and what it is wired to.
-  "app list",
-  "app tools",
-  // Shape, never contents-by-arbitrary-SQL.
-  "db list",
-  "db tables",
-  "db schema",
-  // What is stored, not what is in it.
-  "storage list",
-  "storage ls",
-  "checkpoint list",
-  "workflow list",
-  "workflow get",
-  "workflow runs",
-  "workflow nodes",
-  "tool list",
-  // The business data an analyst exists to read.
-  "business resources",
-  "business list",
-  "business get",
-  // The database service's own inventory.
-  "neon status",
-  "neon list"
-]);
 function assertRoleMayRun(argv) {
   const role = (process.env.WORKSER_ROLE ?? "").trim();
   if (!role) return;
   const commandArgv = stripLeadingGlobalOptions(argv);
-  const verb = commandArgv[0];
-  if (!verb) return;
+  if (!commandArgv[0]) return;
   const pair = `${commandArgv[0]} ${commandArgv[1] ?? ""}`.trim();
   if (NEVER[pair] && !(pair === "task approval" && (commandArgv[2] === "request" || !commandArgv[2]))) {
     throw new WorkserError(NEVER[pair], { code: "role_forbidden" });
   }
-  if (READ_PAIRS.has(pair)) return;
-  const allowed = ROLE_VERBS[role];
-  const list = allowed ?? READS;
-  if (!list.includes(verb)) {
-    throw new WorkserError(
-      `The ${role} role can't run \`workser ${verb}\`. Report what you found instead, and the step that owns this will do it.`,
-      { code: "role_forbidden" }
-    );
-  }
 }
 function stripLeadingGlobalOptions(argv) {
   const takesValue = /* @__PURE__ */ new Set([
@@ -12445,7 +12290,7 @@ function colour(d) {
 
 // src/index.ts
 var pkg = {
-  version: true ? "0.6.22" : "0.0.0-dev"
+  version: true ? "0.6.26" : "0.0.0-dev"
 };
 var program2 = new Command();
 program2.name("workser").description(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workser/cli",
-  "version": "0.6.22",
+  "version": "0.6.26",
   "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

@@ -22,7 +22,6 @@ screen long. Find your row, run that **one** command — every line costs you.
 | Follow the project's brand — colours, fonts, logo | `design …` | `workser help brand` |
 | Provision or query Postgres; list end users | `db …`, `auth …` | `workser help database` |
 | See the project's other apps, and wire one to another | `project …`, `env … --app` | `workser help apps` |
-| Build a desktop app, sign it, ship an installer | `deploy`, `env …` | `workser help desktop` |
 | Deploy, set env vars, read logs, check a domain | `deploy`, `env …`, `logs`, `versions`, `domain`, `open` | `workser help deploy` |
 | Save work before a risky change, undo it, sync this folder | `checkpoint`, `restore`, `sync` | `workser help version-control` |
 | Put files in the project's bucket | `storage …` | `workser help storage` |
@@ -90,11 +89,10 @@ move between its projects (`--project <id>`, or `cd`); another org returns
    `workser decision list --json` (so you don't quietly reverse a decision) 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 subtask list, never the Board.** Phases are
-   `workser task subtask add` — not `board create`, which makes a second,
-   driftable "the plan" the task page never reads. Write the narrative once as
-   `doc create`, plus `decision create` for a real tradeoff; a plan in your reply
-   alone is gone when the conversation scrolls. `workser help sdlc-entities`.
+3. **Choose the planning level first.** Two-plus owner-visible deliveries are a
+   **goal**: read `workser help goals`, run `goal create`, then stop for agreement.
+   One delivery is a task; `task subtask add` records its implementation steps.
+   Goal phases are owner checkpoints across tasks; subtasks are not phases.
 4. **Stay in your lane.** On `owner_only` (exit 6) or `out_of_scope` (exit 7),
    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
@@ -110,12 +108,12 @@ move between its projects (`--project <id>`, or `cd`); another org returns
    `git reset --hard`, `DROP`/`TRUNCATE`, `curl | sh`, …) are refused by Workser's
    safety policy — don't attempt them; use migrations + scoped changes instead.
 
-## Typical flow: build → ship
+## Typical flow: one task → build → ship
 
 ```bash
 workser status --json                           # 1. orient
 workser decision list --json                    # 2. what's already decided
-workser task subtask add "Phase 2 — …" --json   # 3. phases → subtasks
+workser task subtask add "Implement …" --json   # 3. steps inside this task
 workser doc create "Plan" --markdown "…" --json # 4. the narrative, once
 workser db create --json                        # 5. provision infra (idempotent)
 workser env set STRIPE_KEY=sk_live_… --json     # 6. configure it
@@ -124,6 +122,15 @@ workser verify --json                           # 7. green build is the bar
 workser deploy --prod --watch --json            # 8. ship → stable *.workser.app URL
 ```
 
+For a larger outcome, propose the shape and stop:
+
+```bash
+workser goal create "Launch checkout" \
+  --phase "Cart" --phase "Payment" --phase "Receipts" \
+  --outcome "A customer can buy something and get a receipt" --json
+# After agreement, link phase tasks with --goal and --phase.
+```
+
 ## Reading results
 
 - Success: use `.data` (`.data.url` after deploy, a `.data` array after `list`).

package/skills/workser/reference/deliverables.md

@@ -101,7 +101,7 @@ forever; if it does, carry on and state clearly what you assumed.
 ## Asking for an app that does not exist yet
 
 The project needs a kind of app it does not have — a backend for the phone app, a
-desktop build of the website. **You cannot create one yourself**, by design: apps
+phone version of the website. **You cannot create one yourself**, by design: apps
 are real infrastructure on the owner's account. Ask, and their click creates it.
 The answer gives you the new app's id.
 
@@ -116,15 +116,19 @@ workser ask "The phone app needs an API to hold its data. Add one?" \
 |---|---|
 | `web` | Next.js site on Workser hosting |
 | `mobile` | Expo / React Native phone app |
-| `desktop` | Next.js + Electron, installs on a Mac or PC |
 | `api` | backend service — `api-hono` (TypeScript) or `api-python` (FastAPI) |
 
 **Name the kind you actually mean.** Asking for `web` because you are unsure is
-how a desktop app gets created as a website: the card shows the owner the kind
+how a phone app gets created as a website: the card shows the owner the kind
 you named, they approve THAT, and the wrong app is provisioned under your own
 sentence asking for the right one. An unknown kind is refused with the list
 above rather than guessed at — read it and ask again.
 
+**There is no desktop app type.** Workser builds websites, phone apps and
+backend services. If the owner asks for a Mac or Windows app, say plainly that
+Workser cannot make one yet — do not offer a web app dressed as a window, and
+do not build a "desktop-style" page instead. That is not what they asked for.
+
 **Never ask for a secret value this way** — the answer is stored and displayed. Ask
 *where* a key should go, then have the user set it (`workser env set` writes it
 without you ever seeing it).

package/skills/workser/reference/images.md

@@ -11,6 +11,7 @@ commands: [image, video, audio]
 workser image generate "<prompt>"            # alias: workser image gen
   -r, --reference <url...>                   # condition on existing images (up to 4)
   -o, --output <path>                        # also download the first image locally
+workser image usage                          # can I generate right now, and what would stop me
 ```
 
 Returns the generated image's public URL, so the usual move is to generate, then use
@@ -34,6 +35,32 @@ workser image gen "same van, from the side" -r https://… -o ./public/van.png -
 - **Placeholder art is not a deliverable.** Generating a hero image to unblock a
   layout is fine; shipping it as the user's brand asset without asking is not.
 
+## This is metered, and it can be refused
+
+Every image is billed to the organization's credit wallet, and each plan includes
+a monthly number of them. Three gates run server-side before anything is drawn —
+the plan tier, the monthly allowance, then the wallet — so a call can come back
+refused having spent nothing.
+
+```bash
+workser image usage --json    # {"limit":10,"used":3,"remaining":7,
+                              #  "credits":{"available":41.2,"requiredPerImage":4.12,"sufficient":true},
+                              #  "canGenerate":true,"blockedBy":null}
+```
+
+- **Check before a batch, not after.** Planning six images is a plan that needs
+  six times `requiredPerImage` in the wallet. `workser image usage` answers that
+  before any of them cost anything; `blockedBy` names which gate would stop you
+  (`plan`, `quota`, `credits`), and it exits non-zero when generation is blocked.
+- **A refusal is final, not a hiccup — do NOT retry it.** `insufficient_credits`
+  (HTTP 402) and `image_quota_reached` (403) come back as those exact codes in
+  `--json`, and the CLI exits 8 for both. Retrying cannot succeed and every
+  attempt is another paid call the owner did not ask for. Stop, and tell the
+  owner what to do: top up credits, or upgrade the plan.
+- **You cannot see their balance any other way**, so do not guess at it from how
+  many images you have already made — a refusal at image four of six leaves the
+  work half-done and looks like a bug.
+
 ## Understanding media you can't natively see or hear
 
 The fallback for a text-only model, or media you have no other way to reach: describe

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

@@ -58,14 +58,17 @@ the same way when the task touches documented behaviour.
 `--infra` match on the server, so the answer covers the whole project rather
 than the first page of it. `decision tag <id>` files one that already exists.
 
-## Work with phases → subtasks + a plan doc, before you build
+## Work with one task's steps → subtasks + 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.
+Do not confuse two levels of planning. A **goal phase** is an owner-visible
+delivery across tasks; create it with `workser goal create` and wait for agreement
+before filing work. A **subtask** is one teammate's implementation step inside a
+single approved task. File those steps before building — not afterwards, and not
+only in your reply, which is gone once the conversation scrolls.
 
 ```bash
-# the phases — this task's own subtask list, not the Board
-workser task subtask add "Phase 1 — schema + migration" --role api --note "…"
+# the implementation steps — this task's own subtask list, not the Board
+workser task subtask add "Create schema + migration" --role api --note "…"
 
 # the plan's narrative, ONE doc, deliberately NOT linked to a subtask
 workser doc create "Checkout — plan" --kind plan --markdown "$(cat plan.md)" --json
@@ -85,9 +88,9 @@ Never tell the user a subtask is locked, and never file a second one alongside
 the wrong one — a plan with a duplicate phase in it is a plan nobody can read
 the progress of.
 
-**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.
+**Don't pass `--work-item` for a goal-wide plan.** A linked document renders on
+its card and is *hidden* from the Docs panel; a plan spanning several goal phases
+belongs to the project, not to the first task.
 
 The bar: if the user closed this conversation now, the subtask list should still
 show what's left and the doc should still explain the plan to whoever continues