primethink-cli 1.4.1__tar.gz → 1.6.0__tar.gz

{primethink_cli-1.4.1 → primethink_cli-1.6.0}/DEVELOPER.md

@@ -55,8 +55,8 @@ pip install -e ".[dev]"
 primethink-cli/
 ├── primethink.py           # Main CLI implementation (single module)
 ├── primethink_mcp.py       # MCP server (pt mcp), reuses primethink.py's helpers; optional [mcp] extra
-├── internal_tools/         # primethink-agent-tools: LangChain tools plugin for PT agents
-│                           #   (own distribution; depends on primethink-cli; reuses its helpers)
+├── primethink_agent_tools/ # Agent tools plugin: LangChain tools for PT agents; optional [agent-tools] extra
+│                           #   (entry point primethink.tools; reuses primethink.py's helpers)
 ├── pyproject.toml          # Package configuration (entry point: pt)
 ├── setup.py                # Legacy packaging shim
 ├── requirements.txt        # Runtime dependencies
@@ -85,7 +85,10 @@ primethink-cli/
     ├── test_task_commands.py # Task command tests
     ├── test_live_app.py    # Safe GitHub template scaffolding tests
     ├── test_install_developer_skill.py # Recursive public skill installer tests
-    └── test_install_skill.py # bundled CLI skill installer tests
+    ├── test_install_skill.py # bundled CLI skill installer tests
+    ├── test_mcp_server.py  # MCP server tests (skipped without the mcp SDK)
+    ├── test_agent_tools.py # Agent tools plugin tests (skipped without langchain-core)
+    └── test_packaging.py   # Wheel/entry-point/extras contract (runs on a base install)
 ```
 
 ## Architecture
@@ -142,7 +145,7 @@ def my_command(thing_id, profile, api_url):
 
 Security boundaries are enforced before the destination is exposed: HTTPS GitHub repository URLs only, compressed/expanded size and file-count limits, repository-relative manifest paths, path-traversal and duplicate-path checks, symbolic-link rejection, and refusal to touch an existing destination. Tests build in-memory ZIP archives and mock `requests.request`; do not make live GitHub calls in the test suite. The default catalog lives in the separate `primethink-app-templates` repository.
 
-Because this command only creates local source files and does not call the PrimeThink API, it has no MCP or `primethink-agent-tools` equivalent.
+Because this command only creates local source files and does not call the PrimeThink API, it has no MCP or agent-tools equivalent.
 
 #### 4. Agent Skill Installation
 
@@ -185,16 +188,18 @@ Key differences from the CLI, driven by MCP-over-stdio constraints:
 
 `mcp` is an optional dependency (the `[mcp]` extra, Python 3.10+); `pt mcp` imports `primethink_mcp` lazily and prints an install hint if the SDK is missing. Tests live in `tests/test_mcp_server.py` and `pytest.importorskip("mcp")` so they skip cleanly where the SDK isn't installed.
 
-#### 7. Agent Tools Plugin (`internal_tools/`)
+#### 7. Agent Tools Plugin (`primethink_agent_tools/`)
 
-`internal_tools/` is a **separate distribution** (`primethink-agent-tools`) that depends on `primethink-cli` and exposes the admin/management API as LangChain tools for PrimeThink agents, discovered via the `primethink.tools` entry point. It reuses the CLI's code rather than re-implementing it:
+`primethink_agent_tools/` ships **inside the `primethink-cli` wheel**, enabled by the optional `[agent-tools]` extra (`langchain-core`, `pydantic`; Python 3.9+). It exposes the admin/management API as LangChain tools for PrimeThink agents, discovered via the `primethink.tools` entry point that `pyproject.toml` declares (`primethink_admin = "primethink_agent_tools:register"`). It reuses the CLI's code rather than re-implementing it:
 
 - **Transport reuse without a rewrite.** Tools call `primethink._api_call` (the CLI's `requests` layer) through a small async wrapper (`client.api_json`) that runs it in `asyncio.to_thread` — the agent runtime is async, and `requests` is sync. No httpx dependency; `requests` comes transitively from `primethink-cli`.
 - **Payload reuse.** Tools import `_clean_payload`, `_TASK_PORTABLE_FIELDS`, `_VERSION_FIELDS`, etc. from `primethink`, so payload shaping matches `pt`/`pt mcp`. Only endpoint path strings are written locally (the accepted trade for not restructuring the CLI).
 - **Auth.** Per-user token from the `ADMIN_PRIMETHINK_API_TOKEN` setting, resolved via the injected `get_user_setting_value` context (`settings.PrimethinkSettingsProvider`), with a `StaticSettingsProvider` fallback for tests/standalone.
 - **Scope.** Admin/management only (tasks, agents, chats, collections + collection↔chat assignment). Excludes hot-path search, document byte transfer, messaging/orchestration, and destructive deletes — those stay native.
 
-This directory is **not** part of the `primethink-cli` wheel (the main `pyproject.toml` ships only `primethink`/`primethink_mcp`); it builds and tests independently (`pip install -e ./internal_tools[dev]`, `cd internal_tools && pytest`). When you add or change an API command that belongs in the agent surface, add/update the matching tool in `internal_tools/src/primethink_agent_tools/tools.py` and its test.
+Because the plugin and the private CLI helpers it imports (`_api_call`, `_clean_payload`, `_TASK_PORTABLE_FIELDS`, `_VERSION_FIELDS`) always ship in the same wheel, there is no cross-package version skew to guard against. The base CLI install is unaffected: the entry point is declared, but nothing loads it unless the PrimeThink API calls it, and `register()` imports langchain lazily — and when it is called without the extra, it raises a `ModuleNotFoundError` whose message names `pip install 'primethink-cli[agent-tools]'` (the API logs it and continues without the plugin). The API image installs `primethink-cli[agent-tools]==<version>`; see [`docs/agent-tools.md`](docs/agent-tools.md) for setup.
+
+Tests live in `tests/test_agent_tools.py` and `pytest.importorskip("langchain_core")`, so they skip where the extra isn't installed (the `dev` extra installs it); the packaging contract (entry point, `pyproject.toml` packages/extras, RECORD contents of a non-editable install, the `register()` install hint) lives in `tests/test_packaging.py` and needs no extra. When you add or change an API command that belongs in the agent surface, add/update the matching tool in `primethink_agent_tools/tools.py` and its test.
 
 ## Adding New Commands
 

{primethink_cli-1.4.1 → primethink_cli-1.6.0}/MANIFEST.in

@@ -7,6 +7,11 @@ recursive-include docs *.md *.txt
 recursive-include install *.sh *.ps1 *.cmd *.rb
 recursive-include scripts *.sh
 recursive-include skills *.md
+# setuptools auto-includes tests/test_*.py; add the package marker and shared
+# fixtures the test modules import (`from tests.conftest import ...`), plus the
+# pytest config, so a bare `pytest` inside an unpacked sdist collects `tests/`.
+recursive-include tests *.py
+include pytest.ini
 # Internal design/spec artifacts live under docs/ but must not ship in the sdist.
 prune docs/superpowers
 global-exclude __pycache__

{primethink_cli-1.4.1/primethink_cli.egg-info → primethink_cli-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: primethink-cli
-Version: 1.4.1
+Version: 1.6.0
 Summary: PrimeThink CLI - A powerful tool for interacting with PrimeThink AI API
 Author-email: PrimeThink <support@primethink.ai>
 License-Expression: MIT
@@ -26,10 +26,16 @@ 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"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
 Requires-Dist: mcp<2,>=1.2.0; python_version >= "3.10" and extra == "dev"
+Requires-Dist: langchain-core>=0.3.0; python_version >= "3.10" and extra == "dev"
+Requires-Dist: pydantic>=2.0; python_version >= "3.10" and extra == "dev"
 Dynamic: license-file
 
 # PrimeThink CLI
@@ -79,7 +85,7 @@ pt chat send --agent AGENT_ID --message "your message"
 | `pt profile remove` | Remove a profile |
 | `pt chat send` | Send a message to a chat (by ID/mention) or an agent |
 | `pt chat list` | List chats (paginated, filterable by star/archive/workspace) |
-| `pt chat create` | Create a new chat |
+| `pt chat create` | Create a new chat (`--from-task-id` launches a task into it) |
 | `pt chat rename` | Rename a chat |
 | `pt chat goal` | Update a chat's goal |
 | `pt chat type` | Switch a chat between `live-app` and `chat` mode |
@@ -99,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) |
@@ -158,7 +164,8 @@ pt chat send --agent AGENT_ID --message "your message"
 | `pt task delete` | Delete a task (asks for confirmation; `--yes` to skip) |
 | `pt task duplicate` | Duplicate a task |
 | `pt task set-public` / `pt task set-private` | Make a task public / private |
-| `pt task publish` | Create/update a task from a project directory |
+| `pt task publish` | Create/update a task from a project directory (`--type`, feature toggles, optional `task.json`) |
+| `pt task launch` | Launch a task into a new chat, optionally inside a workspace |
 | `pt task test` | Sync a task goal into a new or existing chat |
 | `pt task export` | Export a task's portable config as JSON (for `pt task import`) |
 | `pt task import` | Create a new task from an exported JSON file (deploy across environments with `--profile`) |
@@ -349,8 +356,12 @@ pt task import tasks/briefing.json --profile production
 
 # Publish a conventional task project (GOAL.md required); pass an ID to update
 pt task publish ./tasks/briefing --virtual-assistant-id 7
+pt task publish ./tasks/briefing --virtual-assistant-id 7 --type group --chat-history --docs-enabled --scheduled-jobs
 pt task publish ./tasks/briefing --task-id 99 --virtual-assistant-id 7
 
+# Launch a task into a chat (optionally inside a workspace), as the web app does
+pt task launch 99 --workspace-id 738
+
 # Make the resulting task public/private, or test its goal in a chat
 pt task set-public 99
 pt task set-private 99
@@ -439,21 +450,20 @@ for the full tool list.
 
 ## Agent Tools Plugin
 
-Beyond the CLI and MCP server, this repo also ships **[`primethink-agent-tools`](internal_tools/)**
-(under `internal_tools/`) — a plugin that exposes the PrimeThink admin/management
-API (tasks, agents, chats, collections) as **LangChain tools for PrimeThink
-agents**, reusing the same client code as `pt`. It's a separate distribution that
-depends on `primethink-cli`, so the CLI stays lean, and the plugin is installed
-only in the agent runtime:
+Beyond the CLI and MCP server, the package also ships the **agent tools plugin**
+(`primethink_agent_tools`) — it exposes the PrimeThink admin/management API
+(tasks, agents, chats, collections) as **LangChain tools for PrimeThink
+agents**, reusing the same client code as `pt`. It's enabled by the optional
+`agent-tools` extra, so plain CLI installs stay lean (no langchain) and the
+plugin is installed only in the agent runtime / API image:
 
 ```bash
-pip install primethink-cli primethink-agent-tools
+pip install 'primethink-cli[agent-tools]'
 ```
 
 The PrimeThink API discovers it automatically via the `primethink.tools` entry
 point. Authentication uses a per-user `ADMIN_PRIMETHINK_API_TOKEN` setting. See
-[`internal_tools/README.md`](internal_tools/README.md) for the tool list, auth,
-and setup.
+[`docs/agent-tools.md`](docs/agent-tools.md) for the tool list, auth, and setup.
 
 ## Agent Skills
 

{primethink_cli-1.4.1 → primethink_cli-1.6.0}/README.md

@@ -45,7 +45,7 @@ pt chat send --agent AGENT_ID --message "your message"
 | `pt profile remove` | Remove a profile |
 | `pt chat send` | Send a message to a chat (by ID/mention) or an agent |
 | `pt chat list` | List chats (paginated, filterable by star/archive/workspace) |
-| `pt chat create` | Create a new chat |
+| `pt chat create` | Create a new chat (`--from-task-id` launches a task into it) |
 | `pt chat rename` | Rename a chat |
 | `pt chat goal` | Update a chat's goal |
 | `pt chat type` | Switch a chat between `live-app` and `chat` mode |
@@ -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) |
@@ -124,7 +124,8 @@ pt chat send --agent AGENT_ID --message "your message"
 | `pt task delete` | Delete a task (asks for confirmation; `--yes` to skip) |
 | `pt task duplicate` | Duplicate a task |
 | `pt task set-public` / `pt task set-private` | Make a task public / private |
-| `pt task publish` | Create/update a task from a project directory |
+| `pt task publish` | Create/update a task from a project directory (`--type`, feature toggles, optional `task.json`) |
+| `pt task launch` | Launch a task into a new chat, optionally inside a workspace |
 | `pt task test` | Sync a task goal into a new or existing chat |
 | `pt task export` | Export a task's portable config as JSON (for `pt task import`) |
 | `pt task import` | Create a new task from an exported JSON file (deploy across environments with `--profile`) |
@@ -315,8 +316,12 @@ pt task import tasks/briefing.json --profile production
 
 # Publish a conventional task project (GOAL.md required); pass an ID to update
 pt task publish ./tasks/briefing --virtual-assistant-id 7
+pt task publish ./tasks/briefing --virtual-assistant-id 7 --type group --chat-history --docs-enabled --scheduled-jobs
 pt task publish ./tasks/briefing --task-id 99 --virtual-assistant-id 7
 
+# Launch a task into a chat (optionally inside a workspace), as the web app does
+pt task launch 99 --workspace-id 738
+
 # Make the resulting task public/private, or test its goal in a chat
 pt task set-public 99
 pt task set-private 99
@@ -405,21 +410,20 @@ for the full tool list.
 
 ## Agent Tools Plugin
 
-Beyond the CLI and MCP server, this repo also ships **[`primethink-agent-tools`](internal_tools/)**
-(under `internal_tools/`) — a plugin that exposes the PrimeThink admin/management
-API (tasks, agents, chats, collections) as **LangChain tools for PrimeThink
-agents**, reusing the same client code as `pt`. It's a separate distribution that
-depends on `primethink-cli`, so the CLI stays lean, and the plugin is installed
-only in the agent runtime:
+Beyond the CLI and MCP server, the package also ships the **agent tools plugin**
+(`primethink_agent_tools`) — it exposes the PrimeThink admin/management API
+(tasks, agents, chats, collections) as **LangChain tools for PrimeThink
+agents**, reusing the same client code as `pt`. It's enabled by the optional
+`agent-tools` extra, so plain CLI installs stay lean (no langchain) and the
+plugin is installed only in the agent runtime / API image:
 
 ```bash
-pip install primethink-cli primethink-agent-tools
+pip install 'primethink-cli[agent-tools]'
 ```
 
 The PrimeThink API discovers it automatically via the `primethink.tools` entry
 point. Authentication uses a per-user `ADMIN_PRIMETHINK_API_TOKEN` setting. See
-[`internal_tools/README.md`](internal_tools/README.md) for the tool list, auth,
-and setup.
+[`docs/agent-tools.md`](docs/agent-tools.md) for the tool list, auth, and setup.
 
 ## Agent Skills
 

{primethink_cli-1.4.1 → primethink_cli-1.6.0}/SPECS.md

@@ -38,7 +38,7 @@ To obtain an API key, go to `Settings > API Keys` in the PrimeThink app and gene
 | `pt chat send CHAT_ID` | `POST /api/v1/chats/{chat_id_or_mention}/messages` |
 | `pt chat send --agent ID` | `POST /api/v1/virtual-assistants/{agent_id}/messages` |
 | `pt chat list` | `GET /api/v1/chats` |
-| `pt chat create` | `POST /api/v1/chats` |
+| `pt chat create` | `POST /api/v1/chats` (`--from-task-id` adds `?copy_from_task_id=`) |
 | `pt chat rename` | `PUT /api/v1/chats/{chat_id}/name` |
 | `pt chat goal` | `PUT /api/v1/chats/{chat_id}/goal` |
 | `pt chat type` | `PUT /api/v1/chats/{chat_id}/page_type?page_type=html\|chat` |
@@ -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` |
@@ -114,7 +114,8 @@ To obtain an API key, go to `Settings > API Keys` in the PrimeThink app and gene
 | `pt task delete` | `DELETE /api/v1/tasks/{task_id}` |
 | `pt task duplicate` | `POST /api/v1/tasks/{task_id}/duplicate` |
 | `pt task set-public` / `set-private` | `PATCH /api/v1/tasks/{task_id}/public-status?task_type=public\|private` |
-| `pt task publish` | `POST /api/v1/tasks/` or `PATCH /api/v1/tasks/{task_id}` |
+| `pt task publish` | `POST /api/v1/tasks/` or `PATCH /api/v1/tasks/{task_id}` (type/toggles from options or the project's `task.json`) |
+| `pt task launch` | `POST /api/v1/chats?copy_from_task_id={task_id}[&task_version_number=N]` (body: optional `chat_workspace_id`, `name`) |
 | `pt task test` | `POST /api/v1/chats` (new only), `PUT /api/v1/chats/{chat_id}/page_type` (existing only), `PUT /api/v1/chats/{chat_id}/goal` |
 | `pt live-app publish` | task create/update + task version + task directory/document/version endpoints |
 | `pt live-app test` | chat create/page-type/goal + chat directory/document/version endpoints |
@@ -309,11 +310,13 @@ pt chat list [--page N] [--page-size N] [--search TEXT] [--starred/--no-starred]
 
 **Body**: JSON object; all fields optional and omitted unless set — `name`, `goal`, `virtual_assistant_id` (int), `chat_workspace_id`, `parent_chat_id` (int), `type` (`standard` | `direct_users`; server default `standard`), `public` (bool), `members` (int array).
 
+**Query parameters** (task launch): `copy_from_task_id` (int) makes the server copy that task's goal, default agent, settings, documents, collections and scheduled job into the new chat and post its initial prompt — the route the web app uses to open a task; `task_version_number` (int, optional) launches a specific version. A `task_id` in the body is ignored by the server. Exposed as `pt task launch` / `pt chat create --from-task-id` and the `launch_task` MCP tool.
+
 **Success statuses**: 200, 201
 
 **CLI Command**:
 ```bash
-pt chat create [--name TEXT] [--goal TEXT | --goal-file PATH] [--virtual-assistant-id ID] [--workspace-id ID] [--parent-chat-id ID] [--type TYPE] [--public/--no-public] [--member USER_ID]...
+pt chat create [--name TEXT] [--goal TEXT | --goal-file PATH] [--virtual-assistant-id ID] [--workspace-id ID] [--parent-chat-id ID] [--type TYPE] [--public/--no-public] [--member USER_ID]... [--from-task-id TASK_ID]
 ```
 
 ---

{primethink_cli-1.4.1 → primethink_cli-1.6.0}/USER_GUIDE.md

@@ -77,7 +77,7 @@ pt version
 
 You should see output like:
 ```
-PrimeThink CLI v1.3.3
+PrimeThink CLI v1.6.0
 ```
 
 ## Getting Started
@@ -713,6 +713,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
@@ -977,8 +990,12 @@ pt task duplicate 99
 
 # Publish a conventional task project; GOAL.md is required
 pt task publish ./tasks/briefing --virtual-assistant-id 7
+pt task publish ./tasks/briefing --virtual-assistant-id 7 --type group --chat-history --docs-enabled --scheduled-jobs
 pt task publish ./tasks/briefing --task-id 99 --virtual-assistant-id 7
 
+# Launch a task into a new chat, optionally inside a workspace (prints the chat JSON + URL)
+pt task launch 99 --workspace-id 738
+
 # Sync the project goal into a new temporary chat or an existing chat
 pt task test ./tasks/briefing
 pt task test ./tasks/briefing --chat-id CHAT_UUID
@@ -994,7 +1011,9 @@ pt task delete 99 --yes
 
 A project directory can override its folder name with `.name.config`, its description with `.description.config`, and its initial prompt with `INITIAL_PROMPT.md`. For type changes other than public/private (e.g. `group` or `catalog`), use `pt task update 99 --type group`.
 
-`pt task publish` prints progress lines rather than JSON, ending with `Task ID: 81`. It takes no task-field options — a created task is private and published with the optional features (memory, chat history, search, summary, documents and collections, scheduled jobs, email integration) switched off. Turn them on afterwards with `pt task update`; a later `pt task publish --task-id` only re-syncs name, description, goal, initial prompt, virtual assistant, and page type, so those settings are not overwritten.
+`pt task publish` prints progress lines rather than JSON, ending with `Task ID: 81`. Task type and feature toggles come from its options (`--type`, `--chat-history`, `--docs-enabled`, `--scheduled-jobs`, `--global-memory`, `--search-in-chat`, `--search-in-documents`, `--summary-enabled`, `--email-integration`, `--share-action`, `--public-chat`, `--run-immediately`), else from an optional `task.json` in the project directory (`{"type": "group", "chat_history": true, "documents_and_collections_enabled": true, "scheduled_jobs_enabled": true}`), else from the conservative defaults: a created task is **private** with memory, chat history, search, summary, documents and collections, scheduled jobs and email integration **switched off** — so a task that relies on its documents or on scheduling must enable them. A later `pt task publish --task-id` re-syncs name, description, goal, initial prompt, virtual assistant and page type plus every type/toggle given on the command line and every accepted field present in `task.json`; settings the project does not state are not overwritten.
+
+`pt task launch TASK_ID` starts a task the way the web app does when you open one: it creates a chat (inside `--workspace-id` when given) that inherits the task's goal, default agent, settings, documents, collections and scheduled job, posts the task's initial prompt, and prints the chat JSON followed by `Chat URL: …`. `pt chat create --from-task-id TASK_ID` does the same through the generic chat-create command.
 
 `pt task test` creates a **new** chat unless you pass `--chat-id`, and prints the chat URL as its last line. A test chat is temporary by default; pass `--permanent` when you mean to keep it. To keep re-testing in the same chat, record the ID on the first run:
 
@@ -1138,10 +1157,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
 
@@ -1264,8 +1283,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.
@@ -1827,6 +1846,10 @@ pt mcp
 
 Point your MCP client at `pt mcp` and provide a `PRIMETHINK_TOKEN` in its server env. See the [MCP Server](#mcp-server) section for a full client-config example.
 
+### Q: What is the `agent-tools` extra?
+
+**A**: It enables the plugin that lets PrimeThink **agents** (not you) manage tasks, agents, chats, and collections through the same client code as `pt`. It's installed in the PrimeThink API image by platform operators, not on your machine — a plain `pip install primethink-cli` doesn't need it. See [docs/agent-tools.md](docs/agent-tools.md).
+
 ### Q: How do I uninstall the CLI?
 
 **A**:

primethink_cli-1.6.0/docs/agent-tools.md

@@ -0,0 +1,116 @@
+# Agent tools plugin (`primethink-cli[agent-tools]`)
+
+PrimeThink API tools for PrimeThink **agents**, packaged as a discoverable
+plugin. It exposes the admin/management surface of the PrimeThink API — tasks,
+agents, chats, and collections (including collection↔chat assignment) — as
+LangChain tools, **reusing the `primethink-cli` client code** so the tool
+encoding never drifts from `pt` / `pt mcp`.
+
+The plugin is the `primethink_agent_tools` package **inside the `primethink-cli`
+distribution**, enabled by the optional **`agent-tools` extra**. A plain
+`pip install primethink-cli` stays lean (no langchain); the extra pulls in
+`langchain-core` and `pydantic` and is installed only where the tools run — the
+agent runtime / API image. One wheel, one version: the plugin and the CLI
+helpers it imports always ship together.
+
+## What it provides
+
+A single capability, code **`primethink_admin`**, with 98 tools (every tool
+name is prefixed `primethink_`):
+
+- **Tasks** — list, create, update, get, export, import, duplicate, launch, publish/unpublish, create-version, upload-image
+- **Task evaluation** — list/add/update evaluation items, set evaluation settings, run an evaluation, list runs, get a run, get results, run a simulation, list simulations
+- **Agents** — list, get, create, update, list-types, resolve-capabilities, attach/detach collections, list documents
+- **Capabilities** — list, create, update, archive, duplicate; **model catalog** — list models, list embedding models
+- **Chats** — list, create (optionally from a task), rename, set-goal, archive/unarchive, list-messages, list-files, save-as-task
+- **Chat members & users** — list chat users, invite/remove members, list/search visible users
+- **Notifications** — list, unread-count, mark read/unread, mark-all-read
+- **Scheduled jobs** — list, create, update, set-status
+- **Chat workspaces** — list, create, rename, set-goal, archive, pin, add/remove chat
+- **Collections** — list, create, get, update, reindex, copy, list-files, assign-to-chat (bulk), list-chat-collections, remove-from-chat, set-collection-status
+- **Directories & document versions** — create/move/rename directory; list versions, create text version, set production version (chat/collection/task)
+- **Tags** — list, create, assign; **Groups** — list, get, create, update, list members, remove members, invite, add/remove agents
+
+### Deliberately *not* here
+
+Semantic search, document byte transfer (upload/download/sync), messaging/
+orchestration, and destructive deletes are **excluded** — those are hot-path,
+large-payload, or already covered by native platform capabilities, and should
+not round-trip through the public API. See the design notes in
+[`DEVELOPER.md`](../DEVELOPER.md).
+
+## Authentication
+
+The tools call the PrimeThink API with a **per-user token** read from PrimeThink
+settings under the name **`ADMIN_PRIMETHINK_API_TOKEN`**. When the API injects a
+plugin context providing `get_user_setting_value`, the token is resolved for the
+acting user (`logged_user_id` / `group_id` come from `RunnableConfig`). This is
+the same `${SETTING}` mechanism MCP capabilities use, so both surfaces share one
+auth story.
+
+The API base URL comes from the `PRIMETHINK_API_URL` setting or env var, falling
+back to the CLI's default (`https://api.primethink.ai`).
+
+## Install
+
+**Requires Python 3.9+** — the base CLI still supports 3.8, but the tool
+signatures use `typing.Annotated` (3.9+) and `langchain-core>=0.3.0` does not
+resolve on 3.8. The `dev` extra installs the plugin's test dependencies only on
+3.10+, so plugin tests skip on a 3.9 checkout.
+
+```bash
+# In the API image (production): one pinned line in requirements.txt
+primethink-cli[agent-tools]==1.6.0
+
+# From a checkout (dev): the dev extra already includes langchain-core
+pip install -e ".[dev]"
+```
+
+**Upgrading a dev environment that had the old standalone plugin** (installed
+with `pip install -e internal_tools` before 1.5.0; it was never published to
+PyPI): uninstall it first — `pip uninstall primethink-agent-tools` — and only
+then install `primethink-cli[agent-tools]`. Both distributions own the same
+`primethink_agent_tools` modules and declare the same `primethink_admin` entry
+point, so leaving both installed yields duplicate registrations, and removing
+the old one afterwards deletes files the new install relies on.
+
+The PrimeThink API discovers the plugin at startup via the `primethink.tools`
+entry point declared by `primethink-cli` — no code changes in the API repo.
+Verify discovery:
+
+```bash
+python -c "from importlib.metadata import entry_points; print(list(entry_points().select(group='primethink.tools')))"
+# [EntryPoint(name='primethink_admin', value='primethink_agent_tools:register', group='primethink.tools')]
+```
+
+Then, as a super-admin, convert the registered `primethink_admin` code into a
+capability (`POST /capabilities/from-registered-tool`, type `internal`), assign
+it to an agent, and set `ADMIN_PRIMETHINK_API_TOKEN` for each user who should be
+able to use it. The tools become available in that agent's chats.
+
+Installing the base CLI without the extra is harmless: the entry point is
+declared, but nothing loads it unless the PrimeThink API calls it, and
+`register()` imports langchain lazily. If the API *does* call it on an install
+without the extra, `register()` raises a `ModuleNotFoundError` that names the
+fix (`pip install 'primethink-cli[agent-tools]'`); the API logs it under
+"Failed to load tool plugin: primethink_admin" and starts without the plugin.
+The same message appears on Python 3.8 — the wheel installs there because the
+CLI supports 3.8, but the plugin's tool signatures need `typing.Annotated`
+(3.9+) and the extra's `langchain-core` does not resolve on 3.8, so `register()`
+checks the interpreter first rather than failing on an opaque `typing` import.
+
+## Develop / test
+
+Tests live in `tests/test_agent_tools.py` and run with the rest of the suite;
+they `pytest.importorskip("langchain_core")` so they skip cleanly where the
+extra isn't installed. The packaging contract (entry point, `pyproject.toml`
+packages/extras, RECORD of a non-editable install, the `register()` install
+hint) is covered by `tests/test_packaging.py`, which needs no extra:
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+Tests mock `primethink.requests.request` (the reused transport) exactly like the
+main CLI tests, so no network access is needed.