primethink-cli 1.5.0__tar.gz → 1.7.0__tar.gz

{primethink_cli-1.5.0/primethink_cli.egg-info → primethink_cli-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: primethink-cli
-Version: 1.5.0
+Version: 1.7.0
 Summary: PrimeThink CLI - A powerful tool for interacting with PrimeThink AI API
 Author-email: PrimeThink <support@primethink.ai>
 License-Expression: MIT
@@ -26,6 +26,7 @@ Requires-Dist: click>=8.0.0
 Requires-Dist: requests>=2.25.0
 Provides-Extra: mcp
 Requires-Dist: mcp<2,>=1.2.0; extra == "mcp"
+Requires-Dist: pydantic>=2.0; extra == "mcp"
 Provides-Extra: agent-tools
 Requires-Dist: langchain-core>=0.3.0; extra == "agent-tools"
 Requires-Dist: pydantic>=2.0; extra == "agent-tools"
@@ -104,7 +105,7 @@ pt chat send --agent AGENT_ID --message "your message"
 | `pt chat sync-from` | Sync a chat's files to a local directory |
 | `pt chat sync` | Two-way sync between a chat folder and a local directory |
 | `pt chatdb init` | Initialize a chat's ChatDB (Live App data) store |
-| `pt chatdb list` | List entities in a chat's ChatDB store |
+| `pt chatdb list` | List entities in a chat's ChatDB store (or an attached DB Collection via `--collection`/`--collection-id`) |
 | `pt chatdb get` | Get one ChatDB entity by ID |
 | `pt chatdb add` | Add one or more rows to a ChatDB entity |
 | `pt chatdb update` | Update ChatDB entities (single or bulk) |
@@ -146,6 +147,10 @@ pt chat send --agent AGENT_ID --message "your message"
 | `pt workspace list` / `create` / `rename` / `set-goal` / `delete` | Manage chat workspaces |
 | `pt workspace archive` / `pin` / `add-chat` / `remove-chat` | Organize chats within workspaces |
 | `pt tag list` / `create` / `assign` | List, create, and assign tags (task/agent/capability/collection) |
+| `pt suite build` / `validate` / `inspect` | Build, check and describe a `.ptsuite` package (apps, tasks, agents, collections, tags, workspace) |
+| `pt suite install` / `uninstall` | Plan (`--dry-run`) and install/upgrade a package idempotently from a file, folder, GitHub or the catalog; remove what it created |
+| `pt suite export` | Turn live tasks and Live Apps (with their agents and collections) into a package folder |
+| `pt suite catalog build` / `list` / `search` | Index a folder/GitHub repo of packages and browse it |
 | `pt group list` / `get` / `create` / `update` / `delete` | Manage groups (organizations) |
 | `pt group members` / `remove-member` / `invite` / `add-agent` | Manage group members, invites, and agents |
 | `pt settings list` / `get` / `set` / `delete` | Manage group/user settings and provider API keys (secrets never shown) |

{primethink_cli-1.5.0 → primethink_cli-1.7.0}/README.md

@@ -65,7 +65,7 @@ pt chat send --agent AGENT_ID --message "your message"
 | `pt chat sync-from` | Sync a chat's files to a local directory |
 | `pt chat sync` | Two-way sync between a chat folder and a local directory |
 | `pt chatdb init` | Initialize a chat's ChatDB (Live App data) store |
-| `pt chatdb list` | List entities in a chat's ChatDB store |
+| `pt chatdb list` | List entities in a chat's ChatDB store (or an attached DB Collection via `--collection`/`--collection-id`) |
 | `pt chatdb get` | Get one ChatDB entity by ID |
 | `pt chatdb add` | Add one or more rows to a ChatDB entity |
 | `pt chatdb update` | Update ChatDB entities (single or bulk) |
@@ -107,6 +107,10 @@ pt chat send --agent AGENT_ID --message "your message"
 | `pt workspace list` / `create` / `rename` / `set-goal` / `delete` | Manage chat workspaces |
 | `pt workspace archive` / `pin` / `add-chat` / `remove-chat` | Organize chats within workspaces |
 | `pt tag list` / `create` / `assign` | List, create, and assign tags (task/agent/capability/collection) |
+| `pt suite build` / `validate` / `inspect` | Build, check and describe a `.ptsuite` package (apps, tasks, agents, collections, tags, workspace) |
+| `pt suite install` / `uninstall` | Plan (`--dry-run`) and install/upgrade a package idempotently from a file, folder, GitHub or the catalog; remove what it created |
+| `pt suite export` | Turn live tasks and Live Apps (with their agents and collections) into a package folder |
+| `pt suite catalog build` / `list` / `search` | Index a folder/GitHub repo of packages and browse it |
 | `pt group list` / `get` / `create` / `update` / `delete` | Manage groups (organizations) |
 | `pt group members` / `remove-member` / `invite` / `add-agent` | Manage group members, invites, and agents |
 | `pt settings list` / `get` / `set` / `delete` | Manage group/user settings and provider API keys (secrets never shown) |

{primethink_cli-1.5.0 → primethink_cli-1.7.0}/SPECS.md

@@ -66,13 +66,13 @@ To obtain an API key, go to `Settings > API Keys` in the PrimeThink app and gene
 | `pt scheduled-job delete` | `DELETE /api/v1/scheduled_jobs/scheduled_job_in_chat/{job_id}` |
 | document download (used by `download-file` and `sync-from`) | `GET /api/v1/documents/{document_id}/download` |
 | `pt chatdb init` | `POST /api/v1/chats/{chat_id}/chatdb/init` |
-| `pt chatdb list` | `POST /api/v1/chats/{chat_id}/chatdb/list` |
-| `pt chatdb get` | `GET /api/v1/chats/{chat_id}/chatdb/entities/{entity_id}` |
-| `pt chatdb add` | `POST /api/v1/chats/{chat_id}/chatdb/entities` |
-| `pt chatdb update` | `PATCH /api/v1/chats/{chat_id}/chatdb/entities` |
-| `pt chatdb delete` | `DELETE /api/v1/chats/{chat_id}/chatdb/entities` |
+| `pt chatdb list` | `POST /api/v1/chats/{chat_id}/chatdb/list` (body may add `collection_name`/`collection_id`) |
+| `pt chatdb get` | `GET /api/v1/chats/{chat_id}/chatdb/entities/{entity_id}` (query: `collection_name`, `collection_id`) |
+| `pt chatdb add` | `POST /api/v1/chats/{chat_id}/chatdb/entities` (body may add `collection_name`/`collection_id`) |
+| `pt chatdb update` | `PATCH /api/v1/chats/{chat_id}/chatdb/entities` (body may add `collection_name`/`collection_id`) |
+| `pt chatdb delete` | `DELETE /api/v1/chats/{chat_id}/chatdb/entities` (body may add `collection_name`/`collection_id`) |
 | `pt collection list` | `GET /api/v1/collections` |
-| `pt collection create` | `POST /api/v1/collections` (params: `name`, `description`, `type`, `public`) |
+| `pt collection create` | `POST /api/v1/collections` (params: `name`, `description`, `type` = `collection`/`skill`/`external_source`/`db`, `public`) |
 | `pt collection get` | `GET /api/v1/collections/{collection_id}` |
 | `pt collection update` | `PATCH /api/v1/collections/{collection_id}` |
 | `pt collection reindex` | `POST /api/v1/collections/{collection_id}/reindex` |
@@ -101,7 +101,6 @@ To obtain an API key, go to `Settings > API Keys` in the PrimeThink app and gene
 | `pt capability delete` | `DELETE /api/v1/virtual-assistants/capabilities/{capability_id}` |
 | `pt capability archive` / `unarchive` | `PUT /api/v1/virtual-assistants/capabilities/{capability_id}/archived?archived=true\|false` |
 | `pt capability duplicate` | `POST /api/v1/virtual-assistants/capabilities/{capability_id}/duplicate` |
-| `pt capability resolve` | resolves capability codes/ids to ids via `GET /api/v1/virtual-assistants/capabilities` |
 | `pt models list` | `GET /api/v1/catalog/llm/models` |
 | `pt models embeddings` | `GET /api/v1/catalog/embeddings/models` |
 | `pt task list` | `GET /api/v1/tasks/` |
@@ -147,6 +146,12 @@ To obtain an API key, go to `Settings > API Keys` in the PrimeThink app and gene
 | `pt tag list` | `GET /api/v1/tags?model=` |
 | `pt tag create` | `POST /api/v1/tags` (`{model, name, tag_category}`) |
 | `pt tag assign` | `PUT /api/v1/tags/assignments` (`{model, owner_id, tag_ids}`) |
+| `pt capability resolve` / `pt agent create --capability` | `GET /api/v1/virtual-assistants/capabilities?page=N&page_size=100` — every page (the endpoint returns only 10 without page parameters) |
+| `pt suite build` / `validate` / `inspect` / `catalog build` | local only (no API) |
+| `pt suite install SOURCE` | reads: `GET /api/v1/virtual-assistants/capabilities` (all pages), `…/virtual-assistants/types`, `/groups/current/settings`, `/users/me/settings`, `/tags?model=`, `/virtual-assistants?search=`, `/collections?search=`, `/tasks/?search=&status=all`, `/chat-workspaces`, `/memories?workspace_id=`, `/chats?search=`, `/chats/{id}/collections`, `/chats/{id}/users`, `/users/me/visible-users`, `/scheduled_jobs/scheduled_jobs_in_chat/{chat}`, `POST /chats/{id}/chatdb/list`; writes (not in `--dry-run`): `POST /tags`, `PUT /tags/assignments`, `POST/PATCH /virtual-assistants/capabilities[/{id}]`, `POST /virtual-assistants`, `PATCH /virtual-assistants/{id}`, `POST /virtual-assistants/{id}/collections/attach`, `POST /collections?name=&type=`, `POST /collections/{id}/documents`, `POST /tasks/`, `PATCH /tasks/{id}`, `POST /tasks/{id}/image`, the `@app` sync of `pt live-app publish`, `POST /tasks/{id}/versions`, `POST /tasks/{id}/collections-files`, `POST /chat-workspaces`, `PUT /chat-workspaces/{id}/goal`, `POST /memories?workspace_id=`, `POST /chats?copy_from_task_id=`, `POST /chats/{id}/collections/{cid}`, `DELETE /chats/{id}/collections`, `POST /chats/{id}/members`, `POST /chats/{id}/chatdb/entities`, `POST/PUT /scheduled_jobs/scheduled_job_in_chat[/{id}]` |
+| `pt suite uninstall ID` | `DELETE /scheduled_jobs/scheduled_job_in_chat/{id}`, `DELETE /tasks/{id}`, `DELETE /virtual-assistants/{id}`, `DELETE /virtual-assistants/capabilities/{id}`; with flags `DELETE /collections/{id}`, `DELETE /chats/{id}` |
+| `pt suite export` | `GET /tasks/{id}`, `GET /virtual-assistants/{id}`, `GET /virtual-assistants/types`, `GET /collections/{id}`, `GET /tasks/{id}/directories?path=/app`, `GET /documents/{id}/download` |
+| `pt suite … github:owner/repo[@ref]` | `GET https://codeload.github.com/{owner}/{repo}/zip/{ref}`, or with `GITHUB_TOKEN` `GET https://api.github.com/repos/{owner}/{repo}/zipball/{ref}` |
 | `pt group list` | `GET /api/v1/groups/` |
 | `pt group get` | `GET /api/v1/groups/{group_id}` |
 | `pt group create` | `POST /api/v1/groups/` |

{primethink_cli-1.5.0 → primethink_cli-1.7.0}/USER_GUIDE.md

@@ -22,11 +22,12 @@ For a terse, complete listing of every command and option, see the [CLI Referenc
 14. [Finding Users](#finding-users)
 15. [Notifications](#notifications)
 16. [Scaffolding Live Apps](#scaffolding-live-apps)
-17. [MCP Server](#mcp-server)
-18. [Common Use Cases](#common-use-cases)
-19. [Tips and Tricks](#tips-and-tricks)
-20. [Troubleshooting](#troubleshooting)
-21. [FAQ](#faq)
+17. [Suite Packages](#suite-packages)
+18. [MCP Server](#mcp-server)
+19. [Common Use Cases](#common-use-cases)
+20. [Tips and Tricks](#tips-and-tricks)
+21. [Troubleshooting](#troubleshooting)
+22. [FAQ](#faq)
 
 ## Introduction
 
@@ -77,7 +78,7 @@ pt version
 
 You should see output like:
 ```
-PrimeThink CLI v1.5.0
+PrimeThink CLI v1.7.0
 ```
 
 ## Getting Started
@@ -713,6 +714,19 @@ pt chatdb delete 123 --entity-id 7          # asks for confirmation; --yes to sk
 
 `--data` takes a single JSON object; `--items` takes a JSON array for bulk operations. On update, `--merge` patches the existing row while `--replace` overwrites it, and `--if-unchanged-since TIMESTAMP` guards against overwriting a row that changed underneath you.
 
+### DB Collections
+
+A **DB Collection** is a collection of type `db` that holds the same kind of entities, but can be shared between chats. Once one is attached to a chat, `list`, `get`, `add`, `update` and `delete` can target it instead of the chat's own ChatDB, by name or by ID:
+
+```bash
+pt collection create --name project-db --type db     # note the id, e.g. 42
+# attach it to the chat in the web app, then:
+pt chatdb add 123 --entity tasks --data '{"title": "a"}' --collection project-db
+pt chatdb list 123 --entity tasks --collection-id 42
+```
+
+Prefer `--collection-id` when two attached DB Collections share a name, or in scripts that should survive a rename. If you pass both, they must identify the same collection. A collection attached read-only accepts `list`/`get` but rejects writes. This mirrors `pt.db('project-db')` / `pt.db(42)` in a Live App.
+
 > Building the Live App itself (the front-end that uses this data) is covered by the **primethink-developer** skill; `pt chatdb` is the deterministic data plane underneath it.
 
 ## Semantic Search
@@ -1144,10 +1158,10 @@ pt eval delete 99 EVAL_ID
 ### 2. Configure how evaluations run
 
 ```bash
-pt eval settings 99 --active --run-time daily --evaluator-agent-id 7 --pass-threshold 0.8
+pt eval settings 99 --active --run-time daily --evaluator-agent-id 7 --pass-threshold 80
 ```
 
-`--run-time` is `manual`, `daily`, `weekly`, or `monthly`; `--pass-threshold` is the minimum score to count as a pass; `--message-delay-ms` throttles messages during a run.
+`--run-time` is `manual`, `daily`, `weekly`, or `monthly`; `--pass-threshold` is the minimum score to count as a pass, as a whole-number percentage from 1 to 100 (`80`, not `0.8`) — anything outside that range is rejected by the CLI before a request is made; `--message-delay-ms` throttles messages during a run.
 
 ### 3. Run it, then read the results
 
@@ -1270,8 +1284,8 @@ Defaults are `--framework react --tailwind --flowbite`. Flowbite depends on Tail
 After generation:
 
 1. Read the generated `README.md`; build and deployment steps differ by template.
-2. Rename the sample Chat DB entity so it is unique to your app.
-3. Replace the sample CRUD interface while retaining the PrimeThink runtime, theme, persistence, and real-time patterns.
+2. Name every Chat DB entity for your app. The templates ship none, and a generic name such as `item` collides with a sibling app in the same chat.
+3. Build the interface on the blank starter, keeping the PrimeThink wiring it ships: the runtime, the host-theme bridge, and the deployment configuration.
 4. Build if required, then upload the files described by the template README.
 
 The default Flowbite React starter is a Vite project and requires a local `npm install` and build. The other default starters are no-build, one-file HTML applications. The CLI itself intentionally runs neither package installation nor generated code.
@@ -1325,6 +1339,82 @@ pt live-app test ./my-live-app --chat-id "$(cat ./my-live-app/.chat-id)"
 
 Automated UI testing of a Live App is not part of the CLI. It is a deterministic, plan-driven workflow provided by the `primethink-developer` skill (`pt install-developer-skill`): the skill captures the running app's accessibility snapshot, authors a reviewable `tests/test_plan.yaml`, runs it with a bundled Playwright runner without an LLM in the execution loop, reads the structured results, and heals failing selectors before re-running.
 
+## Suite Packages
+
+A **suite package** (`.ptsuite`) installs a complete working set in one step: Live Apps,
+tasks with their schedules, the agents they run on, DB and document collections, tags,
+and a workspace with its shared rules and the chats to open. It is a folder with a
+`manifest.json` — shipped as that folder, zipped as a `.ptsuite` file, or kept in a
+GitHub repository.
+
+### Look before you install
+
+```bash
+pt suite inspect ./primethink.gtm-1.0.0.ptsuite
+```
+
+`inspect` shows the name and description in your language, what the package needs
+(capabilities, agent types, a minimum CLI version, settings such as `SERPER_API_KEY`), its
+install parameters, and everything it contains.
+
+### Install
+
+Always plan first — a dry run only reads from PrimeThink:
+
+```bash
+pt suite install ./primethink.gtm-1.0.0.ptsuite --params gtm.params.json --model openai:gpt-5.4 --dry-run
+pt suite install ./primethink.gtm-1.0.0.ptsuite --params gtm.params.json --model openai:gpt-5.4 --yes
+```
+
+The plan lists every resource as *create*, *update* or *ok*. A **BLOCKED** line (a missing
+capability or required setting, a CLI too old) means nothing will be written; the message
+says how to fix it. `--model` is the model for agents the package does not pin
+(`pt models list --only-configured`).
+
+Parameters come from the package (`inspect` lists them), as a JSON file (`--params`) or one
+at a time (`--param key=value`, where the value may be JSON).
+
+### Upgrade and re-run
+
+Installing again is safe and is how you upgrade: the installer finds what it created
+(even from another machine), updates it in place and adds what is new. It never deletes a
+collection, never removes a capability from an agent, and never overwrites a reference
+row you have edited (seed rows are insert-only). After a daylight-saving change, run it
+again with `--reschedule` — PrimeThink stores schedules in UTC.
+
+### Sources and the catalog
+
+```bash
+pt suite install github:primethink-ai/primethink-catalog/suites/gtm@gtm@1.0.0
+pt suite catalog list --catalog github:primethink-ai/primethink-catalog
+pt suite catalog search "sales" --kind suite
+pt suite install gtm@1.0.0          # by name, through the catalog
+```
+
+For a private repository set `GITHUB_TOKEN`; it is sent only to GitHub.
+
+### Make your own
+
+```bash
+pt suite export --task-id 81 --task-id 82 -o ./my-suite --id acme.onboarding
+# add ./my-suite/icon.png (a PNG), review the files, then:
+pt suite build ./my-suite
+```
+
+`build` hashes every file into the manifest and zips it. `validate` refuses scripts,
+secrets, environment ids, and files that changed after the build. `pt suite catalog build
+DIR` indexes a folder of packages into `catalog.json`.
+
+### Remove
+
+```bash
+pt suite uninstall primethink.gtm --dry-run
+pt suite uninstall primethink.gtm --yes
+```
+
+Only what the install created is removed. Collections (your data) and chats stay unless
+you pass `--delete-data` / `--delete-chats`.
+
 ## MCP Server
 
 Core API management operations can also be exposed over the [Model Context

{primethink_cli-1.5.0 → primethink_cli-1.7.0}/docs/agent-tools.md

@@ -60,7 +60,7 @@ resolve on 3.8. The `dev` extra installs the plugin's test dependencies only on
 
 ```bash
 # In the API image (production): one pinned line in requirements.txt
-primethink-cli[agent-tools]==1.5.0
+primethink-cli[agent-tools]==1.7.0
 
 # From a checkout (dev): the dev extra already includes langchain-core
 pip install -e ".[dev]"

{primethink_cli-1.5.0 → primethink_cli-1.7.0}/docs/cli-reference.md

@@ -1,6 +1,6 @@
 # PrimeThink CLI — Command Reference
 
-Complete reference for every command in the PrimeThink CLI (`pt`), version 1.5.0.
+Complete reference for every command in the PrimeThink CLI (`pt`), version 1.7.0.
 
 Commands are organized into noun groups: `profile`, `live-app`, `chat`, `collection`, `agent`, `task`, `search`, and `image`.
 
@@ -17,6 +17,14 @@ Commands are organized into noun groups: `profile`, `live-app`, `chat`, `collect
   - [`pt live-app new`](#pt-live-app-new)
   - [`pt live-app publish`](#pt-live-app-publish)
   - [`pt live-app test`](#pt-live-app-test)
+- [Suite packages: `pt suite`](#suite-packages-pt-suite)
+  - [`pt suite build`](#pt-suite-build)
+  - [`pt suite validate`](#pt-suite-validate)
+  - [`pt suite inspect`](#pt-suite-inspect)
+  - [`pt suite install`](#pt-suite-install)
+  - [`pt suite uninstall`](#pt-suite-uninstall)
+  - [`pt suite export`](#pt-suite-export)
+  - [`pt suite catalog`](#pt-suite-catalog)
 - [Profiles: `pt profile`](#profiles-pt-profile)
   - [`pt profile add`](#pt-profile-add)
   - [`pt profile use`](#pt-profile-use)
@@ -221,7 +229,7 @@ Display the CLI version.
 
 ```bash
 pt version
-# PrimeThink CLI v1.5.0
+# PrimeThink CLI v1.7.0
 ```
 
 ### `pt whoami`
@@ -507,6 +515,181 @@ iterating on. The status check alone would miss a run that exits `0` without pri
 
 ---
 
+## Suite packages: `pt suite`
+
+A **suite package** bundles Live Apps, tasks, agents, custom capabilities, collections,
+tags and a workspace into one declarative package — a folder with `manifest.json` at its
+root, that folder zipped as a **`.ptsuite`** file, or the same folder in a GitHub
+repository. Resources reference each other by package **key**, never by id; the installer
+maps keys to ids in the target environment. Nothing in a package is executed on the
+installing machine. Design: `docs/superpowers/specs/2026-09-28-ptsuite-package-design.md`.
+
+```bash
+pt suite build DIR [-o FILE] [--no-zip]
+pt suite validate SOURCE [--catalog C]
+pt suite inspect SOURCE [--catalog C] [--json] [--help-text]
+pt suite install SOURCE [--params FILE] [--param k=v ...] [--dry-run] [--yes]
+                 [--agent-type NAME|ID] [--model M] [--reschedule] [--catalog C]
+pt suite uninstall SUITE_ID [--delete-data] [--delete-chats] [--dry-run] [--yes]
+pt suite export --task-id ID [--task-id ID ...] -o DIR [--id ID] [--version V]
+pt suite catalog build DIR [--refresh]
+pt suite catalog list [--catalog C] [--kind suite|app|task|agent] [--tag T] [--json]
+pt suite catalog search TEXT [--catalog C] [--kind K] [--json]
+```
+
+**`SOURCE`** is any of: a package folder; a `.ptsuite` file;
+`github:owner/repo[/path][@ref]` (the ref may itself contain `@`, e.g.
+`github:primethink-ai/primethink-catalog/suites/gtm@gtm@1.0.0`); or a catalog name
+`name[@version]`, resolved through `--catalog` / `$PT_CATALOG` / the default
+`github:primethink-ai/primethink-catalog`. Public repositories download from
+`codeload.github.com`. With `GITHUB_TOKEN` set, the download goes to `api.github.com`
+with the token, and GitHub's redirect to codeload drops it — the token is never sent
+anywhere else.
+
+### Package layout
+
+```
+manifest.json          format, kind (suite|app|task|agent), id, version (semver), name, description
+                       (a string or a language map with "en"), icon (PNG), help, help_url,
+                       languages, tags, requires {cli, capabilities, agent_types, models},
+                       prerequisites {settings[{name, scope, required, description}], permissions,
+                       notes}, params, contents[{path, sha256, bytes}]
+params.schema.json     install parameters (JSON Schema subset: type, properties, required, items,
+                       enum, pattern, minItems, default)
+tags.json              [{key, name, model: task|agent|capability|collection}]
+capabilities/<key>.json  custom api/mcp capabilities {name, code, type, access_type, options, …}
+agents/<key>.json      {name, public_description, description|description_file, type, model,
+                        access_type, capabilities: [code | "@capabilities/<key>"], collections, tags}
+collections/<key>.json {name, type: db|collection|skill|external_source, description, schema,
+                        seed {entity: file.jsonl}, files, for_each, attach_to, tags}
+apps/<key>/app.json    task fields + {agent, extra_agents, evaluator_agent, collections, tags,
+                        goal_file, initial_prompt_file, image, dist, schedule}
+apps/<key>/dist/…      the flat build uploaded to @app
+tasks/<key>/task.json  as app.json, without dist; schedule {nl, prompt_file|prompt, timezone}
+workspace.json         {name, goal|goal_file, memories|memories_file, chats[{key, app|task, name,
+                        for_each, in_workspace, collections, only_collections, invite}]}
+```
+
+- **Templates** — a collection or chat with `for_each: "<param>"` is expanded once per
+  item of that array parameter; `{field}` placeholders in `name`/`invite` come from the
+  item. `attach_to: ["apps/<key>", …]` attaches every instance to those apps/tasks.
+- **`invite`** — emails, `{field}` from the item, or `@params.<name>` (a list parameter).
+- **`only_collections: true`** on a chat detaches any collection not listed for it (an
+  introducer's Portal chat carries only its own collection).
+- `requires.models` is informational (not checked).
+
+### `pt suite build`
+
+Recomputes `manifest.contents` (SHA-256 and size of every file), validates, and writes a
+deterministic zip (sorted entries, fixed timestamps: the same folder always produces the
+same bytes). Final line: `Built FILE (N files, B bytes, sha256 …)`. `--no-zip` only
+refreshes contents and validates (`Valid: id version`).
+
+### `pt suite validate`
+
+Checks the manifest (format, kind, id, semver, name/description, the icon is a real PNG),
+every file against `contents` (no unlisted, missing or modified file), every reference
+(agents, collections, capabilities, tags, templates, chats), the apps' `dist` is flat with
+`index.html`, images match their extension, seed rows carry a unique `seed_key`, no
+environment ids (`virtual_assistant_id` …) appear, **no script or executable files**, and
+**no secret-shaped strings** (API keys, tokens, private keys). A prerequisite setting that
+carries a value is an error. Exit 1 on any error.
+
+### `pt suite inspect`
+
+Name, description, requirements, prerequisites, parameters and contents, in the user's
+language (`PT_LANG`, else `LANG`). `--json` prints the manifest (without `contents`), the
+resource list, the parameter schema, errors and warnings. `--help-text` prints the
+package's `HELP.md`.
+
+### `pt suite install`
+
+Plans first, then applies (after a confirmation, or with `--yes`). `--dry-run` prints the
+plan and sends **only reads** (GETs, plus `chatdb/list` to compare seed rows).
+
+1. **Prerequisites** — `requires.cli` (`>=X.Y.Z`), capability codes, agent types, and
+   required settings (checked by name at group/user scope; a missing one prints the exact
+   `pt settings set NAME <value> --scope group`). Any blocker stops the install before a write.
+2. **Tags** — created if missing, plus one `suite:<id>` tag per model used.
+3. **Capabilities** (custom) — created, or updated by code.
+4. **Agents** — found by provenance / name, else created with the type (`type`, else
+   `--agent-type`) and model (`model`, else `--model`). Capabilities are the **union** of
+   what the agent has and what the package wants: `PATCH` replaces the set, so the
+   installer never drops one.
+5. **Collections** — found by exact name (a different type is a blocker), else created;
+   `files` uploaded if missing.
+6. **Apps and tasks** — created or PATCHed with their fields; apps' `dist` synced into
+   `@app` (identical files are left unchanged) and a Production version created; the image
+   is uploaded on create.
+7. **Attachments** — collections on tasks (`POST /tasks/{id}/collections-files`) and RAG
+   collections on agents.
+8. **Workspace** — created or its goal updated; missing `workspace_constitution` memories added.
+9. **Chats** — each launched from its task (`POST /chats?copy_from_task_id=…`) into the
+   workspace unless `in_workspace: false`; collections attached; members invited (users
+   already in the chat are skipped).
+10. **Seed** — through the first chat that carries the collection. **Insert-only**: a row
+    whose `seed_key` exists is never updated or deleted.
+11. **Schedules** — a scheduled job in each chat of a task with a `schedule` (created, or
+    updated when its `nl` changed or with `--reschedule`, e.g. after a clock change).
+
+Every created task and agent records `extra.ptsuite = {id, version, key}`, and every
+resource gets the `suite:<id>` tag, so a re-install finds its resources **without** the
+local lock file (a Deep1 sandbox loses its files). The lock file
+`.ptsuite/<api host>/<id>.lock.json` (key → id, what this install created) is a cache and
+the input to `uninstall`. Final line:
+`Installed ID VERSION: N apps, N tasks, N agents, N collections, N chats`.
+
+### `pt suite uninstall`
+
+Removes what the install **created** (from its lock file): scheduled jobs, apps, tasks,
+agents and custom capabilities. Resources it found and updated are left alone.
+Collections stay unless `--delete-data` (their rows remain server-side), chats unless
+`--delete-chats`.
+
+### `pt suite export`
+
+Turns live tasks/Live Apps into a package folder: each task becomes `apps/<key>` (page type
+html; its `@app` files are downloaded into `dist/`) or `tasks/<key>`, its agents become
+`agents/<key>.json` (+ description), custom api/mcp capabilities become
+`capabilities/<key>.json` (review them for secrets), attached collections become
+descriptors (no rows or files), tags become `tags.json`. Ids become keys. Add `icon.png`,
+review, then `pt suite build`.
+
+### `pt suite catalog`
+
+A catalog is a folder or GitHub repo of packages with a generated `catalog.json`.
+`catalog build DIR` validates every package under DIR and writes the index (id, kind,
+version, path, name, description, icon, tags, languages, requires, counts, and the
+SHA-256 of each package's canonical zip — `install NAME` refuses a package that no longer
+matches it). `--refresh` recomputes each package's contents first. `list` and `search`
+read a catalog (every search word must match id, name, description or tags).
+Versions are git tags `<slug>@<version>`: `pt suite install gtm@1.2.0` fetches
+`github:<catalog>/<path>@gtm@1.2.0`.
+
+| Step | Endpoint |
+|---|---|
+| capabilities | `GET /api/v1/virtual-assistants/capabilities?page=&page_size=` (all pages), `POST`/`PATCH …/capabilities/{id}` |
+| agent types | `GET /api/v1/virtual-assistants/types` |
+| settings | `GET /api/v1/groups/current/settings`, `GET /api/v1/users/me/settings` |
+| tags | `GET /api/v1/tags?model=`, `POST /api/v1/tags`, `PUT /api/v1/tags/assignments` |
+| agents | `GET /api/v1/virtual-assistants?search=`, `GET/PATCH /api/v1/virtual-assistants/{id}`, `POST /api/v1/virtual-assistants`, `POST …/{id}/collections/attach` |
+| collections | `GET /api/v1/collections?search=`, `POST /api/v1/collections`, `GET …/{id}/directories`, `POST …/{id}/documents` |
+| apps/tasks | `GET /api/v1/tasks/?search=&status=all`, `POST /api/v1/tasks/`, `GET/PATCH /api/v1/tasks/{id}`, `POST …/image`, `@app` sync (as `pt live-app publish`), `POST …/versions`, `POST …/collections-files` |
+| workspace | `GET/POST /api/v1/chat-workspaces`, `PUT …/{id}/goal`, `GET/POST /api/v1/memories?workspace_id=` |
+| chats | `POST /api/v1/chats?copy_from_task_id=`, `GET /api/v1/chats?search=`, `GET/POST …/{id}/collections[/{cid}]`, `DELETE …/{id}/collections`, `GET …/{id}/users`, `POST …/{id}/members`, `GET /api/v1/users/me/visible-users` |
+| seed | `POST /api/v1/chats/{id}/chatdb/list`, `POST /api/v1/chats/{id}/chatdb/entities` (with `collection_id`) |
+| schedules | `GET /api/v1/scheduled_jobs/scheduled_jobs_in_chat/{chat}`, `POST/PUT /api/v1/scheduled_jobs/scheduled_job_in_chat[/{id}]` |
+
+```bash
+pt suite build ./gtm-suite/package/gtm -o primethink.gtm-1.0.0.ptsuite
+pt suite inspect primethink.gtm-1.0.0.ptsuite
+pt suite install primethink.gtm-1.0.0.ptsuite --params gtm.params.json --model openai:gpt-5.4 --dry-run
+pt suite install primethink.gtm-1.0.0.ptsuite --params gtm.params.json --model openai:gpt-5.4 --yes
+pt suite catalog list --catalog github:primethink-ai/primethink-catalog --kind app
+```
+
+---
+
 ## Profiles: `pt profile`
 
 Profiles let you store multiple API tokens (e.g. for different accounts or environments) and switch between them.
@@ -1021,6 +1204,13 @@ Entities are grouped by name (think tables); each row has an `id`. Initialize th
 
 > Unlike `pt chat`/`pt collection`, this group *does* use `-p` for `--profile` (there is no `--path` here).
 
+**Targeting a DB Collection.** By default every command below except `init` reads and writes the chat's own ChatDB. Pass `--collection NAME` and/or `--collection-id N` to target a **DB Collection** (a collection of type `db`, see `pt collection create --type db`) attached to the chat instead. The ID is unambiguous when several attached DB Collections share a name, and it survives a rename; when you pass both, they must identify the same collection or the API answers 404. Writes (`add`, `update`, `delete`) to a collection attached read-only are rejected with 403. The target is sent as `collection_name`/`collection_id` in the request body, or as query parameters for `get`. There is no `pt` command to attach a collection to a chat yet — attach it in the web app.
+
+```bash
+pt chatdb list 123 --entity tasks --collection project-db
+pt chatdb add 123 --entity tasks --data '{"title": "a"}' --collection-id 42
+```
+
 ### `pt chatdb init`
 
 Initialize the ChatDB store for a chat.
@@ -1047,6 +1237,8 @@ pt chatdb list CHAT_ID [OPTIONS]
 | `--offset` | Row offset |
 | `--page` | Page number |
 | `--page-size` | Results per page |
+| `--collection` | Target an attached DB Collection by name instead of the chat's own ChatDB |
+| `--collection-id` | Target an attached DB Collection by ID (≥ 1; unambiguous when names repeat) |
 
 Calls `POST /api/v1/chats/{chat_id}/chatdb/list`.
 
@@ -1060,9 +1252,14 @@ pt chatdb list 123 --entity todos --filters '{"done": false}' --limit 20
 Get a single ChatDB entity by its ID.
 
 ```bash
-pt chatdb get CHAT_ID ENTITY_ID [--profile NAME] [--api-url URL]
+pt chatdb get CHAT_ID ENTITY_ID [--collection NAME] [--collection-id N] [--profile NAME] [--api-url URL]
 ```
 
+| Option | Description |
+|---|---|
+| `--collection` | Target an attached DB Collection by name instead of the chat's own ChatDB |
+| `--collection-id` | Target an attached DB Collection by ID (≥ 1; unambiguous when names repeat) |
+
 Calls `GET /api/v1/chats/{chat_id}/chatdb/entities/{entity_id}`.
 
 ### `pt chatdb add`
@@ -1078,6 +1275,8 @@ pt chatdb add CHAT_ID --entity NAME [--data JSON] [--items JSON]
 | `--entity` | Entity name to add to (required) |
 | `--data` | A single row as a JSON object |
 | `--items` | Multiple rows as a JSON array (bulk insert) |
+| `--collection` | Target an attached DB Collection by name instead of the chat's own ChatDB |
+| `--collection-id` | Target an attached DB Collection by ID (≥ 1; unambiguous when names repeat) |
 
 Calls `POST /api/v1/chats/{chat_id}/chatdb/entities`.
 
@@ -1101,8 +1300,10 @@ pt chatdb update CHAT_ID [OPTIONS]
 | `--merge` / `--replace` | Merge `--data` into the existing row or replace it (server default applies if unset) |
 | `--items` | Bulk updates as a JSON array |
 | `--if-unchanged-since` | Only update if the row is unchanged since this timestamp (optimistic concurrency) |
+| `--collection` | Target an attached DB Collection by name instead of the chat's own ChatDB |
+| `--collection-id` | Target an attached DB Collection by ID (≥ 1; unambiguous when names repeat) |
 
-Requires at least one of `--entity-id`/`--data` or `--items`. Calls `PATCH /api/v1/chats/{chat_id}/chatdb/entities`.
+Requires at least one of `--entity-id`/`--data` or `--items`; a collection target on its own does not count. Calls `PATCH /api/v1/chats/{chat_id}/chatdb/entities`.
 
 ```bash
 pt chatdb update 123 --entity-id 7 --data '{"done": true}' --merge
@@ -1113,9 +1314,17 @@ pt chatdb update 123 --entity-id 7 --data '{"done": true}' --merge
 Delete a single row (`--entity-id`) or several (`--ids`). **Destructive and irreversible** — prompts for confirmation unless `--yes` is passed.
 
 ```bash
-pt chatdb delete CHAT_ID [--entity-id N | --ids 1,2,3] [--yes]
+pt chatdb delete CHAT_ID [--entity-id N | --ids 1,2,3] [--collection NAME] [--collection-id N] [--yes]
 ```
 
+| Option | Description |
+|---|---|
+| `--entity-id` | ID of a single row to delete |
+| `--ids` | Comma-separated row IDs to delete |
+| `--collection` | Target an attached DB Collection by name instead of the chat's own ChatDB |
+| `--collection-id` | Target an attached DB Collection by ID (≥ 1; unambiguous when names repeat) |
+| `--yes` | Skip the confirmation prompt |
+
 Requires `--entity-id` or `--ids`. Calls `DELETE /api/v1/chats/{chat_id}/chatdb/entities`.
 
 ```bash
@@ -1162,7 +1371,7 @@ pt collection create --name NAME [OPTIONS]
 |---|---|
 | `--name` | Collection name (required) |
 | `--description` | Collection description |
-| `--type` | Collection type: `collection`, `skill`, or `external_source` (server default: `collection`) |
+| `--type` | Collection type: `collection`, `skill`, `external_source`, or `db` (a DB Collection: structured entities that `pt chatdb --collection` and Live Apps' `pt.db()` read and write) (server default: `collection`) |
 | `--public` / `--private` | Make the collection public or private (server default: private) |
 
 Calls `POST /api/v1/collections` and prints the created collection as JSON.
@@ -1198,7 +1407,7 @@ pt collection update COLLECTION_ID [OPTIONS]
 |---|---|
 | `--name` | Collection name |
 | `--description` | Collection description |
-| `--type` | Collection type: `collection`, `skill`, or `external_source` |
+| `--type` | Collection type: `collection`, `skill`, `external_source`, or `db` |
 | `--public` / `--private` | Make the collection public or private |
 | `--indexed` / `--not-indexed` | Enable or disable indexing |
 | `--ocr-instructions` | OCR instructions for document processing |
@@ -2472,7 +2681,7 @@ pt eval update TASK_ID EVAL_ID [--user-query …] [--ideal-response …] [--type
 pt eval delete TASK_ID EVAL_ID [--yes]                       # DESTRUCTIVE
 
 # Configure how evaluations run
-pt eval settings TASK_ID [--active | --inactive] [--run-time manual|daily|weekly|monthly] [--evaluator-agent-id N] [--pass-threshold F] [--message-delay-ms N]
+pt eval settings TASK_ID [--active | --inactive] [--run-time manual|daily|weekly|monthly] [--evaluator-agent-id N] [--pass-threshold 1-100] [--message-delay-ms N]
 
 # Run an evaluation and inspect its runs/results
 pt eval run TASK_ID [--version N] [--model-override M]
@@ -2503,13 +2712,13 @@ pt eval delete-simulation TASK_ID SIM_ID [--yes]             # DESTRUCTIVE
 | `simulations` | `GET /api/v1/tasks/{id}/simulations` | `list_task_simulations` |
 | `delete-simulation` | `DELETE /api/v1/tasks/{id}/simulations/{sim_id}` | `delete_task_simulation` |
 
-`--type` for a test case is `exact` (exact-match), `similar` (fuzzy/semantic match), or `agent` (an evaluator agent judges the response). `--examples` takes a JSON object of good/bad example fields. `--chat-group` (default `1`) groups related test cases.
+`--pass-threshold` is the minimum score that counts as a pass, as a whole-number percentage from 1 to 100 (`80`, not `0.8`); the CLI rejects anything outside that range with a usage error before any request is made. `--type` for a test case is `exact` (exact-match), `similar` (fuzzy/semantic match), or `agent` (an evaluator agent judges the response). `--examples` takes a JSON object of good/bad example fields. `--chat-group` (default `1`) groups related test cases.
 
 ```bash
 # Build a two-case plan, make it evaluator-judged and daily, then run it
 pt eval add 99 --user-query "What's your return window?" --ideal-response "30 days" --type similar
 pt eval add 99 --user-query "Refund a gift?" --ideal-response "Yes, store credit" --type agent --evaluator-agent-id 7
-pt eval settings 99 --active --run-time daily --evaluator-agent-id 7 --pass-threshold 0.8
+pt eval settings 99 --active --run-time daily --evaluator-agent-id 7 --pass-threshold 80
 pt eval run 99
 pt eval results 99 | jq '.[] | {case, passed, score}'
 ```