@specset/cli 0.5.0 → 0.6.0

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,104 @@
+---
+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 { 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 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.
+
+## 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 }`
+
+## 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, SubmittalAttachment],
+         projectScope: MyProjects, limit: 20) {
+    groups { referenceType totalCount
+             items { url title previewText projectName } }
+  }
+}' -F orgId=<org-id>
+```
+
+## Working With Results
+
+- 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/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,104 @@
+---
+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|sb://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 an ID from a search result
+specset tools run getSpecSectionContent -F id='sb://spec/....'
+```
+
+Output is the tool's JSON payload (`{ success, message?, result? }`); a `{ success: false }` payload exits non-zero.
+
+### 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 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 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.

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
 ---
 
@@ -14,71 +14,27 @@ The `specset` CLI handles OAuth login, org switching, and request signing. The e
 
 This is the core skill — setup and mechanics only. Domain workflows live in sibling skills:
 
-| Skill | Use for |
-|---|---|
-| `specset-search` | Finding anything across specs, drawings, submittals, RFIs, documents, and closeout records |
-| `specset-tools` | Calling Specset's own retrieval tools directly (`specset tools`, `specset mcp`) — deeper than search, lighter than the in-app agent |
-| `specset-projects` | Creating projects, uploading spec/drawing PDFs, publishing spec and drawing sets |
-| `specset-submittals` | Submittal lifecycle, attachments, approvers, and AI compliance reviews |
-| `specset-rfis` | RFI logging, tracking, and responses |
-| `specset-closeout` | Assets, locations, products, companies, warranties, and maintenance |
-| `specset-agent` | Delegating deep project questions to Specset's in-app AI agent |
-| `specset-admin` | Org members, invites, and whitelabel branding |
+| Skill                | Use for                                                                                                                             |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `specset-search`     | Finding anything across specs, drawings, submittals, RFIs, documents, and closeout records                                          |
+| `specset-tools`      | Calling Specset's own retrieval tools directly (`specset tools`, `specset mcp`) — deeper than search, lighter than the in-app agent |
+| `specset-projects`   | Creating projects, uploading spec/drawing PDFs, publishing spec and drawing sets                                                    |
+| `specset-submittals` | Submittal lifecycle, attachments, approvers, and AI compliance reviews                                                              |
+| `specset-rfis`       | RFI logging, tracking, and responses                                                                                                |
+| `specset-closeout`   | Assets, locations, products, companies, warranties, and maintenance                                                                 |
+| `specset-agent`      | Delegating deep project questions to Specset's in-app AI agent                                                                      |
+| `specset-admin`      | Org members, invites, and whitelabel branding                                                                                       |
 
 `specset skill install --target <claude|codex|chatgpt>` installs and updates the whole family (`specset skill list` shows what's bundled) — if a skill named above is missing from your skills directory, run it for the current agent.
 
 ## 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,71 +65,30 @@ 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
 
-Several workflows attach an uploaded file — submittal PDFs, RFI attachments, project documents, org logos. Files are uploaded directly to storage via a presigned URL, so attaching one is a three-step flow that needs `bash`, `curl`, and `jq`. The result is a **file id** you pass to whatever mutation consumes it.
-
-1. Request a presigned upload URL:
-
-```bash
-specset api --query 'mutation($orgId: ID!) {
-  generateFileUploadUrl(orgId: $orgId) { id url fields { key value } }
-}' -F orgId=<your-org-id> > upload.json
-```
-
-2. POST the file to that URL with the returned form fields — the `file` field must come **last**:
+Several workflows attach an uploaded file — submittal PDFs, RFI attachments, project documents, and org logos. Use the streaming upload command; it requests a presigned storage URL, sends the file without buffering it whole, finalizes the upload, and returns the **cloud file id** required by attachment mutations:
 
 ```bash
-URL=$(jq -r '.data.generateFileUploadUrl.url' upload.json)
-ARGS=()
-while IFS= read -r kv; do ARGS+=(-F "$kv"); done \
-  < <(jq -r '.data.generateFileUploadUrl.fields[] | "\(.key)=\(.value)"' upload.json)
-curl -sf -X POST "${ARGS[@]}" -F "file=@document.pdf" "$URL"
+specset files upload ./document.pdf
+specset files upload ./photo.jpg --type image/jpeg --json
 ```
 
-3. Finalize the upload to create the file record and capture its id:
+The active organization is used automatically. With `--json`, read the id from `.id`; without it, the command prints the id. The optional `--type` defaults to `application/octet-stream`.
 
-```bash
-UPLOAD_ID=$(jq -r '.data.generateFileUploadUrl.id' upload.json)
-FILE_ID=$(specset api --query 'mutation($orgId: ID!, $id: ID!, $filename: String!) {
-  completeUpload(orgId: $orgId, id: $id, filename: $filename) { id }
-}' -F orgId=<your-org-id> -F id=$UPLOAD_ID -F filename=document.pdf | jq -r '.data.completeUpload.id')
-```
-
-Get your org id first if you don't have it:
-
-```bash
-specset api --query '{ me { orgMembers { org { id slug name } } } }'
-```
+Hosted MCP clients that support OpenAI file parameters receive the equivalent `uploadFile` tool. Pass its returned `.cloudFileId` to domain mutations that accept attachment ids; its `.id` is an `sb://file/...` citation. `getFileDownload` returns an MCP resource link backed by a short-lived URL when the hosted client needs bytes back.
 
 ## Waiting on Background Processing
 
@@ -187,19 +102,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>`.