@workser/cli 0.1.0 → 0.2.0

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

@@ -0,0 +1,42 @@
+---
+topic: neon
+title: The project's own Neon backend
+summary: Neon-branch object storage and functions. Dedicated tenancy only.
+commands: [neon]
+---
+
+# The project's own Neon backend
+
+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`.
+
+```
+workser neon status                       # tenancy + toggles + region verdict
+workser neon storage list | create <name> | rm <bucket>
+workser neon storage ls <bucket> [prefix]
+workser neon storage put <bucket> <local> [key]
+workser neon storage get <bucket> <key> [dest]
+workser neon storage url <bucket> <key>   # temporary download URL
+workser neon functions list | deploy <slug> <zip> | rm <slug>
+```
+
+## Check `neon status` first — always
+
+Three things must all be true: **dedicated tenancy**, the capability **switched on**,
+and a **supported region**.
+
+Region is fixed when the project is created. `regionSupportsNeonBackend: false` is
+**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).
+
+## Notes that matter
+
+- **`neon storage rm <bucket>` deletes the bucket and everything in it.** Not
+  reversible. Confirm with the user first.
+- **`neon storage url`** issues a short-lived URL — prefer it to moving large files
+  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.

package/skills/workser/reference/roles.md

@@ -0,0 +1,33 @@
+---
+topic: roles
+title: Delegate to roles
+summary: Hand a focused subtask to another configured local agent.
+commands: [agent]
+---
+
+# Delegate to roles
+
+The user can configure **roles** — named specialists each backed by a local CLI agent
+(e.g. `qa` → codex, `designer` → claude_code).
+
+```
+workser agent list                  # main agent + configured roles (+ which are runnable)
+workser agent run <role> "<task>"   # delegate a focused subtask (runs isolated)
+workser agent main                  # show the configured main agent
+```
+
+## How to use it
+
+Run `workser agent list --json` first — it tells you which roles exist **and** which
+are actually runnable on this machine. Delegating to a role that isn't installed just
+fails.
+
+`workser agent run <role> "<task>" --json` runs the role as an **isolated local
+subagent** with its own context and returns `{role, agent, output, exitCode}`.
+
+- Hand off focused subtasks — review this diff, design this screen — to keep your own
+  context lean and get a specialized second perspective.
+- **A non-zero `exitCode` means the role's run failed.** Surface that; don't quietly
+  treat empty output as success.
+- The subagent doesn't share your context. Put everything it needs in the task
+  string; it cannot see the conversation you're in.

package/skills/workser/reference/storage.md

@@ -0,0 +1,37 @@
+---
+topic: storage
+title: File storage
+summary: The project's default bucket — upload, list, download.
+commands: [storage]
+---
+
+# File storage
+
+The project's default bucket (Cloudflare R2 behind Workser). Every project gets one;
+`create` is idempotent.
+
+```
+workser storage create [name]       # provision the bucket (idempotent)
+workser storage list                # the project's bucket
+workser storage ls [prefix]         # list objects in the bucket
+workser storage put <local> <key>   # upload a file into the bucket
+workser storage get <key> [dest]    # download an object (or print its URL)
+```
+
+## Notes that matter
+
+- **One bucket per project, shared by its apps.** Namespace your keys by app or
+  feature (`invoices/2026/…`) rather than assuming the root is yours.
+- **`storage get` with no destination prints a URL** instead of writing a file —
+  useful when you just want to hand the user something to click.
+- **This is not where app uploads should go through you.** At runtime the app uses
+  `workser.storage` from `@workser/app`, and for anything large it should request a
+  presigned upload URL so the bytes never pass through Workser. See the
+  `workser-sdk` skill.
+
+## Not the same as `workser neon storage`
+
+`storage` is the default R2 bucket every project has. `neon storage` is additive
+infrastructure on the project's own Neon branch, available only on dedicated tenancy
+in a supported region. They are different stores — a file put in one is not visible
+in the other. See `reference/neon-backend.md`.