@specset/cli 0.2.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@specset/cli",
+  "version": "0.2.0",
+  "description": "Command-line interface for Specset — authenticate, run GraphQL queries, and chat with Specset project agents.",
+  "license": "Apache-2.0",
+  "homepage": "https://specset.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/specsetai/specbook.git",
+    "directory": "apps/cli"
+  },
+  "keywords": [
+    "specset",
+    "construction",
+    "cli",
+    "graphql",
+    "agent"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "bin": {
+    "specset": "./dist/main.js"
+  },
+  "dependencies": {
+    "open": "^11.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/specset/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: specset
+description: Core CLI for Specset — install, authenticate, 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.
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+# Specset CLI (`specset`)
+
+Use this skill to work with a Specset organization from the command line: run GraphQL queries against your data (projects, drawings, specs, submittals, …) and manage authentication and org context.
+
+The `specset` CLI handles OAuth login, org switching, and request signing. The exact flag surface of the installed version is authoritative in its own help output — prefer `specset --help` and `specset <command> --help` over memorized flags when something doesn't match this document.
+
+## Skill Family
+
+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-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` 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.
+
+## First-Run Setup
+
+Perform this setup yourself when the user 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:
+
+```bash
+which specset || npm install -g @specset/cli
+```
+
+Requires Node.js 20+ with npm. If `npm` itself is missing, stop and ask the user to install Node.js (https://nodejs.org) first.
+
+2. Check authentication with `specset auth status`. If not logged in, start the login flow — it opens the user's browser; tell them 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. On a headless machine (no browser), login isn't possible; direct the user to a machine with a browser. 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
+```
+
+Credentials persist across sessions in `~/.config/specset/config.yml` (mode 0600) — setup only needs to happen once per machine.
+
+## Running GraphQL
+
+Use the `api` subcommand. It accepts the operation via `--query` or stdin, and string variables via `-F key=value` (repeatable). Output is the raw JSON GraphQL response (`{ data, errors }`) — non-zero exit on HTTP errors or `errors[]`.
+
+```bash
+# Simple query
+specset api --query '{ me { id email firstName } }'
+
+# Query with an ID variable
+specset api \
+  --query 'query($id: ID!) { project(id: $id) { id name } }' \
+  -F id=abc-123
+
+# Long operation via stdin
+specset api <<'GQL'
+query {
+  me { id email orgMembers { id org { id slug name } } }
+}
+GQL
+```
+
+### Variable Limitations
+
+`-F key=value` only sends **string** values. For non-string args (numbers, booleans, enums, input objects, lists), inline literals directly in the operation rather than parameterizing them. Reserve `-F` for IDs and plain strings.
+
+### Schema Discovery
+
+Discover the API shape through introspection queries:
+
+```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.
+
+## 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**:
+
+```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"
+```
+
+3. Finalize the upload to create the file record and capture its id:
+
+```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 } } } }'
+```
+
+## Waiting on Background Processing
+
+Document imports and other bulk operations return a `BulkAction` and continue in the background. There are no subscriptions over `specset api` — poll with short sleeps and cap your retries:
+
+```bash
+specset api --query 'query($id: ID!) {
+  bulkAction(id: $id) { totalCount completedCount failedCount }
+}' -F id=<bulk-action-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
+
+- 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.
+
+## 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>`.
+- 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 requires a browser; on a headless machine, run the CLI from a machine with a browser first, or contact Specset support about headless options.
+- After upgrading the CLI (`npm i -g @specset/cli@latest`), refresh the skills with `specset skill install`.

package/skills/specset-admin/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: specset-admin
+description: Use when administering a Specset organization — inviting and managing members and roles, or applying whitelabel branding (colors, logos) — for org membership, permissions, or appearance tasks.
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+# Org Administration
+
+Requires the `specset` CLI, logged in with an active org. If a command fails with `command not found`, `Not logged in`, or `No active organization`, follow First-Run Setup in the `specset` skill.
+
+Every operation here takes your org id — get it with `{ me { orgMembers { org { id slug name } } } }` if you don't have it. Remember Variable Limitations in the `specset` skill: inline enums, lists, and input objects as literals in the operation text; reserve `-F` for ids and plain strings. When an operation or argument doesn't match this document, introspect (see the `specset` skill → Schema Discovery) rather than guess. These mutations change real people's access and the whole org's appearance — confirm each one with the user before running it.
+
+## Members
+
+Roles (`OrgMemberTeamRole`): `Member`, `Manager`, `Admin`. Statuses (`OrgMemberStatus`): `PendingApproval`, `Active`, `Deactivated`. You need to be an org Admin for most mutations in this skill.
+
+List members — filtered flat list or paginated search:
+
+```bash
+specset api --query 'query($orgId: ID!) {
+  orgMembers(orgId: $orgId, statuses: [Active]) {
+    id role status user { id email firstName lastName }
+  }
+}' -F orgId=<org-id>
+
+specset api --query 'query($orgId: ID!, $search: String) {
+  paginatedOrgMembers(orgId: $orgId, search: $search, first: 20) {
+    edges { node { id role status user { email } } }
+    pageInfo { hasNextPage endCursor totalCount }
+  }
+}' -F orgId=<org-id> -F search="smith"
+```
+
+Manage them (all take the **membership** id from the queries above, not the user id):
+
+- `updateOrgMember(id: ID!, role: ..., projectIds: [ID!])` — `role` is required even when unchanged, so resend the current role when only touching `projectIds`. `projectIds` scopes a Member to specific projects; omit it to leave project access alone.
+- `approveOrgMember(id: ID!)` — activate a `PendingApproval` member.
+- `deactivateOrgMember(id: ID!)` / `reactivateOrgMember(id: ID!)` — suspend and restore access. Deactivation is reversible and preserves history — always prefer it over any form of member deletion.
+
+```bash
+specset api --query 'mutation($id: ID!) {
+  updateOrgMember(id: $id, role: Manager) { id role user { email } }
+}' -F id=<org-member-id>
+```
+
+## Invites
+
+- `orgInvites(orgId: ID!)` / `paginatedOrgInvites(orgId: ID!, first: Int, after: String)` — pending invites; select `{ id email role inviteUrl }`.
+- `createOrgInvite(orgId: ID!, email: String!, role: ..., projectIds: [ID!])` — sends the invite email; `projectIds` (optional, inline the list) pre-scopes a Member to specific projects. Set `role` deliberately — don't default people to more access than they need. Share the returned `inviteUrl` if the email might not land.
+- `updateOrgInvite(id: ID!, role: ..., projectIds: [ID!])` — `role` is required.
+- `deleteOrgInvite(id: ID!)` — revoke a pending invite.
+
+```bash
+specset api --query 'mutation($orgId: ID!, $email: String!) {
+  createOrgInvite(orgId: $orgId, email: $email, role: Member) {
+    id email role inviteUrl
+  }
+}' -F orgId=<org-id> -F email=alex@example.com
+```
+
+## Branding Your Organization
+
+Appearance changes require the **whitelabel** plan feature: without it the mutation is rejected for org admins, and custom branding won't render even if set. If you hit an authorization error on `appearance`, or branding saves but doesn't show, email support@specset.com about whitelabel access.
+
+### Colors
+
+Theming hangs off five anchor colors; the app derives the full light and dark palettes from them:
+
+| Anchor | Drives |
+|---|---|
+| `brand` | Primary buttons, links, navigation highlights |
+| `magic` | AI/agent accent surfaces |
+| `success` | Positive states |
+| `danger` | Destructive/error states |
+| `warning` | Caution states |
+
+Each is a `#rrggbb` hex string. `appearance` is an input object, so inline it. **`updateOrg` replaces the whole appearance object** — include every anchor you want on every call; any you omit are cleared back to the stock theme.
+
+```bash
+specset api --query 'mutation($id: ID!) {
+  updateOrg(id: $id, appearance: { anchors: {
+    brand: "#003087", magic: "#0085CA", success: "#4B8320",
+    danger: "#B71300", warning: "#FF8400"
+  } }) {
+    id
+    appearance { anchors { brand magic success danger warning } }
+  }
+}' -F id=<org-id>
+```
+
+Pick a `brand` dark enough to hold white text (roughly: not a pastel) — it becomes button and link color on white backgrounds. Branding applies to every member of the org, so confirm the palette with the user before writing it.
+
+### Logos
+
+Two slots, both attached by file id on `updateOrg`:
+
+- `logoId` — square mark; shown where space is tight (collapsed navigation).
+- `wideLogoId` — horizontal mark + wordmark; shown in the expanded header.
+
+Upload the image first following Uploading Files in the `specset` skill to get a file id, then attach:
+
+```bash
+specset api --query 'mutation($id: ID!, $fileId: ID!) {
+  updateOrg(id: $id, wideLogoId: $fileId) { id wideLogo { id } }
+}' -F id=<org-id> -F fileId=<file-id>
+```
+
+Use `logoId: $fileId` for the square mark. Passing `null` (inline) clears a slot.
+
+## Safety
+
+- Confirm every mutation before running it. For role changes, deactivations, and invite deletions, echo the affected person's email back to the user first — these change real access immediately.
+- Prefer `deactivateOrgMember` over anything destructive; never hard-delete a membership.
+- Never pass `maxCredits` or `skus` to `updateOrg` — those fields are managed by Specset and the mutation will be rejected.
+- On `updateOrg`, send only the fields you mean to change (plus the full `appearance` object when changing any part of it).
+- Creating or deleting organizations, SSO, and email-domain management are out of scope for this skill — direct the user to support@specset.com.

package/skills/specset-agent/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: specset-agent
+description: Ask Specset's in-project AI agent questions that need deep project understanding — schedules, spec interpretation, cross-document analysis — via `specset agent chat`. Use when raw GraphQL isn't enough or when unsure how to answer from data.
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+# Specset Agent Chat
+
+Requires the `specset` CLI, logged in with an active org. If a command fails with `command not found`, `Not logged in`, or `No active organization`, follow First-Run Setup in the `specset` skill.
+
+Specset runs its own project-aware AI agent with full access to a project's specs, drawings, submittals, RFIs, and closeout data. `specset agent chat` sends it a message and waits for the full response — use it for questions that need Specset's own project understanding rather than raw data access.
+
+## When to Delegate vs. Query Directly
+
+Delegate to the agent when the answer requires reading and interpreting documents:
+
+- Equipment and schedule extraction ("what mechanical equipment is scheduled on level 2?")
+- Spec interpretation ("what are the submittal requirements in section 08 71 00?")
+- Drawing analysis ("which sheets show the roof drainage details?")
+- Drafting a submittal log from the specs (see the `specset-submittals` skill for applying the result)
+- Comparing plan sets or revisions
+
+Query directly with `specset api` when the user wants structured records — lists, lookups, creates, updates. The `specset-search`, `specset-projects`, `specset-submittals`, `specset-rfis`, and `specset-closeout` skills cover those workflows.
+
+## Driving a Conversation
+
+```bash
+# Ask a question scoped to a project
+specset agent chat --project <projectId> -m "What mechanical equipment is scheduled on level 2?"
+
+# Continue the same conversation (thread id is in the first response)
+specset agent chat --thread <threadId> -m "Which of those have submittals?"
+
+# Review a past conversation
+specset agent show <threadId>
+```
+
+Use `--json` for machine-readable output (all commands accept it). Long-running questions may need `--timeout <seconds>` — document analysis can take a few minutes.
+
+Find a project id first if you don't have one:
+
+```bash
+specset api --query 'query { projects { id name } }'
+```
+
+## Notes
+
+- Keep one thread per topic: follow-ups via `--thread` give the agent the prior context and produce better answers than fresh threads.
+- The agent may propose changes (creating submittals, updating records) but those are applied through the Specset UI thread where the user approves them — CLI chat is best treated as read/analysis oriented. To make changes headlessly, use the mutations documented in the domain skills instead.
+- The agent answers from the project you scope it to; double-check the `--project` id when results look unrelated.

package/skills/specset-closeout/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: specset-closeout
+description: Use when managing Specset closeout and facilities data — assets, locations, products, companies, warranties, and maintenance tasks, plus their documents and links — for closeout package or O&M/facilities tasks.
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+# Closeout & Facilities Data
+
+Requires the `specset` CLI, logged in with an active org. If a command fails with `command not found`, `Not logged in`, or `No active organization`, follow First-Run Setup in the `specset` skill.
+
+Run every operation with `specset api`. All ids are plain UUIDs. Remember Variable Limitations in the `specset` skill: `-F` sends strings only — inline every enum, number, boolean, list, and input object as a literal in the operation text, and reserve `-F` for ids and plain strings. This document is not exhaustive — when an operation or argument doesn't match, introspect (see the `specset` skill → Schema Discovery) rather than guess.
+
+## Entity Model
+
+**Locations** are the spatial scaffold (site → building → level → room), nesting via `parentId`. **Systems** are disciplines and equipment groups (HVAC, electrical, fire protection), also nested. **Products** are the spec'd make/models. **Assets** are installed instances: each asset sits at one location, is optionally an instance of one product with one responsible **company**, and can join multiple systems through role-tagged memberships. **Warranties** and **maintenance tasks** hang off assets, and maintenance tasks accumulate **completions** (service-log entries). Everything is scoped to a project.
+
+## The Per-Entity Pattern
+
+Asset, Location, Product, Company, System, Warranty, and MaintenanceTask share one surface:
+
+| Operation | Shape |
+|---|---|
+| `<entity>(id: ID!)` | Single record (`null` if missing or in another org) |
+| `paginated<Entities>(projectId: ID!, limit: Int, offset: Int, ...)` | Returns `{ items { ... } totalFilteredCount }` |
+| `search<Entities>(projectId: ID!, search: String)` | Fuzzy text lookup |
+| `create<Entity>(input: ...)` / `update<Entity>(input: ...)` | Update inputs take `id` plus only the fields to change |
+| `delete<Entity>(id: ID!)` | Hard delete — see Safety |
+
+Real deviations:
+
+- **Asset** — create requires `projectId` + `locationId`. `paginatedAssets` also takes `search` and a `filters` input (`statuses`, `locationIds`, `productIds`, `systemIds`, `responsibleCompanyIds`, `parentIds`, `archived`) for cross-entity tracing.
+- **Warranty / MaintenanceTask** — asset-scoped: create inputs take `assetId` (not `projectId`); no `search<Entities>` query, and `search` on their paginated lists is ignored — scope by asset with `warrantiesByAsset(assetId)` / `maintenanceTasksByAsset(assetId)` instead.
+- Batch deletes exist for some entities (`deleteLocations(ids)`, `deleteCompanies(ids)`, `deleteSystems(ids)`, `deleteWarranties(ids)`, `deleteMaintenanceTasks(ids)`) — same confirmation rules as single deletes.
+
+Introspect the input object before composing any create or update, e.g. `{ __type(name: "CreateAssetInput") { inputFields { name type { name kind ofType { name } } } } }`.
+
+Worked example — find, then create:
+
+```bash
+specset api --query 'query($projectId: ID!) {
+  paginatedAssets(projectId: $projectId, search: "AHU", limit: 20, offset: 0) {
+    totalFilteredCount
+    items { id tag status location { id name } product { id name } }
+  }
+}' -F projectId=<project-id>
+
+specset api --query 'mutation($projectId: ID!, $locationId: ID!, $productId: ID!) {
+  createAsset(input: {
+    projectId: $projectId, locationId: $locationId, productId: $productId,
+    tag: "AHU-1", status: Installed, quantity: 1
+  }) { id tag status }
+}' -F projectId=<project-id> -F locationId=<location-id> -F productId=<product-id>
+```
+
+Prefer `update<Entity>` for changes: pass `id` plus only what changes; pass `null` to clear an optional relationship (e.g. `productId: null`). Update inputs for Asset, Location, Product, Company, and System accept `archived: true` — a reversible soft-archive that drops the record from default lists. Prefer it over delete.
+
+## Asset Links
+
+Three `set*` mutations each **replace** the full id set for the given `(assetId, role)` tuple — anything previously linked at that role and not in the new list is removed; pass `[]` to clear. Inline the enum and the id list:
+
+- `setAssetSystems(assetId: ID!, role: ..., systemIds: [ID!]!)` — roles: `Primary`, `Secondary`, `Control`, `MonitoredBy`, `Other`. Read back with `assetSystemMemberships(assetId)`.
+- `setAssetSubmittals(assetId: ID!, relationship: ..., submittalIds: [ID!]!)` — relationships: `Source`, `Revision`, `Substitution`, `Addendum`. Read back with `assetSubmittalLinks(assetId)`.
+- `setAssetDrawingSheets(assetId: ID!, role: ..., drawingSheetIds: [ID!]!)` — roles include `Plan`, `Schedule`, `Diagram`, `Detail`, `AsBuilt`, `Other`. Read back with `assetDrawingSheetLinks(assetId)`.
+
+```bash
+specset api --query 'mutation($assetId: ID!, $systemId: ID!) {
+  setAssetSystems(assetId: $assetId, role: Primary, systemIds: [$systemId]) {
+    id role system { id name }
+  }
+}' -F assetId=<asset-id> -F systemId=<system-id>
+```
+
+## Entity Documents
+
+Each entity links to project documents through a role-tagged pivot. Find document ids with `documents(projectId: ID!) { id title }`. The pattern (uniform across Location, Product, Company, System, Warranty, MaintenanceTask; substitute the entity name):
+
+- `<entity>Documents(<entity>Id: ID!)` — list the pivots. Select `{ id roles document { id title } }`.
+- `set<Entity>DocumentRoles(<entity>Id: ID!, documentId: ID!, roles: [...]!)` — upsert the linkage; an empty `roles` list removes it (and the document itself if orphaned). Roles are per-entity enums — e.g. `ProductDocumentRole` is `Datasheet`, `InstallationManual`, `OperationManual`, `MaintenanceManual`, `Warranty`, `SubmittalPackage`, `Other`; introspect each entity's enum before use.
+- `delete<Entity>Document(id: ID!)` — takes the **pivot** id from the list query, not the document id.
+
+Asset is the exception: it has `assetDocuments(assetId)` and `deleteAssetDocument(id)` but no set-roles mutation.
+
+## Documentation Blocks
+
+Asset, Location, Product, Company, and System each carry a markdown documentation block used by closeout exports:
+
+- `update<Entity>Documentation(id: ID!, markdown: String!)` — replace the block. Pass `markdown` via `-F` (it's a plain string).
+- `mark<Entity>DocumentationComplete(id: ID!)` — attest the block is current (clears it from stale-documentation rollups).
+
+## Maintenance Completions
+
+Service history lives on completions under each task:
+
+- `maintenanceTaskCompletions(maintenanceTaskId: ID!)` — select `{ id performedDate dueDate performedByName result }`.
+- `createMaintenanceTaskCompletion(input: { maintenanceTaskId, performedDate, ... })` — `performedDate` is required; optional `dueDate`, `performedByName`, `performedByCompanyId`, `result`. Introspect `CreateMaintenanceTaskCompletionInput` for the full set.
+- `updateMaintenanceTaskCompletion(input: { id, ... })` / `deleteMaintenanceTaskCompletion(id: ID!)`.
+- Completion documents: `addMaintenanceTaskCompletionDocument(completionId: ID!, documentId: ID!)` and `deleteMaintenanceTaskCompletionDocument(id: ID!)` (pivot id).
+
+## Dedup / Re-Pointing Recipe
+
+For duplicate products P1 (loser) and P2 (survivor):
+
+1. `paginatedAssets(projectId: ..., filters: { productIds: ["<p1-id>"] })` — collect affected assets.
+2. `updateAsset(input: { id: ..., productId: "<p2-id>" })` per asset.
+3. Re-run step 1 and confirm zero results.
+4. `updateProduct(input: { id: "<p1-id>", archived: true })` — archive the loser; delete only if it is clearly an unreferenced mistake.
+
+The same shape works for duplicate companies, locations, and systems.
+
+## Safety
+
+- Confirm with the user before every mutation. For deletes, name the exact record (tag/name + id) and get explicit approval — they are hard deletes with no undo.
+- Prefer `update` over delete-and-recreate, and `archived: true` over delete: deleting a product, location, or company silently nulls the references on assets that pointed at it. Check impact first with the filtered list queries.
+- Removing a document linkage can delete the underlying document if nothing else references it — say so when confirming.

package/skills/specset-projects/SKILL.md

@@ -0,0 +1,113 @@
+---
+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
+
+Requires the `specset` CLI, logged in with an active org. If a command fails with `command not found`, `Not logged in`, or `No active organization`, follow First-Run Setup in the `specset` skill.
+
+This skill mutates data — confirm with the user before each mutation, and always confirm the project name and which files belong to it before creating anything. Remember Variable Limitations from the `specset` skill: `-F` sends **strings only** — inline every enum, boolean, int, list, and input object as a literal; reserve `-F` for IDs and plain strings. When an operation or argument here doesn't match, introspect (see Schema Discovery in the `specset` skill).
+
+## 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. Agents that miss this conclude the creation failed and create duplicates — don't. Fetch the new project by `project(id)`, and add membership as a separate step, mirroring the UI.
+
+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. Never run it without explicit user confirmation that names the exact project ("delete Riverside Medical Center — permanently?"). If the user just wants it out of the way, archive instead.
+
+## Troubleshooting
+
+- Authorization error on a mutation — the user lacks that permission; the same rules as the UI apply. Surface the message, don't retry.
+- A freshly created project "missing" from `projects` — that's the membership gotcha above, not a failure. Check `project(id)` before recreating anything.
+- A document reports a failed processing status on the BulkAction — report it to the user; re-uploading is their call.
+- A lookup by id returns `null` — the record belongs to a different org than the active one; check `specset auth status`.