@specset/cli 0.5.0 → 0.6.0

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,7 +48,7 @@ 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
 
@@ -60,42 +58,28 @@ Most tools are project-scoped. Either pass `--project` (a UUID or `sb://project/
 
 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:
 
-```bash
-# Drawing sheets — image (rendered PNG, default), pdf (single-sheet), file (whole set).
-# Also accepts a sheet number with --project. Read the PNG with vision to inspect geometry.
-specset drawings download 'sb://drawing/<uuid>#nodeId=d1' --out /tmp/sheets/
-specset drawings download E308 --project <projectId> --format pdf
-
-# Project documents — also covers RFI attachments and closeout documents,
-# which all reference a document:
-specset docs download 'sb://doc/<uuid>'
-
-# Spec sections — per-section PDF slice (default) or the whole source spec file.
-# Also accepts a section number with --project:
-specset specs download '23 31 19' --project <projectId>
-specset specs download 'sb://spec/<uuid>' --asset book
-
-# Submittals — compiled package (default when present), cover sheet, or attachments.
-# --list shows the asset inventory first:
-specset submittals download 'sb://sub/<uuid>' --list
-specset submittals download 'sb://sub/<uuid>' --asset attachment --index 2
-specset submittals download 'sb://sub/<uuid>' --asset attachment --all --out ./sub-42/
-
-# RFIs — question + response attachments:
-specset rfis download 'sb://rfi/<uuid>' --list
-specset rfis download 'sb://rfi/<uuid>' --all --out ./rfi-7/
-
-# Raw file resources — the escape hatch when you already hold an sb://file id:
-specset files download 'sb://file/<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 with your vision/file-reading tool**.
+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)
+## MCP servers (local and hosted)
 
-`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:
+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.
+- `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).
+
+Register the local transport once and the client can call the tools directly:
 
 ```bash
 # Claude Code
@@ -108,9 +92,12 @@ codex mcp add specset -- specset mcp
 ```
 
 Notes:
+
 - The server writes only the MCP protocol to stdout; diagnostics go to stderr.
 - Scope (org, optional project, host) is fixed for the life of the server — restart it to change scope.
 - If the session expires mid-run, tool calls return an actionable error; run `specset login` and restart the server.
+- 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