@specset/cli 0.4.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specset/cli",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Command-line interface for Specset — authenticate, run GraphQL queries, and chat with Specset project agents.",
   "license": "Apache-2.0",
   "homepage": "https://specset.com",

package/skills/specset/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: specset
-description: Core CLI for Specset — install or update the CLI, authenticate with a browser or device code, switch organizations, and run GraphQL with `specset api`. Start here for any Specset task, and whenever a specset command fails with auth or org errors.
+description: Core CLI for Specset — install or update the CLI, authenticate with a browser or device code, switch organizations, and run GraphQL with `specset api`. Start here for CLI setup or raw GraphQL access, and whenever a specset command fails with auth or org errors.
 allowed-tools: Bash Read AskUserQuestion
 ---
 
@@ -29,56 +29,12 @@ This is the core skill — setup and mechanics only. Domain workflows live in si
 
 ## First-Run Setup
 
-Perform this setup yourself 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.
+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. Ensure the CLI is installed and current. Installing or updating an agent skill/plugin does not upgrade an existing global npm package. Check the installed and published versions:
-
-```bash
-specset --version 2>/dev/null || true
-npm view @specset/cli version
-```
-
-If `specset` is missing or its version is older than the published version, update it and verify the result:
-
-```bash
-npm install -g @specset/cli@latest
-specset --version
-```
-
-Requires Node.js 20+ with npm. If `npm` itself is missing, stop and ask the user to install Node.js (https://nodejs.org) first. Do not replace a source-linked development CLI when its version is newer than npm.
-
-2. Check authentication with `specset auth status`. If not logged in, choose the login mode based on whether the user can see a browser opened by this environment.
-
-**If a visible browser is unavailable** — including remote or in-app agent sessions, SSH, containers, and CI — use device authentication from the outset:
-
-```bash
-specset login --device
-```
-
-It prints a short code and a link (`https://<host>/device?code=XXXX-XXXX`). Show both to the user and ask them to open the link on any device and approve; the command completes on its own once they do. The code expires after 15 minutes — if it does, run the command again for a fresh one.
-
-When a visible browser is available on the same machine, use the browser flow and tell the user to complete sign-in there while the command waits:
-
-```bash
-specset login
-```
-
-Login is interactive by design — never try to bypass it or handle credentials directly. Don't launch a login mid-task without telling the user what's happening.
-
-3. Pick the active organization (required for org-scoped queries):
-
-```bash
-specset org list
-specset org use <slug>
-```
-
-If the user belongs to exactly one org, select it; otherwise ask which to use.
-
-4. Confirm everything is ready:
-
-```bash
-specset auth status
-```
+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.
+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.
 
@@ -109,34 +65,17 @@ GQL
 
 ### Schema Discovery
 
-Discover the API shape through introspection queries:
+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:
 
 ```bash
-# Top-level queries
-specset api --query '{ __schema { queryType { fields { name description } } } }'
-
-# Fields on a specific type
 specset api --query '{ __type(name: "Project") { fields { name type { name kind ofType { name } } } } }'
-
-# Input object shape
-specset api --query '{ __type(name: "CreateSubmittalInput") { inputFields { name type { name kind ofType { name } } } } }'
 ```
 
-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.
+The same pattern works for input objects (`inputFields`) and the top-level surface (`{ __schema { queryType { fields { name description } } } }`).
 
 ## Agent Tools and MCP
 
-Beyond raw GraphQL, the CLI exposes Specset's own retrieval tools — semantic and keyword search over specs, drawings, submittals, RFIs, documents (plus closeout and schedule where enabled) — for an AI agent to call directly. Reach for these when you want the actual content to reason over, not just record previews.
-
-- **As commands:** `specset tools list` to see what's available, then `specset tools run <name> --input '{...}'` (or `-F key=value`).
-- **As a native MCP server:** `specset mcp` runs a stdio MCP server that surfaces these tools to an MCP client, reusing your CLI login, org, and host. Register it once:
-
-```bash
-claude mcp add specset -- specset mcp      # Claude Code
-codex mcp add specset -- specset mcp       # Codex
-```
-
-See the `specset-tools` skill for the full workflow — project scoping, the `-F` JSON-parsing difference, 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 the `sb://` citation convention.
 
 ## Uploading Files
 
@@ -187,19 +126,11 @@ specset api --query 'query($id: ID!) {
 
 Processing large PDF sets takes minutes; poll every 15–30 seconds and tell the user what's in flight rather than blocking silently.
 
-## Safety Rules
+## Safety
 
-- Default to read-only queries.
-- Confirm with the user before executing mutations that create, update, or delete data.
-- Never hardcode credentials in commands — the CLI manages tokens via OAuth.
-- Tokens live in `~/.config/specset/config.yml`; do not echo or copy that file's contents.
+Confirm with the user before executing mutations that create, update, or delete data. The domain skills note the mutations with non-obvious consequences.
 
 ## Troubleshooting
 
-- `command not found: specset` — run the First-Run Setup above.
-- `Not logged in` — run `specset login` (opens the user's browser; tell them to complete sign-in there).
-- `No active organization selected` — run `specset org list`, then `specset org use <slug>`.
+- 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>`.
-- Login hangs or the browser can't reach this machine (SSH, container, CI) — use `specset login --device`: it prints a code + link the user approves from any device.
-- `specset --version` is older than `npm view @specset/cli version`, or a documented flag is missing — run `npm install -g @specset/cli@latest`, then verify with `specset --version`.
-- After upgrading the CLI (`npm i -g @specset/cli@latest`), refresh the skills with `specset skill install --target <claude|codex|chatgpt>`.

package/skills/specset-admin/SKILL.md

@@ -6,9 +6,7 @@ allowed-tools: Bash Read AskUserQuestion
 
 # Org Administration
 
-Requires the `specset` CLI, logged in with an active org. If a command fails with `command not found`, `Not logged in`, or `No active organization`, follow First-Run Setup in the `specset` skill.
-
-Every operation here takes your org id — get it with `{ me { orgMembers { org { id slug name } } } }` if you don't have it. Remember Variable Limitations in the `specset` skill: inline enums, lists, and input objects as literals in the operation text; reserve `-F` for ids and plain strings. When an operation or argument doesn't match this document, introspect (see the `specset` skill → Schema Discovery) rather than guess. These mutations change real people's access and the whole org's appearance — confirm each one with the user before running it.
+Every operation here takes your org id — get it with `{ me { orgMembers { org { id slug name } } } }` if you don't have it. Inline enums, lists, and input objects in the operation text (`-F` is strings-only; Variable Limitations and Schema Discovery live in the `specset` skill). These mutations change real people's access and the whole org's appearance.
 
 ## Members
 
@@ -35,7 +33,7 @@ Manage them (all take the **membership** id from the queries above, not the user
 
 - `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.
 - `approveOrgMember(id: ID!)` — activate a `PendingApproval` member.
-- `deactivateOrgMember(id: ID!)` / `reactivateOrgMember(id: ID!)` — suspend and restore access. Deactivation is reversible and preserves history — always prefer it over any form of member deletion.
+- `deactivateOrgMember(id: ID!)` / `reactivateOrgMember(id: ID!)` — suspend and restore access. Deactivation is reversible and preserves history — prefer it over any form of member deletion.
 
 ```bash
 specset api --query 'mutation($id: ID!) {
@@ -88,7 +86,7 @@ specset api --query 'mutation($id: ID!) {
 }' -F id=<org-id>
 ```
 
-Pick a `brand` dark enough to hold white text (roughly: not a pastel) — it becomes button and link color on white backgrounds. Branding applies to every member of the org, so confirm the palette with the user before writing it.
+`brand` becomes the button and link color on white backgrounds, so it needs to hold white text. Branding applies to every member of the org — confirm the palette with the user before writing it.
 
 ### Logos
 
@@ -109,8 +107,6 @@ Use `logoId: $fileId` for the square mark. Passing `null` (inline) clears a slot
 
 ## Safety
 
-- Confirm every mutation before running it. For role changes, deactivations, and invite deletions, echo the affected person's email back to the user first — these change real access immediately.
-- Prefer `deactivateOrgMember` over anything destructive; never hard-delete a membership.
-- Never pass `maxCredits` or `skus` to `updateOrg` — those fields are managed by Specset and the mutation will be rejected.
-- On `updateOrg`, send only the fields you mean to change (plus the full `appearance` object when changing any part of it).
+- For role changes, deactivations, and invite deletions, echo the affected person's email back to the user first — these change real access immediately.
+- `updateOrg` rejects `maxCredits` and `skus` — those fields are managed by Specset. Send only the fields you mean to change (plus the full `appearance` object when changing any part of it).
 - Creating or deleting organizations, SSO, and email-domain management are out of scope for this skill — direct the user to support@specset.com.

package/skills/specset-agent/SKILL.md

@@ -6,8 +6,6 @@ allowed-tools: Bash Read AskUserQuestion
 
 # Specset Agent Chat
 
-Requires the `specset` CLI, logged in with an active org. If a command fails with `command not found`, `Not logged in`, or `No active organization`, follow First-Run Setup in the `specset` skill.
-
 Specset runs its own project-aware AI agent with full access to a project's specs, drawings, submittals, RFIs, and closeout data. `specset agent chat` sends it a message and waits for the full response — use it for questions that need Specset's own project understanding rather than raw data access.
 
 ## When to Delegate vs. Query Directly

package/skills/specset-closeout/SKILL.md

@@ -6,9 +6,7 @@ allowed-tools: Bash Read AskUserQuestion
 
 # Closeout & Facilities Data
 
-Requires the `specset` CLI, logged in with an active org. If a command fails with `command not found`, `Not logged in`, or `No active organization`, follow First-Run Setup in the `specset` skill.
-
-Run every operation with `specset api`. All ids are plain UUIDs. Remember Variable Limitations in the `specset` skill: `-F` sends strings only — inline every enum, number, boolean, list, and input object as a literal in the operation text, and reserve `-F` for ids and plain strings. This document is not exhaustive — when an operation or argument doesn't match, introspect (see the `specset` skill → Schema Discovery) rather than guess.
+Run every operation with `specset api`. All ids are plain UUIDs. Inline enums, numbers, lists, and input objects in the operation text (`-F` is strings-only; Variable Limitations and Schema Discovery live in the `specset` skill).
 
 ## Entity Model
 
@@ -34,24 +32,6 @@ Real deviations:
 
 Introspect the input object before composing any create or update, e.g. `{ __type(name: "CreateAssetInput") { inputFields { name type { name kind ofType { name } } } } }`.
 
-Worked example — find, then create:
-
-```bash
-specset api --query 'query($projectId: ID!) {
-  paginatedAssets(projectId: $projectId, search: "AHU", limit: 20, offset: 0) {
-    totalFilteredCount
-    items { id tag status location { id name } product { id name } }
-  }
-}' -F projectId=<project-id>
-
-specset api --query 'mutation($projectId: ID!, $locationId: ID!, $productId: ID!) {
-  createAsset(input: {
-    projectId: $projectId, locationId: $locationId, productId: $productId,
-    tag: "AHU-1", status: Installed, quantity: 1
-  }) { id tag status }
-}' -F projectId=<project-id> -F locationId=<location-id> -F productId=<product-id>
-```
-
 Prefer `update<Entity>` for changes: pass `id` plus only what changes; pass `null` to clear an optional relationship (e.g. `productId: null`). Update inputs for Asset, Location, Product, Company, and System accept `archived: true` — a reversible soft-archive that drops the record from default lists. Prefer it over delete.
 
 ## Asset Links
@@ -109,6 +89,6 @@ The same shape works for duplicate companies, locations, and systems.
 
 ## Safety
 
-- Confirm with the user before every mutation. For deletes, name the exact record (tag/name + id) and get explicit approval — they are hard deletes with no undo.
+- Deletes here are hard deletes with no undo — name the exact record (tag/name + id) when confirming.
 - Prefer `update` over delete-and-recreate, and `archived: true` over delete: deleting a product, location, or company silently nulls the references on assets that pointed at it. Check impact first with the filtered list queries.
 - Removing a document linkage can delete the underlying document if nothing else references it — say so when confirming.

package/skills/specset-projects/SKILL.md

@@ -6,9 +6,7 @@ allowed-tools: Bash Read AskUserQuestion
 
 # Specset Projects
 
-Requires the `specset` CLI, logged in with an active org. If a command fails with `command not found`, `Not logged in`, or `No active organization`, follow First-Run Setup in the `specset` skill.
-
-This skill mutates data — confirm with the user before each mutation, and always confirm the project name and which files belong to it before creating anything. Remember Variable Limitations from the `specset` skill: `-F` sends **strings only** — inline every enum, boolean, int, list, and input object as a literal; reserve `-F` for IDs and plain strings. When an operation or argument here doesn't match, introspect (see Schema Discovery in the `specset` skill).
+This skill mutates data — confirm the project name and which files belong to it before creating anything. Inline enums, ints, lists, and input objects in the operation text (`-F` is strings-only; Variable Limitations and Schema Discovery live in the `specset` skill).
 
 ## Reading Projects
 
@@ -22,7 +20,7 @@ project(id: ID!): Project!
 
 ## Creating a Project
 
-`createProject` does **not** add the creator as a project member, so the new project won't appear in the default `projects` list. Agents that miss this conclude the creation failed and create duplicates — don't. Fetch the new project by `project(id)`, and add membership as a separate step, mirroring the UI.
+`createProject` does **not** add the creator as a project member, so the new project won't appear in the default `projects` list — fetch it by `project(id)`, and add membership as a separate step, mirroring the UI.
 
 1. Create it:
 
@@ -103,11 +101,10 @@ updateDrawingSetPrecedence(projectId: ID!, drawingSetIds: [ID!]!): [DrawingSet!]
 ## Archiving and Deleting
 
 - **Prefer `archiveProject(id: ID!)`** — reversible via `unarchiveProject(id: ID!)`. Archived projects drop out of default lists but keep all data.
-- **`deleteProject(id: ID!)` permanently destroys the entire project** — documents, specs, drawings, submittals, RFIs, everything. Never run it without explicit user confirmation that names the exact project ("delete Riverside Medical Center — permanently?"). If the user just wants it out of the way, archive instead.
+- **`deleteProject(id: ID!)` permanently destroys the entire project** — documents, specs, drawings, submittals, RFIs, everything. Confirm with the user, naming the exact project, before running it. If they just want it out of the way, archive instead.
 
 ## Troubleshooting
 
 - Authorization error on a mutation — the user lacks that permission; the same rules as the UI apply. Surface the message, don't retry.
-- A freshly created project "missing" from `projects` — that's the membership gotcha above, not a failure. Check `project(id)` before recreating anything.
+- A freshly created project "missing" from `projects` — that's the membership gotcha above, not a failure.
 - A document reports a failed processing status on the BulkAction — report it to the user; re-uploading is their call.
-- A lookup by id returns `null` — the record belongs to a different org than the active one; check `specset auth status`.

package/skills/specset-rfis/SKILL.md

@@ -6,15 +6,13 @@ allowed-tools: Bash Read AskUserQuestion
 
 # Specset RFIs
 
-Requires the `specset` CLI, logged in with an active org. If a command fails with `command not found`, `Not logged in`, or `No active organization`, follow First-Run Setup in the `specset` skill.
-
 How the data is shaped:
 
 - An RFI is a `subject` + `question`, numbered within the project, with a lifecycle `status` (RfiStatus: `Draft | Open | Closed`).
 - `rfiNumber` is unique within a project — `createRfi` rejects a duplicate outright.
 - Responses accumulate on the RFI; exactly one can be marked **official** — the answer of record that justifies closing the RFI.
 
-The sketches below are minimal. When an operation or argument doesn't match, introspect rather than guess (see Schema Discovery in the `specset` skill). Enums, booleans, ints, and lists must be inlined in the operation text — reserve `-F` for IDs and plain strings (see Variable Limitations there).
+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).
 
 ## Reading
 
@@ -57,21 +55,7 @@ specset api --query 'query($projectId: ID!, $search: String) {
 
 If the source document carries no number, omit `rfiNumber` and the project's numbering scheme assigns the next one (fetch `nextAvailableRfiNumber` first if the user wants to see it). Numbers you do supply are canonicalized — generic `RFI-` prefixes are normalized — so the stored value may differ slightly from your input; read `rfiNumber` back from the mutation result.
 
-```bash
-specset api <<'GQL'
-mutation {
-  createRfi(input: {
-    projectId: "<project-id>"
-    subject: "Clarify hollow metal frame anchor spacing"
-    question: "Detail 5/A-501 shows anchors at 16 inches; spec 08 11 13 says 24. Which governs?"
-    status: Draft
-    specSectionIds: ["<spec-section-id>"]
-    drawingSheetIds: ["<drawing-sheet-id>"]
-    dueDate: "2026-08-01T00:00:00Z"
-  }) { id rfiNumber subject status }
-}
-GQL
-```
+`createRfi(input: { projectId, subject, question, status, specSectionIds: [...], drawingSheetIds: [...], dueDate }) { id rfiNumber subject status }`
 
 Field conventions:
 
@@ -91,20 +75,9 @@ specset api --query 'mutation($id: ID!) {
 
 Responses form the answer trail. Attach the reply document via `attachmentCloudFileIds` (file ids come from Uploading Files in the `specset` skill):
 
-```bash
-specset api <<'GQL'
-mutation {
-  createRfiResponse(input: {
-    rfiId: "<rfi-id>"
-    body: "Use 16-inch anchor spacing per detail 5/A-501; the spec table is superseded."
-    attachmentCloudFileIds: ["<file-id>"]
-  }) { id isOfficialResponse }
-}
-GQL
-```
-
+- `createRfiResponse(input: { rfiId, body, attachmentCloudFileIds: [...] }) { id isOfficialResponse }`
 - `updateRfiResponse(input: { id, body })` — edit a response body.
-- `markRfiResponseAsOfficial(id)` / `unmarkRfiResponseAsOfficial(id)` — designate or revoke the answer of record. There is no official flag on create: create the response first, then mark it. Mark a response official only when it is the signed reply of record (typically the architect's or engineer's), not a discussion comment.
+- `markRfiResponseAsOfficial(id)` / `unmarkRfiResponseAsOfficial(id)` — designate or revoke the answer of record. There is no official flag on create: create the response first, then mark it. The official response is normally the signed reply of record (typically the architect's or engineer's), not a discussion comment.
 - `deleteRfiResponse(id)` — confirm with the user first.
 
 The typical close-out sequence is: `createRfiResponse` → `markRfiResponseAsOfficial` → `updateRfi(input: { id, status: Closed })`.
@@ -119,6 +92,5 @@ Attachments on the RFI itself carry the question-side documents (sketches, photo
 
 ## Safety
 
-- Confirm with the user before every mutation (see Safety Rules in the `specset` skill) — creates included.
 - `deleteRfi(id)` removes the RFI along with its responses and attachments. Prefer closing an RFI over deleting it; delete only on explicit instruction, after showing what will be lost.
 - Marking or unmarking an official response changes the project's answer of record — name the response you're promoting before running it.

package/skills/specset-search/SKILL.md

@@ -6,11 +6,9 @@ allowed-tools: Bash Read AskUserQuestion
 
 # Specset Search
 
-Requires the `specset` CLI, logged in with an active org. If a command fails with `command not found`, `Not logged in`, or `No active organization`, follow First-Run Setup in the `specset` skill.
-
 This skill is read-only — everything here is a query, so nothing needs user confirmation before running.
 
-Remember Variable Limitations from the `specset` skill: `-F` sends **strings only**. Inline every enum, boolean, int, and list as a literal in the operation text; reserve `-F` for IDs and plain strings. If an operation or argument below doesn't match what the server accepts, introspect rather than guess — see Schema Discovery in the `specset` skill.
+`-F` sends strings only: inline enums, booleans, ints, and lists as literals in the operation text (Variable Limitations and Schema Discovery live in the `specset` skill).
 
 ## Choosing an Operation
 
@@ -42,13 +40,13 @@ At least one of `query` or `keywords` is required; they can be combined. Results
 { groups { referenceType totalCount items { url title previewText score projectId projectName } } nextOffset }
 ```
 
-### Project Scope (`ProjectScope`, inline it)
+### Project Scope (`ProjectScope`)
 
 - `CurrentProject` — default; `projectId` is required.
 - `MyProjects` — every project the user is a member of in the org.
 - `AllProjects` — every project in the org. Requires the org **Manager** or **Admin** role — plain Members get an authorization error, so fall back to `MyProjects` when that happens.
 
-### Record Types (`SourceReferenceType`, inline it)
+### Record Types (`SourceReferenceType`)
 
 Filter with `referenceTypes`. Common values: `SpecSection`, `DrawingSheet`, `Document`, `Submittal`, `SubmittalAttachment`, `Rfi`, and the closeout types `Company`, `Location`, `Product`, `Asset`, `Warranty`, `MaintenanceTask`. Introspect the `SourceReferenceType` enum for the full list.
 
@@ -78,7 +76,7 @@ specSectionByNumber(projectId: ID!, sectionNumber: String!): SpecSection      #
 drawingSheetByNumber(projectId: ID!, sheetNumber: String!): DrawingSheet      # nullable
 ```
 
-To browse or filter within a project, the paginated lists take `projectId`, an optional `search` string, and `limit`/`offset` ints (inline the ints); both return `{ items totalFilteredCount }`:
+To browse or filter within a project, the paginated lists take `projectId`, an optional `search` string, and `limit`/`offset` ints; both return `{ items totalFilteredCount }`:
 
 ```graphql
 paginatedSpecSections(projectId: ID!, search: String, limit: Int, offset: Int): SpecSectionPage!
@@ -87,23 +85,7 @@ paginatedDrawingSheets(projectId: ID!, search: String, limit: Int, offset: Int):
 
 Useful item fields: `id sectionNumber title numberAndTitle` on SpecSection, `id sheetNumber title` on DrawingSheet.
 
-## Examples
-
-Semantic search scoped to one project:
-
-```bash
-specset api --query 'query($orgId: ID!, $projectId: ID!, $q: String!) {
-  search(orgId: $orgId, projectId: $projectId, query: $q,
-         projectScope: CurrentProject, limit: 10) {
-    groups { referenceType totalCount
-             items { url title previewText score } }
-    nextOffset
-  }
-}' -F orgId=<org-id> -F projectId=<project-id> \
-   -F q='vibration isolation requirements for rooftop mechanical equipment'
-```
-
-Keyword search filtered to submittals, across all of the user's projects (note the inlined list, enums, and int):
+## Example
 
 ```bash
 specset api --query 'query($orgId: ID!) {
@@ -116,18 +98,7 @@ specset api --query 'query($orgId: ID!) {
 }' -F orgId=<org-id>
 ```
 
-Direct lookup by section number:
-
-```bash
-specset api --query 'query($projectId: ID!, $n: String!) {
-  specSectionByNumber(projectId: $projectId, sectionNumber: $n) {
-    id sectionNumber title numberAndTitle
-  }
-}' -F projectId=<project-id> -F n='23 05 48'
-```
-
 ## Working With Results
 
-- Each result's `url` is a Specset reference URL — `sb://spec/<id>`, `sb://drawing/<id>`, `sb://sub/<id>`, `sb://rfi/<id>`, `sb://doc/<id>`, and so on. The UUID inside is the record's GraphQL `id`; extract it for follow-up queries on that record.
-- Lookups by id are scoped to the **active org**: an id from a different org returns `null` rather than an error. If a known-good id comes back null, check `specset auth status` and switch orgs.
+- Each result's `url` is a Specset reference URL (`sb://spec/<id>`, `sb://sub/<id>`, …); the UUID inside is the record's GraphQL `id` — extract it for follow-up queries. The scheme is documented in the `specset-tools` skill.
 - For follow-up work on what you found — updating submittals, answering RFIs, closeout records, or project/document changes — hand off to the `specset-submittals`, `specset-rfis`, `specset-closeout`, or `specset-projects` skill.

package/skills/specset-submittals/SKILL.md

@@ -6,15 +6,13 @@ allowed-tools: Bash Read AskUserQuestion
 
 # Specset Submittals
 
-Requires the `specset` CLI, logged in with an active org. If a command fails with `command not found`, `Not logged in`, or `No active organization`, follow First-Run Setup in the `specset` skill.
-
 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.
 - A submittal number is only unique per (spec section, number) within a project — the bare number alone is not.
 
-The sketches below are minimal. When an operation or argument doesn't match, introspect rather than guess (see Schema Discovery in the `specset` skill). Enums, booleans, ints, and lists must be inlined in the operation text — reserve `-F` for IDs and plain strings (see Variable Limitations there).
+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).
 
 ## Reading
 
@@ -46,22 +44,9 @@ Also available:
 
 ## Creating
 
-Dedupe first: run `searchSubmittals` with the submittal number (or title plus section). A match on (spec section, number) is authoritative — never create a duplicate; the API does not enforce this for you. Omit `submittalNumber` to auto-number in the project's sequence.
+Dedupe first: run `searchSubmittals` with the submittal number (or title plus section). A match on (spec section, number) is authoritative — never create a duplicate; the API does not enforce this for you.
 
-```bash
-specset api <<'GQL'
-mutation {
-  createSubmittal(input: {
-    projectId: "<project-id>"
-    title: "Hollow Metal Doors and Frames - Product Data"
-    submittalNumber: "08 11 13-001"
-    specSectionIds: ["<spec-section-id>"]
-    submittalTypeId: "<submittal-type-id>"
-    status: Draft
-  }) { id submittalNumber title }
-}
-GQL
-```
+`createSubmittal(input: { projectId, title, submittalNumber, specSectionIds: [...], submittalTypeId, status }) { id submittalNumber title }` — omit `submittalNumber` to auto-number in the project's sequence.
 
 **From a PDF**: upload it first (see Uploading Files in the `specset` skill) and pass the resulting file id as `cloudFileId` — Specset extracts the number, title, and section from the document, so you can omit them. Add `autoReviewMode: GeneratePlanAndApprove` to start an AI compliance review in the same call (`GeneratePlan` pauses at the plan for approval; default `None`).
 
@@ -96,52 +81,19 @@ File ids come from Uploading Files in the `specset` skill.
 
 Track who reviews the submittal and what they returned:
 
-```bash
-specset api <<'GQL'
-mutation {
-  createSubmittalApprover(input: {
-    submittalId: "<submittal-id>"
-    userId: "<user-id>"
-    dueDate: "2026-08-01T00:00:00Z"
-    responseRequired: true
-  }) { id order status }
-}
-GQL
-```
+- `createSubmittalApprover(input: { submittalId, userId, dueDate, responseRequired }) { id order status }`
 
 Record a returned response with `updateSubmittalApprover(input: { id, status: ApprovedAsNoted, comment: "...", returnedDate: "...", cloudFileIds: [...] })`. `status` is SubmittalApproverResponseStatus: `Approved | ApprovedAsNoted | ForRecordOnly | Pending | Rejected | ReviseAndResubmit | Void | Submitted`. `approverType` distinguishes `Approver` (default) from `Submitter`; `sentDate` and `distributed` track routing. Remove with `deleteSubmittalApprover(id)`.
 
 ## AI Compliance Reviews
 
-Three steps: create, poll, compile. Arguments are top-level (no input object).
-
-```bash
-# 1. Start the review
-specset api --query 'mutation($submittalId: ID!) {
-  createSubmittalReview(submittalId: $submittalId, createMode: GeneratePlanAndApprove) { id }
-}' -F submittalId=<submittal-id>
-```
-
-Optional: `prompt` (focus instructions, a plain string), and `specSectionIds` / `drawingSheetIds` (inline lists) to pin the spec basis.
+Three steps — arguments are top-level (no input object):
 
-```bash
-# 2. Poll until lastReviewedAt is set — reviews take minutes; see
-#    Waiting on Background Processing in the specset skill for cadence
-specset api --query 'query($id: ID!) {
-  submittalReview(id: $id) { id status oneLiner lastReviewedAt }
-}' -F id=<review-id>
-```
-
-`status` is the verdict, ReviewStatus: `Compliant | NonCompliant | MissingInfo | ClarificationsNeeded | NotApplicable`.
-
-```bash
-# 3. Compile the annotated, marked-up PDF
-specset api --query 'mutation($id: ID!) {
-  compileSubmittalReview(id: $id, includeIssueToc: true) { id compiledReview { id } }
-}' -F id=<review-id>
-```
+1. `createSubmittalReview(submittalId, createMode: GeneratePlanAndApprove) { id }` — optional: `prompt` (focus instructions, a plain string), and `specSectionIds` / `drawingSheetIds` (inline lists) to pin the spec basis.
+2. Poll `submittalReview(id) { id status oneLiner lastReviewedAt }` until `lastReviewedAt` is set — reviews take minutes; see Waiting on Background Processing in the `specset` skill for cadence. `status` is the verdict, ReviewStatus: `Compliant | NonCompliant | MissingInfo | ClarificationsNeeded | NotApplicable`.
+3. `compileSubmittalReview(id, includeIssueToc: true) { id compiledReview { id } }` compiles the annotated, marked-up PDF. `excludedIssueIds: [...]` (inlined) drops chosen issues from the compiled PDF and TOC.
 
-`excludedIssueIds: [...]` (inlined) drops chosen issues from the compiled PDF and TOC. `updateSubmittalReview(id, comments)` records reviewer comments; `deleteSubmittalReview(id)` removes a review.
+`updateSubmittalReview(id, comments)` records reviewer comments; `deleteSubmittalReview(id)` removes a review.
 
 ## Drafting a Whole Submittal Log
 
@@ -159,6 +111,4 @@ Applying skips rows whose (section, number) already exists and writes per-row re
 
 ## Safety
 
-- Confirm with the user before every mutation (see Safety Rules in the `specset` skill) — creates included.
-- `deleteSubmittal(id)` removes one revision. `deleteSubmittal(id, deleteAllRevisions: true)` removes the entire revision chain — state that difference and get explicit confirmation before using it.
-- Never loop deletes over a list the user hasn't seen.
+`deleteSubmittal(id)` removes one revision; `deleteSubmittal(id, deleteAllRevisions: true)` removes the entire revision chain — state that difference when confirming the delete.

package/skills/specset-tools/SKILL.md

@@ -6,8 +6,6 @@ allowed-tools: Bash Read AskUserQuestion
 
 # Specset Agent Tools (`specset tools`, `specset mcp`)
 
-Requires the `specset` CLI, logged in with an active org. If a command fails with `command not found`, `Not logged in`, or `No active organization`, follow First-Run Setup in the `specset` skill.
-
 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.
 
 ## When to use which surface
@@ -50,12 +48,29 @@ Output is the tool's JSON payload (`{ success, message?, result? }`); a `{ succe
 
 ### Identifiers are citation IDs, not 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 **not** web URLs — don't present them to a person as clickable 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.
 
 ### 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.
 
+## 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:
+
+| 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 |
+
+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.
+
+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.
+
 ## MCP server (Claude Code, Codex, other MCP clients)
 
 `specset mcp` runs a stdio MCP server that exposes these tools natively, reusing your CLI login, org, and host config. Register it once and the client can call the tools directly: