@workser/cli 0.3.1 → 0.6.1

package/skills/workser/reference/neon-backend.md

@@ -1,18 +1,31 @@
 ---
 topic: neon
-title: The project's own Neon backend
-summary: Neon-branch object storage and functions. Dedicated tenancy only.
+title: The project's own database
+summary: Branches, databases, compute, plus Neon-branch object storage and functions. Dedicated tenancy only.
 commands: [neon]
 ---
 
-# The project's own Neon backend
+# The project's own database
 
-S3-compatible object storage and Node.js HTTP functions on the project's own Neon
-branch — they branch with the database. **Additive** infrastructure, not a
-replacement for `workser storage`.
+The project's database, run the way an operator runs one: branches (copies of
+the data), the databases on them, and the compute that serves them. Plus
+S3-compatible object storage and Node.js HTTP functions on the same branch.
 
 ```
 workser neon status                       # tenancy + toggles + region verdict
+
+workser neon branch list                  # copies of the data; the live one is marked
+workser neon branch create qa-run         # a copy to work on, made in a second
+workser neon branch create qa --from <id> --no-compute
+workser neon branch reset <branchId>      # throw its changes away (asks the owner)
+workser neon branch rm <branchId>         # delete it and its data (asks the owner)
+
+workser neon database list [--branch <id>]
+workser neon database create <name> [--branch <id>] [--owner <role>]
+workser neon database rm <name> [--branch <id>]   # asks the owner
+
+workser neon endpoints                    # what compute is running, and idle
+
 workser neon storage list | create <name> | rm <bucket>
 workser neon storage ls <bucket> [prefix]
 workser neon storage put <bucket> <local> [key]
@@ -30,6 +43,24 @@ Region is fixed when the project is created. `regionSupportsNeonBackend: false`
 **final, not retryable** — no amount of waiting or retrying changes it. When you see
 it, say so plainly and fall back to `workser storage` (the default bucket).
 
+## Branches are the useful one
+
+A branch is a **full copy of the data**, made in about a second, costing almost
+nothing until something writes to it. That is what lets a check run against real
+data without being able to damage it — give a QA step its own branch instead of
+pointing it at the live database.
+
+Two things cannot happen at all, whatever anyone approves: **the branch the app
+runs on cannot be deleted or reset**, and neither can **the database it connects
+to**. Those refusals come from the server, not from the approval prompt. If you
+meant to reset a copy and got that message, you named the live one.
+
+`reset` deletes nothing by name and destroys just as much: it replaces a
+branch's contents with its source's. It asks the owner for exactly that reason.
+
+`--no-compute` makes a branch with no compute. It is cheaper and **nothing can
+connect to it** — useful as a snapshot, useless as somewhere to run tests.
+
 ## Notes that matter
 
 - **`neon storage rm <bucket>` deletes the bucket and everything in it.** Not
@@ -38,5 +69,8 @@ it, say so plainly and fall back to `workser storage` (the default bucket).
   through Workser.
 - **Functions deploy from a zip.** Build the bundle first, then
   `workser neon functions deploy <slug> <zip>`.
-- **Most apps don't need this.** If the user just wants to store uploads, the default
-  bucket in `reference/storage.md` is the answer.
+- **`neon endpoints` is the cost question.** `active` means it is billing;
+  `idle` means it is not. It is the only place in the product that answers "what
+  is this database costing me while nothing is happening".
+- **Most apps never need the storage or functions half.** If the user just wants
+  to store uploads, the default bucket in `reference/storage.md` is the answer.

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

@@ -1,28 +1,27 @@
 ---
 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]
+title: Decisions and requirements
+summary: Read what this project already decided, and record what a future maintainer will need. Phased work itself is subtasks, not board cards — see `workser help tasks`.
+commands: [board, decision, requirement]
 ---
 
-# Board cards, decisions, requirements, and docs
+# Decisions and requirements
 
 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.
+the Orbit desktop's Project Memory panel uses, so anything here appears there too
+— and, inside an Orbit-spawned run, as an inline card in the conversation.
+Documents have their own guide: `workser help docs`. Phased work is tracked as
+subtasks, not here — see `workser help tasks`.
+
+> **The Board (`workser board ...`) is deprecated for agent use.** It used to be
+> where a multi-phase plan went, one card per phase — and the phase was ALSO a
+> subtask the planning turn had just filed for the same piece of work. That gave
+> a task two competing plans, one of which this task's own page never reads and
+> nothing kept in sync with the other. Phases are `project_tasks` subtasks now,
+> full stop: `workser task subtask add`. Do not run `workser board create` for
+> planned work — see `workser help tasks`.
 
 ```
-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>
@@ -33,11 +32,6 @@ 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
@@ -45,7 +39,6 @@ workser doc update <id> [--title <text>] [--markdown <text>]
 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)
 ```
 
@@ -55,20 +48,18 @@ 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
+## Work with phases → 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.
 
 ```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
+# the phases themselves — this task's own subtask list, not the Board
+workser task subtask add "Phase 1 — schema + migration" --role api \
+  --note "Add orders/line_items tables and the migration."
+workser task subtask add "Phase 2 — checkout API" --role api --note "…"
+
+# the plan's narrative, ONE doc, deliberately NOT linked to a subtask
 workser doc create "Checkout — implementation plan" --markdown "$(cat plan.md)" --json
 
 # the approach, if the plan settled something with real alternatives
@@ -76,49 +67,23 @@ workser decision create "Carts live server-side" --context "…" --decision "…
 ```
 
 **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:
+its card and is *hidden* from the Docs panel; a plan spanning three phases
+belongs to the project, not to phase 1.
 
-```
-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.
+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
+it.
 
 ## 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.
+`--context` is why it came up, `--decision` what was decided, `--consequences`
+the follow-on effects. There is deliberately **no `decision update`** — a 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`.
+Requirements legitimately move along, so they do have `update`.
 
 ```
 workser requirement create "Support SSO" --body "Enterprise customers need SAML." \
@@ -129,22 +94,8 @@ 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
+rich text the Docs panel renders and as a git-tracked mirror at
+`.workser/docs/<id>.md`; `workser doc show <id> --markdown` reports that path so
+you can read the file with your normal tools.
 
-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.
+Revise trd saying "fix the bug" is not fixing the bug.

package/skills/workser/reference/tasks.md

@@ -14,6 +14,9 @@ below defaults to it and you rarely pass an id at all.
 ```
 workser task list [--status <value>] [--label <value>] [--limit <n>]
 workser task show [id]                  # the task you are in, with its steps
+workser task create <title> [--note <text>] [--kind <value>]
+                           [--label <value...>] [--app <id...>]
+                           [--infra <ref...>]
 
 workser task subtask add <title> [--role <value>] [--kind <value>]
                                  [--note <text>] [--app <id...>]
@@ -22,6 +25,7 @@ workser task subtask add <title> [--role <value>] [--kind <value>]
 workser task subtask list [taskId]
 workser task subtask update <id> [--title|--note|--role|--kind|--scope]
 workser task subtask remove <id>
+workser task subtask send-back <id> --note <text>   # redo it, and say why
 
 workser task can-start [id]             # may work begin? refuses until approved
 workser task approval request           # tell the owner the plan is ready
@@ -36,6 +40,16 @@ Team's own table. Filing your plan on the Board puts it somewhere the owner's
 task page never reads: they see "created work item" and an empty plan. Use
 `task subtask add`.
 
+## Opening work from a project channel
+
+When a project-channel conversation produces actionable work, the PM may record
+it with `workser task create`. Orbit supplies the channel and source-message IDs;
+the command records them and posts the new task card as a Project Manager message
+automatically. Do not invent or ask for those IDs.
+
+Opening a task does **not** approve it or start implementation. The task remains
+awaiting the owner. Never approve or dispatch a task you opened yourself.
+
 ## Planning a task
 
 Read the project first, then propose. One `subtask add` per step:
@@ -80,3 +94,23 @@ workser task done --summary "The report now shows cost per KOL, with six months
 ```
 
 Write the summary for someone who runs a business and does not read code.
+
+## Sending a step back
+
+A step that finished but is not good enough is **sent back**, not replaced:
+
+```
+workser task subtask send-back 3f2a… --note "The totals ignore refunds."
+```
+
+That puts it in the queue again as a **second attempt** on the same step. Two
+reasons it matters that this is not a new step:
+
+- The owner's screen can then say *"1 send-back, fixed — 2nd run passed"*. A
+  replacement step says only that two steps exist, which tells them nothing
+  about whether their team caught its own mistake.
+- `--note` is the reason, and it is recorded against the attempt being
+  rejected. Without it the history can say a step ran twice but not why.
+
+It refuses a step that is still working. Let it finish first — the run is
+still writing to it.

package/skills/workser/reference/usage.md

@@ -0,0 +1,48 @@
+---
+topic: usage
+title: Usage — what is being used, against the plan
+summary: How much database, file storage, projects and apps are in use, and how close that is to what the plan allows.
+commands: [usage]
+---
+
+# Usage — what is being used, against the plan
+
+```
+workser usage        # storage, projects, apps — and how close each is to the limit
+```
+
+Run it before you propose anything that adds to a count. "Create another
+project" is a plan you can only sensibly make if you know the plan allows two
+and two already exist.
+
+## Two scopes in one answer, on purpose
+
+* **Database and files are ORGANISATION-wide.** One pool across every project.
+  There is no per-project storage limit, and reporting one would invent it.
+* **Projects, and apps in this project, are counted where they apply.** These
+  are the limits people actually hit.
+
+## Two kinds of limit, which do not mean the same thing
+
+* **Hard cap** — projects, apps. Going over is **refused**. `workser usage`
+  exits non-zero when one is reached, so a step can gate on it.
+* **Soft allowance** — database, files. Going over is **billed as extra**,
+  never blocked. It does not fail the command, because a customer growing past
+  their allowance should not have their automation start breaking that day.
+
+## "not measured" is not zero
+
+A figure that could not be read prints as `not measured`, with the reason, and
+draws no bar. Do not report it as `0`, and do not tell the user they have room
+based on it — nobody looked.
+
+If a scan comes back with a figure missing, say which one and why. "Your
+database is using 2.5 GB of 10; the file total could not be read" is a useful
+sentence. "You are using 2.5 GB of 20" is not, and it is wrong.
+
+## What to do with it
+
+- Near a **soft** limit: tell the owner what the extra will cost them, and what
+  is taking the space. Do not delete anything to make a number look better.
+- At a **hard** cap: say which plan raises it. Do not attempt the create — it
+  will be refused, and a failed attempt reads to the owner as a broken product.