@specset/cli 1.0.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specset/cli",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Command-line interface for Specset — authenticate, run GraphQL queries, and chat with Specset project agents.",
   "license": "Elastic-2.0",
   "homepage": "https://specset.com",
@@ -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,6 +1,6 @@
 {
   "name": "specset",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Search and manage Specset construction project data with shared skills and MCP tools.",
   "author": {
     "name": "Specset"

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

@@ -1,6 +1,6 @@
 {
   "name": "specset",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Search and manage Specset construction project data with shared skills and MCP tools.",
   "author": {
     "name": "Specset",
@@ -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/skills/specset/SKILL.md

@@ -31,13 +31,15 @@ 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 preserves the raw JSON GraphQL envelope (`{ data, errors }`) — non-zero exit on HTTP errors or `errors[]`.
@@ -59,6 +61,14 @@ 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.
@@ -116,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,22 +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.

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

@@ -164,9 +164,163 @@ Other lifecycle operations:
 
 ## Entity Documents and Documentation
 
-Location, Product, Company, System, and Warranty link project Documents through entity-specific role-tagged pivots. Read `<entity>Documents(<entity>Id)`, then call `set<Entity>DocumentRoles(<entity>Id, documentId, roles)` after introspecting that entity's role enum. An empty role list removes the pivot and may delete the underlying Document when it becomes orphaned. Asset is the exception: it exposes `assetDocuments(assetId)` and `deleteAssetDocument(id)`, but no set-roles mutation.
+Asset, Location, Product, Company, System, and Warranty link project Documents through entity-specific role-tagged pivots. Read `<entity>Documents(<entity>Id)`, then call `set<Entity>DocumentRoles(<entity>Id, documentId, roles)` after introspecting that entity's role enum (`AssetDocumentRole`, `ProductDocumentRole`, `SystemDocumentRole`, `LocationDocumentRole`, `CompanyDocumentRole`, `WarrantyDocumentRole`). The roles array is replaced atomically; an empty role list removes the pivot and may delete the underlying Document when it becomes orphaned. Asset also exposes `deleteAssetDocument(id)`.
 
-Asset, Location, Product, Company, and System also have markdown documentation blocks. `update<Entity>Documentation(id, markdown)` replaces the block; `mark<Entity>DocumentationComplete(id)` attests that it is current.
+Attaching a new file is a three-step flow — the same Document can then be linked to several entities (a family IOM shared by every product in the family):
+
+```bash
+CLOUD_FILE=$(specset files upload ./aaon-rn-iom.pdf --type application/pdf --json | jq -r .id)
+specset api --query "mutation { createDocumentsFromCloudFiles(cloudFileIds: [\"$CLOUD_FILE\"], projectId: \"<project-id>\") { id title } }"
+specset api --query 'mutation { updateDocument(id: "<document-id>", title: "AAON RN Series — IOM") { id } }'   # title drives lists and PDF bookmarks; the default is the filename
+specset api --query 'mutation { setProductDocumentRoles(productId: "<product-id>", documentId: "<document-id>", roles: [OperationManual, MaintenanceManual]) { id } }'
+```
+
+Existing project Documents work too — a submittal attachment's `document { id }` (from `paginatedSubmittals … attachments { document { id title } }`) can be linked directly as `SubmittalPackage`/`Datasheet`; the only check is that the Document belongs to the same project. To bind a slice of a large file, `extractPagesFromFileResource(id: <fileResourceId>, pages: [3, 4, 5])` returns a new CloudFile to feed into `createDocumentsFromCloudFiles`. Only PDF files merge into the O&M package export; images and other types are listed as references.
+
+Asset, Location, Product, Company, and System also have markdown documentation blocks. `update<Entity>Documentation(id, markdown)` replaces the block; `mark<Entity>DocumentationComplete(id)` attests that it is current. Any later create/update/link on the entity (a new document pivot, a warranty document, a field edit) marks the documentation stale again, so when seeding a graph write documentation **last**. Calling `mark<Entity>DocumentationComplete` with an empty block sets the state to `NotApplicable`, which the package readiness report accepts — use it for entities that don't warrant prose rather than writing filler.
+
+### Writing documentation that reads well in the O&M package export
+
+The rules below are the same ones the in-app documentation agent follows (they are one shared block; a test keeps this copy in sync).
+
+### Where Documentation Renders
+
+The documentation block renders on the entity's show page and in the compiled O&M closeout package PDF — a formal handover manual the owner's facilities team keeps for decades. The manual already prints the following from structured data, so documentation never restates it:
+
+- Identity: tag, serial number, status, install and commissioning dates, quantity, location path, manufacturer, model, spec section, classification, data-package tier.
+- Warranties: kind, start and expiration dates, duration, claims contact and the terms text.
+- Maintenance schedule: every plan, procedure, frequency, craft and estimated hours, built from the maintenance plan records.
+- Spare parts: name, SKU, manufacturer part number, quantity and vendor, from the part records.
+- Contacts: the responsible company with phone and email, plus a per-system contacts rollup.
+- Linked documents: every datasheet, manual, warranty and report, listed and bound directly behind the entity's page.
+
+### What to Write
+
+Spend the narrative on what tables cannot say: sequences of operation with real setpoints, startup and shutdown, seasonal and emergency procedures, troubleshooting, safety warnings, cross-system interfaces, and callouts where sources conflict. Describe the equipment, not the records — state how it works and how it is cared for, and fold genuine unknowns into one short "Open Items" list, one line each, without citations. A short block with two real sections beats a full template of filler: omit every section the sources don't genuinely cover, and leaving the block blank is a valid outcome for an entity with nothing to add.
+
+Write for the building operator in plain language. Paraphrase manual procedures as proper markdown lists, and fix concatenation artifacts (double periods, misspelled manufacturer names) from sources.
+
+Keep the block free of what the manual already prints and of anything that goes stale:
+
+- No warranty terms or dates in prose, no frequency lists or task inventories, no tag/serial/model/quantity dossiers, no contractor names or phone numbers, and no parts tables pasted from manuals — replacement-parts data belongs in part records.
+- No claims about the state of the records ("no dates are populated", "this task is recorded on the checklist") — they end up contradicting the printed tables.
+- No restatement of the entity's `description` field as the opening — both print in sequence.
+- No internal vocabulary ("portal", "normalized", "occurrence basis", "identity guard", "MaintenanceTask", "sourceMarkdown"), entity UUIDs, or extraction and slug references.
+- No all-caps sentences or blockquote dumps of manual text, and no sections whose only content is "not established in reviewed source" or "see the linked manual".
+
+### Citations
+
+Citations are clickable in the app and plain text in the printed manual, so keep them sparse and short: at most one per section, placed at the end of the claim it supports, as a markdown link whose display text is a short label such as "Siemens O&M p. 712" or "Warranty Table p. 5". Use citation URLs exactly as returned by the tools. The entity's bound-documents list already anchors provenance, so there are no per-sentence citations, multi-citation parentheticals, full source filenames, paragraph numbers, spreadsheet cell references, or dedicated "Source:" lines (print strips those).
+
+### Headings
+
+The entity name renders as the page title, the block is embedded under a "Documentation" heading on the show page, and it may be re-rendered inside a parent entity's hierarchical view, so heading levels must compose:
+
+- Top-level sections use `##`; sub-sections use `###`, then `####`, without skipping levels.
+- Begin with the first content section (for example `## Description`). The entity's own name is never a heading and `#` is never used — that level is the page title, and a leading H1 matching the entity name is suppressed in print.
+- Keep section names consistent with the templates below so sibling entities render with the same structure.
+
+### Section Templates
+
+Use these section orderings with the operator-facing names shown; most entities warrant only one to three of them.
+
+**Product** — the canonical home for manufacturer operating knowledge. A product with any linked submittal, datasheet, manual or warranty document gets a block; only a product with no linked source documents is left blank. Location and system blocks may roll product knowledge up but never replace it.
+
+```markdown
+## Description        (1-3 sentences: what it is and its role — not metadata)
+## Operation          (sequence of operation, setpoints, modes, interlocks)
+## Routine Maintenance (procedure steps and precautions — never frequencies; the schedule table prints those)
+## Troubleshooting
+## Safety
+## Open Items
+```
+
+**System** — the system in its own words, spanning multiple products. A parent system covers only what is true of the whole (shared operation, shared safety): the manual prints the subsystems list and rolls up schedules, warranties and contacts, so content common to sibling systems lives once on the parent and each child gets at most one sentence of scope.
+
+```markdown
+## Description        (what the system is and its boundary, 2-4 sentences)
+## Sequence of Operation
+## Interfaces         (only real cross-system relationships: what feeds, releases, or controls what)
+## Seasonal & Emergency Procedures
+## Troubleshooting
+## Safety
+## Open Items
+```
+
+**Location** — building or area overview.
+
+```markdown
+## Description
+## Access & Safety
+## Open Items
+```
+
+**Asset** — installation-specific facts only; most assets need very little.
+
+```markdown
+## As-Installed Configuration  (field settings, orientations, connections not captured by structured fields)
+## Commissioning Notes
+## Open Items
+```
+
+**Company** — only what the contacts block cannot carry.
+
+```markdown
+## Escalation
+## Supplier Portal
+```
+
+### Example (Product)
+
+```markdown
+## Description
+Passive rubber check valves preventing backflow from rivers, oceans, and storm water into outfall lines.
+
+## Operation
+Flow opens the bill section; back-pressure closes it. No power or operator action required. Do not exceed 25 psi back-pressure [Manual p. 3](sb://doc/...).
+
+## Routine Maintenance
+1. Clear debris from the bill opening.
+2. Inspect the elastomer for cuts or abrasion; replace on any through-cut.
+
+## Troubleshooting
+Standing water upstream usually means debris is holding the bill open — clear before assuming valve failure.
+```
+
+## Parts and Meter Readings
+
+`createPart(input: { projectId, name, sku, manufacturerPartNumber, unit, quantity, minQuantity, maxQuantity, unitCost, stocked, bin, vendorId, assetLinks: [{ assetId, quantity }] })` creates a stocked part with its per-asset quantities; `createPartMovement(input: { partId, quantity, note })` records receipts (positive) and consumption (negative), and `countedQuantity` records a cycle count. Read with `paginatedParts(projectId, filters)`.
+
+`logMeterReading(assetId, unit: Hours|Cycles, value, readAt)` records a runtime or cycle reading; meter-triggered plan tiers (`meterUnit`/`meterThreshold`) generate work from these. `meterReadings(assetId, unit, limit)` lists them.
+
+## Closeout Packages (O&M manual export)
+
+A closeout package compiles the graph into one bookmarked PDF: front matter (cover, directory, warranty log, hyperlinked TOC), a slip sheet and overview per system (or location), a data page per asset, and every linked PDF document bound behind its owner (each unique file once). Scope is `Project` (everything), `Systems`, `Assets`, or `Locations` with `targetIds`; `orderingAxis` is `System` (default) or `Location`.
+
+Check readiness first — it is deterministic and the same builder the compile uses, so a clean report means a clean manual:
+
+```bash
+specset api --query '{ closeoutPackageReadiness(projectId: "<project-id>", scopeKind: Project) { warningCount warnings } }'
+```
+
+Warning kinds and how to clear them: `DocumentationMissing`/`DocumentationOutdated` (write or mark documentation complete on the named Asset/Product/System/Location), `AssetFieldMissing` (serial number or install date), `WarrantyMissing` (every asset needs at least one Warranty), `ProductManualMissing` (each Product needs an `OperationManual` or `MaintenanceManual` document), `PlanWithoutProcedure` (a plan with no tiers), `AttachmentNotMergeable` (non-PDF), `TargetDeleted`. `EmptyScope` blocks creation.
+
+```bash
+specset api --query 'mutation { createCloseoutPackageExport(input: { projectId: "<project-id>", scopeKind: Project, orderingAxis: System, includeAttachments: true, title: "… O&M Manual" }) { id workflow { status } } }'
+specset api --query '{ closeoutPackageExport(id: "<export-id>") { completedAt warnings workflow { status progress error } fileResource { id name } } }'
+specset files download <file-resource-id> --out manual.pdf     # once workflow.status is Completed
+```
+
+`paginatedCloseoutPackageExports(projectId)` lists prior exports; exports are immutable records — regenerate by creating a new one; `deleteCloseoutPackageExport(id)` removes one and its file. In the app the same flow lives under the project's Closeout → Packages page.
+
+## Enabling closeout
+
+`CloseoutAuthService.isCloseoutActive` requires the org SKU **and** (unless the org is in `fmMode`) the project toggle. Both are superadmin operations; `updateOrg(skus)` replaces the whole SKU object, so read the current flags and resend them:
+
+```bash
+specset api --query '{ org(id: "<org-id>") { skus { closeout fmMode dailyLog scheduling estimation agentSessions agentSkills customAgents whitelabel modelRoutingV2 } } }'
+specset api --query 'mutation { updateOrg(id: "<org-id>", skus: { closeout: true, dailyLog: true, scheduling: true }) { id } updateProject(id: "<project-id>", toolSettings: { closeout: true }) { id } }'
+```
 
 ## Dedup / Re-pointing
 

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

@@ -0,0 +1,27 @@
+---
+name: specset-issues
+description: Use when working with a Specset project's design-review issues from the CLI — listing the queue by severity, tier, or verification state, and reading each issue's verdict.
+allowed-tools: Bash Read AskUserQuestion
+---
+
+# Specset Issues
+
+Design reviews (Design Review, Drawing Review, Design Quality Review, Project Review) and issue-finding skills file **issues** on a project. Each issue can be **verified** by an adversarial agent that re-reads the cited sheets and sections and records a verdict — `Confirmed` or `Rejected` — with a short justification. New review issues are verified automatically; skill-run issues, issues filed before verification existed, and issues whose runs ended without a verdict are verified on demand.
+
+## Reading the queue
+
+```bash
+specset issues list --project <projectId>                                   # active, non-Cleanup issues
+specset issues list --project <projectId> --severity High,Medium --notVerified --limit 500
+specset issues list --project <projectId> --thread <reviewThreadId> --json  # one review's findings
+specset issues list --project <projectId> --thread <runThreadId> --org <slug>  # a skill run, by the id agent chat printed
+```
+
+- `--severity` takes a comma list (`High`, `Medium`, `Low`); `--notVerified` keeps only issues with no verdict; `--archived` switches to the archived set.
+- `--thread` matches the thread and every review thread under it: a skill's issues belong to its delegated review, so the run id `specset agent chat` prints finds them directly. `--org` pins the organization like the other commands.
+- Cleanup-tier issues (real but self-resolving, kept out of the review queue) are excluded unless you pass `--includeCleanup` — the same rule the app's default queue uses.
+- The table shows `#number severity tier verdict title`; `verdict` is `Confirmed`, `Rejected`, `verifying` (run in flight) or `unverified`. `--json` returns the full rows including the originating review thread.
+
+## Verification
+
+Verdicts come from the app's own verification runs: new review issues are verified automatically, and a member can start verification for an individual issue from the issue in the app. `specset issues list` shows the verdict on every row (`--notVerified` to find the ones still waiting).