primitive-admin 1.0.63 → 1.0.64

package/README.md

@@ -59,10 +59,7 @@ The globally linked `primitive` command uses the compiled files in `cli/dist/`,
 # Login via browser OAuth
 primitive login
 
-# Set your working app context
-primitive use "My App"
-
-# List users in the current app
+# List users in the app this project's environment names
 primitive users list
 
 # View help for any command
@@ -75,14 +72,14 @@ primitive apps --help
 The CLI uses browser-based OAuth for authentication. When you run `primitive login`, it opens your browser to authenticate via Google OAuth and stores credentials locally.
 
 ```bash
-# Login to the environment resolved from .primitive/config.json
-# (project mode), or the default/PRIMITIVE_SERVER_URL server (legacy mode)
+# Login to the environment resolved from the project config, or — outside a
+# project — to the default/PRIMITIVE_SERVER_URL server
 primitive login
 
 # Login to a specific named environment
 primitive -e prod login
 
-# Login to a custom server without a project config (legacy mode)
+# Login to a custom server from outside a project
 PRIMITIVE_SERVER_URL=https://api.example.com primitive login
 
 # View current session
@@ -95,39 +92,50 @@ primitive token
 primitive logout
 ```
 
-Credentials are stored in `~/.primitive/credentials.json` with mode 0600.
+Inside a project, credentials are stored per environment in the gitignored
+`<projectRoot>/.primitive/credentials.json`; a `login` run outside a project
+writes `~/.primitive/credentials.json`. Both are mode 0600. Only `login`,
+`logout`, `bootstrap` and `init` work outside a project — every other command
+stops with an error naming the missing `primitive/config.json`, rather than
+reading the global file (see [Outside a project](#outside-a-project)).
 
 ## App Context
 
-Most commands require an app ID. You can specify it in two ways:
+Every environment names exactly one app, via `"appId"` in
+`primitive/config.json`. Selecting an environment selects its app, so most
+commands need no app argument at all — and there is no separate, per-machine
+"current app" that could point somewhere else.
 
-1. **Flag**: `primitive users list --app 01HXYZ...`
-2. **Context**: Set once with `primitive use`, then omit from commands
+```bash
+# The app the selected environment names
+primitive whoami
+primitive env show
+
+# Point an environment at a different app: edit its "appId" in
+# primitive/config.json.
+```
 
-Commands that only need an app ID (like `list`) also accept it as a positional argument:
+Commands that read across apps still take an explicit one. Those that only need
+an app ID (like `list`) accept it as a positional argument:
 ```bash
 primitive users list 01HXYZ...
 ```
 
-Commands with other required arguments use only `--app` for the app ID:
+Commands with other required arguments use `--app`:
 ```bash
 primitive workflows get <workflow-id> --app 01HXYZ...
 ```
 
-```bash
-# Interactive app selection
-primitive use
-
-# Set by name or ID
-primitive use "My App"
-primitive use 01HXYZ...
+### Outside a project
 
-# View current context
-primitive context
-
-# Clear context
-primitive context clear
-```
+With no project config up the directory tree there is no environment, so there
+is nothing for an app-scoped command to target. Only `login`, `logout`,
+`bootstrap` and `init` work there; everything else (`whoami`, `apps list`,
+`env add`, `config pull`, …) exits non-zero with an error that names the
+missing `primitive/config.json` and points at `primitive init`. The CLI never
+falls back to `~/.primitive/credentials.json` for those commands, and no flag
+redirects a command at another project's tree — run it from inside the project
+whose environment names the app.
 
 ## Commands
 
@@ -459,6 +467,40 @@ primitive documents import [app-id] <path> --overwrite --aliases overwrite|skip
 
 Export creates a directory per document with `metadata.json`, `document.yjs` (Yjs state), `permissions.json` (for reference), and `blobs/` (attachments). Permissions are exported for reference but not restored during import — the importing admin is the new owner and manages sharing in the target app. Document IDs are preserved across import. User-scoped aliases can be restored with `--aliases overwrite` (update existing) or `--aliases skip` (keep existing, default).
 
+### Collections
+
+Group documents into a named set and share the whole set at once.
+
+```bash
+primitive collections list [app-id] --all                 # --all: every collection (admin)
+primitive collections create <name> --description <text>  # --owner <userId-or-email> (admin)
+primitive collections get <collection-id>
+primitive collections update <collection-id> --name <name>
+primitive collections delete <collection-id>              # documents are preserved
+primitive collections access <collection-id>              # groups + members in one view
+primitive collections for-document <document-id>
+```
+
+**Documents, members and group grants:**
+```bash
+primitive collections documents list|add|remove <collection-id> [document-id]
+primitive collections members list|add|remove <collection-id> [user-id] --permission reader
+primitive collections share <collection-id> --group <type>/<id> --permission read-write
+primitive collections unshare <collection-id> --group <type>/<id>
+```
+
+**Export / Import:**
+```bash
+primitive collections export --output <dir>               # writes <dir>/collections.json
+primitive collections import <path> --dry-run             # plan and problems, writes nothing
+primitive collections import <path> --overwrite           # merge into an existing same-named collection
+primitive collections import <path> --owner <userId-or-email>  # one owner for every collection
+```
+
+`collections export` writes `collections.json` beside the `manifest.json` and `documents/` directory a document export leaves there, so one directory is one app's migration: per collection its name, description, type, context id, owner, group grants, direct members with their level, and which documents it holds. Run `documents import` **before** `collections import` — the file refers to documents by the ids that import preserves.
+
+Both verbs are for admin tokens. Owners and members are recorded as emails, because app users are scoped to their app and a source app's user id means nothing in the target. The import reads before it writes: it resolves every owner, member, document and group, plans `create`/`merge`/`skip`/`refused` per collection, then applies group grants, members and documents in that order. Matching is by name; `--overwrite` merges only into a collection whose owner, type and context id match, since none of those can change after creation. A group grant the target holds at another level is updated to the level the file records, and effective access follows it — except above 200 documents, where the server refuses a collection-wide group change whole (`COLLECTION_FANOUT_LIMIT`) and the import reports it as a `group` problem. Per-item problems go to stderr and to `--json.problems`; the exit code is 1 when any was reported. Collection ids are not preserved, and the groups themselves, collection resource metadata and pending member invitations do not travel.
+
 ### Groups
 
 Manage groups, members, and memberships.
@@ -565,14 +607,17 @@ primitive catalog integrations delete <catalog-id>
 Author app configuration as TOML files and reconcile them with the server.
 
 ```bash
-primitive config init [app-id] --dir ./config    # Initialize config directory
-primitive config pull [app-id] --dir ./config    # Pull remote config to local
-primitive config push [app-id] --dir ./config    # Push local config to remote
-primitive config diff [app-id] --dir ./config    # Show differences
+primitive config init    # Scaffold the environment's config directory
+primitive config pull    # Pull remote config into it
+primitive config push    # Push it to the server
+primitive config diff    # Show differences
 ```
 
+The directory is the selected environment's committed tree,
+`primitive/<env>/`, and there is no flag that relocates it or points it at
+another app: select a different environment with `--env <name>` (#3154).
+
 **Options:**
-- `--dir <path>` - Config directory (default: ./config)
 - `--dry-run` - Show changes without applying (push only)
 - `--force` - Overwrite remote changes (push only)
 
@@ -581,8 +626,8 @@ primitive config diff [app-id] --dir ./config    # Show differences
 The sync commands use TOML files for configuration. Here's the directory structure:
 
 ```
-config/
-  .primitive-sync.json     # Sync state (auto-generated)
+primitive/<env>/
+  .sync-state.json         # Sync state (auto-generated, committed)
   app.toml                 # App settings
   integrations/
     weather-api.toml       # Integration configs
@@ -646,6 +691,7 @@ allowedPaths = ["/weather", "/forecast"]
 
 ```toml
 [prompt]
+kind = "chat"
 key = "summarizer"
 displayName = "Text Summarizer"
 description = "Summarizes input text"
@@ -654,6 +700,8 @@ description = "Summarizes input text"
 name = "default"
 provider = "openrouter"
 model = "google/gemini-2.0-flash-001"
+
+[configs.chat]
 temperature = "0.7"
 maxTokens = 500
 systemPrompt = "You are a helpful assistant."
@@ -663,6 +711,8 @@ userPromptTemplate = "Summarize: {{ input.text }}"
 name = "concise"
 provider = "openrouter"
 model = "google/gemini-2.0-flash-001"
+
+[configs.chat]
 temperature = "0.3"
 maxTokens = 200
 systemPrompt = "You create very brief summaries."
@@ -678,9 +728,46 @@ All list/get commands support `--json` for machine-readable output:
 primitive apps list
 
 # JSON output for scripting
-primitive apps list --json | jq '.[0].appId'
+primitive apps list --json | jq '.items[0].id'
+```
+
+### The list envelope
+
+**Every** `<noun> list --json` prints the same object — no exceptions, and
+never a bare array. It is `{ items, hasMore, nextCursor? }`, the envelope
+#2357 named, and #3646 made universal:
+
+```jsonc
+{
+  "items": [ /* the rows */ ],
+  "hasMore": false,          // is there another page?
+  "nextCursor": "01HXY..."   // present only when hasMore is true
+}
+```
+
+So `jq '.items[]'` works against any noun, and a script never has to know which
+one it asked about. A `list` whose subject carries context that is not a row —
+`env list`'s current selection, `guides list`'s resolved docs version — prints
+those as extra keys beside these three; the three always mean the same thing.
+
+Pagination follows the **route**, not the verb:
+
+- A `list` backed by a paged server route carries `--limit <n>` and
+  `--cursor <cursor>`, prints exactly one page, and reports that page's
+  `hasMore`/`nextCursor`. It never walks the chain for you.
+- A `list` backed by a route that does not paginate carries neither flag and
+  prints the whole set as `{ "items": [...], "hasMore": false }`.
+
+```bash
+# One page, then the next
+primitive users list --json --limit 50
+primitive users list --json --limit 50 --cursor "$(primitive users list --json --limit 50 | jq -r .nextCursor)"
 ```
 
+`primitive help --json` reports which flags a given `list` carries. The rules
+themselves, and the guard that enforces them across the whole command manifest,
+are in [`docs/cli-design.md`](../docs/cli-design.md).
+
 ### Stdout vs. stderr
 
 The CLI follows the same convention as `git`, `kubectl`, `aws`, and `gh`:
@@ -745,8 +832,8 @@ Shape (`schemaVersion: 1`):
           "name": "push",
           "description": "…",
           "aliases": [],
-          "args": [ { "name": "app-id", "required": false, "variadic": false, "description": "…" } ],
-          "options": [ { "flags": "--dir <path>", "description": "…", "required": true, "defaultValue": null, "hidden": false } ],
+          "args": [],
+          "options": [ { "flags": "--dry-run", "description": "…", "required": false, "defaultValue": null, "hidden": false } ],
           "commands": []
         }
       ]
@@ -816,17 +903,17 @@ Internal helpers (`collectParamRefs`, `declaredParamNames`,
 
 ## Environment Variables
 
-- `PRIMITIVE_SERVER_URL` - Server URL for login in legacy mode (defaults to `https://primitiveapi.com`)
+- `PRIMITIVE_SERVER_URL` - Server URL for `login` outside a project (defaults to `https://primitiveapi.com`)
 
 **Login server resolution:**
-1. Project mode (`.primitive/config.json` present): the active environment's
+1. Project mode (`primitive/config.json` present): the active environment's
    `apiUrl`. Select the environment with `-e <name>`, `PRIMITIVE_ENV`,
    `primitive env use <name>` (this machine's selection, stored in the
    gitignored `.primitive/local.json`), or the committed `defaultEnvironment`
    — in that order. An unresolvable environment fails loudly — `login`
    never silently falls back to production.
-2. Legacy mode (no project config): `PRIMITIVE_SERVER_URL`, else the default
-   `https://primitiveapi.com`.
+2. Outside a project (no project config): `PRIMITIVE_SERVER_URL`, else the
+   default `https://primitiveapi.com`.
 
 > `login` no longer accepts `-s/--server` (removed in a breaking change). Use
 > `-e <env>` in a project, or `PRIMITIVE_SERVER_URL` for local dev / scripts.
@@ -907,8 +994,11 @@ cli/tests/
 ### "Not logged in" error
 Run `primitive login` to authenticate.
 
-### "No app specified" error
-Either pass an app ID as an argument, use `--app <id>`, or set context with `primitive use`.
+### "No primitive/config.json found" error
+The command ran outside a Primitive project. Every app-scoped command reads its
+server, app and configuration tree from the project's environment, so `cd` into
+the project (any subdirectory works) or create one with `primitive init`. There
+is no global fallback and no flag that points the command elsewhere.
 
 ### Token expired
 The CLI automatically refreshes tokens. If issues persist, try `primitive logout` then `primitive login`.