@specset/cli 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specset/cli",
-  "version": "0.3.0",
+  "version": "0.4.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/skills/specset/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: specset
-description: Core CLI for Specset — install, authenticate, switch organizations, and run GraphQL with `specset api`. Start here for any Specset task, and whenever a specset command fails with auth or org errors.
+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 any Specset task, and whenever a specset command fails with auth or org errors.
 allowed-tools: Bash Read AskUserQuestion
 ---
 
@@ -17,6 +17,7 @@ This is the core skill — setup and mechanics only. Domain workflows live in si
 | 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 |
@@ -28,25 +29,27 @@ This is the core skill — setup and mechanics only. Domain workflows live in si
 
 ## First-Run Setup
 
-Perform this setup yourself when the user asks to get started with Specset (or when a command fails because the CLI is missing or unauthenticated). Every step is idempotent — skip any that's already satisfied.
+Perform this setup yourself 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. Ensure the CLI is installed:
+1. Ensure the CLI is installed and current. Installing or updating an agent skill/plugin does not upgrade an existing global npm package. Check the installed and published versions:
 
 ```bash
-which specset || npm install -g @specset/cli
+specset --version 2>/dev/null || true
+npm view @specset/cli version
 ```
 
-Requires Node.js 20+ with npm. If `npm` itself is missing, stop and ask the user to install Node.js (https://nodejs.org) first.
-
-2. Check authentication with `specset auth status`. If not logged in, start the login flow — it opens the user's browser; tell them to complete sign-in there while the command waits:
+If `specset` is missing or its version is older than the published version, update it and verify the result:
 
 ```bash
-specset login
+npm install -g @specset/cli@latest
+specset --version
 ```
 
-Login is interactive by design — never try to bypass it or handle credentials directly. Don't launch a login mid-task without telling the user what's happening.
+Requires Node.js 20+ with npm. If `npm` itself is missing, stop and ask the user to install Node.js (https://nodejs.org) first. Do not replace a source-linked development CLI when its version is newer than npm.
 
-**On a headless machine** (container, SSH, CI — anywhere the browser isn't on this machine), use the device flow instead:
+2. Check authentication with `specset auth status`. If not logged in, choose the login mode based on whether the user can see a browser opened by this environment.
+
+**If a visible browser is unavailable** — including remote or in-app agent sessions, SSH, containers, and CI — use device authentication from the outset:
 
 ```bash
 specset login --device
@@ -54,6 +57,14 @@ specset login --device
 
 It prints a short code and a link (`https://<host>/device?code=XXXX-XXXX`). Show both to the user and ask them to open the link on any device and approve; the command completes on its own once they do. The code expires after 15 minutes — if it does, run the command again for a fresh one.
 
+When a visible browser is available on the same machine, use the browser flow and tell the user to complete sign-in there while the command waits:
+
+```bash
+specset login
+```
+
+Login is interactive by design — never try to bypass it or handle credentials directly. Don't launch a login mid-task without telling the user what's happening.
+
 3. Pick the active organization (required for org-scoped queries):
 
 ```bash
@@ -113,6 +124,20 @@ specset api --query '{ __type(name: "CreateSubmittalInput") { inputFields { name
 
 The domain skills document the operations that matter for each workflow, but they are not exhaustive — when an operation or argument doesn't match, introspect rather than guess.
 
+## Agent Tools and MCP
+
+Beyond raw GraphQL, the CLI exposes Specset's own retrieval tools — semantic and keyword search over specs, drawings, submittals, RFIs, documents (plus closeout and schedule where enabled) — for an AI agent to call directly. Reach for these when you want the actual content to reason over, not just record previews.
+
+- **As commands:** `specset tools list` to see what's available, then `specset tools run <name> --input '{...}'` (or `-F key=value`).
+- **As a native MCP server:** `specset mcp` runs a stdio MCP server that surfaces these tools to an MCP client, reusing your CLI login, org, and host. Register it once:
+
+```bash
+claude mcp add specset -- specset mcp      # Claude Code
+codex mcp add specset -- specset mcp       # Codex
+```
+
+See the `specset-tools` skill for the full workflow — project scoping, the `-F` JSON-parsing difference, and the `sb://` citation convention.
+
 ## Uploading Files
 
 Several workflows attach an uploaded file — submittal PDFs, RFI attachments, project documents, org logos. Files are uploaded directly to storage via a presigned URL, so attaching one is a three-step flow that needs `bash`, `curl`, and `jq`. The result is a **file id** you pass to whatever mutation consumes it.
@@ -176,4 +201,5 @@ Processing large PDF sets takes minutes; poll every 15–30 seconds and tell the
 - `No active organization selected` — run `specset org list`, then `specset org use <slug>`.
 - A lookup by id returns `null` without an error — the record usually belongs to a different org than the active one; check `specset auth status` and switch with `specset org use <slug>`.
 - Login hangs or the browser can't reach this machine (SSH, container, CI) — use `specset login --device`: it prints a code + link the user approves from any device.
+- `specset --version` is older than `npm view @specset/cli version`, or a documented flag is missing — run `npm install -g @specset/cli@latest`, then verify with `specset --version`.
 - After upgrading the CLI (`npm i -g @specset/cli@latest`), refresh the skills with `specset skill install --target <claude|codex|chatgpt>`.

package/skills/specset-search/SKILL.md

@@ -18,6 +18,8 @@ Remember Variable Limitations from the `specset` skill: `-F` sends **strings onl
 - **`quickSearch`** — fast flat matching against titles and identifiers; use when the user roughly knows the record's name or number.
 - **Precise lookups** — when the user already has a spec section number or drawing sheet number, skip search and fetch directly.
 
+> Need the actual content, not just previews and IDs? The `specset-tools` skill exposes Specset's own retrieval tools (`specset tools run searchSpecSections`, `searchDrawingSheets`, `searchDocuments`, …), which return expanded, citation-anchored markdown. Use `search`/`quickSearch` here to locate records cheaply; reach for `specset-tools` when you need to read and reason over the content.
+
 ## Unified Search: `search`
 
 ```graphql

package/skills/specset-tools/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: specset-tools
+description: Use when an agent should call Specset's own retrieval tools directly — semantic/keyword search and structured reads over specs, drawings, submittals, RFIs, documents, closeout, and schedule — via `specset tools` or a `specset mcp` server. Deeper than raw GraphQL search; lighter than delegating to the in-app agent.
+allowed-tools: Bash Read AskUserQuestion
+---
+
+# Specset Agent Tools (`specset tools`, `specset mcp`)
+
+Requires the `specset` CLI, logged in with an active org. If a command fails with `command not found`, `Not logged in`, or `No active organization`, follow First-Run Setup in the `specset` skill.
+
+These are the same read-only retrieval tools Specset's own in-app agent uses — exposed so external agents can call them directly. Everything here is read-only; nothing needs user confirmation.
+
+## When to use which surface
+
+There are three tiers of Specset retrieval. Pick the lightest one that answers the question:
+
+1. **Typed GraphQL search** (`specset-search` skill: `search`, `quickSearch`, `specSectionByNumber`, …) — cheapest, returns previews and IDs. Best for "does X exist / find the record."
+2. **Agent tools** (this skill) — the middle tier. `searchSpecSections` / `searchDrawingSheets` / `searchDocuments` return expanded, citation-anchored markdown (the real retrieval), and the `get*Content` tools read full sections. Best when you need the actual content to reason over.
+3. **In-app agent** (`specset-agent` skill: `specset agent chat`) — heaviest. Delegates the whole question to Specset's agent, which reasons and synthesizes. Best when the answer needs cross-document judgment, not just retrieval.
+
+## Listing tools
+
+```bash
+specset tools list
+specset tools list --project <projectId|sb://project/...>
+specset tools list --json     # full input schemas
+```
+
+The listing includes usage guidance and marks project-scoped tools. The exact set depends on the org (closeout and schedule tools require their SKUs) and on whether a project is in scope.
+
+## Running a tool
+
+Provide input as a JSON object (`--input`) or as repeated `-F key=value` fields. **Unlike `specset api -F` (strings only), `specset tools run -F` JSON-parses each value**, so numbers, booleans, and lists work:
+
+```bash
+# JSON input
+specset tools run searchSpecSections \
+  --project <projectId> \
+  --input '{"query": "concrete curing requirements"}'
+
+# Field form (values are JSON-parsed, string fallback)
+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/....'
+```
+
+Output is the tool's JSON payload (`{ success, message?, result? }`); a `{ success: false }` payload exits non-zero.
+
+### Identifiers are citation IDs, not 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 **not** web URLs — don't present them to a person as clickable links.
+
+### 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.
+
+## MCP server (Claude Code, Codex, other MCP clients)
+
+`specset mcp` runs a stdio MCP server that exposes these tools natively, reusing your CLI login, org, and host config. Register it once and the client can call the tools directly:
+
+```bash
+# Claude Code
+claude mcp add specset -- specset mcp
+# Optionally pin a project and/or host:
+claude mcp add specset -- specset mcp --project <projectId> --host https://app.specbook.ai
+
+# Codex
+codex mcp add specset -- specset mcp
+```
+
+Notes:
+- The server writes only the MCP protocol to stdout; diagnostics go to stderr.
+- Scope (org, optional project, host) is fixed for the life of the server — restart it to change scope.
+- If the session expires mid-run, tool calls return an actionable error; run `specset login` and restart the server.
+
+## Stability
+
+This surface is experimental — tool names and input schemas may change. For automation you need to keep stable, prefer the typed `search` / `quickSearch` GraphQL queries in the `specset-search` skill.