primitive-admin 1.1.0-alpha.8 → 1.1.0-alpha.81

package/assets/skill/skills/primitive-platform/SKILL.md

@@ -0,0 +1,811 @@
+---
+name: primitive-platform
+description: >
+  Expert guide for building applications on the Primitive platform. MUST be used whenever the user
+  is writing code that uses js-bao, js-bao-wss-client, primitive-app components, or any Primitive
+  platform feature (documents, databases, workflows, prompts, integrations, blobs, authentication,
+  users/groups). Also trigger whenever about to run any `primitive` CLI command (e.g., primitive config, primitive integrations, primitive apps, primitive env) to ensure Step 0 CLI verification is performed first. After writing or modifying code that touches Primitive
+  APIs, this skill cross-references the implementation against official guides and automatically
+  corrects common mistakes. Use this skill even if the user doesn't explicitly ask for it —
+  any Primitive-related code should be validated against current best practices. Also use it
+  when something looks like a platform bug or missing platform capability, to decide whether
+  (and how) to file a platform issue. Also trigger whenever the user wants to upgrade or update
+  the app to a newer platform version — bumping js-bao, js-bao-wss-client, primitive-app, or the
+  primitive CLI — which follows the "Upgrading Platform Libraries" workflow below.
+allowed-tools: Bash, Read, Edit, Write, Glob, Grep, Agent
+---
+
+# Primitive Platform Development Guide
+
+You are an expert on the Primitive platform. Your job is to help developers write correct,
+idiomatic Primitive code by leveraging the CLI's built-in guide system and enforcing best practices.
+
+**The CLI guides are the single source of truth.** Never hardcode or memorize guide content —
+always fetch the latest from the CLI.
+
+## Step 0: Verify CLI Configuration
+
+The Primitive CLI is **project-scoped**, and project mode is **strongly preferred** for any work
+inside a repo. Each project has a `primitive/config.json` (committed to the repo) that defines
+named environments (`dev`, `prod`, `staging`, …), where each environment binds an `apiUrl` and a
+required `appId`. Per-environment auth tokens live in `.primitive/credentials.json`
+(gitignored). There is no global "currently active app" — the active environment determines the
+server *and* the app.
+
+There is no global fallback. Outside a project only `primitive login` and `primitive init` work
+(plus `logout`, login's inverse, and `bootstrap`, which creates the first admin on a fresh server);
+every other command stops with an error naming the missing `primitive/config.json`. **Treat a
+missing project config as a setup gap to fix, not a mode to operate in.**
+
+**Before running any CLI commands**, your *first* check is whether the project is in project mode:
+
+```bash
+ls primitive/config.json   # exists at project root or any ancestor?
+```
+
+The two branches below are not equivalent — pick the one that matches reality and follow it.
+
+### Branch A — `primitive/config.json` exists (project mode)
+
+The active environment is resolved in this order:
+1. `--env <name>` flag on the command
+2. `PRIMITIVE_ENV` environment variable
+3. This machine's selection in `.primitive/local.json` (written by `primitive env use`, gitignored)
+4. `defaultEnvironment` in `primitive/config.json` — the committed team default
+5. The sole environment, if exactly one is defined
+
+`primitive env use <name>` does NOT edit the committed config: pointing this
+machine at a different backend never shows up as a file change. `env list`
+shows the resolved current environment and the committed team default
+separately, and reports a corrupt or dangling selection rather than falling
+back to the default.
+
+Confirm you're targeting the correct environment:
+
+1. **Read the CLI header.** Every command prints `Env | App | Server` at the top of its output —
+   verify these match the project's intended target.
+2. **Inspect the project config:**
+
+   ```bash
+   primitive env list           # All environments (CURRENT and TEAM DEFAULT shown separately)
+   primitive env show           # Details for the currently-resolved env
+   primitive whoami             # Authenticated user + resolved server/app
+   ```
+
+**To switch environments** for a one-off command, pass `--env <name>`. To point this machine at
+a different environment, run `primitive env use <name>` (local state; the committed
+`defaultEnvironment` is unchanged). To switch the *app* an env points at, edit the env's
+`appId` in `primitive/config.json`. Every environment names exactly one app, and there is no
+per-machine app selection that could differ from it.
+
+### Branch B — no project config (project mode NOT set up)
+
+Without a project config there is nothing to run against. Every app-scoped command (`whoami`,
+`apps list`, `config pull`, …) exits non-zero with an error naming the missing
+`primitive/config.json` and pointing at `primitive init`. The CLI does not fall back to
+`~/.primitive/credentials.json` or any other global state, and no flag points a command at another
+directory's tree — so there is no "proceed against global state" option to offer, and `--app`,
+`--env` or environment variables do not change what the error does.
+
+**Your default action is to get into a project.** Stop and work out with the user which of the two
+supported flows applies before doing anything else:
+
+1. **This repo is (or should become) a Primitive project that was never scaffolded** — run
+   `primitive init` at the repo root. `init` creates the app, writes `primitive/config.json` with a
+   `dev` environment bound to that app, and seeds that environment's credentials from the session
+   it logs you in with. It prompts before overwriting a non-empty directory, so read what it says.
+2. **The project already exists somewhere else** — `cd` into it (or any subdirectory; the CLI walks
+   up to find `primitive/config.json`) and run the command there. To reach a different app, use
+   the project whose environment names it; there is no cross-app read from outside a project.
+
+Prompt the user, e.g.:
+
+> "This repo has no `primitive/config.json`, so the CLI has no environment to target and every
+> app-scoped command stops here. If this repo should be a Primitive project, I'll run
+> `primitive init` at the root, which creates the app and the config. If the project lives
+> elsewhere, tell me where and I'll run the commands from there. Which is it?"
+
+`primitive env add` does NOT create the config — it adds an environment to an existing one and
+fails with the same error outside a project. Use it once a project exists, to bind a second
+backend (`primitive env add prod --api-url <url> --app-id <id>`).
+
+Do not rely on `.env` files like `PRIMITIVE_API_URL` to control CLI targeting — those are not
+read by the CLI, and the project config is the source of truth.
+
+**Why this matters:** If the CLI were pointed at the wrong environment (e.g., prod instead of dev),
+commands like `primitive config push` would modify the wrong server. Refusing outside a project is
+what makes that mistake impossible to commit silently: the only target a command has is the one the
+project's environment names. Verify and surface it before running mutating operations.
+
+## Step 1: Discover Available Guides
+
+Before writing or reviewing any Primitive code, run:
+
+```bash
+primitive guides list
+```
+
+This returns the full list of available guide topics with descriptions, keywords, and use cases.
+The `COMBINATIONS` column shows which `(language, platform)` variants each guide is available in
+(e.g. `ts; swift`). Use this output to determine which guides are relevant to the current task —
+and which language/platform variant to request in Step 2.
+
+### Determine the project's language and platform
+
+Figure out what the project you're working in targets, then request the matching variant when
+fetching guides:
+
+- A `Package.swift`, `*.xcodeproj`, or `project.yml` → `--language swift` (plus `--platform ios`
+  or `--platform macos` as appropriate).
+- A Vite/React/Node web app (`package.json`, `js-bao-wss-client`) → `--language ts --platform web`.
+
+If you can't tell, omit the flags — every guide has a default variant, so a bare
+`primitive guides get <topic>` always returns something useful.
+
+## Step 2: Fetch the Relevant Guides
+
+For each relevant topic identified in Step 1, fetch the full guide, passing the project's
+language/platform so you get the right variant:
+
+```bash
+primitive guides get <topic> --language <ts|swift> --platform <web|ios|macos>
+# or, when the project's language/platform is unknown or doesn't matter:
+primitive guides get <topic>
+```
+
+`--language` accepts aliases (`typescript`/`javascript`/`js` → `ts`). These flags **never fail**:
+an unknown value or an unavailable combination falls back to the guide's default variant rather
+than erroring, so it's always safe to pass your best guess.
+
+**Always fetch guide(s) BEFORE writing code.** If multiple features are involved, fetch multiple
+guides. The guides contain:
+- Complete API documentation with method signatures
+- Working code examples in the requested language (e.g. TypeScript or Swift)
+- Common patterns and anti-patterns
+- Configuration examples (TOML files for `primitive config`)
+- Decision frameworks for architecture choices
+
+**Do not guess or assume API patterns.** If you're unsure about a method signature, parameter,
+or pattern, fetch the guide. The guides are comprehensive and authoritative.
+
+## Step 3: Write Code Following Guide Patterns
+
+When writing Primitive code:
+
+1. **Follow the patterns from the fetched guides exactly** — method names, argument order, lifecycle patterns
+2. **Use `primitive config`** for all backend configuration (workflows, prompts, integrations, databases)
+3. **Server functions are TypeScript in the config tree** — `functions/<key>.toml` states the gate, the `entry` and the limits, the code sits beside it, and `primitive config push` builds the bundle (npm deps inlined, `primitive-functions` left to the platform) and ships it with the authored source bytes. Relative and absolute imports must stay inside the config tree; npm packages are imported by name. The push also TYPECHECKS the sources against the declarations it generates and refuses the function with the compiler's own diagnostics when they do not hold (`tsc -p functions/tsconfig.json --noEmit` reproduces it; `--no-typecheck` skips it). A function's key is unique per app ACROSS workflows, functions, scripts and webhooks — one namespace
+4. **Configuration lives in TOML files** in version control, pushed via `primitive config push` — including test cases, authored as sidecars at `prompts/<key>.tests/`, `workflows/<key>.tests/`, `transforms/<name>.tests/` and `integrations/<key>.tests/` (one `[test]` file per case, with its attachments in a directory of the same name). A case file's name is its identity: `config pull` writes it back under that name and renaming it renames the case, so the checked-in tree reconciles on a fresh clone instead of duplicating
+5. **Run `pnpm codegen`** after creating or modifying js-bao models
+
+## Step 4: Post-Code Review (Automatic)
+
+After writing or modifying Primitive-related code, **automatically perform this review**:
+
+### 4a. Identify What Was Written
+Determine which Primitive features the new/modified code touches by scanning for:
+- Import statements from `js-bao`, `js-bao-wss-client`, or `primitive-app`
+- Primitive API calls (documents.open, databases.connect, workflows, etc.)
+- Model definitions, schemas, queries
+- Configuration files (TOML for sync)
+
+### 4b. Fetch and Cross-Reference
+Run `primitive guides list` to identify which guides cover the features used, then fetch each one
+in the project's language/platform:
+```bash
+primitive guides get <topic> --language <ts|swift> --platform <web|ios|macos>
+```
+
+Compare the written code against the guide content:
+- **API usage patterns** — Are methods called correctly with proper arguments?
+- **Lifecycle management** — Are documents opened before queries? Is auth checked first?
+- **Access control** — Are CEL expressions or permissions configured properly?
+- **Anti-patterns** — Does the code do anything the guide explicitly warns against?
+- **Untyped workflow invocation** — Is `client.workflows.start`/`runSync` called with a string-literal `workflowKey` and a hand-typed/cast `input`/`output` (e.g. `result.output as {...}`) instead of a generated invoker? That's a finding whenever the workflow has an `inputSchema`/`outputSchema` to generate from — regenerate with `primitive workflows codegen` (`--lang swift` for iOS/macOS) and call through the factory it emits instead, per the workflows guide's "Typed invocation (codegen)" section.
+- **Missing steps** — Does the code need `pnpm codegen`, `primitive workflows codegen`, `primitive config push`, or other follow-up?
+
+### 4c. Report and Fix
+If issues are found:
+1. **Explain the issue** — cite the specific guide section that applies
+2. **Show the fix** — provide corrected code
+3. **Apply the fix** — edit the file directly (don't just suggest, actually fix it)
+4. **Note any CLI commands needed** — e.g., `pnpm codegen` or `primitive config push`
+
+If no issues are found, briefly confirm the code follows best practices.
+
+## CLI Quick Reference
+
+Remind users of these essential commands when relevant:
+
+```bash
+# Verify current configuration (DO THIS FIRST)
+primitive env list                 # List environments (CURRENT vs committed TEAM DEFAULT)
+primitive env show                 # Details for the currently-resolved env (api URL, app ID)
+primitive whoami                   # Authenticated user + resolved server/app
+
+# Switching environments
+primitive env use <name>           # Select this machine's environment (gitignored local state)
+primitive --env <name> <command>   # One-off override for a single command
+PRIMITIVE_ENV=<name> <command>     # Override via env var (useful in scripts/CI)
+
+# Setup — existing project (most common: adopting Primitive in an existing repo)
+pnpm add -g primitive-admin                             # Install CLI (pnpm preferred; npm works too)
+primitive env add dev --api-url <url> --app-id <id>     # Add env to primitive/config.json
+primitive env add prod --api-url <url> --app-id <id>    # (creates the file if missing)
+primitive login                                         # Authenticate (tokens stored per-env)
+
+# Setup — brand-new project (greenfield only)
+primitive init my-new-app                               # Scaffolds template, creates a new app
+                                                        # on the server, runs pnpm install.
+primitive init my-new-app --platform web,ios            # One app, a web client AND a native
+                                                        # client: web/ and ios/, with the project
+                                                        # config, git repo and the shared
+                                                        # models/models.toml at the root.
+
+# Setup — adding a client to an app that already exists
+primitive init ios --platform ios                       # Run INSIDE the app's repo: adds the
+                                                        # client to the app the nearest ancestor
+                                                        # primitive/config.json targets. Writes
+                                                        # no nested .primitive/ or .git/ and makes
+                                                        # no commit — review with `git status`.
+                                                        # Read the multi-client guide first.
+
+# Guides (the most important commands for development)
+primitive guides list              # See all guides: topics, descriptions, available (lang,platform) combinations
+primitive guides get <topic>       # Read a guide's default variant
+primitive guides get <topic> --language swift --platform ios   # Read a specific language/platform variant
+
+# Configuration as Code
+primitive config init  # Scaffold the environment's config directory
+primitive config pull  # Pull config from server
+primitive config push  # Push config to server
+primitive config diff  # Preview changes before push
+
+# Taking something out of service (or putting it back)
+primitive workflows disable <key>       # same verb pair on every type that has one
+primitive cron-triggers disable <id>
+primitive webhooks disable <id>
+primitive integrations disable <key>
+primitive prompts disable <key>
+primitive functions disable <id>        # a pushed server function
+primitive users disable <user-id>       # a person, not an object — reversible
+primitive feature-flags disable <key>   # super-admin platform toggle
+
+# Retiring an object (soft delete; NOT the same as disable)
+primitive workflows archive <key>       # same verb on the six types that carry
+primitive cron-triggers archive <id>    # `archived`; confirms first, -y skips
+primitive webhooks archive <id>
+primitive integrations archive <id>     # the ID column of `integrations list`
+primitive prompts archive <id>          # the ID column of `prompts list`
+primitive functions archive <id>        # the ID column of `functions list`
+
+# Common operations
+primitive apps list                # List apps on the active env's server
+primitive apps create "Name"       # Create an app (does NOT auto-bind to an env;
+                                   # edit primitive/config.json or use `env add` to bind)
+```
+
+**Availability is not configuration.** Whether a workflow, cron trigger,
+webhook, integration, prompt or server function is in service is one
+server-owned `status` field, changed only by `<noun> enable|disable` (or the
+matching console action) and by the delete flow, whose CLI spelling is
+`<noun> archive` on those same six types. It is not a TOML key: `config pull` does not emit it,
+`config push` never sends it, and a file that still carries a `status` line
+fails the push with a message naming the verbs. So a push cannot put something back in service
+that an operator took out of it, and a fresh environment stood up from config
+has everything active. Anything newly CREATED is active; there is no `draft`
+state on any object. For a server function, creation is the only writer of
+`active`: a `config push` to a disabled function updates its code and leaves it
+out of service, so shipping a fix never puts a public endpoint back in service
+on its own.
+
+The keys spelled `status` that ARE yours are the per-VERSION ones: a prompt's
+`[[configs]] status`, and a workflow named config's `[config] status` in its
+`workflows/<key>.configs/<name>.toml` sidecar. They say which named version is
+retired, not whether the object is serving. For a prompt, `config pull` writes
+the line only for a config that is retired (`status = "archived"`); an omitted
+line means `active`, so an ordinary pulled prompt file carries no `status` at
+all. A workflow config sidecar still states its own either way.
+
+**`archive` retires, `--prune` destroys.** `<noun> archive <id>` writes the
+third value, `archived`: the delete lifecycle rather than availability. The row
+is kept so its history still resolves, it goes on holding its key — and, for
+webhooks and cron triggers, its slot against the per-app cap — `enable` refuses
+it, and there is no un-archive. Reclaiming the key means a hard delete: remove
+the object's TOML file and run a confirmed `primitive config push --prune`, then
+re-add the file and push. There is no `--hard` flag and no per-type `delete`
+verb; prune-by-push is the CLI's only hard delete. `users` and `admins` carry
+`enable`/`disable` but no `archive` — people are not configuration objects.
+
+Per-VERSION status is a different thing and stays in TOML: a prompt, workflow
+or script config retires a named version with `status = "archived"` inside its
+`[[configs]]` entry, which says which version is live, not whether the object
+is serving.
+
+## Debugging and inspection
+
+The CLI is the reference surface for inspecting a running app — reading what
+happened without opening the admin UI. The inspection commands share one set of
+conventions so they behave predictably across resources.
+
+```bash
+# Workflow runs (the reference tailing command)
+primitive workflows runs list <workflow-id>            # recent runs
+primitive workflows runs list <workflow-id> --json     # normalized inspection items
+primitive workflows runs list <workflow-id> --watch    # re-render the list every 2s (snapshot)
+primitive workflows runs list <workflow-id> --follow   # append runs as they start or change (tail)
+primitive workflows runs list --user-id <user-id>      # one user's runs, across every workflow
+primitive workflows runs steps <workflow-id> <run-id>  # every step run of one run
+primitive workflows runs status <workflow-id> <run-id> # one run's status + step results
+
+# The other log-shaped views
+primitive integrations logs <integration-id>           # outbound calls: status, timing, actor
+primitive webhooks events <webhook-id>                 # inbound deliveries and how they were handled
+primitive analytics events                             # app activity events
+
+# Per-subject analytics — one home, the analytics noun
+primitive analytics workflows --window-days 7          # top workflows by runs
+primitive analytics prompts --window-days 7            # top prompts by executions
+primitive analytics integrations                       # calls, error rate, latency
+primitive analytics workflow-usage                     # step kinds configured, and their runs
+
+# Blob storage
+primitive blob-buckets list                            # buckets in the app (app-scoped: no selector)
+primitive blob-buckets head <bucket> <key>             # object metadata without downloading
+
+# Live connections and sessions
+primitive connections list --user-id <id>              # active WebSocket connections
+primitive sessions list --user-id <id>                 # auth sessions
+
+# Database records and app documents
+primitive databases records query <database> ...       # read records
+primitive databases records get <database> <model-name> <record-id>
+primitive documents records query <document> <model-name> [--filter '{...}']
+primitive documents records get <document> <model-name> <record-id>
+primitive documents dump <document-id>                 # every model's records as JSON
+primitive documents export <document-id>               # dump a document's contents
+primitive documents create "<title>" [--owner <user-id-or-email>]  # mint a document (--owner needs a super-admin or assigned-console-admin token; app-role admins create as themselves)
+primitive documents delete <document-id> [-y] [--json]  # delete a document (document owner / app owner / super-admin or assigned-console-admin; app-role admins only via a containing collection's document.delete rule)
+
+# Metadata
+primitive metadata get <type> <id> <category>          # resource metadata VALUES
+primitive metadata-category-configs list               # category DEFINITIONS (schema + read/write rules)
+primitive metadata-category-configs get <type> <category>
+```
+
+**Uniform flags across every inspection command:**
+
+- `--app <id>` — target app (falls back to the resolved env's app).
+- `--json` — the output you parse in scripts. Most commands print the endpoint
+  payload as-is; the log views below normalize theirs into the shared item
+  shape. Either way it is a JSON document, never a bare array — except the
+  type-config readers (`group-type-configs`, `collection-type-configs`,
+  `metadata-category-configs`), whose `list --json` prints the configs as a
+  bare array (`jq '.[]'`). Data goes to
+  stdout; status, warnings and the `CLI Version: …` banner go to stderr — so
+  even the always-JSON commands that take no `--json` flag pipe cleanly
+  (`primitive documents dump <doc> | jq .`).
+- `--limit <n>` / `--cursor <c>` — paged reads. The response envelope is always
+  `{ items, hasMore, nextCursor? }`. Both `records query` verbs print that
+  envelope whatever shape their endpoint returns, and neither emits the
+  deprecated `cursor` alias — read `nextCursor`. Aggregate reads walk the
+  `nextCursor` chain.
+- `list` always requires a **selector** (`--user-id`, `--owner`, a resource id, …)
+  so it never enumerates the whole app — **except** genuinely app-scoped
+  resources like `blob-buckets list`, which lists the app's buckets directly.
+  `--user-id` is the spelling on every list/inspection selector; `connections
+  list`, `sessions list` and `tokens list` still accept `--user` as a
+  deprecated alias that prints a notice on stderr.
+
+**One `--json` item shape across the log views.** `workflows runs list`,
+`workflows runs steps`, `integrations logs`, `webhooks events` and `analytics
+events` all emit the same item envelope inside their endpoint's pagination
+envelope — never a bare array:
+
+```json
+{
+  "items": [
+    {
+      "source": "workflow-run",
+      "timestamp": "2026-07-24T18:03:11.204Z",
+      "outcome": "error",
+      "nativeStatus": "failed",
+      "correlation": { "runId": "01J…", "workflowId": "01J…", "userId": "01J…" },
+      "detail": { "workflowKey": "summarize", "errorMessage": "…" }
+    }
+  ],
+  "hasMore": false
+}
+```
+
+- `source` is the discriminator: `workflow-run`, `workflow-step`,
+  `integration`, `webhook`, `activity`.
+- `outcome` is the normalized verdict — `ok`, `error`, `pending`, or `neutral`
+  — and `nativeStatus` keeps the source's own value (an HTTP integer, `failed`,
+  `duplicate`, …) verbatim, so filtering on the raw value stays possible. A
+  webhook that was accepted but matched no active workflow is `ok` with
+  `nativeStatus: "workflow_inactive"` — a non-dispatch, not a failure.
+- `correlation` carries the pivot keys that let you follow one operation
+  between views (`runId`, `stepId`, `traceId`, `workflowId`, `webhookId`,
+  `userId`) plus the row's own id (`stepRunId`, `eventId`), so a row you
+  printed can always be looked up again.
+- `detail` is a per-source allowlist of operator-facing fields, not the whole
+  stored record.
+- Pagination rides alongside `items`: `hasMore` plus `nextCursor` where the
+  endpoint pages by cursor, `page`/`pageSize`/`totalRows` for `analytics
+  events`. `integrations logs` returns `{ items }` — it filters within a
+  bounded scan rather than paging.
+- The normalization is `--json`-only: the human tables stay per-view because
+  each shows columns the shared shape has no room for (queue delay, inter-step
+  gap, token counts, event id). `--watch --json` reprints the same envelope
+  each tick; `--follow --json` emits one item per line (newline-delimited
+  JSON), since a tail has no closing bracket to wait for.
+
+**Per-user inspection.** Two views can be keyed on a user:
+
+```bash
+primitive workflows runs list --user-id <user-id>   # every run that user started
+primitive analytics events --user-id <user-id>      # that user's activity events
+```
+
+`workflows runs list --user-id` makes `<workflow-id>` optional — it lists the
+user's runs across every workflow. Pass both to narrow to one workflow.
+`integrations logs` and `webhooks events` have no `--user-id`: an integration
+invocation records the actor but is indexed by integration, and a webhook event
+carries no user identity at all. To follow a user through those, take the
+`runId`/`traceId` from that user's workflow runs and match it in the
+integration logs.
+
+**`--watch` vs `--follow` (both poll — there is no server push):**
+
+- `--watch` re-fetches the current snapshot each interval and re-renders the whole
+  view (a periodic re-`list`/`get`). It works on any list command with no server
+  change.
+- `--follow` tails: it appends new/changed rows since a server-owned checkpoint,
+  like `tail -f`. It is offered **only** where the endpoint supports the resume
+  contract (today: `workflows runs list`); other commands offer only `--watch`
+  until their endpoint adds it. Passing `--follow` where it isn't supported fails
+  with a clear message.
+- `--interval <seconds>` sets the poll interval (minimum 1s, default 2s).
+- `--watch` and `--follow` are mutually exclusive.
+- `--json --follow` emits **NDJSON** (one JSON object per new row per line) — a
+  tail is an unbounded stream, so it can't be one array; pipe it to `jq -c`.
+  `--json --watch` emits one array per redraw.
+- Ctrl-C stops a tail cleanly (exit 0).
+
+**`--follow` shows the latest observed version of a row, not every state change.**
+It re-emits a run when a newer version is observed between polls, so a run you
+already saw can reappear at its new position after its status changes — that is
+expected, not a duplicate. Fast transitions that happen between two polls collapse
+to the latest stored version. This is near-lossless observed-version tailing:
+rows sharing a timestamp, or a delayed index update, can occasionally be skipped
+or re-shown. Use it to watch activity, not as an exactly-once event log.
+
+## When the User is Starting a New Feature
+
+If the user describes a new feature they want to build:
+
+1. **Verify CLI configuration** per Step 0 — confirm the active environment in
+   `primitive/config.json` (and its bound `apiUrl` / `appId`) match the project's intended target
+   before running any commands
+2. **Run `primitive guides list`** to discover available topics and their `(language, platform)` combinations
+3. **Identify which guides are relevant** to their feature from the list output
+4. **Fetch those guides** with `primitive guides get <topic> --language <lang> --platform <platform>`
+   (using the project's language/platform; omit the flags if unknown)
+5. **Recommend a data modeling approach** based on the guide content. If requirements are unclear or ambiguous, **ask the user clarifying questions before proceeding** — it's much easier to get the data model right upfront than to migrate later
+6. **Outline the implementation steps** referencing specific patterns from the guides
+7. **Write the code** following the patterns exactly
+8. **Review automatically** per Step 4 above
+
+## When the User Asks "How Do I...?"
+
+For any question about Primitive platform capabilities:
+
+1. **Run `primitive guides list`** to find the relevant topic (and its available language/platform combinations)
+2. **Fetch the guide**: `primitive guides get <topic> --language <lang> --platform <platform>` (omit the flags if the language/platform is unknown)
+3. **Answer from the guide content** — don't guess or make up APIs
+4. **Include working code examples** from the guide
+5. **Point the user to the guide** for further reading: "You can see more examples by running `primitive guides get <topic>`"
+
+## Upgrading Platform Libraries
+
+When the user asks to upgrade the app to a newer platform version, follow this workflow.
+An upgrade is not just a version bump: after the libraries move, workarounds built for old
+platform bugs should come out, the starter template the app was scaffolded from has usually
+moved too, and new platform capabilities should be considered. The refreshed guides are the
+source of truth for what the platform can do now.
+
+The backend is upgraded by the platform team, not by the app — the app only chooses which
+environment it points at (Step 0). A library upgrade against the production environment
+needs no server-side changes.
+
+### 1. Snapshot the current state
+
+- Read `package.json` and note the installed versions of the platform packages the app
+  uses: `js-bao`, `js-bao-wss-client`, `primitive-app`, and `primitive-admin` (the CLI).
+- Check what's available: `pnpm view <pkg> dist-tags` for each. Compare the target tag's
+  version against what's installed — a dist-tag can lag (or even point behind another
+  tag), so confirm the upgrade actually moves forward before proceeding.
+- Locate the app's platform feedback doc (convention below). Note its upgrade stamp and
+  the tracked workarounds — Step 5 revisits each one.
+
+### 2. Upgrade the CLI first
+
+```bash
+pnpm add -g primitive-admin@latest   # pnpm preferred; use npm if that's how the CLI was installed
+```
+
+Upgrading the CLI first matters for two reasons:
+
+- The CLI bundles this skill and silently refreshes the installed copy on its next run.
+  After upgrading, **re-read this skill file** — the guidance itself may have changed.
+- The CLI serves the guides, and guides are cached at `~/.primitive/guides/` with a
+  24-hour TTL. Nothing invalidates that cache when packages update, so after any upgrade
+  pass `--refresh` on the first `primitive guides list` / `primitive guides get` calls
+  (or clear the cache: `rm -rf ~/.primitive/guides`). Otherwise you may be reading
+  yesterday's guides against today's libraries.
+
+### 3. Upgrade the app's libraries
+
+```bash
+# pnpm by default (use npm only if the app already uses npm), for the packages the app uses:
+pnpm add js-bao@latest js-bao-wss-client@latest primitive-app@latest
+```
+
+Upgrade the libraries **before** fetching guides: the guides system selects its version
+channel from the *installed* `js-bao-wss-client` major, so fetching first returns guides
+for the old version. Then refetch the guides for every feature area the app uses,
+passing `--refresh` on the first call.
+
+### 4. Fix breaking changes
+
+Run the app's typecheck/build. For every error, consult the refreshed guide for that
+feature area and migrate the code to the current API — don't pin back or suppress. A
+major version bump means breaking changes are expected; treat the migration as part of
+the upgrade, not an optional follow-up.
+
+### 5. Retire resolved workarounds
+
+For each workaround tracked in the feedback doc, re-test the underlying platform
+behavior against the upgraded libraries (a small repro, or the app test that covers it).
+If the platform now behaves correctly, remove the workaround code and move the item to
+Resolved. If not, keep it and note the version it was last checked against. Stale
+workarounds are a real cost — they mask platform behavior and confuse later readers —
+so default to removing them the moment they're unnecessary.
+
+### 6. Adopt template updates
+
+The app was scaffolded by `primitive init` from a starter template —
+`Primitive-Labs/primitive-vue-template` for web apps, `Primitive-Labs/primitive-swift-template`
+for iOS. Those templates keep moving with the platform: config, setup, and wiring fixes
+land there and never reach an app generated months earlier. Scan the template the app came
+from (both, if the app has a web and an iOS client) and pull forward what applies. Fetch
+the branch matching the channel you're upgrading to — `main` for production, `alpha` for
+alpha:
+
+```bash
+# Vue
+curl -sL https://github.com/Primitive-Labs/primitive-vue-template/archive/refs/heads/main.tar.gz \
+  | tar -xz -C /tmp
+# Swift
+gh api repos/Primitive-Labs/primitive-swift-template/tarball/main > /tmp/swift-template.tgz
+```
+
+Then compare the template against the app file by file:
+
+- **The app never changed it → move it over.** Where the app still carries the template's
+  version unchanged, take the newer one. That includes files the template has added since
+  the app was scaffolded. No need to ask.
+- **The app removed it → leave it removed.** A file or block the app deleted was deleted
+  on purpose. Never restore it.
+- **Both changed it → ask.** Where the app has its own edits to something the template
+  also changed, don't overwrite. Say what the template's change does and why it landed,
+  then ask whether to merge it in. Ask once per coherent change, not per hunk.
+
+Telling those three cases apart needs a baseline: the template commit the app last synced
+from, recorded in the feedback doc (below). With it, diff baseline→template to see what
+the template changed and baseline→app to see what the app changed; only files in both
+sets need a question. Without a stamp you can't tell an app edit from a template edit, so
+treat every differing file as "ask" — and record the stamp this time.
+
+### 7. Adopt and suggest new features
+
+Re-run `primitive guides list` (topics appear and grow over time) and skim the refreshed
+guides for the app's feature areas. Compare against what the app actually does:
+
+- Where a new platform capability clearly replaces app-level code (less code, same
+  behavior), adopt it as part of the upgrade.
+- Where a capability opens something new but needs a product decision, don't build it —
+  report it as a suggestion with a pointer to the relevant guide section.
+
+### 8. Verify and stamp
+
+Run the app's tests, apply the Step 4 post-code review to everything modified, and
+update the feedback doc's upgrade stamp (date, channel, versions, and the template
+commit synced in Step 6).
+
+### The platform feedback doc
+
+Convention: a `PRIMITIVE-FEEDBACK.md` at the app root tracks the app's relationship to the
+platform — when it was last upgraded, and which workarounds exist for platform issues.
+This is what makes upgrades mechanical instead of archaeological. If the app doesn't
+have one, create it during the first upgrade:
+
+```markdown
+# Platform Feedback
+
+## Upgrade stamp
+- Last upgraded: 2026-07-21
+- Channel: production
+- Versions: js-bao-wss-client 2.0.6, primitive-app 3.0.5, js-bao 0.5.1, primitive-admin 1.0.55
+- Template: primitive-vue-template @ main 0f1c2d3
+
+## Open items
+- [#1234] Symptom or missing capability. Workaround: `src/lib/foo.ts:42` (retry loop).
+
+## Resolved
+- [#1101] Symptom. Workaround removed 2026-07-21.
+```
+
+Issue numbers refer to platform issues where known (Primitive-Labs members); items
+without an issue number are fine — the doc is useful even when the issue tracker isn't
+accessible.
+
+## Filing Platform Issues
+
+Sometimes the problem is in the platform itself — a bug in js-bao, the client library,
+the CLI, or a capability the platform doesn't have — rather than in the user's app.
+Platform work is tracked as GitHub issues on `Primitive-Labs/js-bao-wss`.
+
+**Gate: only suggest filing an issue if the signed-in GitHub user is a member of the
+Primitive-Labs org.** Check silently before ever raising the option:
+
+```bash
+gh api user/memberships/orgs/Primitive-Labs --jq .state 2>/dev/null
+```
+
+If this doesn't print `active` (not a member, or `gh` is missing or unauthenticated),
+don't mention filing an issue at all — help the user work around the problem instead.
+
+### Tracker hygiene (issues and comments alike)
+
+Everything you write to the tracker — new issues and follow-up comments on existing
+ones — is read by an agent pipeline and by maintainers who have none of your session's
+context. What you write is all they get, and investigating is the assignee's job —
+yours is to state the problem clearly.
+
+- **Brevity and clarity win over verbosity.** Keep the prose to 1000 characters or
+  less. Fenced code blocks (repro commands, config, verbatim error output) don't count
+  toward the cap — precision there is what makes an issue reproducible. If the prose
+  doesn't fit, you're including solution detail or context the assignee can rediscover.
+- **Self-contained.** Assume the reader knows nothing about the user's app and has no
+  internal knowledge of the platform. Reference related issues by number, but inline
+  whatever context is needed to read the issue standalone.
+- **Describe the problem, not the solution.** Don't prescribe the fix or assume a
+  particular implementation.
+- **Don't relitigate decisions rejected in earlier issues** — carry forward the
+  discovered tradeoffs, stated neutrally.
+
+### Bugs (an existing platform feature not working as designed)
+
+Body template — fill each section with as much precision as possible, so the issue is
+easy to reproduce on the first try:
+
+```
+## Repro steps
+<numbered, precise, minimal: exact API calls, config, versions. The test:
+someone with no context reproduces it on the first try>
+
+## Observed behavior
+<what actually happens, with verbatim error text / response bodies in fenced
+blocks>
+
+## Expected behavior
+<what should happen instead, stated as an observable outcome — this is what
+"fixed" means, and what a fix will be tested against>
+
+## Design review needed?
+<tick any that apply; leave all unticked if the fix looks self-contained>
+
+- [ ] Involves a critical security decision (auth, permissions, CEL, secrets, webhook
+      verification, DO routing)
+- [ ] Risks a performance regression on a per-request, per-message or per-connection path
+- [ ] Requires a data model or index change (`models.yaml`)
+- [ ] Breaks an existing API contract (removes or retypes something in `openapi.json`, or
+      changes a `src/client` public signature non-additively)
+```
+
+Write "Expected behavior" as the acceptance criterion: the observable outcome that
+defines the bug as fixed. If prior investigation exists (an earlier thread, a
+session's debugging), link it — don't inline a root-cause theory as fact.
+
+The "Design review needed?" checkboxes decide the bug's route: any tick sends it
+through the design gate; all unticked sends it straight to implementation, with
+"Expected behavior" as the acceptance criteria. When unsure, leave a box unticked —
+the worker re-checks against its own diff and routes itself back if one applies.
+
+Labels: `type:bug` only.
+
+### Features / enhancements / platform extensions
+
+```
+## Problem
+<the application-level problem being solved, and who hits it — a concrete
+scenario, not an abstraction, and not a solution>
+
+## What I tried
+<existing platform features attempted, and why each falls short — omit if none apply>
+
+## What a solution needs to enable
+<the outcomes a solution must make possible, as bullets — capabilities from
+the consumer's perspective, not designs>
+```
+
+Keep "What a solution needs to enable" outcome-shaped: "an app can resume a follow
+from the last event it saw across restarts" — not "add a `resumeAfter` token to the
+list endpoint". If you have a design idea worth preserving, put it in a comment,
+clearly labeled as an idea — never in the body.
+
+Labels: `type:feature` only.
+
+### Filing
+
+Use only `type:bug` or `type:feature` (e.g. file performance problems as `type:bug`
+with measurements in the repro steps). Search open issues for duplicates first:
+
+```bash
+gh issue list --repo Primitive-Labs/js-bao-wss --search "<keywords>" --state open \
+  --json number,title
+```
+
+Then create the issue with exactly one `type:*` label and nothing else — **no
+assignee** (triage assigns sponsors; unassigned is the correct starting state), no
+priority labels, no `state:*` label, and no `dispatch-v3` (state and dispatch labels
+are added together by triage once it judges the filing complete — never by the
+filer; an issue waiting for triage is the correct starting state):
+
+```bash
+gh issue create --repo Primitive-Labs/js-bao-wss \
+  --title "<one-line symptom or need>" \
+  --label "type:bug" \
+  --body "<template body>"
+```
+
+The templates above mirror the canonical ones in the js-bao-wss repo at
+`.claude/skills/_shared/templates/` (`bug-filing.md`, `feature-filing.md`,
+`docs-filing.md`), which the pipeline validates against with
+`.claude/skills/_shared/check-filing.sh` before an issue can be picked up — a body
+missing a required section stalls in triage until a human repairs it. If the
+templates here and the repo's ever disagree, the repo's win. When working inside a
+js-bao-wss checkout, don't file by hand at all: use that repo's `/file-issue` skill,
+which interviews for the sections, validates the draft offline, and files with the
+right labels.
+
+### Follow-up comments on existing issues
+
+When the duplicate search finds an issue that already covers the problem, comment
+there instead of filing. A comment is a **delta on the thread, not a fresh report** —
+the hygiene rules above (1000-character prose cap, fenced blocks exempt, problem not
+solution, self-contained) apply to it unchanged, plus:
+
+- **Lead with what's new**: a repro, a counterexample, a version/deployment where the
+  behavior changed, a confirmation that it no longer reproduces. Don't restate what
+  the thread already establishes — reference it.
+- **Evidence goes in fenced blocks**, exactly as in an issue body: numbered repro
+  steps, exact commands and API calls, verbatim errors, versions and app/resource
+  ids. Prose interprets the evidence; it must not be the container for it.
+- **One comment, one issue's scope.** Evidence that implicates a *different* issue
+  belongs in a separate comment on that issue, cross-referenced by number — not
+  folded into this one.
+- **State facts; leave triage to the maintainers.** Stage, priority, closure, and
+  duplicate-of verdicts are theirs. If the evidence points at a next step (re-test
+  after X lands, likely duplicate of #N), one closing sentence may say so — never
+  more.
+
+### Record the issue in the app
+
+After filing, add an entry to the app's `PRIMITIVE-FEEDBACK.md` (see "The platform feedback doc"
+above) under **Open items**: the issue number, a one-line symptom, and — if you built a
+workaround in the app — where it lives (`file:line`). This is what lets a future upgrade
+find and remove the workaround once the platform fix ships. If a workaround is added
+later for an already-filed issue, update the entry then.