@derive-to/mcp 0.1.0 → 0.4.0

package/SKILL.md

@@ -22,10 +22,10 @@ Your identity (agent name, workspace, role) is in the server instructions — th
 | Tool | Use |
 |---|---|
 | `list_artifacts` | Find: the artifacts in your workspace (short id, title, kind, version, visibility). Optional `query` filters by title. |
-| `read` | Read an artifact's content by short id. For a bundle, omit `section` for the outline or pass a `section` (page path) for one page; pass `version` to read history. |
-| `catch_up` | Start here on an artifact: its state in one call — what changed since `since_version`, the open/outdated comment threads, and version history. Pass `comments` (open/addressed/resolved/outdated) for that filtered feedback queue, or `response_format='detailed'` (with optional `since_version`/`to_version`) to fold in the exact line diff. |
-| `comment` | Leave feedback, reply (`reply_to` a thread id), anchor to a `quote`, and/or resolve/reopen (`set_state`). |
-| `publish` | Save a revision. `content` for a single file, `files` (path→content map) for a multi-page bundle. Omit `short_id` to create new (title required); pass it to add a version. `addresses` lists thread ids this revision resolves. |
+| `read` | Read an artifact's content by short id, as **Markdown by default** (HTML is converted — headings, lists, tables, code fences; the styling noise is dropped). Omit `section` and a small doc/bundle returns whole; a **large one returns its outline first** (heading slugs for a single-file doc, page paths for a bundle) — call again with a `section` (a slug, a bundle page, `page.html#slug`, or `"*"` for the full clipped document). Pass `format:'html'` for the exact stored source (needed before publish `edits`) or `format:'text'` for flat visible text (what comment `quote`s anchor against). Pass `version` to read history. An image page in a bundle comes back as a real image, not garbage text. |
+| `catch_up` | Start here on an artifact: its state in one call — what changed since `since_version`, the open/outdated comment threads, the `review` round state, and version history. Pass `comments` (open/addressed/resolved/outdated) for that filtered feedback queue, or `response_format='detailed'` (with optional `since_version`/`to_version`) to fold in a line diff — of the **readable Markdown form**, not raw HTML, so it shows what changed instead of tag noise. Waiting on a review? Pass `wait` (seconds, max 50) to long-poll: the call blocks until the human sends back / approves / comments — chain these instead of sleeping. |
+| `comment` | Leave feedback, reply (`reply_to` a thread id), anchor to a `quote`, react (`react: "👍"` with `reply_to` — the loop's lightweight ack, landing on the thread's latest human comment), and/or resolve/reopen (`set_state`). |
+| `publish` | Save a revision. `content` for a single file, `files` (path→content map) for a multi-page bundle, or **`edits`** (`[{old_str, new_str}]`) to revise part of a single-file artifact without resending it. Omit `short_id` to create new (title required); pass it to add a version. `addresses` lists thread ids this revision resolves; `request_review:true` opens a review round for your human. New artifacts land **private** by default (the human you act for owns the draft) — they promote via the share dialog, so don't pass a wider `visibility` unasked. The result's `opened_in_tab` says whether an open Derive tab caught the push; when false, open the `url` for the user if they should see it now. |
 
 ## Role decides: live publish vs proposal
 
@@ -46,6 +46,61 @@ human approves rather than live content.
 3. **Revise**, then **`comment`** (reply/resolve) and/or **`publish`** (pass `addresses`
    to resolve the threads this revision fixes) — same URL, a new version. Comment
    highlights re-anchor to the moved text.
+4. **Review rounds** (the /derive loop): publish with `request_review:true`, then
+   chain `catch_up(short_id, wait: 50)` — each call returns the moment the human
+   hits Send back / Approve (or ~50s pass). On `sent_back`, sweep ALL threads (any
+   author, anchored or not), ack every human comment FIRST
+   (`comment(reply_to, react:"👍")` at minimum), then revise and publish with
+   `addresses` + `request_review:true` for the next round. The human never
+   resolves threads — you settle thread state.
+
+## Reading big documents
+
+`read` never hands you a wall of JSON-escaped HTML. A content-bearing response is
+a small frontmatter header (short id, title, version, format, section, size, url)
+followed by a blank line and the raw body — real newlines, greppable if a client
+spills it to a file. When a document is large, `read` (no `section`) returns its
+heading outline instead of the full text:
+
+```
+{ "sections": [
+    { "slug": "why-one-engine", "level": 2, "text": "Why: one engine", "chars": 2210 },
+    { "slug": "pr-6-the-fix",   "level": 2, "text": "PR-6: the fix",   "chars": 4812 }
+  ], "next": "Call read again with a section slug…" }
+```
+
+Pull just the part you need: `read(short_id, { section: "pr-6-the-fix" })`. Pass
+`section: "*"` to force the full (clipped) document when you genuinely need it all.
+
+## Edit, don't resend
+
+Once you've read a section, revise it with `publish`'s `edits` instead of
+resending the whole artifact:
+
+```
+publish(short_id, { edits: [{ old_str: "exact text from the source", new_str: "replacement" }] })
+```
+
+Each `old_str` must match **exactly once** in the current stored source — the
+same contract as a coding Edit tool. If it doesn't match (or matches more than
+once), nothing is applied and the error names which edit failed, so you add more
+surrounding context and retry. For an HTML artifact, read with `format:'html'`
+first — the Markdown view won't match raw source. Pass `base_version` (the
+version you read) to fail fast instead of silently editing a version you never saw.
+
+## Mockups & screens
+
+Reading Markdown by default doesn't flatten design work:
+
+- **See it rendered**: every `read` response's frontmatter carries the artifact's
+  `url` — open it in a real browser (or a browser-automation tool) to view or
+  screenshot the live page.
+- **See its structure/copy**: the default Markdown read.
+- **See a screenshot inline**: reading an image page of a bundle (`section:
+  "shot.png"`) returns a real image content block, not decoded bytes as text.
+- **Edit it**: `read(section, format:'html')` for the exact markup, then
+  `publish({ edits })` for a surgical change — a label, a color token — without
+  resending the whole design.
 
 ## Keep comments anchorable
 
@@ -59,7 +114,18 @@ wrong place.
 
 - Versions are immutable; `@vN` URLs never change. The viewer groups rapid
   same-author revisions into time-based sessions, but every revision is addressable.
-- Multi-page bundles are readable (`read` with a `section`, `catch_up`) and revisable
+- Multi-page bundles are readable on both servers (`read` with a `section` — a page
+  path, or `page.html#slug` for one heading's part; `catch_up`) but revisable only
   over the remote `/mcp` server via `publish` with a `files` map. Over the stdio
-  `@derive-to/mcp` server, bundles are publish-via-remote/web only, and `comment` set_state
-  takes a `comment_id`. Both servers expose the same 5 tools.
+  `@derive-to/mcp` server, bundles are publish-via-remote/web only, and `comment`
+  set_state takes a `comment_id`. `edits` (single-file only) works on both. Both
+  servers expose the same 5 tools.
+- An older self-hosted Derive server that predates `format`/`section`/`outline`
+  responds to `read` with a note that it returned the full raw artifact instead —
+  the stdio client detects this from a missing response header and degrades rather
+  than silently misreading a section.
+- The stdio server shares the machine's `derive login` — no token to paste. It acts as
+  your stored default account/workspace unless `DERIVE_ACCOUNT`/`DERIVE_WORKSPACE`
+  pin the project to a specific one (id or name; set in `.mcp.json`'s `env`). Still no
+  `whoami` tool, but a wrong pin fails loudly at startup rather than silently
+  targeting the wrong workspace.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@derive-to/mcp",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Stdio MCP server for Derive — list, read, catch up on, comment on, and publish artifacts on a Derive instance.",
   "keywords": [
@@ -37,24 +37,25 @@
     ".": "./src/index.ts",
     "./client": "./src/client.ts"
   },
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
   "dependencies": {
+    "@derive-to/cli": "workspace:*",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "tsx": "^4.19.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@derive/api": "workspace:*",
+    "@derive/db": "workspace:*",
+    "@derive/storage": "workspace:*",
     "@hono/node-server": "^2.0.5",
     "@types/node": "^25.9.3",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.9",
-    "@derive/api": "0.1.0",
-    "@derive/db": "0.1.0",
-    "@derive/storage": "0.1.0"
-  },
-  "scripts": {
-    "start": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
+    "vitest": "^4.1.9"
   }
-}
+}

package/src/client.ts

@@ -1,19 +1,37 @@
 /** HTTP client for a Derive server. Shared by the MCP server and any tooling. */
 
+/** One exact-match search/replace edit (the Edit-tool contract). */
+export interface DocEdit {
+  old_str: string
+  new_str: string
+}
+
 export interface PublishArgs {
-  content: string | Uint8Array
-  filename: string
+  /** Full content for a fresh publish/republish. Omit when using `edits` instead. */
+  content?: string | Uint8Array
+  filename?: string
   title?: string
   slug?: string
   spa?: boolean
   message?: string
-  visibility?: "public" | "link" | "org" | "password" | "private"
-  /** Unlock password, required when visibility is "password". */
+  /** The v2 access triple for a NEW artifact (see access-model.md); ignored on a
+   *  republish. */
+  workspaceAccess?: "none" | "member"
+  linkRole?: "none" | "viewer" | "commenter" | "editor"
+  listed?: "none" | "workspace" | "public"
+  /** A lock on the world link (optional). */
   password?: string
   /** When set, publishes a new version of this artifact instead of a new one. */
   id?: string
   /** Comment ids whose threads to resolve as part of this (re)publish. */
   resolves?: string[]
+  /** Open a review round for this version (the /derive loop's ask). */
+  requestReview?: boolean
+  /** Exact-match search/replace against the current stored source, INSTEAD of
+   *  `content` — revises without resending the whole artifact. Requires `id`. */
+  edits?: DocEdit[]
+  /** Safety check for `edits`: reject if the artifact moved past this version. */
+  baseVersion?: number
 }
 
 export type CommentState = "open" | "addressed" | "resolved" | "outdated"
@@ -28,6 +46,8 @@ export interface CommentJson {
   author: string
   state: CommentState
   created_at: string
+  /** emoji → actor display names (the ack surface). */
+  reactions?: Record<string, string[]>
 }
 
 export interface ArtifactSummaryJson {
@@ -35,16 +55,23 @@ export interface ArtifactSummaryJson {
   title: string | null
   kind: "file" | "bundle"
   current_version: number
-  visibility: string
+  workspace_access?: string
+  link_role?: string
+  listed?: string
 }
 
 /** A revision submitted for human review instead of published live. */
 export interface ProposeArgs {
-  content: string
+  /** Full content for the proposal. Omit when using `edits` instead. */
+  content?: string
   filename?: string
   message: string
   /** Thread ids this revision addresses (flip to `addressed`, resolve on approval). */
   addresses?: string[]
+  /** Exact-match search/replace against the current stored source, INSTEAD of
+   *  `content`. */
+  edits?: DocEdit[]
+  baseVersion?: number
 }
 export interface ProposalJson {
   id: string
@@ -81,11 +108,28 @@ export interface ArtifactJson {
   url: string
   title: string | null
   kind: "file" | "bundle"
-  visibility: string
+  /** The v2 access triple (see access-model.md); optional so an older server that
+   *  still returns `visibility` doesn't fail the type. */
+  workspace_access?: string
+  link_role?: string
+  listed?: string
   current_version: number
   versions: VersionJson[]
   /** Time-grouped version view (newest-first); present on the detail endpoint. */
   sessions?: SessionJson[]
+  /** Publish-response extras (agent-credentialed publishes only). */
+  review_requested?: boolean
+  opened_in_tab?: boolean
+}
+
+/** One review round: the human-ack primitive of the /derive loop. */
+export interface ReviewRoundJson {
+  id: string
+  state: "pending" | "sent_back" | "approved"
+  version: number
+  note: string | null
+  created_at: string
+  resolved_at: string | null
 }
 
 export interface DiffOpJson {
@@ -106,6 +150,32 @@ export interface ViewStatsJson {
   recent: { viewer: string; kind: "user" | "anon"; at: string }[]
 }
 
+export interface ContentOpts {
+  version?: number
+  /** A heading slug (single-file) or page path (bundle, optionally page#slug). */
+  section?: string
+  format?: "markdown" | "text"
+}
+
+/** A content read: the body plus the server's X-Derive-* capability headers, so a
+ *  caller can tell an older self-hosted server (no headers at all) from a real
+ *  raw-format response and degrade gracefully instead of misreading intent. */
+export interface ContentResult {
+  text: string
+  /** Null when the server predates these params (no X-Derive-Format header). */
+  format: string | null
+  section: string | null
+  sectionCount: number | null
+  supportsParams: boolean
+}
+
+export interface OutlineSectionJson {
+  level: number
+  text: string
+  slug: string
+  chars: number
+}
+
 export interface DeriveClient {
   /** List the workspace's artifacts (optionally filtered by a title query). */
   list(query?: string): Promise<ArtifactSummaryJson[]>
@@ -113,13 +183,26 @@ export interface DeriveClient {
   /** Submit a single-file revision for human review (does not go live). */
   propose(shortId: string, args: ProposeArgs): Promise<ProposalJson>
   get(shortId: string): Promise<ArtifactJson>
-  getContent(shortId: string, version?: number): Promise<string>
+  getContent(shortId: string, opts?: ContentOpts): Promise<ContentResult>
+  /** The heading (single-file) or page (bundle) outline. Empty `sections` on an
+   *  older server that doesn't understand `?outline=1` (it 400s or ignores it). */
+  getOutline(
+    shortId: string,
+    version?: number,
+  ): Promise<{ sections: OutlineSectionJson[]; pages: { path: string; type?: string }[] | null }>
   listComments(shortId: string, state?: CommentState): Promise<CommentJson[]>
   createComment(shortId: string, args: NewCommentArgs): Promise<CommentJson>
   /** Resolve or reopen the thread a comment belongs to. */
   setThreadState(shortId: string, commentId: string, state: "resolved" | "open"): Promise<void>
-  /** Line diff between two versions (defaults: current-1 → current). */
-  diff(shortId: string, from?: number, to?: number): Promise<DiffJson>
+  /** Line diff between two versions (defaults: current-1 → current). `content:
+   *  "markdown"` diffs the readable Markdown form instead of raw source. */
+  diff(shortId: string, from?: number, to?: number, content?: "raw" | "markdown"): Promise<DiffJson>
+  /** The artifact's review rounds (newest first) + the pending one, if any. */
+  getReview(
+    shortId: string,
+  ): Promise<{ rounds: ReviewRoundJson[]; pending: ReviewRoundJson | null }>
+  /** Toggle an emoji reaction on a comment (the loop's lightweight ack). */
+  react(shortId: string, commentId: string, emoji: string): Promise<void>
   /** Restore a past version as a new current revision. */
   restore(shortId: string, version: number): Promise<ArtifactJson>
   /** Aggregated view analytics. */
@@ -129,6 +212,11 @@ export interface DeriveClient {
 export interface ClientOptions {
   baseUrl: string
   token?: string
+  /** Which workspace `token` acts in for this request — the token itself already
+   *  reaches every workspace its owner belongs to; this just tells the server
+   *  which one. Omit to fall back to the grant's own default (unchanged
+   *  behavior for a plain static DERIVE_TOKEN). */
+  workspace?: string
   /** Override fetch (used in tests to target an in-process server). */
   fetchImpl?: typeof fetch
 }
@@ -136,9 +224,10 @@ export interface ClientOptions {
 export function createClient(opts: ClientOptions): DeriveClient {
   const base = opts.baseUrl.replace(/\/$/, "")
   const f = opts.fetchImpl ?? fetch
-  const authHeaders: Record<string, string> = opts.token
-    ? { Authorization: `Bearer ${opts.token}` }
-    : {}
+  const authHeaders: Record<string, string> = {
+    ...(opts.token ? { Authorization: `Bearer ${opts.token}` } : {}),
+    ...(opts.workspace ? { "X-Derive-Workspace": opts.workspace } : {}),
+  }
 
   async function ok(res: Response): Promise<unknown> {
     if (res.ok) return res.json()
@@ -156,17 +245,28 @@ export function createClient(opts: ClientOptions): DeriveClient {
     },
 
     async publish(args) {
-      const bytes =
-        typeof args.content === "string" ? new TextEncoder().encode(args.content) : args.content
       const form = new FormData()
-      form.append("file", new Blob([bytes as BlobPart]), args.filename)
+      if (args.edits) {
+        // Surgical revision: no file upload, the server materializes it from the
+        // current stored source. Requires an existing artifact (args.id).
+        form.append("edits", JSON.stringify(args.edits))
+        if (args.baseVersion != null) form.append("base_version", String(args.baseVersion))
+        if (args.filename) form.append("filename", args.filename)
+      } else {
+        const bytes =
+          typeof args.content === "string" ? new TextEncoder().encode(args.content) : args.content
+        form.append("file", new Blob([bytes as BlobPart]), args.filename ?? "index.html")
+      }
       if (args.title) form.append("title", args.title)
       if (args.slug) form.append("slug", args.slug)
       if (args.message) form.append("message", args.message)
-      if (args.visibility) form.append("visibility", args.visibility)
+      if (args.workspaceAccess) form.append("workspace_access", args.workspaceAccess)
+      if (args.linkRole) form.append("link_role", args.linkRole)
+      if (args.listed) form.append("listed", args.listed)
       if (args.password) form.append("password", args.password)
       if (args.spa) form.append("spa", "true")
       if (args.resolves?.length) form.append("resolves", args.resolves.join(","))
+      if (args.requestReview) form.append("request_review", "true")
       const url = args.id ? `${base}/v1/artifacts/${args.id}/versions` : `${base}/v1/artifacts`
       return ok(
         await f(url, { method: "POST", body: form, headers: authHeaders }),
@@ -175,11 +275,16 @@ export function createClient(opts: ClientOptions): DeriveClient {
 
     async propose(shortId, args) {
       const form = new FormData()
-      form.append(
-        "file",
-        new Blob([new TextEncoder().encode(args.content)]),
-        args.filename ?? "index.html",
-      )
+      if (args.edits) {
+        form.append("edits", JSON.stringify(args.edits))
+        if (args.baseVersion != null) form.append("base_version", String(args.baseVersion))
+      } else {
+        form.append(
+          "file",
+          new Blob([new TextEncoder().encode(args.content ?? "")]),
+          args.filename ?? "index.html",
+        )
+      }
       form.append("message", args.message)
       if (args.addresses?.length) form.append("addresses", args.addresses.join(","))
       return ok(
@@ -197,14 +302,44 @@ export function createClient(opts: ClientOptions): DeriveClient {
       ) as Promise<ArtifactJson>
     },
 
-    async getContent(shortId, version) {
-      const q = version ? `?v=${version}` : ""
-      const res = await f(`${base}/v1/artifacts/${shortId}/content${q}`, { headers: authHeaders })
+    async getContent(shortId, opts) {
+      const q = new URLSearchParams()
+      if (opts?.version) q.set("v", String(opts.version))
+      if (opts?.section) q.set("section", opts.section)
+      if (opts?.format) q.set("format", opts.format)
+      const qs = q.toString()
+      const res = await f(`${base}/v1/artifacts/${shortId}/content${qs ? `?${qs}` : ""}`, {
+        headers: authHeaders,
+      })
       if (!res.ok) {
         const body = (await res.json().catch(() => ({}))) as { error?: string }
         throw new Error(`derive ${res.status}: ${body.error ?? res.statusText}`)
       }
-      return res.text()
+      const format = res.headers.get("x-derive-format")
+      return {
+        text: await res.text(),
+        format,
+        section: res.headers.get("x-derive-section"),
+        sectionCount: res.headers.has("x-derive-sections")
+          ? Number(res.headers.get("x-derive-sections"))
+          : null,
+        // No X-Derive-Format header at all = a server that predates these params
+        // (an older self-hosted instance) — the caller should treat this as raw
+        // whole-artifact content and not assume format/section were honored.
+        supportsParams: format !== null,
+      }
+    },
+
+    async getOutline(shortId, version) {
+      const q = new URLSearchParams({ outline: "1" })
+      if (version) q.set("v", String(version))
+      const res = await f(`${base}/v1/artifacts/${shortId}/content?${q}`, { headers: authHeaders })
+      if (!res.ok) return { sections: [], pages: null }
+      const body = (await res.json()) as {
+        sections?: OutlineSectionJson[]
+        pages?: { path: string; type?: string }[]
+      }
+      return { sections: body.sections ?? [], pages: body.pages ?? null }
     },
 
     async listComments(shortId, state) {
@@ -235,15 +370,32 @@ export function createClient(opts: ClientOptions): DeriveClient {
       )
     },
 
-    async diff(shortId, from, to) {
+    async diff(shortId, from, to, content) {
       const q = new URLSearchParams({ format: "json" })
       if (from != null) q.set("from", String(from))
       if (to != null) q.set("to", String(to))
+      if (content === "markdown") q.set("content", "markdown")
       return ok(
         await f(`${base}/v1/artifacts/${shortId}/diff?${q}`, { headers: authHeaders }),
       ) as Promise<DiffJson>
     },
 
+    async getReview(shortId) {
+      return ok(
+        await f(`${base}/v1/artifacts/${shortId}/review`, { headers: authHeaders }),
+      ) as Promise<{ rounds: ReviewRoundJson[]; pending: ReviewRoundJson | null }>
+    },
+
+    async react(shortId, commentId, emoji) {
+      await ok(
+        await f(`${base}/v1/artifacts/${shortId}/comments/${commentId}/react`, {
+          method: "POST",
+          headers: { ...authHeaders, "content-type": "application/json" },
+          body: JSON.stringify({ emoji }),
+        }),
+      )
+    },
+
     async restore(shortId, version) {
       return ok(
         await f(`${base}/v1/artifacts/${shortId}/restore`, {

package/src/index.ts

@@ -1,21 +1,96 @@
 import { readFileSync } from "node:fs"
 import { fileURLToPath } from "node:url"
+import {
+  findAccountWorkspace,
+  freshToken,
+  getAccount,
+  getDefault,
+  listAccounts,
+  resolveAccountRef,
+  resolveWorkspaceRef,
+} from "@derive-to/cli/config"
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod"
 import { createClient } from "./client"
 
 // Stdio MCP server for self-hosters: `npx @derive-to/mcp` talks to a Derive instance over
-// the /v1 HTTP API (DERIVE_SERVER) with a bearer (DERIVE_TOKEN). It exposes the SAME five
-// tools as the remote /mcp server — list_artifacts, read, catch_up, comment, publish —
-// so the vocabulary is identical whether an agent connects over OAuth or a static
-// token. (A static token already has publish rights, so publish here goes live unless
-// you pass for_review; bundle publishing is remote-only.)
+// the /v1 HTTP API (DERIVE_SERVER). It exposes the SAME tools as the remote /mcp
+// server — list_workspaces, list_artifacts, read, catch_up, comment, publish — so the
+// vocabulary is identical whether an agent connects over OAuth or a static token.
+//
+// No token to paste: by default this reads the SAME local store `derive login`
+// writes (~/.config/derive/credentials.json), refreshing silently — sign in once
+// on the machine and every project's MCP server just works. DERIVE_ACCOUNT /
+// DERIVE_WORKSPACE pin which signed-in account/workspace THIS project acts as by
+// DEFAULT (id or name); unset, it falls back to your stored default. Because one
+// login reaches every workspace the account belongs to, any tool also takes a
+// per-call `workspace` argument (see list_workspaces) to act in another one without
+// changing that pin. DERIVE_TOKEN remains an escape hatch for a static bearer (CI,
+// no local login) — DERIVE_WORKSPACE has no effect there, since a static token
+// already acts as every workspace's owner.
+const server_ = process.env.DERIVE_SERVER ?? "http://localhost:8080"
 
-const client = createClient({
-  baseUrl: process.env.DERIVE_SERVER ?? "http://localhost:8080",
-  token: process.env.DERIVE_TOKEN,
-})
+/** {token, workspace} for the client below — see the module doc comment for the
+ *  precedence. Kept out of `createClient` itself so a resolution failure fails
+ *  loudly at startup (a clear thrown message) instead of quietly targeting the
+ *  wrong workspace, or surfacing as an unexplained 401 mid-session. Not signed
+ *  in at all (no env override, nothing saved) degrades gracefully to anonymous,
+ *  same as today's unset DERIVE_TOKEN — only an env var naming something that
+ *  doesn't exist is an error. */
+async function resolveAuth(): Promise<{
+  token?: string
+  workspace?: string
+  accountId?: string
+}> {
+  if (process.env.DERIVE_TOKEN) return { token: process.env.DERIVE_TOKEN }
+
+  const accountEnv = process.env.DERIVE_ACCOUNT
+  const workspaceEnv = process.env.DERIVE_WORKSPACE
+  let accountId: string | null
+  let workspace: string | undefined
+
+  if (accountEnv) {
+    accountId = resolveAccountRef(server_, accountEnv)
+    if (!accountId)
+      throw new Error(
+        `DERIVE_ACCOUNT "${accountEnv}" isn't signed in on this machine — run \`derive login\`.`,
+      )
+    if (workspaceEnv) {
+      const found = findAccountWorkspace(server_, accountId, workspaceEnv)
+      if (!found)
+        throw new Error(
+          `DERIVE_WORKSPACE "${workspaceEnv}" isn't one of that account's workspaces — run \`derive workspaces --account ${accountEnv}\`.`,
+        )
+      workspace = found.id
+    } else {
+      workspace = getAccount(server_, accountId)?.defaultWorkspace ?? undefined
+    }
+  } else if (workspaceEnv) {
+    const resolved = resolveWorkspaceRef(server_, workspaceEnv)
+    if (!resolved)
+      throw new Error(
+        `DERIVE_WORKSPACE "${workspaceEnv}" isn't a workspace on any signed-in account.`,
+      )
+    if ("ambiguous" in resolved)
+      throw new Error(
+        `DERIVE_WORKSPACE "${workspaceEnv}" matches workspaces under more than one account — set DERIVE_ACCOUNT too.`,
+      )
+    accountId = resolved.accountId
+    workspace = resolved.workspaceId
+  } else {
+    const def = getDefault(server_)
+    accountId = def?.account ?? null
+    workspace = def?.workspace ?? undefined
+  }
+
+  if (!accountId) return {}
+  const token = (await freshToken(server_, accountId)) ?? undefined
+  return { token, workspace, accountId }
+}
+
+const { token, workspace, accountId } = await resolveAuth()
+const client = createClient({ baseUrl: server_, token, workspace })
 
 // The agent guide, served as an MCP resource (single source: SKILL.md).
 const GUIDE = (() => {
@@ -30,17 +105,94 @@ const server = new McpServer({ name: "derive", version: "1.0.0" })
 
 const text = (s: string) => ({ content: [{ type: "text" as const, text: s }] })
 const json = (v: unknown) => text(JSON.stringify(v, null, 2))
+const err = (s: string) => ({
+  content: [{ type: "text" as const, text: s }],
+  isError: true as const,
+})
+
+// A content-bearing response: a frontmatter-style header, a blank line, then the
+// RAW body — never JSON-escaped (parity with the remote server's envelope).
+const doc = (meta: Record<string, string | number | null | undefined>, body: string) => {
+  const head = Object.entries(meta)
+    .filter(([, v]) => v !== undefined && v !== null)
+    .map(([k, v]) => `${k}: ${v}`)
+    .join("\n")
+  return text(`---\n${head}\n---\n\n${body}`)
+}
+
+// A `workspace` arg (id or name) on any tool acts in THAT workspace for the one
+// call, without re-pinning the session: the token already reaches every workspace
+// the account belongs to, so we just build a throwaway client that sends the
+// matching X-Derive-Workspace header. Names resolve against the active account's
+// local roster; an unrecognized ref is passed through as a literal id (a static
+// DERIVE_TOKEN caller has no roster to match names against). Omit → the session's
+// resolved default client.
+const resolveWsId = (ref: string): string => {
+  if (accountId) {
+    const found = findAccountWorkspace(server_, accountId, ref)
+    if (found) return found.id
+  }
+  return ref
+}
+const clientFor = (ref?: string) =>
+  ref ? createClient({ baseUrl: server_, token, workspace: resolveWsId(ref) }) : client
+const wsArg = z
+  .string()
+  .optional()
+  .describe(
+    "Workspace to act in — its id or name from list_workspaces. Omit to use this session's default workspace.",
+  )
+
+// The signed-in roster on THIS machine (shared by the list_workspaces tool and the
+// derive://workspaces resource) — read fresh so a sibling `derive login`/`describe`
+// shows up mid-session.
+const buildRoster = () => {
+  const accounts = listAccounts(server_).map((a) => {
+    const account = getAccount(server_, a.id)
+    return {
+      account_id: a.id,
+      handle: a.handle,
+      is_default_account: a.isDefault,
+      workspaces: Object.entries(account?.workspaces ?? {}).map(([id, w]) => ({
+        workspace_id: id,
+        name: w.name,
+        role: w.role,
+        description: w.description ?? null,
+        is_default_workspace: id === account?.defaultWorkspace,
+        is_active: id === workspace,
+      })),
+    }
+  })
+  const active = accountId
+    ? { server: server_, account_id: accountId, workspace_id: workspace ?? null }
+    : { server: server_, note: "No signed-in account resolved for this session." }
+  return { active, accounts }
+}
+
+// WORKSPACES — the switcher: every workspace signed in on this machine ---------
+server.registerTool(
+  "list_workspaces",
+  {
+    description:
+      "List every workspace signed in on this machine you can act in — id, name, your role, local description, and which is active. One login reaches them all; pass a workspace's id or name as the `workspace` argument to list_artifacts / read / catch_up / comment / publish to act there for that call.",
+    inputSchema: {},
+  },
+  async () => json(buildRoster()),
+)
 
 // FIND ------------------------------------------------------------------------
 server.registerTool(
   "list_artifacts",
   {
     description:
-      "List the artifacts in your workspace — short id, title, kind, current version, visibility. Start here to find what to work on, then catch_up or read it.",
-    inputSchema: { query: z.string().optional().describe("Optional title search filter.") },
+      "List the artifacts in your workspace — short id, title, kind, current version, access. Defaults to this session's workspace; pass `workspace` (id or name from list_workspaces) to list another. Start here to find what to work on, then catch_up or read it.",
+    inputSchema: {
+      query: z.string().optional().describe("Optional title search filter."),
+      workspace: wsArg,
+    },
   },
-  async ({ query }) => {
-    const arts = await client.list(query)
+  async ({ query, workspace: ws }) => {
+    const arts = await clientFor(ws).list(query)
     return json({ count: arts.length, artifacts: arts })
   },
 )
@@ -50,17 +202,74 @@ server.registerTool(
   "read",
   {
     description:
-      "Read an artifact's CONTENT by short id (a past `version` defaults to current). For what CHANGED or the comment threads, use catch_up instead.",
+      "Read an artifact's CONTENT by short id, as Markdown by default (HTML is converted). Omit `section` to see the outline first (heading slugs for a single-file doc, page paths for a bundle) — call again with a `section` (or \"*\" for the full document) once you know what you want. Pass `format:'html'` for the exact source (needed before publish `edits`), or a past `version` for history. For what CHANGED or the comment threads, use catch_up instead. (Older self-hosted servers that predate these params return the whole artifact regardless of section/format — noted in the response when that happens.)",
     inputSchema: {
       short_id: z.string(),
+      section: z
+        .string()
+        .optional()
+        .describe(
+          'A heading slug (single-file) or page path (bundle, optionally page#slug). Pass "*" for the full document.',
+        ),
+      format: z
+        .enum(["markdown", "text"])
+        .optional()
+        .describe("markdown (default, HTML converted) or text (flat visible text)."),
       version: z.number().int().optional().describe("Defaults to the current version."),
+      workspace: wsArg,
     },
   },
-  async ({ short_id, version }) => {
+  async ({ short_id, section, format, version, workspace: ws }) => {
+    const client = clientFor(ws)
     const a = await client.get(short_id)
-    const body = await client.getContent(short_id, version)
     const v = version ?? a.current_version
-    return json({ short_id, title: a.title, kind: a.kind, version: v, content: body })
+
+    // No section: show the outline first (mirrors the remote server's
+    // outline-before-blind-dump behavior). Falls back to full content when the
+    // artifact has no headings/pages, or the server predates `?outline=1`.
+    if (!section) {
+      const outline = await client.getOutline(short_id, version)
+      if (outline.sections.length || outline.pages) {
+        return json({
+          short_id,
+          title: a.title,
+          kind: a.kind,
+          version: v,
+          ...(outline.sections.length ? { sections: outline.sections } : {}),
+          ...(outline.pages ? { pages: outline.pages } : {}),
+          next:
+            outline.sections.length || outline.pages?.length
+              ? 'Call read again with a `section` (a slug/page above), or section:"*" for the full document.'
+              : undefined,
+        })
+      }
+    }
+
+    try {
+      const result = await client.getContent(short_id, {
+        version,
+        section,
+        format: format ?? "markdown",
+      })
+      if (!result.supportsParams)
+        return doc(
+          { short_id, title: a.title, kind: a.kind, version: v },
+          `${result.text}\n\n[note: this server predates section/format params — returning the full raw artifact.]`,
+        )
+      return doc(
+        {
+          short_id,
+          title: a.title,
+          kind: a.kind,
+          version: v,
+          ...(result.format ? { format: result.format } : {}),
+          ...(result.section ? { section: result.section } : {}),
+        },
+        result.text,
+      )
+    } catch (e) {
+      return err(e instanceof Error ? e.message : "read failed")
+    }
   },
 )
 
@@ -69,9 +278,10 @@ server.registerTool(
   "catch_up",
   {
     description:
-      "START HERE on an artifact. Its state in one call: a summary, the versions since `since_version`, the open (and outdated) comment threads, and the full version history. " +
+      "START HERE on an artifact. Its state in one call: a summary, the review round, the versions since `since_version`, the open (and outdated) comment threads, and the full version history. " +
       "Pass `comments` (open / addressed / resolved / outdated) to instead get that filtered thread list — your feedback queue. " +
-      "Pass `response_format='detailed'` (optionally with `since_version`/`to_version`) to fold in the exact line diff between two versions.",
+      "Pass `response_format='detailed'` (optionally with `since_version`/`to_version`) to fold in a line diff between two versions — of their readable Markdown form, not raw HTML. " +
+      "WAITING ON A REVIEW? Pass `wait` (seconds, max 50) to block until the human sends back or approves — chain these instead of sleeping between polls.",
     inputSchema: {
       short_id: z.string(),
       since_version: z
@@ -94,9 +304,28 @@ server.registerTool(
         .enum(["summary", "detailed"])
         .optional()
         .describe("'summary' (default) omits the line diff; 'detailed' includes it."),
+      wait: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe(
+          "Long-poll: block up to this many seconds for the human's next review action before returning. Returns immediately when something is already actionable.",
+        ),
+      workspace: wsArg,
     },
   },
-  async ({ short_id, since_version, to_version, comments, response_format }) => {
+  async ({
+    short_id,
+    since_version,
+    to_version,
+    comments,
+    response_format,
+    wait,
+    workspace: ws,
+  }) => {
+    const client = clientFor(ws)
     const summarizeComment = (c: {
       thread_id: string
       author: string
@@ -121,20 +350,76 @@ server.registerTool(
       })
     }
 
+    // Long-poll (self-host shim flavor): the /v1 API has no blocking endpoint,
+    // so poll every 2.5s until the human acts or the wait runs out — the same
+    // contract as the remote server's wait on a coarser clock. "Acts" = the
+    // round changes OR the open-comment count moves (so waiting works with no
+    // round open, exactly like the server's comment.created wake). Transient
+    // errors retry; they never end the wait early. A settled round that still
+    // applies to the current head is already actionable and returns at once.
+    if (wait) {
+      const deadline = Date.now() + wait * 1000
+      const snap = () =>
+        Promise.all([
+          client.get(short_id),
+          client.getReview(short_id),
+          client.listComments(short_id, "open"),
+        ]).then(([art, rev, open]) => {
+          const round = rev.pending ?? rev.rounds[0] ?? null
+          return {
+            key: `${round?.id ?? "none"}:${round?.state ?? "none"}:${open.length}`,
+            actionable:
+              !!round && round.state !== "pending" && round.version >= art.current_version,
+          }
+        })
+      let baseline: string | null = null
+      for (;;) {
+        const cur = await snap().catch(() => null)
+        if (cur) {
+          if (baseline === null) {
+            baseline = cur.key
+            if (cur.actionable) break
+          } else if (cur.key !== baseline) break
+        }
+        if (Date.now() >= deadline) break
+        await new Promise((r) => setTimeout(r, 2500))
+      }
+    }
+
     const a = await client.get(short_id)
     const head = a.current_version
     const to = Math.min(head, Math.max(1, to_version ?? head))
     const since = Math.min(to, Math.max(1, since_version ?? to - 1))
     const history = a.versions.slice().sort((x, y) => y.n - x.n)
     const newVersions = history.filter((v) => v.n > since && v.n <= to)
-    const [open, outdated, addressed] = await Promise.all([
+    const [open, outdated, addressed, reviewState] = await Promise.all([
       client.listComments(short_id, "open"),
       client.listComments(short_id, "outdated"),
       client.listComments(short_id, "addressed"),
+      client.getReview(short_id).catch(() => ({ rounds: [], pending: null })),
     ])
+    const round = reviewState.pending ?? reviewState.rounds[0] ?? null
+    const review = round
+      ? {
+          state: round.state,
+          version: round.version,
+          requested_at: round.created_at,
+          resolved_at: round.resolved_at,
+          note: round.note,
+        }
+      : null
+    const reviewBit = review
+      ? review.state === "pending"
+        ? ` Review requested on v${review.version} — waiting for the human.`
+        : review.state === "sent_back"
+          ? ` The human sent back their review of v${review.version} — read the open threads, revise, and re-request.`
+          : ` The human approved v${review.version} — you're clear to proceed.`
+      : ""
     let entryDiff: string | undefined
     if (response_format === "detailed" && since < to) {
-      const d = await client.diff(short_id, since, to)
+      // Diff the readable Markdown form, not raw HTML — kills tag noise and
+      // avoids a minified one-line document producing one useless del/add pair.
+      const d = await client.diff(short_id, since, to, "markdown")
       entryDiff = d.ops
         .map((o) => `${o.t === "add" ? "+" : o.t === "del" ? "-" : " "} ${o.line}`)
         .join("\n")
@@ -143,10 +428,11 @@ server.registerTool(
     const addressedBit = addressed.length ? ` ${addressed.length} addressed (pending review).` : ""
     const summary =
       since >= to
-        ? `You're up to date on "${a.title}" (v${head}); ${open.length} open comment(s).${addressedBit}${outdatedBit}`
-        : `"${a.title}": ${newVersions.length} new version(s) since v${since} (now v${to}). ${open.length} open comment(s).${addressedBit}${outdatedBit}`
+        ? `You're up to date on "${a.title}" (v${head}); ${open.length} open comment(s).${addressedBit}${outdatedBit}${reviewBit}`
+        : `"${a.title}": ${newVersions.length} new version(s) since v${since} (now v${to}). ${open.length} open comment(s).${addressedBit}${outdatedBit}${reviewBit}`
     return json({
       summary,
+      review,
       short_id,
       since,
       to,
@@ -170,7 +456,7 @@ server.registerTool(
   "comment",
   {
     description:
-      "Leave feedback, reply in a thread, and/or resolve or reopen a thread. Anchor a NEW comment to a quoted span with `quote`. Reply by passing the thread id as `reply_to`. Resolve/reopen by passing `set_state` with a `comment_id` from the thread (or the comment you just left).",
+      "Leave feedback, reply in a thread, react, and/or resolve or reopen a thread. Anchor a NEW comment to a quoted span with `quote`. Reply by passing the thread id as `reply_to`. Pass `react` with a `comment_id` (or `reply_to` to hit the thread's latest comment) to acknowledge feedback without the noise of a reply — the loop's minimum ack. Resolve/reopen by passing `set_state` with a `comment_id` from the thread (or the comment you just left).",
     inputSchema: {
       short_id: z.string(),
       body: z
@@ -182,16 +468,24 @@ server.registerTool(
         .optional()
         .describe("A thread id to reply in; omit to start a new thread."),
       quote: z.string().optional().describe("Exact text to anchor a NEW comment to."),
+      react: z
+        .enum(["👍", "❤️", "🎉", "😄", "👀", "🙏", "🚀", "👎"])
+        .optional()
+        .describe("React to a comment (with `comment_id` or `reply_to`) — 👍 is the loop's ack."),
       set_state: z.enum(["resolved", "open"]).optional().describe("Resolve or reopen a thread."),
       comment_id: z
         .string()
         .optional()
-        .describe("A comment in the thread to set_state on (when not posting)."),
+        .describe("A comment in the thread to react to / set_state on (when not posting)."),
+      workspace: wsArg,
     },
   },
-  async ({ short_id, body, reply_to, quote, set_state, comment_id }) => {
-    if (!body && !set_state)
-      return text("Provide `body` (to comment) or `set_state` (to resolve/reopen).")
+  async ({ short_id, body, reply_to, quote, react, set_state, comment_id, workspace: ws }) => {
+    const client = clientFor(ws)
+    if (!body && !set_state && !react)
+      return text(
+        "Provide `body` (to comment), `react` (to acknowledge), or `set_state` (to resolve/reopen).",
+      )
     let posted: Awaited<ReturnType<typeof client.createComment>> | undefined
     if (body) {
       const anchor = quote ? { type: "TextQuoteSelector", exact: quote } : undefined
@@ -202,6 +496,32 @@ server.registerTool(
         author: "agent",
       })
     }
+    let reactNote = ""
+    if (react) {
+      // The ack target: an explicit comment, else the newest comment in the
+      // thread by someone ELSE — never the agent's own just-posted reply. One
+      // unfiltered fetch covers every thread state (the human may have replied
+      // on a resolved thread).
+      const all = await client.listComments(short_id)
+      let target = comment_id
+      if (!target && reply_to) {
+        const thread = all
+          .filter((cm) => cm.thread_id === reply_to)
+          .sort((x, y) => x.created_at.localeCompare(y.created_at))
+        const other = [...thread].reverse().find((cm) => cm.author !== "agent")
+        target = (other ?? thread[thread.length - 1])?.id
+      }
+      if (!target)
+        return text("`react` needs a `comment_id` or a `reply_to` thread to acknowledge.")
+      // The /react route TOGGLES; skipping an already-present emoji keeps a
+      // retried ack from silently removing it.
+      if (all.find((cm) => cm.id === target)?.reactions?.[react]?.length) {
+        reactNote = ` · already acknowledged with ${react}`
+      } else {
+        await client.react(short_id, target, react)
+        reactNote = ` · acknowledged with ${react}`
+      }
+    }
     let stateNote = ""
     if (set_state) {
       const ref = posted?.id ?? comment_id
@@ -216,9 +536,12 @@ server.registerTool(
       const where = reply_to
         ? `replied in thread ${posted.thread_id}`
         : `new thread ${posted.thread_id}`
-      return text(`${where} (comment ${posted.id})${quote ? ` on “${quote}”` : ""}${stateNote}.`)
+      return text(
+        `${where} (comment ${posted.id})${quote ? ` on “${quote}”` : ""}${reactNote}${stateNote}.`,
+      )
     }
-    return text(`Thread ${set_state === "resolved" ? "resolved" : "reopened"}.`)
+    if (!set_state) return text(`Acknowledged${reactNote.replace(" · acknowledged", "")}.`)
+    return text(`Thread ${set_state === "resolved" ? "resolved" : "reopened"}${reactNote}.`)
   },
 )
 
@@ -227,9 +550,33 @@ server.registerTool(
   "publish",
   {
     description:
-      "Publish a single-file artifact and get a permanent URL. OMIT short_id to create a NEW artifact (title recommended); PASS short_id to publish a new version (same URL). Pass for_review:true to file it as a PROPOSAL a human approves instead of going live. Pass `addresses` with the thread ids this revision resolves. (Multi-page bundles are published via the web app or the remote /mcp server.)",
+      "Publish a single-file artifact and get a permanent URL. OMIT short_id to create a NEW artifact (title recommended); PASS short_id to publish a new version (same URL). To CHANGE PART of an existing artifact, prefer `edits` (exact-match search/replace against the stored source — read format:'html' first) over resending everything via `content`. Pass for_review:true to file it as a PROPOSAL a human approves instead of going live. Pass `addresses` with the thread ids this revision resolves. (Multi-page bundles are published via the web app or the remote /mcp server.)",
     inputSchema: {
-      content: z.string().describe("The artifact's text content (HTML or Markdown)."),
+      content: z
+        .string()
+        .optional()
+        .describe("The artifact's full text content (HTML or Markdown). Use this OR `edits`."),
+      edits: z
+        .array(
+          z.object({
+            old_str: z
+              .string()
+              .describe(
+                "Exact text from the STORED SOURCE (read format:'html' first on an HTML artifact). Must occur exactly once.",
+              ),
+            new_str: z.string().describe("Replacement text. Empty string deletes."),
+          }),
+        )
+        .optional()
+        .describe(
+          "Surgical revision without resending the artifact: exact-match search/replace against the current stored source, applied in order. Errors (applying nothing) if any old_str matches zero or multiple times. Requires `short_id`; use INSTEAD of `content`.",
+        ),
+      base_version: z
+        .number()
+        .optional()
+        .describe(
+          "Safety check for `edits`: pass the version you read; errors instead of applying if the artifact moved past it.",
+        ),
       filename: z
         .string()
         .optional()
@@ -239,10 +586,12 @@ server.registerTool(
         .optional()
         .describe("Omit to create a new artifact; pass it to add a version."),
       title: z.string().optional(),
-      // `password` stays CLI/web-only (it needs a password argument this tool
-      // doesn't take). Omitted ⇒ the server default, `private` (the publish is
-      // owned by the user the agent acts on behalf of).
-      visibility: z.enum(["public", "link", "org", "private"]).optional(),
+      // The v2 access triple for a NEW artifact (see access-model.md); omit any to
+      // take the workspace default (the team draft — the human you act for owns it
+      // and promotes it when ready). Ignored on a republish.
+      workspace_access: z.enum(["none", "member"]).optional(),
+      link_role: z.enum(["none", "viewer", "commenter", "editor"]).optional(),
+      listed: z.enum(["none", "workspace", "public"]).optional(),
       message: z.string().optional().describe("What changed in this version."),
       for_review: z
         .boolean()
@@ -252,42 +601,93 @@ server.registerTool(
         .array(z.string())
         .optional()
         .describe("Thread ids this revision resolves (live publish) or addresses (proposal)."),
+      request_review: z
+        .boolean()
+        .optional()
+        .describe(
+          "Open a review round asking your human to review this version — the /derive loop. Poll catch_up's `review` (or pass `wait`) for the state.",
+        ),
+      workspace: wsArg,
     },
   },
-  async ({ content, filename, short_id, title, visibility, message, for_review, addresses }) => {
+  async ({
+    content,
+    edits,
+    base_version,
+    filename,
+    short_id,
+    title,
+    workspace_access,
+    link_role,
+    listed,
+    message,
+    for_review,
+    addresses,
+    request_review,
+    workspace: ws,
+  }) => {
+    const client = clientFor(ws)
+    if (content !== undefined && edits) return text("Provide `content` OR `edits`, not both.")
     if (for_review) {
       if (!short_id) return text("A proposal revises an EXISTING artifact — pass its short_id.")
-      const p = await client.propose(short_id, {
+      try {
+        const p = await client.propose(short_id, {
+          content,
+          edits,
+          baseVersion: base_version,
+          filename,
+          message: message ?? "Proposed revision",
+          addresses,
+        })
+        const note = p.addressed?.length ? ` · addressed ${p.addressed.length} thread(s)` : ""
+        return json({
+          proposed: true,
+          proposal_id: p.id,
+          base_version: p.base_version,
+          note: `Submitted for review (not live)${note}.`,
+        })
+      } catch (e) {
+        return err(e instanceof Error ? e.message : "propose failed")
+      }
+    }
+    if (edits && !short_id) return text("`edits` revises an EXISTING artifact — pass its short_id.")
+    let a: Awaited<ReturnType<typeof client.publish>>
+    try {
+      a = await client.publish({
+        id: short_id,
         content,
-        filename,
-        message: message ?? "Proposed revision",
-        addresses,
-      })
-      const note = p.addressed?.length ? ` · addressed ${p.addressed.length} thread(s)` : ""
-      return json({
-        proposed: true,
-        proposal_id: p.id,
-        base_version: p.base_version,
-        note: `Submitted for review (not live)${note}.`,
+        edits,
+        baseVersion: base_version,
+        filename: filename ?? (edits ? undefined : "index.html"),
+        title,
+        workspaceAccess: workspace_access,
+        linkRole: link_role,
+        listed,
+        message,
+        resolves: addresses,
+        requestReview: request_review,
       })
+    } catch (e) {
+      return err(e instanceof Error ? e.message : "publish failed")
     }
-    const a = await client.publish({
-      id: short_id,
-      content,
-      filename: filename ?? "index.html",
-      title,
-      visibility,
-      message,
-      resolves: addresses,
-    })
     const note = addresses?.length ? ` · resolved ${addresses.length} thread(s)` : ""
+    const openNote =
+      a.opened_in_tab === false
+        ? " No open Derive tab caught this push — open the url for the user if they should see it now."
+        : ""
     return json({
       published: true,
       short_id: a.short_id,
+      ...(a.review_requested ? { review_requested: true } : {}),
       version: a.current_version,
       url: a.url,
       title: a.title,
-      note: short_id ? `Live — new version${note}.` : `Live — created "${a.title}"${note}.`,
+      listed: a.listed,
+      link_role: a.link_role,
+      ...(a.opened_in_tab !== undefined ? { opened_in_tab: a.opened_in_tab } : {}),
+      note:
+        (short_id ? `Live — new version${note}.` : `Live — created "${a.title}"${note}.`) +
+        openNote,
     })
   },
 )
@@ -304,4 +704,35 @@ server.registerResource(
   async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: GUIDE }] }),
 )
 
+// Every account/workspace signed in on THIS machine, with the local `description`
+// each was given via `derive workspace describe` — the context a bare name can't
+// carry. This tool's OWN live calls only ever act as `active` below (fixed at
+// startup by DERIVE_ACCOUNT/DERIVE_WORKSPACE or the stored default); the rest of
+// the roster is visibility only, for deciding whether that pin is still the right
+// one — e.g. before proposing a change to a project's .mcp.json. Read fresh (not
+// cached at startup) since `derive workspace describe` can run in a sibling
+// terminal mid-session.
+server.registerResource(
+  "derive-workspaces",
+  "derive://workspaces",
+  {
+    title: "Signed-in accounts & workspaces",
+    description:
+      "Every account and workspace signed in on this machine, each with its local `description` " +
+      "(what it's FOR, set via `derive workspace describe`) if one has been set. `active` is the " +
+      "one this session's tools actually publish to — read this before assuming a bare workspace " +
+      "name is enough context, or before touching a project's DERIVE_ACCOUNT/DERIVE_WORKSPACE pin.",
+    mimeType: "application/json",
+  },
+  async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify(buildRoster(), null, 2),
+      },
+    ],
+  }),
+)
+
 await server.connect(new StdioServerTransport())

package/LICENSE

@@ -1,105 +0,0 @@
-# Functional Source License, Version 1.1, ALv2 Future License
-
-## Abbreviation
-
-FSL-1.1-ALv2
-
-## Notice
-
-Copyright 2026 Anir Agarwal <Agarwal.anir@gmail.com>
-
-## Terms and Conditions
-
-### Licensor ("We")
-
-The party offering the Software under these Terms and Conditions.
-
-### The Software
-
-The "Software" is each version of the software that we make available under
-these Terms and Conditions, as indicated by our inclusion of these Terms and
-Conditions with the Software.
-
-### License Grant
-
-Subject to your compliance with this License Grant and the Patents,
-Redistribution and Trademark clauses below, we hereby grant you the right to
-use, copy, modify, create derivative works, publicly perform, publicly display
-and redistribute the Software for any Permitted Purpose identified below.
-
-### Permitted Purpose
-
-A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
-means making the Software available to others in a commercial product or
-service that:
-
-1. substitutes for the Software;
-
-2. substitutes for any other product or service we offer using the Software
-   that exists as of the date we make the Software available; or
-
-3. offers the same or substantially similar functionality as the Software.
-
-Permitted Purposes specifically include using the Software:
-
-1. for your internal use and access;
-
-2. for non-commercial education;
-
-3. for non-commercial research; and
-
-4. in connection with professional services that you provide to a licensee
-   using the Software in accordance with these Terms and Conditions.
-
-### Patents
-
-To the extent your use for a Permitted Purpose would necessarily infringe our
-patents, the license grant above includes a license under our patents. If you
-make a claim against any party that the Software infringes or contributes to
-the infringement of any patent, then your patent license to the Software ends
-immediately.
-
-### Redistribution
-
-The Terms and Conditions apply to all copies, modifications and derivatives of
-the Software.
-
-If you redistribute any copies, modifications or derivatives of the Software,
-you must include a copy of or a link to these Terms and Conditions and not
-remove any copyright notices provided in or with the Software.
-
-### Disclaimer
-
-THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
-PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
-
-IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
-SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
-EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
-
-### Trademarks
-
-Except for displaying the License Details and identifying us as the origin of
-the Software, you have no right under these Terms and Conditions to use our
-trademarks, trade names, service marks or product names.
-
-## Grant of Future License
-
-We hereby irrevocably grant you an additional license to use the Software under
-the Apache License, Version 2.0 that is effective on the second anniversary of
-the date we make the Software available. On or after that date, you may use the
-Software under the Apache License, Version 2.0, in which case the following
-will apply:
-
-Licensed under the Apache License, Version 2.0 (the "License"); you may not use
-this file except in compliance with the License.
-
-You may obtain a copy of the License at
-
-http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software distributed
-under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-CONDITIONS OF ANY KIND, either express or implied. See the License for the
-specific language governing permissions and limitations under the License.