@specset/cli 0.2.0

package/skills/specset-rfis/SKILL.md

@@ -0,0 +1,124 @@
+---
+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
+
+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).
+
+## 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.
+
+```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
+```
+
+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):
+
+```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
+```
+
+- `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.
+- `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
+
+- 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

@@ -0,0 +1,131 @@
+---
+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
+
+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.
+
+## 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.
+
+## 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`, inline it)
+
+- `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)
+
+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 (inline the 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.
+
+## 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):
+
+```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>
+```
+
+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.
+- 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

@@ -0,0 +1,164 @@
+---
+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
+
+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).
+
+## 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. Omit `submittalNumber` to auto-number in the project's sequence.
+
+```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
+```
+
+**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:
+
+```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
+```
+
+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.
+
+```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>
+```
+
+`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
+
+- 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.