primitive-admin 1.1.0-alpha.83 → 1.1.0-alpha.85

package/README.md

@@ -657,6 +657,7 @@ allowedPaths = ["/weather", "/forecast"]
 
 ```toml
 [prompt]
+kind = "chat"
 key = "summarizer"
 displayName = "Text Summarizer"
 description = "Summarizes input text"
@@ -665,6 +666,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."
@@ -674,6 +677,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."
@@ -689,9 +694,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`: