@specset/cli 0.5.1 → 1.0.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@specset/cli",
-  "version": "0.5.1",
+  "version": "1.0.0",
   "description": "Command-line interface for Specset — authenticate, run GraphQL queries, and chat with Specset project agents.",
-  "license": "Apache-2.0",
+  "license": "Elastic-2.0",
   "homepage": "https://specset.com",
   "repository": {
     "type": "git",

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

@@ -0,0 +1,18 @@
+{
+  "name": "specset",
+  "version": "1.0.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": "Elastic-2.0",
+  "keywords": [
+    "construction",
+    "drawings",
+    "specifications",
+    "submittals",
+    "rfis"
+  ]
+}

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

@@ -0,0 +1,42 @@
+{
+  "name": "specset",
+  "version": "1.0.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": "Elastic-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,11 @@
+# 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.
+- External tool and GraphQL source references are presented as clickable `https://app.specbook.ai/go/...` links. Bundled skills instruct agents to include relevant returned links in answers so users can open the cited source in Specset.
+
+`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,120 @@
+---
+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 preserves the raw JSON GraphQL envelope (`{ 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.
+
+### IDs and Source Links
+
+- GraphQL fields named `id` are ordinary UUIDs. Use those UUIDs for GraphQL `ID` variables.
+- Citation-bearing fields named `url` and source references embedded in text are emitted as clickable `https://app.specbook.ai/go/<type>/<uuid>` links. The CLI accepts a complete Specset `/go` link in an **`ID`-typed variable** and extracts its UUID automatically (any focus parameters on the link are dropped, with a warning on stderr). Links inlined as literals in the query text, or passed in non-ID variables, are sent to the server verbatim — inline bare UUIDs there instead.
+- `-F` values for non-ID variables are always sent byte-for-byte as typed. Storing a `/go` link in a text field is fine — it is a real URL.
+- Response output rewrites Specset's internal reference representation to public `/go` links by default; `specset api --refs internal` returns the byte-exact server response for low-level debugging and should not be used in user-facing answers.
+- Include relevant returned `/go` links as descriptive Markdown source links in answers so the user can open the exact source in Specset. Cite only links actually returned by Specset; never manufacture one from an unrelated UUID.
+
+### 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 clickable Specset source links.
+
+## 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 a clickable `https://app.specbook.ai/go/file/...` source link. `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,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
+
+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.
+
+Agent transcripts expose their source references as clickable `https://app.specbook.ai/go/...` links. Preserve the most relevant returned links as descriptive Markdown citations when relaying the answer to the user. Do not fabricate additional links from UUIDs. An identifier that is not an `https://` link (a thread-local short id or `doc:`-prefixed identifier) is internal — pass it back into commands verbatim, but never present it to the user as a clickable link. Both `--project` and `--thread` accept returned Specset links as well as UUIDs.
+
+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,188 @@
+---
+name: specset-closeout
+description: Use when managing Specset closeout and facilities data — assets, locations, products, companies, warranties, procedures, maintenance plans, work orders, and their documents and links.
+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` sends strings only; Variable Limitations and Schema Discovery live in the `specset` skill).
+
+## Entity Model
+
+**Locations** are the spatial scaffold (site → building → level → room), nesting through `parentId`. **Systems** are disciplines and equipment groups, also nested. **Products** are specified make/models. **Assets** are installed instances: each asset has a location, may reference a product and responsible company, and can join multiple systems. **Warranties** attach to assets.
+
+Maintenance has three layers:
+
+- **Procedure** — reusable checklist content: ordered typed fields, descriptions, and source references.
+- **MaintenancePlan** — a schedule on exactly one Product, Asset, Location, or System. Product plans fan out to installed assets. Its `tiers` are independent schedule items that pair a Procedure with a calendar cadence, meter trigger, or both.
+- **WorkOrder** — a concrete occurrence or ad-hoc job. Generated work orders snapshot their checklist fields, so history remains stable when a Procedure changes.
+
+`MaintenanceTask` and its completion API no longer exist. Use Procedure, MaintenancePlan, and WorkOrder operations below.
+
+## Discover Before Mutating
+
+Input objects evolve, especially checklist fields and plan tiers. Introspect the relevant input before composing a mutation:
+
+```bash
+specset api --query '{
+  createPlan: __type(name: "CreateMaintenancePlanInput") {
+    inputFields { name type { kind name ofType { kind name } } }
+  }
+  tier: __type(name: "MaintenancePlanTierInput") {
+    inputFields { name type { kind name ofType { kind name } } }
+  }
+  complete: __type(name: "CompleteWorkOrderInput") {
+    inputFields { name type { kind name ofType { kind name } } }
+  }
+}'
+```
+
+Inline input objects and enums in the operation text. Use `-F` for UUIDs, dates, and other scalar strings.
+
+## Core Closeout Records
+
+Asset, Location, Product, Company, System, and Warranty retain the standard surface:
+
+| Operation                                                           | Shape                                       |
+| ------------------------------------------------------------------- | ------------------------------------------- |
+| `<entity>(id: ID!)`                                                 | Single record; nullable when missing        |
+| `paginated<Entities>(projectId: ID!, limit: Int, offset: Int, ...)` | `{ items { ... } totalFilteredCount }`      |
+| `create<Entity>(input: ...)` / `update<Entity>(input: ...)`         | Update inputs take `id` plus changed fields |
+| `delete<Entity>(id: ID!)`                                           | Hard delete; follow Safety below            |
+
+Notable differences:
+
+- Asset creation requires `projectId` and `locationId`. `paginatedAssets` accepts `search` and filters such as `statuses`, `locationIds`, `productIds`, `systemIds`, `responsibleCompanyIds`, `parentIds`, and `archived`.
+- Warranty is asset-scoped; use `warrantiesByAsset(assetId)` to browse one asset's warranties.
+- Location, Product, Company, System, and Asset updates support reversible `archived` state. Prefer archiving to deletion.
+- Batch-delete availability varies. Introspect the mutation root rather than guessing an operation name.
+
+Asset link setters replace the complete set for the given role/relationship; omitted ids are removed and `[]` clears the set:
+
+- `setAssetSystems(assetId, role, systemIds)` / `assetSystemMemberships(assetId)`
+- `setAssetSubmittals(assetId, relationship, submittalIds)` / `assetSubmittalLinks(assetId)`
+- `setAssetDrawingSheets(assetId, role, drawingSheetIds)` / `assetDrawingSheetLinks(assetId)`
+
+## Procedures
+
+Use `procedure(id)` and `paginatedProcedures(projectId, filters, limit, offset)`. Procedure list filters include `search` and `archived`.
+
+Create a reusable checklist with its fields atomically:
+
+```bash
+specset api --query 'mutation($projectId: ID!) {
+  createProcedure(input: {
+    projectId: $projectId
+    name: "Quarterly AHU service"
+    fields: [
+      { name: "Inspect belts", fieldType: Checkbox }
+      { name: "Record supply temperature", fieldType: Number, unit: "°F" }
+    ]
+  }) {
+    id name updatedAt
+    fields { id name fieldType position required }
+  }
+}' -F projectId=<project-id>
+```
+
+The fields' array order sets their `position`; neither `CreateProcedureFieldInput` nor `UpdateProcedureFieldInput` accepts a `position` property. `updateProcedure(input: { id, ... })` is partial for scalar fields. Supplying `fields` performs a full checklist replacement; first read the current fields and include the `id` of every row that should retain its identity. `deleteProcedure(id, force)` is guarded when active plans use it. Do not set `force: true` without naming the affected plans and confirming the destructive change.
+
+## Maintenance Plans and Tiers
+
+Read with `maintenancePlan(id)`, `paginatedMaintenancePlans(projectId, filters, limit, offset)`, or `maintenancePlansForAsset(assetId, includeProductPlans)`.
+
+Create requires exactly one subject id (`productId`, `assetId`, `locationId`, or `systemId`) and a `frequencyKind`. Prefer `tiers`; the top-level procedure and interval fields remain a single-item compatibility surface. Supply either:
+
+- single-tier compatibility fields: `procedureId` (or inline `procedure`) plus `intervalValue` / `intervalUnit`; or
+- `tiers: [MaintenancePlanTierInput!]` for independent schedule items. Each item selects one `procedureId` or creates one inline.
+
+Do not mix `tiers` with the single-tier procedure/cadence fields. Calendar item units are `Days`, `Weeks`, `Months`, or `Years`. Optional meter conditions live on each item as the pair `meterUnit` (`Hours` or `Cycles`) and `meterThreshold`; provide both or neither. Calendar cadences are independent and do not need to be multiples of one another. Set `skipLowerTiersOnSharedDate: true` to suppress a shorter calendar item when it naturally shares a date with a longer one; each work order still contains only its own Procedure. A suppressed item's meter condition stays armed and may create that item's work order later. `gateOnOpen` prevents repeated meter-generated work while an occurrence remains open.
+
+```bash
+specset api --query 'mutation($assetId: ID!, $monthlyId: ID!, $quarterlyId: ID!) {
+  createMaintenancePlan(input: {
+    assetId: $assetId
+    name: "AHU PM program"
+    frequencyKind: Calendar
+    skipLowerTiersOnSharedDate: true
+    gateOnOpen: true
+    tiers: [
+      { procedureId: $monthlyId, intervalValue: 1, intervalUnit: Months }
+      {
+        procedureId: $quarterlyId
+        intervalValue: 3
+        intervalUnit: Months
+        meterUnit: Hours
+        meterThreshold: 500
+      }
+    ]
+  }) {
+    id name frequencyKind skipLowerTiersOnSharedDate gateOnOpen
+    tiers {
+      id intervalValue intervalUnit meterUnit meterThreshold
+      procedure { id name }
+    }
+    openWorkOrderCount
+  }
+}' -F assetId=<asset-id> -F monthlyId=<procedure-id> -F quarterlyId=<procedure-id>
+```
+
+For a meter-only plan, prefer the typed input: `schedule: { meter: { unit: Hours|Cycles, threshold: <n>, gateOnOpen } }` with a single tier. The legacy encoding (`frequencyKind: RuntimeHours` or `Cycles`) additionally requires plan-level `intervalValue` set to the threshold and `intervalUnit: Hours`/`Cycles` — a threshold on the item alone is rejected. For an on-demand plan, use `AsNeeded`, `EventTriggered`, or `Other` and omit calendar and meter fields.
+
+`updateMaintenancePlan(input: { id, ... })` can retarget the subject: pass exactly one of `productId`/`assetId`/`locationId`/`systemId` (same project). Open work orders for the old subject are retired — untouched ones removed, in-progress ones canceled — and fresh chains generate for the new subject. Supplying `tiers` fully replaces the schedule-item set: include the `id` of every existing item to update/retain, omit an item only when it should be removed, and omit `id` only for new items. Read the plan and its item ids immediately before updating.
+
+Use `createWorkOrderFromPlan(planId, targetAssetId, dueDate, coveredTierIds)` for an early/manual occurrence of a plan. Product plans require the concrete `targetAssetId`. `coveredTierIds` is optional; when supplied it states exactly which tiers the occurrence performs.
+
+## Work Orders
+
+Use `workOrder(id)`, `paginatedWorkOrders(projectId, filters, limit, offset)`, and `paginatedGroupedWorkOrders(projectId, groupBy, groupKeys, filters, limit, offset)`. Grouped reads require both the grouping dimensions and the current group-key path. Useful fields include `status`, `dueDate`, `performedDate`, `priority`, `assignee`, `plan`, `planTier`, `coveredTiers`, `fields`, and `documents`.
+
+`createWorkOrder(input)` creates ad-hoc work and requires exactly one of `assetId`, `locationId`, or `systemId`, plus `name`. Optional `fields` create a reusable inline Procedure; optional `recurrence` also creates a MaintenancePlan. Use `updateWorkOrder(input: { id, ... })` for editable metadata.
+
+Checklist responses use `setWorkOrderFieldResponse(input)` or `setWorkOrderFieldResponses(inputs)`. Introspect `SetWorkOrderFieldResponseInput`: answer columns vary by field type (`valueNumber`, `valueText`, `valueChoice`, `status`, and `note`).
+
+Complete work through the batch mutation even for one row:
+
+```bash
+specset api --query 'mutation($id: ID!, $performedDate: DateTime!) {
+  completeWorkOrders(inputs: [{ id: $id, performedDate: $performedDate }]) {
+    workOrder { id status performedDate }
+    nextWorkOrder { id status dueDate }
+  }
+}' -F id=<work-order-id> -F performedDate=2026-08-04
+```
+
+Other lifecycle operations:
+
+- `skipWorkOrder(id, notes, mode)` — closes the occurrence as skipped; omit `mode` for normal independent-item plans. Non-default modes exist only for historical merged work orders.
+- `reopenWorkOrder(id)` — reopens completed/skipped work when allowed.
+- `makeWorkOrderRecurring(workOrderId, recurrence)` — converts eligible ad-hoc work into a recurring plan.
+- `deleteWorkOrder(id)` — hard delete.
+- `bulkAssignWorkOrders(selection, assigneeId)` and `bulkDeleteWorkOrders(selection)` operate on an explicit selection object.
+- `addWorkOrderDocument(workOrderId, documentId, workOrderFieldId)` and `removeWorkOrderDocument(id)` manage evidence. Removal takes the WorkOrderDocument pivot id.
+
+## Entity Documents and Documentation
+
+Location, Product, Company, System, and Warranty link project Documents through entity-specific role-tagged pivots. Read `<entity>Documents(<entity>Id)`, then call `set<Entity>DocumentRoles(<entity>Id, documentId, roles)` after introspecting that entity's role enum. An empty role list removes the pivot and may delete the underlying Document when it becomes orphaned. Asset is the exception: it exposes `assetDocuments(assetId)` and `deleteAssetDocument(id)`, but no set-roles mutation.
+
+Asset, Location, Product, Company, and System also have markdown documentation blocks. `update<Entity>Documentation(id, markdown)` replaces the block; `mark<Entity>DocumentationComplete(id)` attests that it is current.
+
+## Dedup / Re-pointing
+
+For duplicate products P1 (loser) and P2 (survivor):
+
+1. Query `paginatedAssets(projectId, filters: { productIds: [P1] })` and collect impacted assets.
+2. `updateAsset(input: { id, productId: P2 })` for each asset.
+3. Re-run the filtered query and confirm zero remaining references.
+4. Archive P1 with `updateProduct(input: { id: P1, archived: true })`.
+
+Use the same impact-first pattern for duplicate companies, locations, and systems.
+
+## Safety
+
+- Deletes are hard and have no undo. Before executing, name the exact record and id and confirm the impact.
+- Prefer partial updates, and prefer `archived: true` to delete where supported.
+- Read Procedure fields and MaintenancePlan tiers before any full-replacement update.
+- Deleting plans or force-deleting Procedures can alter future generated work. Check active plan/open-work-order counts first.
+- Removing a document linkage can delete an orphaned underlying Document; disclose that before confirming.