@specset/cli 0.6.0 → 1.0.0

package/skills/specset-closeout/SKILL.md

@@ -1,94 +1,188 @@
 ---
 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.
+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` is strings-only; Variable Limitations and Schema Discovery live in the `specset` skill).
+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 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.
+**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.
 
-## The Per-Entity Pattern
+Maintenance has three layers:
 
-Asset, Location, Product, Company, System, Warranty, and MaintenanceTask share one surface:
+- **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.
 
-| 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 |
+`MaintenanceTask` and its completion API no longer exist. Use Procedure, MaintenancePlan, and WorkOrder operations below.
 
-Real deviations:
+## Discover Before Mutating
 
-- **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.
+Input objects evolve, especially checklist fields and plan tiers. Introspect the relevant input before composing a mutation:
 
-Introspect the input object before composing any create or update, e.g. `{ __type(name: "CreateAssetInput") { inputFields { name type { name kind ofType { name } } } } }`.
+```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:
 
-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.
+| 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            |
 
-## Asset Links
+Notable differences:
 
-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:
+- 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.
 
-- `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)`.
+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($assetId: ID!, $systemId: ID!) {
-  setAssetSystems(assetId: $assetId, role: Primary, systemIds: [$systemId]) {
-    id role system { id name }
+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 assetId=<asset-id> -F systemId=<system-id>
+}' -F projectId=<project-id>
 ```
 
-## Entity Documents
+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.
 
-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):
+## Maintenance Plans and Tiers
 
-- `<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.
+Read with `maintenancePlan(id)`, `paginatedMaintenancePlans(projectId, filters, limit, offset)`, or `maintenancePlansForAsset(assetId, includeProductPlans)`.
 
-Asset is the exception: it has `assetDocuments(assetId)` and `deleteAssetDocument(id)` but no set-roles mutation.
+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:
 
-## Documentation Blocks
+- 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
+```
 
-Asset, Location, Product, Company, and System each carry a markdown documentation block used by closeout exports:
+Other lifecycle operations:
 
-- `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).
+- `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.
 
-## Maintenance Completions
+## Entity Documents and Documentation
 
-Service history lives on completions under each task:
+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.
 
-- `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).
+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 Recipe
+## Dedup / Re-pointing
 
 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.
+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 })`.
 
-The same shape works for duplicate companies, locations, and systems.
+Use the same impact-first pattern 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.
+- 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.

package/skills/specset-search/SKILL.md

@@ -37,7 +37,22 @@ search(
 At least one of `query` or `keywords` is required; they can be combined. Results:
 
 ```graphql
-{ groups { referenceType totalCount items { url title previewText score projectId projectName } } nextOffset }
+{
+  groups {
+    referenceType
+    totalCount
+    items {
+      id
+      url
+      title
+      previewText
+      score
+      projectId
+      projectName
+    }
+  }
+  nextOffset
+}
 ```
 
 ### Project Scope (`ProjectScope`)
@@ -48,7 +63,7 @@ At least one of `query` or `keywords` is required; they can be combined. Results
 
 ### Record Types (`SourceReferenceType`)
 
-Filter with `referenceTypes`. Common values: `SpecSection`, `DrawingSheet`, `Document`, `Submittal`, `SubmittalAttachment`, `Rfi`, and the closeout types `Company`, `Location`, `Product`, `Asset`, `Warranty`, `MaintenanceTask`. Introspect the `SourceReferenceType` enum for the full list.
+Filter semantic `search` with the record types it materializes: `SpecSection`, `DrawingSheet`, `Document`, `Submittal`, and `Rfi`. Other values exist in the shared `SourceReferenceType` enum but are not necessarily supported by this operation.
 
 ## Quick Search: `quickSearch`
 
@@ -67,6 +82,8 @@ quickSearch(
 
 Results: `{ items { id url number title referenceType score projectId projectName summary } totalCount }`
 
+`quickSearch` also supports explicitly requested closeout title records: `Company`, `Location`, `System`, `Product`, `Asset`, and `MaintenancePlan`. It does not currently return `Warranty`, `Procedure`, or `WorkOrder` rows. `MaintenanceTask` is a deprecated legacy-link redirect, not a searchable record type. Omit `referenceTypes` for the standard global-search defaults, or introspect `SourceReferenceType` and use only a type supported by the selected operation.
+
 ## Precise Lookups
 
 When the user hands you a section or sheet number, look it up directly:
@@ -90,15 +107,16 @@ Useful item fields: `id sectionNumber title numberAndTitle` on SpecSection, `id
 ```bash
 specset api --query 'query($orgId: ID!) {
   search(orgId: $orgId, keywords: ["AHU-1"],
-         referenceTypes: [Submittal, SubmittalAttachment],
+         referenceTypes: [Submittal],
          projectScope: MyProjects, limit: 20) {
     groups { referenceType totalCount
-             items { url title previewText projectName } }
+             items { id url title previewText projectName } }
   }
 }' -F orgId=<org-id>
 ```
 
 ## Working With Results
 
-- Each result's `url` is a Specset reference URL (`sb://spec/<id>`, `sb://sub/<id>`, …); the UUID inside is the record's GraphQL `id` — extract it for follow-up queries. The scheme is documented in the `specset-tools` skill.
+- Each result's `id` is the UUID for follow-up GraphQL calls. Its `url` is the clickable source link (`https://app.specbook.ai/go/spec/<uuid>`, `https://app.specbook.ai/go/sub/<uuid>`, …) and can be passed directly into Specset tools and download commands.
+- In user-facing answers, include the most relevant returned `url` values as descriptive Markdown source links so the user can open the result in Specset. Never synthesize a `/go` link from a UUID that was not returned as a source link.
 - For follow-up work on what you found — updating submittals, answering RFIs, closeout records, or project/document changes — hand off to the `specset-submittals`, `specset-rfis`, `specset-closeout`, or `specset-projects` skill.

package/skills/specset-tools/SKILL.md

@@ -20,7 +20,7 @@ There are three tiers of Specset retrieval. Pick the lightest one that answers t
 
 ```bash
 specset tools list
-specset tools list --project <projectId|sb://project/...>
+specset tools list --project <projectId|https://app.specbook.ai/go/project/...>
 specset tools list --json     # full input schemas
 ```
 
@@ -40,32 +40,33 @@ specset tools run searchSpecSections \
 specset tools run searchSpecSections --project <projectId> \
   -F query="fire rating" -F keywords='["ASTM E119"]' -F limit=5
 
-# Read a specific section's full content using an ID from a search result
-specset tools run getSpecSectionContent -F id='sb://spec/....'
+# Read a specific section's full content using a source link from a search result
+specset tools run getSpecSectionContent \
+  -F id='https://app.specbook.ai/go/spec/<uuid>'
 ```
 
 Output is the tool's JSON payload (`{ success, message?, result? }`); a `{ success: false }` payload exits non-zero.
 
-### Identifiers are citation IDs, not links
+### Source links
 
-Tool results embed identifiers shaped like `sb://spec/<uuid>` or `sb://drawing/<uuid>`. Pass them back into other tools verbatim (e.g. into `getSpecSectionContent`, `getDrawingSheet`). They are citation identifiers, not web URLs.
+Tool results expose clickable links shaped like `https://app.specbook.ai/go/spec/<uuid>` or `https://app.specbook.ai/go/drawing/<uuid>`. Pass them back into other tools verbatim (for example, into `getSpecSectionContent` or `getDrawingSheet`). Include the most relevant returned links as descriptive Markdown citations in user-facing answers. Never invent a link or construct one from an unrelated UUID. An identifier that is not an `https://` link (a thread-local short id or `doc:`-prefixed identifier) is internal — pass it back into tools verbatim, but never present it to the user as a clickable link.
 
 ### Project scoping
 
-Most tools are project-scoped. Either pass `--project` (a UUID or `sb://project/...`), or include `projectId` in the tool input. Use `listProjects` to discover project IDs. With `--project` set, per-call `projectId` becomes optional.
+Most tools are project-scoped. Either pass `--project` (a UUID or returned `/go/project/...` link), or include `projectId` in the tool input. Use `listProjects` to discover projects. With `--project` set, per-call `projectId` becomes optional.
 
 ## Downloading source files (drawings, documents, specs, submittals, RFIs)
 
-The retrieval tools return **extracted text**, which is authoritative for schedules, notes, and spec paragraphs — but cannot answer spatial/visual questions (routing, clearances, what a plan view actually shows) and never carries the original file. Every entity has a download command, and **each accepts its `sb://` citation URL verbatim** (as returned by issues, search, and tool results — any `#page=`/`#nodeId=` fragment is ignored) or a bare UUID:
+The retrieval tools return **extracted text**, which is authoritative for schedules, notes, and spec paragraphs — but cannot answer spatial/visual questions (routing, clearances, what a plan view actually shows) and never carries the original file. Every entity has a download command, and **each accepts its returned Specset `/go` link verbatim** (citation focus parameters are ignored for downloads) or a bare UUID:
 
-| Entity         | Command                                           | Also accepts                                     | Formats / options                                                                                                                       |
-| -------------- | ------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| Drawing sheets | `specset drawings download 'sb://drawing/<uuid>'` | sheet number + `--project`                       | `--format image` (rendered PNG, default), `pdf` (single sheet), `file` (whole set)                                                      |
-| Documents      | `specset docs download 'sb://doc/<uuid>'`         |                                                  | also covers RFI attachments and closeout documents                                                                                      |
-| Spec sections  | `specset specs download 'sb://spec/<uuid>'`       | section number (e.g. `'23 31 19'`) + `--project` | per-section PDF slice (default), `--asset book` (whole source spec file)                                                                |
-| Submittals     | `specset submittals download 'sb://sub/<uuid>'`   |                                                  | compiled package (default when present); `--list` shows the asset inventory; `--asset attachment --index 2`, `--asset attachment --all` |
-| RFIs           | `specset rfis download 'sb://rfi/<uuid>'`         |                                                  | question + response attachments; `--list`, `--all`                                                                                      |
-| File resources | `specset files download 'sb://file/<uuid>'`       |                                                  | escape hatch when you already hold an `sb://file` id                                                                                    |
+| Entity         | Command                                                                 | Also accepts                                     | Formats / options                                                                                                                       |
+| -------------- | ----------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Drawing sheets | `specset drawings download 'https://app.specbook.ai/go/drawing/<uuid>'` | sheet number + `--project`                       | `--format image` (rendered PNG, default), `pdf` (single sheet), `file` (whole set)                                                      |
+| Documents      | `specset docs download 'https://app.specbook.ai/go/doc/<uuid>'`         |                                                  | also covers RFI attachments and closeout documents                                                                                      |
+| Spec sections  | `specset specs download 'https://app.specbook.ai/go/spec/<uuid>'`       | section number (e.g. `'23 31 19'`) + `--project` | per-section PDF slice (default), `--asset book` (whole source spec file)                                                                |
+| Submittals     | `specset submittals download 'https://app.specbook.ai/go/sub/<uuid>'`   |                                                  | compiled package (default when present); `--list` shows the asset inventory; `--asset attachment --index 2`, `--asset attachment --all` |
+| RFIs           | `specset rfis download 'https://app.specbook.ai/go/rfi/<uuid>'`         |                                                  | question + response attachments; `--list`, `--all`                                                                                      |
+| File resources | `specset files download 'https://app.specbook.ai/go/file/<uuid>'`       |                                                  | escape hatch for a returned file source link                                                                                            |
 
 All commands support `--json` (structured `{files: [{path, bytes, ...}]}` output) and `--out` (file path, or directory for multi-file downloads). A citation passed to the wrong command errors with the right one to use.