@specset/cli 0.5.1 → 1.0.0

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

@@ -0,0 +1,110 @@
+---
+name: specset-projects
+description: Use when standing up a new Specset project or adding document sets to one — create the project, upload spec/drawing PDFs, monitor processing, and publish spec sets and drawing sets.
+allowed-tools: Bash Read AskUserQuestion
+---
+
+# Specset Projects
+
+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
+
+```graphql
+projects(orgId: ID!, archived: Boolean, includeAll: Boolean = false): [Project!]!
+paginatedProjects(orgId: ID!, search: String, limit: Int, offset: Int, archived: Boolean = false): ProjectPage!   # { items totalFilteredCount }
+project(id: ID!): Project!
+```
+
+**`projects` is membership-filtered by default** — it returns only projects where the caller is a project member. Inline `includeAll: true` to list every project in the org. Use `paginatedProjects` with a `search` string to find a project by name.
+
+## 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 — fetch it by `project(id)`, and add membership as a separate step, mirroring the UI.
+
+1. Create it:
+
+```bash
+specset api --query 'mutation($orgId: ID!, $name: String!) {
+  createProject(orgId: $orgId, name: $name) { id name }
+}' -F orgId=<org-id> -F name='Riverside Medical Center'
+```
+
+2. Get your own user id with `{ me { id } }`, then add yourself (and anyone else the user names) as a member. `role` is an optional `OrgMemberTeamRole` enum — `Member`, `Manager`, or `Admin` — inlined when specified:
+
+```bash
+specset api --query 'mutation($projectId: ID!, $userId: ID!) {
+  addProjectMember(projectId: $projectId, userId: $userId, role: Member) { id }
+}' -F projectId=<project-id> -F userId=<user-id>
+```
+
+## Importing Documents
+
+1. Upload each PDF following Uploading Files in the `specset` skill. Each `completeUpload` returns a **cloud file id** — collect them.
+2. Register the uploads on the project in a single call. The input object is inlined; ID variables are fine as its leaves:
+
+```bash
+specset api --query 'mutation($projectId: ID!, $f1: ID!, $f2: ID!) {
+  createProjectDocuments(input: {
+    projectId: $projectId
+    cloudFileIds: [$f1, $f2]
+    autoImport: true
+  }) { id totalCount completedCount failedCount }
+}' -F projectId=<project-id> -F f1=<cloud-file-id> -F f2=<cloud-file-id>
+```
+
+3. It returns a **BulkAction** — poll it per Waiting on Background Processing in the `specset` skill. Processing extracts each document's outline and content, indexes it for search, and splits it into candidate spec files and drawing files by page range.
+
+### `autoImport`: publish automatically or curate
+
+- `autoImport: true` — every generated spec/drawing file is classified and published into default sets automatically. Use when the user wants everything live immediately.
+- Omit it (or `false`) — files land **unpromoted** for manual curation below. Use when the user wants to control set titles, membership, or ordering.
+
+Ask the user when their intent is ambiguous — this choice changes what gets published. The input also supports folders: `parentFolderId` / `newFolderName` for flat imports, or `folderTree` + `files` to mirror a directory structure — introspect `CreateProjectDocumentsInput` for those shapes.
+
+## Publishing Spec and Drawing Sets
+
+Publishing promotes processed files into a SpecSet or DrawingSet container. After a non-autoImport run finishes:
+
+1. Review what processing generated, and summarize it to the user before publishing:
+
+```graphql
+unpromotedSpecFiles(projectId: ID!): [SpecFile!]!        # { id title }
+unpromotedDrawingFiles(projectId: ID!): [DrawingFile!]!  # { id title }
+```
+
+Empty lists mean processing hasn't finished, or `autoImport` already promoted everything.
+
+2. Create a set and assign files into it (`issuedAt` is an optional DateTime — inline an ISO literal like `issuedAt: "2026-06-01T00:00:00Z"`):
+
+```bash
+specset api --query 'mutation($projectId: ID!, $title: String!) {
+  createSpecSet(title: $title, projectId: $projectId) { id title }
+}' -F projectId=<project-id> -F title='Issued for Construction'
+
+specset api --query 'mutation($specSetId: ID!, $f1: ID!) {
+  assignSpecFilesToSpecSet(specSetId: $specSetId, specFileIds: [$f1]) { id }
+}' -F specSetId=<spec-set-id> -F f1=<spec-file-id>
+```
+
+The drawing side is symmetric: `createDrawingSet(title: String!, projectId: ID!, issuedAt: DateTime)` then `assignDrawingFilesToDrawingSet(drawingSetId: ID!, drawingFileIds: [ID!]!)`.
+
+3. When a project has multiple sets (e.g. an addendum on top of the base issue), set which one governs. Pass the **complete** list of set ids, highest precedence first:
+
+```graphql
+updateSpecSetPrecedence(projectId: ID!, specSetIds: [ID!]!): [SpecSet!]!
+updateDrawingSetPrecedence(projectId: ID!, drawingSetIds: [ID!]!): [DrawingSet!]!
+```
+
+4. Verify and summarize — query `project(id)` (not the membership-filtered `projects` list) with `specSets { id title }` and `drawingSets { id title }`, and report what was created.
+
+## 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. 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.
+- A document reports a failed processing status on the BulkAction — report it to the user; re-uploading is their call.

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

@@ -0,0 +1,96 @@
+---
+name: specset-rfis
+description: Manage Specset RFIs — list, search, create, update, and record responses including the official answer of record. Use for any RFI logging or tracking task.
+allowed-tools: Bash Read AskUserQuestion
+---
+
+# Specset RFIs
+
+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 — inline enums, ints, and lists in the operation text (`-F` is strings-only; Variable Limitations and Schema Discovery live in the `specset` skill).
+
+## Reading
+
+```bash
+# One RFI with its responses
+specset api --query 'query($id: ID!) {
+  rfi(id: $id) {
+    id rfiNumber subject question status dueDate costImpact scheduleImpact
+    responses { id body isOfficialResponse createdAt }
+    attachments { id }
+  }
+}' -F id=<rfi-id>
+
+# Filtered list — enums inlined, never via -F
+specset api --query 'query($projectId: ID!) {
+  rfis(projectId: $projectId, statuses: [Open]) {
+    id rfiNumber subject status dueDate
+  }
+}' -F projectId=<project-id>
+```
+
+Also available:
+
+- `paginatedRfis(projectId, search, limit: 25, offset: 0) { totalFilteredCount items { ... } }` — offset pagination; `search` matches subject and number. Use it for dedupe checks.
+- `nextAvailableRfiNumber(projectId)` — the next number in the project's sequence, as a string.
+- `rfiResponses(projectId) { id body isOfficialResponse }` — every response across the project.
+
+## Creating
+
+Dedupe first: search `paginatedRfis` with the RFI number from the document. A match by `rfiNumber` within the project is authoritative — never create a duplicate.
+
+```bash
+specset api --query 'query($projectId: ID!, $search: String) {
+  paginatedRfis(projectId: $projectId, search: $search, limit: 5, offset: 0) {
+    totalFilteredCount
+    items { id rfiNumber subject status }
+  }
+}' -F projectId=<project-id> -F search=RFI-000017
+```
+
+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.
+
+`createRfi(input: { projectId, subject, question, status, specSectionIds: [...], drawingSheetIds: [...], dueDate }) { id rfiNumber subject status }`
+
+Field conventions:
+
+- `status` defaults to `Draft`. Promote to `Open` when the RFI is formally issued; move to `Closed` only once the official response is recorded.
+- `costImpact` and `scheduleImpact` are RfiImpact enums (`Yes | No`) — set them only when the user or source document states an impact explicitly; leave them unset otherwise.
+- `rfiManagerId` assigns the managing org member.
+
+Update with `updateRfi(input: { id, ... })` — same fields minus `projectId`; pass only what changes:
+
+```bash
+specset api --query 'mutation($id: ID!) {
+  updateRfi(input: { id: $id, status: Open }) { id status }
+}' -F id=<rfi-id>
+```
+
+## Responses
+
+Responses form the answer trail. Attach the reply document via `attachmentCloudFileIds` (file ids come from Uploading Files in the `specset` skill):
+
+- `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. 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 })`.
+
+## Attachments
+
+Attachments on the RFI itself carry the question-side documents (sketches, photos, the original request PDF); response documents ride on the response via `attachmentCloudFileIds` above. Upload files per Uploading Files in the `specset` skill.
+
+- `createRfiAttachment(input: { rfiId, cloudFileId })`
+- `deleteRfiAttachment(id)`
+- `reorderRfiAttachments(input: { rfiId, attachmentIds: [...] })`
+
+## Safety
+
+- `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/plugin/specset/skills/specset-search/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: specset-search
+description: Use when the user asks to find, look up, or locate anything in their Specset projects — semantic and keyword search across specs, drawing sheets, submittals, RFIs, documents, and closeout records.
+allowed-tools: Bash Read AskUserQuestion
+---
+
+# Specset Search
+
+This skill is read-only — everything here is a query, so nothing needs user confirmation before running.
+
+`-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
+
+- **`search`** — the main tool: semantic (natural-language) and/or keyword search over indexed content, results grouped by record type.
+- **`quickSearch`** — fast flat matching against titles and identifiers; use when the user roughly knows the record's name or number.
+- **Precise lookups** — when the user already has a spec section number or drawing sheet number, skip search and fetch directly.
+
+> Need the actual content, not just previews and IDs? The `specset-tools` skill exposes Specset's own retrieval tools (`specset tools run searchSpecSections`, `searchDrawingSheets`, `searchDocuments`, …), which return expanded, citation-anchored markdown. Use `search`/`quickSearch` here to locate records cheaply; reach for `specset-tools` when you need to read and reason over the content.
+
+## Unified Search: `search`
+
+```graphql
+search(
+  orgId: ID!
+  projectId: ID                      # required when projectScope is CurrentProject
+  query: String                      # natural-language semantic query
+  keywords: [String!]                # exact term matching — inline the list
+  referenceTypes: [SourceReferenceType!]   # inline; omit to search all types
+  projectScope: ProjectScope = CurrentProject
+  titleOnly: Boolean = false
+  limit: Int = 10
+  offset: Int = 0
+): SearchResults!
+```
+
+At least one of `query` or `keywords` is required; they can be combined. Results:
+
+```graphql
+{
+  groups {
+    referenceType
+    totalCount
+    items {
+      id
+      url
+      title
+      previewText
+      score
+      projectId
+      projectName
+    }
+  }
+  nextOffset
+}
+```
+
+### 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`)
+
+Filter semantic `search` with the record types it materializes: `SpecSection`, `DrawingSheet`, `Document`, `Submittal`, and `Rfi`. Other values exist in the shared `SourceReferenceType` enum but are not necessarily supported by this operation.
+
+## Quick Search: `quickSearch`
+
+Substring matching against titles and identifiers — cheap and fast, no semantic ranking.
+
+```graphql
+quickSearch(
+  orgId: ID!
+  projectId: ID
+  query: String!
+  referenceTypes: [SourceReferenceType!]
+  projectScope: ProjectScope = CurrentProject
+  limit: Int = 20
+): QuickSearchResults!
+```
+
+Results: `{ items { id url number title referenceType score projectId projectName summary } totalCount }`
+
+`quickSearch` also supports explicitly requested closeout title records: `Company`, `Location`, `System`, `Product`, `Asset`, and `MaintenancePlan`. It does not currently return `Warranty`, `Procedure`, or `WorkOrder` rows. `MaintenanceTask` is a deprecated legacy-link redirect, not a searchable record type. Omit `referenceTypes` for the standard global-search defaults, or introspect `SourceReferenceType` and use only a type supported by the selected operation.
+
+## Precise Lookups
+
+When the user hands you a section or sheet number, look it up directly:
+
+```graphql
+specSectionByNumber(projectId: ID!, sectionNumber: String!): SpecSection      # nullable
+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; both return `{ items totalFilteredCount }`:
+
+```graphql
+paginatedSpecSections(projectId: ID!, search: String, limit: Int, offset: Int): SpecSectionPage!
+paginatedDrawingSheets(projectId: ID!, search: String, limit: Int, offset: Int): DrawingSheetPage!
+```
+
+Useful item fields: `id sectionNumber title numberAndTitle` on SpecSection, `id sheetNumber title` on DrawingSheet.
+
+## Example
+
+```bash
+specset api --query 'query($orgId: ID!) {
+  search(orgId: $orgId, keywords: ["AHU-1"],
+         referenceTypes: [Submittal],
+         projectScope: MyProjects, limit: 20) {
+    groups { referenceType totalCount
+             items { id url title previewText projectName } }
+  }
+}' -F orgId=<org-id>
+```
+
+## Working With Results
+
+- Each result's `id` is the UUID for follow-up GraphQL calls. Its `url` is the clickable source link (`https://app.specbook.ai/go/spec/<uuid>`, `https://app.specbook.ai/go/sub/<uuid>`, …) and can be passed directly into Specset tools and download commands.
+- In user-facing answers, include the most relevant returned `url` values as descriptive Markdown source links so the user can open the result in Specset. Never synthesize a `/go` link from a UUID that was not returned as a source link.
+- 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/plugin/specset/skills/specset-submittals/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: specset-submittals
+description: Manage Specset submittals — list, search, create, revise, attach files, track approvers, and run AI spec-compliance reviews. Use for any submittal log or submittal review task.
+allowed-tools: Bash Read AskUserQuestion
+---
+
+# Specset Submittals
+
+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 — inline enums, ints, and lists in the operation text (`-F` is strings-only; Variable Limitations and Schema Discovery live in the `specset` skill).
+
+## Reading
+
+```bash
+# One submittal with its relationships
+specset api --query 'query($id: ID!) {
+  submittal(id: $id) {
+    id submittalNumber sectionNumber title revision status workingStatus
+    attachments { id description }
+    approvers { id status comment returnedDate }
+    submittalReviews { id status oneLiner lastReviewedAt }
+  }
+}' -F id=<submittal-id>
+
+# Filtered list — enums inlined, never via -F
+specset api --query 'query($projectId: ID!) {
+  submittals(projectId: $projectId, statuses: [Open], workingStatuses: [Pending, Submitted]) {
+    id submittalNumber sectionNumber title workingStatus submitByDate
+  }
+}' -F projectId=<project-id>
+```
+
+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.
+- `submittalTypes(projectId) { id name label }` — the project's configured types, for `submittalTypeId`.
+
+## 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.
+
+`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`).
+
+Update with `updateSubmittal(input: { id, ... })` — same fields as create, minus `projectId`/`cloudFileId`. Pass only what changes.
+
+## Revisions
+
+`createSubmittalRevision` supersedes the current revision with a fresh one reset to Draft:
+
+```bash
+specset api --query 'mutation($id: ID!) {
+  createSubmittalRevision(input: { id: $id, cloudFileIds: ["<file-id>"] }) {
+    id revision status
+  }
+}' -F id=<submittal-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.
+
+## Attachments
+
+File ids come from Uploading Files in the `specset` skill.
+
+- `createSubmittalAttachment(input: { submittalId, cloudFileId, type, description, order })`
+- `createSubmittalAttachments(input: { submittalId, cloudFileIds: [...], autoReviewMode })` — batch form
+- `updateSubmittalAttachment(input: { id, type, description, order })`
+- `deleteSubmittalAttachment(id)`
+
+`type` is a SubmittalAttachmentType enum (`ProductData`, `ShopDrawing`, `Certifications`, …) — introspect for the full list and inline the value.
+
+## Approvers
+
+Track who reviews the submittal and what they returned:
+
+- `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 — arguments are top-level (no input object):
+
+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.
+
+`updateSubmittalReview(id, comments)` records reviewer comments; `deleteSubmittalReview(id)` removes a review.
+
+## Drafting a Whole Submittal Log
+
+Generating a full log from the specs is an agent job, not raw GraphQL. Use the `specset-agent` skill and ask the in-app agent to draft a submittal log for the project — the run produces a SubmittalLog artifact on its thread. Read the drafted rows (each entry has a numeric id) with `agentArtifact(id) { id title content }`, let the user pick, then apply:
+
+```bash
+specset api --query 'mutation($artifactId: ID!) {
+  applySubmittalLog(input: { artifactId: $artifactId, selectedSubmittalLogIds: [1, 2, 3] }) {
+    id content
+  }
+}' -F artifactId=<artifact-id>
+```
+
+Applying skips rows whose (section, number) already exists and writes per-row results back onto the artifact — re-read `content` to report errors and warnings.
+
+## Safety
+
+`deleteSubmittal(id)` removes one revision; `deleteSubmittal(id, deleteAllRevisions: true)` removes the entire revision chain — state that difference when confirming the delete.

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

@@ -0,0 +1,105 @@
+---
+name: specset-tools
+description: Use when an agent should call Specset's own retrieval tools directly — semantic/keyword search and structured reads over specs, drawings, submittals, RFIs, documents, closeout, and schedule — via `specset tools` or a `specset mcp` server. Deeper than raw GraphQL search; lighter than delegating to the in-app agent.
+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.
+
+## When to use which surface
+
+There are three tiers of Specset retrieval. Pick the lightest one that answers the question:
+
+1. **Typed GraphQL search** (`specset-search` skill: `search`, `quickSearch`, `specSectionByNumber`, …) — cheapest, returns previews and IDs. Best for "does X exist / find the record."
+2. **Agent tools** (this skill) — the middle tier. `searchSpecSections` / `searchDrawingSheets` / `searchDocuments` return expanded, citation-anchored markdown (the real retrieval), and the `get*Content` tools read full sections. Best when you need the actual content to reason over.
+3. **In-app agent** (`specset-agent` skill: `specset agent chat`) — heaviest. Delegates the whole question to Specset's agent, which reasons and synthesizes. Best when the answer needs cross-document judgment, not just retrieval.
+
+## Listing tools
+
+```bash
+specset tools list
+specset tools list --project <projectId|https://app.specbook.ai/go/project/...>
+specset tools list --json     # full input schemas
+```
+
+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.
+
+## Running a tool
+
+Provide input as a JSON object (`--input`) or as repeated `-F key=value` fields. **Unlike `specset api -F` (strings only), `specset tools run -F` JSON-parses each value**, so numbers, booleans, and lists work:
+
+```bash
+# JSON input
+specset tools run searchSpecSections \
+  --project <projectId> \
+  --input '{"query": "concrete curing requirements"}'
+
+# Field form (values are JSON-parsed, string fallback)
+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 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.
+
+### Source links
+
+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 returned `/go/project/...` link), or include `projectId` in the tool input. Use `listProjects` to discover projects. 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 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 '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.
+
+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 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.
+- `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
+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
+
+# Codex
+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
+
+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.