@specset/cli 0.6.0 → 2.0.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@specset/cli",
-  "version": "0.6.0",
+  "version": "2.0.0",
   "description": "Command-line interface for Specset — authenticate, run GraphQL queries, and chat with Specset project agents.",
-  "license": "Apache-2.0",
+  "license": "Elastic-2.0",
   "homepage": "https://specset.com",
   "repository": {
     "type": "git",
@@ -17,14 +17,18 @@
     "agent"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "type": "module",
   "bin": {
     "specset": "./dist/main.js"
   },
   "dependencies": {
-    "open": "^11.0.0"
+    "@anthropic-ai/claude-agent-sdk": "0.3.257",
+    "@anthropic-ai/sdk": "0.93.0",
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "open": "^11.0.0",
+    "zod": "^4.1.9"
   },
   "publishConfig": {
     "access": "public"

package/plugin/specset/.claude-plugin/plugin.json

@@ -1,13 +1,13 @@
 {
   "name": "specset",
-  "version": "0.6.0",
+  "version": "2.0.0",
   "description": "Search and manage Specset construction project data with shared skills and MCP tools.",
   "author": {
     "name": "Specset"
   },
   "homepage": "https://docs.specset.com",
   "repository": "https://github.com/specsetai/specset-plugins",
-  "license": "Apache-2.0",
+  "license": "Elastic-2.0",
   "keywords": [
     "construction",
     "drawings",

package/plugin/specset/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "specset",
-  "version": "0.6.0",
+  "version": "2.0.0",
   "description": "Search and manage Specset construction project data with shared skills and MCP tools.",
   "author": {
     "name": "Specset",
@@ -9,7 +9,7 @@
   },
   "homepage": "https://docs.specset.com",
   "repository": "https://github.com/specsetai/specset-plugins",
-  "license": "Apache-2.0",
+  "license": "Elastic-2.0",
   "keywords": [
     "construction",
     "drawings",
@@ -20,7 +20,7 @@
   "mcpServers": "./.mcp.json",
   "interface": {
     "displayName": "Specset",
-    "shortDescription": "Search and manage construction project data",
+    "shortDescription": "Search construction documents",
     "longDescription": "Use Specset skills and MCP tools to search specifications and drawings, inspect project records, manage workflows, and transfer files.",
     "developerName": "Specset",
     "category": "Productivity",
@@ -30,6 +30,7 @@
       "File transfer"
     ],
     "websiteURL": "https://specset.com",
+    "supportURL": "https://specset.com/contact",
     "privacyPolicyURL": "https://specset.com/privacy",
     "termsOfServiceURL": "https://specset.com/terms",
     "defaultPrompt": [
@@ -37,6 +38,8 @@
       "Compare this submittal with the specifications.",
       "Show me the latest RFIs affecting this work."
     ],
-    "brandColor": "#1F6FEB"
+    "brandColor": "#1F6FEB",
+    "composerIcon": "./assets/icon.png",
+    "logo": "./assets/icon.png"
   }
 }

package/plugin/specset/README.md

@@ -4,6 +4,7 @@ This is the source template for the universal Specset plugin bundle.
 
 - Codex and Claude Code discover the bundled skills and start `specset mcp` over stdio. The CLI owns browser/device authentication and direct local file transfer.
 - ChatGPT and other hosted clients connect to Specset's Streamable HTTP MCP endpoint at `https://<host>/mcp`. OAuth 2.1 consent binds the grant to the selected organization; the server uses the same tool registry and adds host-file upload and signed-download tools.
+- External tool and GraphQL source references are presented as clickable `https://app.specbook.ai/go/...` links. Bundled skills instruct agents to include relevant returned links in answers so users can open the cited source in Specset.
 
 `yarn nx run cli:package` copies the canonical `apps/cli/skills` tree into this plugin template under `apps/cli/publish/plugin/specset`. Keep skill source changes in `apps/cli/skills`; do not hand-edit a staged copy.
 

package/plugin/specset/skills/specset/SKILL.md

@@ -31,16 +31,18 @@ This is the core skill — setup and mechanics only. Domain workflows live in si
 
 Run this when the user installs or updates the skill/plugin, asks to get started with Specset, or when a command fails because the CLI is missing or unauthenticated. Every step is idempotent — skip any that's already satisfied.
 
-1. **Install or update the CLI** (Node.js 20+). Installing a skill/plugin does not upgrade the npm package. If `specset --version` is missing or older than `npm view @specset/cli version`, run `npm install -g @specset/cli@latest` (don't replace a source-linked development CLI whose version is newer than npm). After upgrading, refresh the skills with `specset skill install --target <claude|codex|chatgpt>`.
-2. **Authenticate** — check with `specset auth status`. If not logged in: `specset login` when a visible browser is available on this machine (tell the user to complete sign-in there while the command waits); `specset login --device` otherwise (SSH, containers, CI, remote/in-app sessions). Device login prints a code and a link (`https://<host>/device?code=XXXX-XXXX`) — show both to the user; the command completes once they approve. Codes expire after 15 minutes; rerun for a fresh one.
+1. **Install or update the CLI** (Node.js 22+). Installing a skill/plugin does not upgrade the npm package. If `specset --version` is missing or older than `npm view @specset/cli version`, run `npm install -g @specset/cli@latest` (don't replace a source-linked development CLI whose version is newer than npm). After upgrading, refresh the skills with `specset skill install --target <claude|codex|chatgpt>`.
+2. **Authenticate** — check with `specset auth status`. If not logged in: `specset login` when a visible browser is available on this machine (tell the user to complete sign-in there while the command waits); `specset login --device` otherwise (SSH, containers, CI, remote/in-app sessions). Device login prints a code and a link (`https://<host>/device?code=XXXX-XXXX`) — show both to the user; the command completes once they approve. Codes expire after 15 minutes; rerun for a fresh one. When any command answers `Session invalid`, run `specset login` (or `--device`) for that host again: it replaces the stored session the server no longer accepts. `specset logout` is only for switching accounts.
 3. **Pick the active organization** (required for org-scoped queries): `specset org list`, then `specset org use <slug>`. If the user belongs to exactly one org, select it; otherwise ask which to use.
 4. **Confirm** with `specset auth status`.
 
 Credentials persist across sessions in `~/.config/specset/config.yml` (mode 0600) — setup only needs to happen once per machine.
 
+If `specset auth status` reports an invalid session, run `specset logout`, then sign in again. Pin the same `--host` on both commands when using a development or non-default host; `login` does not replace an existing stored session.
+
 ## Running GraphQL
 
-Use the `api` subcommand. It accepts the operation via `--query` or stdin, and string variables via `-F key=value` (repeatable). Output is the raw JSON GraphQL response (`{ data, errors }`) — non-zero exit on HTTP errors or `errors[]`.
+Use the `api` subcommand. It accepts the operation via `--query` or stdin, and string variables via `-F key=value` (repeatable). Output preserves the raw JSON GraphQL envelope (`{ data, errors }`) — non-zero exit on HTTP errors or `errors[]`.
 
 ```bash
 # Simple query
@@ -59,10 +61,26 @@ query {
 GQL
 ```
 
+### Organization scope
+
+Calls run in the active organization (`specset org use <slug>`). Pass `--org <slug|id>` to pin a different org for one call — required when the project belongs to another org, and safer in parallel sessions because the active org is shared config that another session can switch mid-task. `--noOrg` omits the org header entirely for global/superadmin operations; the two flags are mutually exclusive.
+
+```bash
+specset api --org poettker --query '{ paginatedAssets(projectId: "…", limit: 5) { totalFilteredCount } }'
+```
+
 ### Variable Limitations
 
 `-F key=value` only sends **string** values. For non-string args (numbers, booleans, enums, input objects, lists), inline literals directly in the operation rather than parameterizing them. Reserve `-F` for IDs and plain strings.
 
+### IDs and Source Links
+
+- GraphQL fields named `id` are ordinary UUIDs. Use those UUIDs for GraphQL `ID` variables.
+- Citation-bearing fields named `url` and source references embedded in text are emitted as clickable `https://app.specbook.ai/go/<type>/<uuid>` links. The CLI accepts a complete Specset `/go` link in an **`ID`-typed variable** and extracts its UUID automatically (any focus parameters on the link are dropped, with a warning on stderr). Links inlined as literals in the query text, or passed in non-ID variables, are sent to the server verbatim — inline bare UUIDs there instead.
+- `-F` values for non-ID variables are always sent byte-for-byte as typed. Storing a `/go` link in a text field is fine — it is a real URL.
+- Response output rewrites Specset's internal reference representation to public `/go` links by default; `specset api --refs internal` returns the byte-exact server response for low-level debugging and should not be used in user-facing answers.
+- Include relevant returned `/go` links as descriptive Markdown source links in answers so the user can open the exact source in Specset. Cite only links actually returned by Specset; never manufacture one from an unrelated UUID.
+
 ### Schema Discovery
 
 The domain skills document the operations that matter for each workflow, but they are not exhaustive — when an operation or argument doesn't match, introspect rather than guess:
@@ -75,7 +93,7 @@ The same pattern works for input objects (`inputFields`) and the top-level surfa
 
 ## Agent Tools and MCP
 
-Beyond raw GraphQL, the CLI exposes Specset's own retrieval tools — semantic and keyword search with actual content to reason over, not just record previews — as direct commands (`specset tools`) and as a native MCP server (`specset mcp`). The `specset-tools` skill owns that workflow: tool listing, project scoping, the `-F` JSON-parsing difference, MCP registration, and the `sb://` citation convention.
+Beyond raw GraphQL, the CLI exposes Specset's own retrieval tools — semantic and keyword search with actual content to reason over, not just record previews — as direct commands (`specset tools`) and as a native MCP server (`specset mcp`). The `specset-tools` skill owns that workflow: tool listing, project scoping, the `-F` JSON-parsing difference, MCP registration, and clickable Specset source links.
 
 ## Uploading Files
 
@@ -88,7 +106,7 @@ specset files upload ./photo.jpg --type image/jpeg --json
 
 The active organization is used automatically. With `--json`, read the id from `.id`; without it, the command prints the id. The optional `--type` defaults to `application/octet-stream`.
 
-Hosted MCP clients that support OpenAI file parameters receive the equivalent `uploadFile` tool. Pass its returned `.cloudFileId` to domain mutations that accept attachment ids; its `.id` is an `sb://file/...` citation. `getFileDownload` returns an MCP resource link backed by a short-lived URL when the hosted client needs bytes back.
+Hosted MCP clients that support OpenAI file parameters receive the equivalent `uploadFile` tool. Pass its returned `.cloudFileId` to domain mutations that accept attachment ids; its `.id` is a clickable `https://app.specbook.ai/go/file/...` source link. `getFileDownload` returns an MCP resource link backed by a short-lived URL when the hosted client needs bytes back.
 
 ## Waiting on Background Processing
 
@@ -108,5 +126,6 @@ Confirm with the user before executing mutations that create, update, or delete
 
 ## Troubleshooting
 
+- A server/network failure while selecting the organization (for example HTTP 502) — check the pinned host and server availability, then retry the same command. This does not establish a login-policy failure.
 - Auth, org, or missing-CLI errors (`command not found`, `Not logged in`, `No active organization selected`, login hangs) — run the matching First-Run Setup step above.
 - A lookup by id returns `null` without an error — the record usually belongs to a different org than the active one; check `specset auth status` and switch with `specset org use <slug>`.

package/plugin/specset/skills/specset-admin/SKILL.md

@@ -31,7 +31,7 @@ specset api --query 'query($orgId: ID!, $search: String) {
 
 Manage them (all take the **membership** id from the queries above, not the user id):
 
-- `updateOrgMember(id: ID!, role: ..., projectIds: [ID!])` — `role` is required even when unchanged, so resend the current role when only touching `projectIds`. `projectIds` scopes a Member to specific projects; omit it to leave project access alone.
+- `updateOrgMember(id: ID!, role: ..., projectIds: [ID!], teamIds: [ID!])` — `role` is required even when unchanged, so resend the current role when only touching `projectIds`. `projectIds` scopes a Member to specific projects (the projects they were added to themselves; ones they're on through a team come with the team); `teamIds` replaces their teams. Omit either to leave it alone. Adding or removing a project, or a team's projects, needs management permission in each of those projects.
 - `approveOrgMember(id: ID!)` — activate a `PendingApproval` member.
 - `deactivateOrgMember(id: ID!)` / `reactivateOrgMember(id: ID!)` — suspend and restore access. Deactivation is reversible and preserves history — prefer it over any form of member deletion.
 
@@ -41,17 +41,31 @@ specset api --query 'mutation($id: ID!) {
 }' -F id=<org-member-id>
 ```
 
-## Invites
+## Teams
 
-- `orgInvites(orgId: ID!)` / `paginatedOrgInvites(orgId: ID!, first: Int, after: String)` — pending invites; select `{ id email role inviteUrl }`.
-- `createOrgInvite(orgId: ID!, email: String!, role: ..., projectIds: [ID!])` — sends the invite email; `projectIds` (optional, inline the list) pre-scopes a Member to specific projects. Set `role` deliberately — don't default people to more access than they need. Share the returned `inviteUrl` if the email might not land.
+A team is a named group of members. Assigning a team to a project puts everyone on it on that project, and changes to the team carry over to every project it's on. Teams don't carry a role: people keep their org role unless a project role is set on them.
+
+- `teams(orgId: ID!)` — select `{ id name members { orgMember { user { email } } } projects { project { id name } } canManage }`.
+- `createTeam(orgId: ID!, name: String!, userIds: [ID!], projectIds: [ID!])`, `updateTeam(id: ID!, name: String, userIds: [ID!], projectIds: [ID!])` (lists replace; assignments to archived projects stay), `deleteTeam(id: ID!)`.
+- On a project: `projectTeams(projectId: ID!)`, `addProjectMembers(projectId: ID!, userIds: [ID!], teamIds: [ID!])`, `removeProjectTeam(id: ID!)` (takes the `ProjectTeam` id).
+
+Changing a team needs org Manager or Admin and management permission in every project the team is on or will be on; `canManage` says whether you have it.
+
+## Adding Users and Invites
+
+Nobody joins an org on someone else's say-so. Both paths below leave the person with a pending invitation they must accept — in the app (existing Specset users see an invite badge), by registering through the invite link, or by signing in with the org's SSO. Until then an added user is an `Invited` member: visible in pickers and assignable, but with no access.
+
+- `createOrgMember(orgId: ID!, email: String!, firstName: String!, lastName: String!, role: ..., projectIds: [ID!], teamIds: [ID!], sendInvite: Boolean)` — adds the person as an `Invited` seat right away so they can be assigned work before they've joined. `sendInvite: true` emails the invite link; existing Specset users get the in-app invitation either way. Returns the `OrgMember` (`status: Invited`).
+- `createOrgInvite(orgId: ID!, email: String!, role: ..., projectIds: [ID!])` — invite-only (no seat until they accept; no `teamIds`, so add teams once they have a seat); also used to (re-)invite an existing `Invited` seat. `projectIds` (optional, inline the list) pre-scopes a Member to specific projects. Set `role` deliberately — don't default people to more access than they need. Share the returned `inviteUrl` if the email might not land.
+- `orgInvites(orgId: ID!)` / `paginatedOrgInvites(orgId: ID!, first: Int, after: String)` — pending invites; select `{ id user { email } role inviteUrl }`.
 - `updateOrgInvite(id: ID!, role: ..., projectIds: [ID!])` — `role` is required.
-- `deleteOrgInvite(id: ID!)` — revoke a pending invite.
+- `resendOrgInvite(id: ID!)` — rotates the link and re-sends the email.
+- `deleteOrgInvite(id: ID!)` — revoke a pending invite (an `Invited` seat stays, as "Not invited"; `deleteOrgMember` removes the seat).
 
 ```bash
 specset api --query 'mutation($orgId: ID!, $email: String!) {
-  createOrgInvite(orgId: $orgId, email: $email, role: Member) {
-    id email role inviteUrl
+  createOrgMember(orgId: $orgId, email: $email, firstName: "Alex", lastName: "Rivera", role: Member, sendInvite: true) {
+    id status user { email }
   }
 }' -F orgId=<org-id> -F email=alex@example.com
 ```

package/plugin/specset/skills/specset-agent/SKILL.md

@@ -29,20 +29,157 @@ specset agent chat --project <projectId> -m "What mechanical equipment is schedu
 # Continue the same conversation (thread id is in the first response)
 specset agent chat --thread <threadId> -m "Which of those have submittals?"
 
+# Attach local files to a new conversation or a follow-up message
+specset agent chat --project <projectId> --file "RFI template.pdf" \
+  -m "Use this template to draft the RFI."
+
 # Review a past conversation
 specset agent show <threadId>
+
+# Download a generated document (artifact ids are included in agent show)
+specset agent export <artifactId> --format docx --out ./filled-rfi.docx
+specset agent export <artifactId> --format pdf --out ./filled-rfi.pdf
+
+# Pin the host and organization when inspecting a local test run
+specset agent show <threadId-or-link> --host https://app2.specset.dev --org <slug-or-id> --json
+
+# Super-admin: inspect the current system prompt, tools, and model-input messages
+specset agent inspect <threadId-or-link> --host https://app2.specset.dev --org <slug-or-id> --json
 ```
 
 Use `--json` for machine-readable output (all commands accept it). Long-running questions may need `--timeout <seconds>` — document analysis can take a few minutes.
 
+`--file <path>` uploads and attaches a file through the same processing flow as
+the app. Repeat it for multiple attachments; PDF, Word, Excel and image MIME types
+are inferred from the extension. It also works with `agent start` and with
+`chat --thread` to attach files to an existing conversation. The upload belongs to
+the thread's organization. Use `--detach` to return the thread id immediately
+while the attachment processing and response continue.
+
+`agent export` supports document artifacts in Word/PDF. Prepared templates retain
+their original formatting; other documents are rebuilt from their saved markdown.
+For documents edited in Pages, export in the app to preserve Pages layout,
+headers, and notes. Other artifact types have their own export formats in the app.
+A delegated draft has its own thread, so run `agent show` on the returned child
+thread to find its artifact id.
+
+Agent transcripts expose their source references as clickable `https://app.specbook.ai/go/...` links. Preserve the most relevant returned links as descriptive Markdown citations when relaying the answer to the user. Do not fabricate additional links from UUIDs. An identifier that is not an `https://` link (a thread-local short id or `doc:`-prefixed identifier) is internal — pass it back into commands verbatim, but never present it to the user as a clickable link. Both `--project` and `--thread` accept returned Specset links as well as UUIDs.
+
 Find a project id first if you don't have one:
 
 ```bash
-specset api --query 'query { projects { id name } }'
+specset projects list --json
+```
+
+## Starting a Review Session Directly
+
+Start a Quick Project Review investigation with an explicit brief and bounded
+scope. Project Review remains a superadmin-only option in the agent picker;
+shared organization and project access checks also apply.
+
+```bash
+specset agent start --type ProjectReview --project <projectId> --noAutoApprovePlan \
+  --title "Building coordination pilot" \
+  -m "Review Building 720.1 at Quick effort for cross-discipline coordination problems. Prioritize the strongest leads and report what you did not examine."
+specset agent show <threadId>
+specset agent approve <threadId> --tool finalizePlan --wait --timeout 1800
 ```
 
+Pin the same `--host` on each command for a development deployment. Inspect the
+short markdown plan before approving. Quick is the default: after approval, the
+root investigates directly with drawing, graph, specification and document tools,
+files issues, and reports examination limits. Standard and Deep use investigation
+workers within the approved budget. All efforts use the agentic review route. Server step
+backstops are not work targets or dollar caps; automatic issue verification follows
+project policy and adds separate cost.
+
+Drawing graph navigation is automatic for eligible projects. Use
+`drawings build-graph --project <projectId> --wait` only for an explicit rebuild.
+Inspect `getDrawingGraphOverview` bundles and quality flags before a benchmark;
+building the graph does not reprocess stale source nodes. `--autoApprovePlan`
+allows immediate execution when the brief is already approved.
+`agent approve --deny --reason "…"` rejects a pending proposal for revision.
+`agent stop <threadId>` cancels a running review and its descendants.
+
+Long-running agents — Design Review, Drawing Review, Design Quality Review, Structured Review, Submittal Log — can be started as their own session without going through a Conversation thread. `specset agent start` creates the thread with the given `--type`, titles it, seeds it with your kickoff instructions, and returns immediately with the thread id; the run continues on the server.
+
+```bash
+specset agent start --type DesignReview --project <projectId> \
+  --title "Building 720.1 - Design Review" --autoApprovePlan \
+  -m "Run a design review restricted to the Building 720.1 spec and drawing areas. Omit the master / no-area pass. Building 720.1's own specifications govern; Appendix A is a backup reference only."
+
+specset agent show <threadId>          # progress, transcript, findings so far
+
+# A Drawing Review runs graph-planned coordination checks; select them up front.
+specset agent start --type DrawingReview --project <projectId> \
+  --coordinationTaskTypes ElectricalDistribution,ArchitectureMepPenetrations \
+  --drawingArea "Building 720.1" --title "Building 720.1 - Coordination" \
+  -m "Coordinate the selected systems for Building 720.1."
+```
+
+- `--type` accepts any top-level agent type (`DesignReview`, `DrawingReview`, `DesignQualityReview`, `StructuredReview`, `SubmittalLog`, …). The kickoff message is the review's scope: name the building areas, disciplines, sections or sheets, what to exclude, and any special coordination checks — the same text a user would type when launching the review in the app.
+- `--type DrawingReview` also needs `--coordinationTaskTypes` (`all`, or a comma-separated subset of the 16 families: `CeilingOverhead`, `EquipmentPowerControls`, `LifeSafetyEgress`, `ArchitectureStructureOpenings`, `ArchitectureMepPenetrations`, `StructuralMepInterfaces`, `EnvelopeWaterproofing`, `FireLifeSafetyProtection`, `CivilSiteUtilities`, `ElectricalDistribution`, `MechanicalSystemsContinuity`, `PlumbingSystemsContinuity`, `StructuralSystemsContinuity`, `FireSuppressionSystemsContinuity`, `FireAlarmEmergencyCommunications`, `TechnologySecurityCommunications`). The server refuses a Drawing Review whose first message carries no scope, and the scope cannot change afterwards, so these flags apply only to new threads. `--drawingArea` limits the review to one building-scoped drawing area, and `--noDrawingArea` limits it to the sheets that belong to no drawing area (the site-wide set; exclusive with `--drawingArea`); `--coordinationTaskIds` narrows it to exact graph task ids for a bounded pilot or rerun (ids must belong to the selected families and area). `--executionIntent` decides how earlier reviews' runs of the same tasks are treated: `Reuse` (the default) answers a task from another review's completed run while the drawings it read are unchanged and leaves Blocked or Failed tasks alone (reported as incomplete), `RetryIncomplete` also re-runs those, and `Fresh` ignores earlier runs. The project needs a current drawing graph (`drawingCoordinationReviewAvailability.graphState` is `Ready`); otherwise the review cannot start.
+- `--debugTrace` writes the thread's agent transcript and drawing-coordination trace to the development server's `.local/debug` for an investigation. `--noDebugTrace` turns it off for a continued thread; omitting the flag preserves its setting. Both flags also work with `agent chat`.
+- Local Drawing Review kickoff uses the same required `--coordinationTaskTypes` and optional `--coordinationTaskIds` / `--drawingArea` flags as `agent start`. Pass them with the first message to `agent serve`; an existing thread keeps its original scope.
+- `--autoApprovePlan` skips plan sign-off. To inspect a plan before execution, pass `--noAutoApprovePlan`: this also disables the CLI's default blanket tool approval, so the session parks at `finalizePlan`. Approve it with `agent approve <threadId> --tool finalizePlan`. Omitting the flag preserves the existing plan setting, but blanket approval defaults on. `--isolateIssues` hides the project's pre-existing issues; `--noIsolateIssues` explicitly restores ordinary issue reads. `--reviewEffort Quick|Standard|Deep` sets a Project Review's effort: Quick investigates the strongest few leads on the root; Standard covers the brief within an approved worker budget; Deep covers the whole surveyed inventory. The plan states the expected worker count and estimated worker cost for approval. Omitting it keeps the thread's setting (Quick for a new thread).
+- `--scanParallelism <n>` sets a positive integer thread override for concurrent scan/coordination tasks (superadmin only). It uses the server's protected settings mutation, preserves other settings, and persists when later messages omit the flag. Each scan reads it at startup; changing it does not resize an already-running scan. For a scoped drawing-review benchmark, add `--scanParallelism 8` to the `agent start` command above or to `agent chat --type DrawingReview --timeout 2400`; select at least eight tasks to exercise that limit. It does not change the shared default or the review's internal visual/admission limits.
+- `--title` names the session in Agent Sessions. `agent start` is `agent chat --detach` for a new thread; use `chat --type … --timeout …` instead when you want to wait for a short run to finish.
+
 ## Notes
 
 - Keep one thread per topic: follow-ups via `--thread` give the agent the prior context and produce better answers than fresh threads.
 - The agent may propose changes (creating submittals, updating records) but those are applied through the Specset UI thread where the user approves them — CLI chat is best treated as read/analysis oriented. To make changes headlessly, use the mutations documented in the domain skills instead.
 - The agent answers from the project you scope it to; double-check the `--project` id when results look unrelated.
+
+For local drawing evaluations, add `--freshVisualReads` to `agent chat` or `agent start` to make every drawing examination a fresh response. It bypasses application response caching only in development; provider prefix discounts remain enabled. Use `--noFreshVisualReads` to restore normal behavior on that task.
+
+For the local comparison-reader arm, add `--drawingComparisonModel OpenAI6Astra` alongside `--freshVisualReads`. Only multi-view, region, or subject-window drawing examinations use Astra medium; single-view overviews keep normal routing. `--drawingComparisonModel Auto` clears that override on an existing task. This switch is ignored in production and does not change planner or worker reasoning models.
+
+## Run agent threads locally with your own Claude Code / Codex
+
+`specset agent serve` connects this machine to Specset. A conversation switched to **Execute locally** (conversation Settings) runs its model calls through the user's own coding harness (Claude Code or Codex) instead of a cloud model, while Specset keeps the agent loop, its tools, approvals and the transcript. Nothing else changes for the user: the thread stays the record.
+
+Install the Codex runtime once (Node.js 22 or newer); Claude uses the runtime bundled with the CLI:
+
+```bash
+specset harness install codex      # pins the native Codex runtime under ~/.specset/harness
+specset harness list               # what is installed, and which harness launched this shell
+```
+
+Codex uses `CODEX_PATH` when set, then `codex` on PATH, then the managed runtime. Claude uses the bundled SDK runtime, then `claude` on PATH. Log in to the harness itself first (`claude auth login`, `codex login`); provider failures such as an exhausted usage limit end the affected run with one visible error.
+
+**When the user asks to run a thread locally**, start the runner in the background so your own tool timeout does not cut it off, then check the thread:
+
+```bash
+specset agent serve --host <deployment> --org <slug> --harness codex &   # or --harness claude
+specset agent show <thread link>       # the transcript so far
+```
+
+What the harness spends is recorded on the thread as unbilled local usage (per model, priced for information only) and kept out of Specset's cost and credit figures.
+
+### Native tools and the run workspace
+
+Native tools are off by default: the harness only calls Specset functions, which the server authorizes and executes (approvals stay in the web app). Turn on **Native tools** in the conversation's Settings to let it also run shell commands and read, search or edit files. Each action is mirrored into the conversation as a local action card, and the thread's **Permissions** setting bounds what happens without asking: Read only, Accept edits, Auto (edits accepted, escalations reviewed) or Full access; for Codex these map to its sandbox (read-only, workspace-write, full access). Native sub-agents stay off; Specset's own sub-agent and fan-out tools run through the same machine.
+
+Each run (a root thread and its children) works in one private directory under `--directory` (`~/.specset/personal-runs/<runner>/runs/<thread>/` by default) with `specs/`, `drawings/`, `docs/`, `inputs/` and `out/`. It starts empty. The `specset` CLI is logged in inside the session as the user for that host and organization, so the harness downloads what it needs: `specset specs download <ref> --out specs/`, `specset drawings download <ref> --format pdf --out drawings/`, `specset docs download <ref> --out docs/`, `specset files download <ref> --out inputs/`, or `specset projects hydrate <project> --out . --include specs,drawings,docs` for a whole project. `.specset/manifest.json` records each file's Specset link, version id and checksum; repeating a download is idempotent and replaces a stale version. Findings cite the Specset link, never the local path.
+
+Files the harness writes under `out/` are the run's deliverables: after each turn that used native tools, and when the run ends, the runner uploads new or changed ones and attaches them to the root thread at their `out/…` path (a re-synced path replaces the earlier attachment). The workspace is removed once its run has ended (checked when the runner starts and stops and every ten minutes) or after seven untouched days; outputs that could not be attached keep the directory for a retry.
+
+Sessions are ephemeral (`persistSession: false` for Claude, `ephemeral: true` for Codex): a restarted runner needs a new machine assignment and starts fresh sessions seeded from Specset's transcript. A lost native continuation fails visibly rather than replaying writes or switching to a cloud model. This is a personal runner executing project content as the local OS user, not an OS sandbox: use a separate account or host for untrusted content.
+
+### Serve multiple local threads
+
+Connect to an organization with `specset agent serve --host <host> --org <slug|id>`; no project or thread is required. Enable **Execute locally** in conversation Settings. A sole eligible connected runner automatically receives your queued local request; with multiple connected runners, choose **Machine** in Settings. The connection command disappears once a machine is connected. Completed, stopped, or expired runs offer **Start a new local run** above the composer; viewing them does not restart them. `--thread <id>` immediately assigns an existing root; `--message "Review electrical coordination" --type DrawingReview --coordinationTaskTypes ElectricalDistribution` creates a local root in the selected project. `--org <slug|id>` pins the org; otherwise the selected org or sole membership on that host is used. Omit `--project` for organization scope, or supply a comma-separated project allowlist. A new message-created thread requires exactly one project. Omit `--harness` to use that host’s saved default or its sole available native runtime; ambiguity requires an explicit choice. Claude uses the CLI’s bundled SDK runtime, then native `claude` on PATH. Codex uses `CODEX_PATH`, native `codex` on PATH, then the managed native runtime from `specset harness install codex`. Startup checks that runtime before registering. Run a separate `serve --host <deployment>` process for each dev worktree. Each process prints and pins its host/org/harness at startup; later CLI host/org changes cannot redirect it. Login, selected org, and harness defaults are stored per host; execution limits apply per runner. For a bounded smoke test, add `--stopAfterIssues 2`; the root counts issues across its children and stops that tree when the threshold is reached (an in-flight batch can exceed it). Only this signed-in user can assign work, and children inherit the same machine, project scope, deadline and thread budget.
+
+`agent serve` uses server-owned orchestration: Temporal executes the agent and its tools, while model requests run through the connected machine. This includes generic drawing-coordination assessments, image inputs and structured output. The runner keeps a native session alive across each complete parallel tool batch and sends back the server's authorized results. All Specset approvals remain in the web app; native tools follow the thread's **Native tools** setting (see above) and native delegation stays off. Independent model requests use independent sessions. Claude uses `persistSession: false`; Codex uses `ephemeral: true`.
+
+For an unattended kickoff, `--autoApprovePlan` skips the plan sign-off and `--autoApprove` approves Specset tools for that message (default off for `serve`). `--isolateIssues` ignores pre-existing project issues when planning a bounded test. The command prints the created or assigned thread link. File attachments and file tool results preserve bytes, MIME type and optional filename through the same transport. Claude receives raw PDFs; Codex receives server-rendered PDF page images, capped at 20 pages per request across all PDFs. Both support image inputs and UTF-8 text attachments. Other binary formats fail explicitly until a compatible reader or conversion is available.
+
+Pin both `--host <deployment>` and `--org <slug>` when using `agent chat`, `agent start`, `agent show`, `agent inspect`, `agent approve` or `agent stop`; these overrides do not change the CLI’s saved selection.
+
+The conversation's Settings lists the models the connected machine reported (Codex's catalog, Claude's supported models) and pins one per harness for the thread, plus a reasoning effort from that model's reported levels (agent steps only; helper calls keep the harness default); `--model` on the machine pins one for every job and shows as fixed there. `--concurrency` defaults to 5 and limits active model calls; tool and approval waits release their slot so even 1 can complete nested fan-out. `--maxThreads` defaults to 100 and `--maxRunSeconds` to 3600 per root authorization. `--model` is fixed on the machine. Specset’s `--autoApprove` message setting controls tool approval; the thread's Permissions setting bounds native tools when they are on. Ctrl-C revokes the registration and stops queued/running descendants. A restart needs a new assignment. A lost native continuation fails visibly rather than replaying writes or switching to a cloud model.
+
+Harness tool callbacks can only wait for results supplied by the server. Each job receives private harness configuration and a minimal environment; with native tools on, that private home also holds a CLI login for the run's host and organization so `specset` works from the harness's shell. Claude shares the selected native credential store and its refresh lock. Codex uses an authentication-only native process to refresh the selected login, then supplies temporary access tokens to isolated inference sessions. Neither copies rotating refresh credentials into job homes. Settings, hooks, plugins and global MCP servers are excluded from inference sessions. Run `claude auth login` first if the harness reports authentication is required. It still runs as the local OS user, not inside an OS sandbox. Use a dedicated account or isolated host for untrusted project content; do not share this personal runner across users. This command requires the matching personal-runner and local-inference server APIs and ships in the next CLI release.
+
+Use `specset agent runners list --json` to inspect your registrations.
+Use `specset agent runners revoke <runner-id>` to stop and revoke one remotely, including an offline runner after a crash.