@specset/cli 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specset/cli",
-  "version": "0.5.0",
+  "version": "0.6.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",

package/plugin/specset/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "specset",
+  "version": "0.6.0",
+  "description": "Search and manage Specset construction project data with shared skills and MCP tools.",
+  "author": {
+    "name": "Specset"
+  },
+  "homepage": "https://docs.specset.com",
+  "repository": "https://github.com/specsetai/specset-plugins",
+  "license": "Apache-2.0",
+  "keywords": [
+    "construction",
+    "drawings",
+    "specifications",
+    "submittals",
+    "rfis"
+  ]
+}

package/plugin/specset/.codex-plugin/plugin.json

@@ -0,0 +1,42 @@
+{
+  "name": "specset",
+  "version": "0.6.0",
+  "description": "Search and manage Specset construction project data with shared skills and MCP tools.",
+  "author": {
+    "name": "Specset",
+    "email": "support@specset.com",
+    "url": "https://specset.com"
+  },
+  "homepage": "https://docs.specset.com",
+  "repository": "https://github.com/specsetai/specset-plugins",
+  "license": "Apache-2.0",
+  "keywords": [
+    "construction",
+    "drawings",
+    "specifications",
+    "submittals",
+    "rfis"
+  ],
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Specset",
+    "shortDescription": "Search and manage construction project data",
+    "longDescription": "Use Specset skills and MCP tools to search specifications and drawings, inspect project records, manage workflows, and transfer files.",
+    "developerName": "Specset",
+    "category": "Productivity",
+    "capabilities": [
+      "Skills",
+      "MCP",
+      "File transfer"
+    ],
+    "websiteURL": "https://specset.com",
+    "privacyPolicyURL": "https://specset.com/privacy",
+    "termsOfServiceURL": "https://specset.com/terms",
+    "defaultPrompt": [
+      "Find the project requirements for this scope.",
+      "Compare this submittal with the specifications.",
+      "Show me the latest RFIs affecting this work."
+    ],
+    "brandColor": "#1F6FEB"
+  }
+}

package/plugin/specset/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "specset": {
+      "command": "specset",
+      "args": ["mcp"]
+    }
+  }
+}

package/plugin/specset/README.md

@@ -0,0 +1,10 @@
+# Specset plugin
+
+This is the source template for the universal Specset plugin bundle.
+
+- Codex and Claude Code discover the bundled skills and start `specset mcp` over stdio. The CLI owns browser/device authentication and direct local file transfer.
+- ChatGPT and other hosted clients connect to Specset's Streamable HTTP MCP endpoint at `https://<host>/mcp`. OAuth 2.1 consent binds the grant to the selected organization; the server uses the same tool registry and adds host-file upload and signed-download tools.
+
+`yarn nx run cli:package` copies the canonical `apps/cli/skills` tree into this plugin template under `apps/cli/publish/plugin/specset`. Keep skill source changes in `apps/cli/skills`; do not hand-edit a staged copy.
+
+The hosted transport publishes OAuth protected-resource and authorization-server metadata, supports Client ID Metadata Documents with PKCE, and issues short-lived audience-bound access tokens with rotating refresh tokens. First-party clients may continue to use a Specset session bearer token with an explicit organization header.

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

@@ -0,0 +1,112 @@
+---
+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 CLI setup or raw GraphQL access, 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-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
+
+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. **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.
+
+## 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
+
+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
+specset api --query '{ __type(name: "Project") { fields { name type { name kind ofType { name } } } } }'
+```
+
+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 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, 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
+specset files upload ./document.pdf
+specset files upload ./photo.jpg --type image/jpeg --json
+```
+
+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`.
+
+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
+
+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
+
+Confirm with the user before executing mutations that create, update, or delete data. The domain skills note the mutations with non-obvious consequences.
+
+## Troubleshooting
+
+- 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>`.

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

@@ -0,0 +1,112 @@
+---
+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
+
+Every operation here takes your org id — get it with `{ me { orgMembers { org { id slug name } } } }` if you don't have it. Inline enums, lists, and input objects in the operation text (`-F` is strings-only; Variable Limitations and Schema Discovery live in the `specset` skill). These mutations change real people's access and the whole org's appearance.
+
+## Members
+
+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 — 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>
+```
+
+`brand` becomes the button and link color on white backgrounds, so it needs to hold white text. Branding applies to every member of the org — confirm the palette with the user before writing it.
+
+### Logos
+
+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
+
+- For role changes, deactivations, and invite deletions, echo the affected person's email back to the user first — these change real access immediately.
+- `updateOrg` rejects `maxCredits` and `skus` — those fields are managed by Specset. Send only the fields you mean to change (plus the full `appearance` object when changing any part of it).
+- Creating or deleting organizations, SSO, and email-domain management are out of scope for this skill — direct the user to support@specset.com.

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

@@ -0,0 +1,48 @@
+---
+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
+
+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/plugin/specset/skills/specset-closeout/SKILL.md

@@ -0,0 +1,94 @@
+---
+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
+
+Run every operation with `specset api`. All ids are plain UUIDs. Inline enums, numbers, lists, and input objects in the operation text (`-F` is strings-only; Variable Limitations and Schema Discovery live in the `specset` skill).
+
+## Entity Model
+
+**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 } } } } }`.
+
+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
+
+- Deletes here are hard deletes with no undo — name the exact record (tag/name + id) when confirming.
+- Prefer `update` over delete-and-recreate, and `archived: true` over delete: deleting a product, location, or company silently nulls the references on assets that pointed at it. Check impact first with the filtered list queries.
+- Removing a document linkage can delete the underlying document if nothing else references it — say so when confirming.

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

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