@specset/cli 0.6.0 → 2.0.0

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

@@ -9,7 +9,7 @@ allowed-tools: Bash Read AskUserQuestion
 How the data is shaped:
 
 - `status` (SubmittalStatus: `Draft | Open | Closed`) is the log lifecycle; `workingStatus` (SubmittalWorkingStatus: `Draft | Submitted | Pending | Approved | ApprovedAsNoted | Rejected | ReviseAndResubmit | ForRecordOnly | Void`) is the ball-in-court state. Set either — the server reconciles the other.
-- Revisions are separate submittal records sharing a `submittalNumber`; list and search queries return only the current revision.
+- Revisions are separate submittal records linked through `parentSubmittal` (the chain, not a shared number, defines a revision); list and search queries return only the current revision.
 - A submittal number is only unique per (spec section, number) within a project — the bare number alone is not.
 
 The sketches below are minimal — inline enums, ints, and lists in the operation text (`-F` is strings-only; Variable Limitations and Schema Discovery live in the `specset` skill).
@@ -39,7 +39,7 @@ Also available:
 
 - `paginatedSubmittals(projectId, search, limit: 25, offset: 0) { totalFilteredCount items { ... } }` — offset pagination with text search.
 - `searchSubmittals(projectId, search)` — lightweight lookup by number or title; use it for dedupe checks.
-- `submittalRevisions(projectId, submittalNumber, specSectionId)` — every revision of one number.
+- `submittalRevisions(id)` — every revision in the given submittal's chain (itself included), highest revision first.
 - `submittalTypes(projectId) { id name label }` — the project's configured types, for `submittalTypeId`.
 
 ## Creating
@@ -66,6 +66,8 @@ specset api --query 'mutation($id: ID!) {
 
 The revision string auto-increments (`0` → `1`, `A` → `B`); pass `revision` only when the document shows one that doesn't match. `autoReviewMode` works here too.
 
+A submittal created from a PDF that identifies an existing current submittal (same section and number, higher revision or a package that presents itself as a resubmittal) is linked as its next revision automatically. `unlinkSubmittalRevision(id) { id revision isCurrent parentSubmittal { id } }` detaches a wrongly linked row: it becomes a separate submittal with the number from its own document and the previous revision becomes current again.
+
 ## Attachments
 
 File ids come from Uploading Files in the `specset` skill.

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

@@ -6,7 +6,7 @@ allowed-tools: Bash Read AskUserQuestion
 
 # Specset Agent Tools (`specset tools`, `specset mcp`)
 
-These are the same read-only retrieval tools Specset's own in-app agent uses — exposed so external agents can call them directly. Everything here is read-only; nothing needs user confirmation.
+These are the same read-only retrieval tools Specset's own in-app agent uses — exposed so external agents can call them directly.
 
 ## When to use which surface
 
@@ -20,8 +20,9 @@ There are three tiers of Specset retrieval. Pick the lightest one that answers t
 
 ```bash
 specset tools list
-specset tools list --project <projectId|sb://project/...>
+specset tools list --project <projectId|https://app.specbook.ai/go/project/...>
 specset tools list --json     # full input schemas
+specset tools list --org <slug>   # catalog for an org other than the active one
 ```
 
 The listing includes usage guidance and marks project-scoped tools. The exact set depends on the org (closeout and schedule tools require their SKUs) and on whether a project is in scope.
@@ -40,42 +41,80 @@ specset tools run searchSpecSections \
 specset tools run searchSpecSections --project <projectId> \
   -F query="fire rating" -F keywords='["ASTM E119"]' -F limit=5
 
-# Read a specific section's full content using an ID from a search result
-specset tools run getSpecSectionContent -F id='sb://spec/....'
+# Read a specific section's full content using a source link from a search result
+specset tools run getSpecSectionContent \
+  -F id='https://app.specbook.ai/go/spec/<uuid>'
 ```
 
 Output is the tool's JSON payload (`{ success, message?, result? }`); a `{ success: false }` payload exits non-zero.
 
-### Identifiers are citation IDs, not links
+### Source links
 
-Tool results embed identifiers shaped like `sb://spec/<uuid>` or `sb://drawing/<uuid>`. Pass them back into other tools verbatim (e.g. into `getSpecSectionContent`, `getDrawingSheet`). They are citation identifiers, not web URLs.
+Tool results expose clickable links shaped like `https://app.specbook.ai/go/spec/<uuid>` or `https://app.specbook.ai/go/drawing/<uuid>`. Pass them back into other tools verbatim (for example, into `getSpecSectionContent` or `getDrawingSheet`). Include the most relevant returned links as descriptive Markdown citations in user-facing answers. Never invent a link or construct one from an unrelated UUID. An identifier that is not an `https://` link (a thread-local short id or `doc:`-prefixed identifier) is internal — pass it back into tools verbatim, but never present it to the user as a clickable link.
 
 ### Project scoping
 
-Most tools are project-scoped. Either pass `--project` (a UUID or `sb://project/...`), or include `projectId` in the tool input. Use `listProjects` to discover project IDs. With `--project` set, per-call `projectId` becomes optional.
+Most tools are project-scoped. Either pass `--project` (a UUID or returned `/go/project/...` link), or include `projectId` in the tool input. Use `listProjects` to discover projects. With `--project` set, per-call `projectId` becomes optional.
+
+Tools use the selected organization on the chosen host, or infer the sole membership when none is selected. Pass `--org <slug|id>` on `tools list` and `tools run` to pin a different org — required when the project belongs to an org other than the active one (the call otherwise fails with "Project … not found"), and safer in parallel sessions because the active org is shared config.
 
 ## Downloading source files (drawings, documents, specs, submittals, RFIs)
 
-The retrieval tools return **extracted text**, which is authoritative for schedules, notes, and spec paragraphs — but cannot answer spatial/visual questions (routing, clearances, what a plan view actually shows) and never carries the original file. Every entity has a download command, and **each accepts its `sb://` citation URL verbatim** (as returned by issues, search, and tool results — any `#page=`/`#nodeId=` fragment is ignored) or a bare UUID:
+The retrieval tools return **extracted text**, which is authoritative for schedules, notes, and spec paragraphs — but cannot answer spatial/visual questions (routing, clearances, what a plan view actually shows) and never carries the original file. Every entity has a download command, and **each accepts its returned Specset `/go` link verbatim** (citation focus parameters are ignored for downloads) or a bare UUID:
 
-| Entity         | Command                                           | Also accepts                                     | Formats / options                                                                                                                       |
-| -------------- | ------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| Drawing sheets | `specset drawings download 'sb://drawing/<uuid>'` | sheet number + `--project`                       | `--format image` (rendered PNG, default), `pdf` (single sheet), `file` (whole set)                                                      |
-| Documents      | `specset docs download 'sb://doc/<uuid>'`         |                                                  | also covers RFI attachments and closeout documents                                                                                      |
-| Spec sections  | `specset specs download 'sb://spec/<uuid>'`       | section number (e.g. `'23 31 19'`) + `--project` | per-section PDF slice (default), `--asset book` (whole source spec file)                                                                |
-| Submittals     | `specset submittals download 'sb://sub/<uuid>'`   |                                                  | compiled package (default when present); `--list` shows the asset inventory; `--asset attachment --index 2`, `--asset attachment --all` |
-| RFIs           | `specset rfis download 'sb://rfi/<uuid>'`         |                                                  | question + response attachments; `--list`, `--all`                                                                                      |
-| File resources | `specset files download 'sb://file/<uuid>'`       |                                                  | escape hatch when you already hold an `sb://file` id                                                                                    |
+| Entity         | Command                                                                 | Also accepts                                     | Formats / options                                                                                                                       |
+| -------------- | ----------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Drawing sheets | `specset drawings download 'https://app.specbook.ai/go/drawing/<uuid>'` | sheet number + `--project`                       | `--format image` (rendered PNG, default), `pdf` (single sheet), `file` (whole set)                                                      |
+| Documents      | `specset docs download 'https://app.specbook.ai/go/doc/<uuid>'`         |                                                  | also covers RFI attachments and closeout documents                                                                                      |
+| Spec sections  | `specset specs download 'https://app.specbook.ai/go/spec/<uuid>'`       | section number (e.g. `'23 31 19'`) + `--project` | per-section PDF slice (default), `--asset book` (whole source spec file)                                                                |
+| Submittals     | `specset submittals download 'https://app.specbook.ai/go/sub/<uuid>'`   |                                                  | compiled package (default when present); `--list` shows the asset inventory; `--asset attachment --index 2`, `--asset attachment --all` |
+| RFIs           | `specset rfis download 'https://app.specbook.ai/go/rfi/<uuid>'`         |                                                  | question + response attachments; `--list`, `--all`                                                                                      |
+| File resources | `specset files download 'https://app.specbook.ai/go/file/<uuid>'`       |                                                  | escape hatch for a returned file source link                                                                                            |
 
 All commands support `--json` (structured `{files: [{path, bytes, ...}]}` output) and `--out` (file path, or directory for multi-file downloads). A citation passed to the wrong command errors with the right one to use.
 
+`drawings download` also accepts `--org <slug|id>` to pin the source organization when parallel sessions might change the active organization, for example `specset drawings download P2.120 --project <id> --org specbook --host <host> --format pdf`.
+
+To inspect an existing detail crop, add `--node <shortId|UUID>`, for example `specset drawings download <sheet-ref> --node d6 --format image --out detail.png`. Use `--format pdf` for the saved crop PDF. This downloads the current revision's stored crop without regenerating it; missing nodes or crops return an error. Node crops do not support `--format file`. JSON output adds the resolved `nodeId` to the normal sheet download metadata.
+
+Its JSON result includes `sheetId` and `revisionId` for the downloaded source. Compare the revision with any previously retrieved content before using that content's coordinates to crop the download.
+
 Typical loop for drawings: search or `getDrawingSheetContent` to find the sheet → hit a visual question the text can't settle → `drawings download` → read the PNG to inspect the geometry.
 
+### Drawn elements: what a drawing view prints, with positions
+
+Before downloading a plan to read a tag or a value off it, check the sheet's **drawn elements**: every printed string on each Drawing node with a 0–1000 box on the node's crop (the ledger), and the tags, runs, connections, cross-references, and printed limits typed from those strings. Each typed element cites ledger rows (`d1a12` = row 12 of node `d1`), so the printed text and its box are always the row's.
+
+```bash
+specset drawings elements show 'https://app.specbook.ai/go/drawing/<uuid>'            # per node: read/typing status, counts, tags, runs, connections, references, limits, keynotes
+specset drawings elements show E6.00 --project <id> --node d1 --grep 800AT             # rows and elements whose text contains 800AT (implies --rows)
+specset drawings elements show E6.00 --project <id> --rows --json                       # every row with kind, box, grid cell, rotation, cloud/revision flags
+```
+
+Read the status line first. A successful ledger read is evidence of printed text; absence claims also need the applicable completeness, recall, revision-cloud and source-coverage gates. Partial reads or unchecked coverage need visual confirmation. A version match alone does not mean a failed extraction succeeded.
+
+Graph tools are automatically available with `--project` for eligible projects (every current drawing sheet uses extraction version 5 or newer; empty projects also qualify). Graphs refresh automatically. To request an immediate rebuild from existing extracted content:
+
+```bash
+specset drawings build-graph --project <id> --wait --timeout 1800 --host <host> --json
+```
+
+Omit `--wait` to return after requesting the build. Waiting confirms a newly persisted graph snapshot, not complete ingestion or review readiness; inspect the returned statistics and `getDrawingGraphOverview` for stale nodes and bundles before reviewing. The server build continues after a timeout, so inspect the overview before requesting another build. This does not reprocess drawings. The command requires the existing `resolveProjectDrawingGraph` and `projectDrawingGraph` server API; it and these instructions ride the next CLI release.
+
+Use `getDrawingGraphOverview` to discover bundle keys, `getCoordinationBundle` for their views, `traverseDrawingReferences` for callout links, and `findDrawingGraphElements` for labeled, schedule-derived assets and rooms. For graphical devices, including unlabeled glyphs, use the candidate symbol lookup when ingestion and a graph rebuild have populated it:
+
+```bash
+specset tools run findDrawingGraphSymbols --project <id> --host <host> \
+  -F canonicalTypes='["LightFixture","Sprinkler"]' -F sheetNumber=A5.01 -F limit=20
+```
+
+It returns source-linked boxes and their supporting legend definitions. You can also filter by `drawingArea`, `nodeId`, or a `scopeKey` returned by `getDrawingGraphOverview`; follow `nextOffset` when `hasMore` is true. These are incomplete candidate observations: zero results do not establish absence, matching types do not link devices across views, and returned counts are not verified physical totals. Confirm an issue-bearing interpretation by downloading and inspecting the source drawing with `specset drawings download <returned-link>`. The in-app visual analysis tool `examineDrawingSheets` is not exposed to external callers.
+
 ## MCP servers (local and hosted)
 
 The same server-side tool registry is available through two transports:
 
-- `specset mcp` is the local stdio transport for Claude Code, Codex, and other clients with shell access. It reuses the CLI login and active organization.
+- `specset mcp` is the local stdio transport for Claude Code, Codex, and other clients with shell access. It reuses the CLI login. Pass `--org <slug|id>` to pin the organization, or use the selected org / sole membership on the chosen host.
 - `https://<specset-host>/mcp` is the stateless Streamable HTTP transport for hosted MCP clients. Its OAuth 2.1 consent flow selects an organization and binds it into the grant, so hosted clients must not put `orgId` in the connection URL. Add `projectId=<project-id>` to pin project scope.
 - First-party clients may instead supply a Specset session bearer token and select the organization with `x-org-id` (or the legacy `orgId` query parameter).
 
@@ -84,8 +123,8 @@ Register the local transport once and the client can call the tools directly:
 ```bash
 # Claude Code
 claude mcp add specset -- specset mcp
-# Optionally pin a project and/or host:
-claude mcp add specset -- specset mcp --project <projectId> --host https://app.specbook.ai
+# Optionally pin organization, project and host:
+claude mcp add specset -- specset mcp --org <slug> --project <projectId> --host https://app.specbook.ai
 
 # Codex
 codex mcp add specset -- specset mcp
@@ -99,6 +138,6 @@ Notes:
 - The hosted transport additionally exposes `uploadFile` (OpenAI host file parameters, streamed into Specset storage) and `getFileDownload` (an MCP resource link backed by a short-lived signed URL). The underlying retrieval tools are still the same allowlisted registry used by stdio.
 - The hosted transport advertises standards-compliant MCP OAuth 2.1 protected-resource and authorization-server metadata. It supports Client ID Metadata Documents, PKCE, resource/audience binding, scoped tools, short-lived access tokens, and rotating refresh tokens.
 
-## Stability
+## Scripting
 
-This surface is experimental — tool names and input schemas may change. For automation you need to keep stable, prefer the typed `search` / `quickSearch` GraphQL queries in the `specset-search` skill.
+Tools are discovered at runtime (`specset tools list`, MCP `tools/list`), and their descriptions and inputs are tuned for agents. For scripts that depend on a fixed response shape, use the typed `search` / `quickSearch` GraphQL queries in the `specset-search` skill.

package/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/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/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.