@usegraft/mcp 0.2.0 → 1.0.0-beta.1

package/dist/index.js

@@ -3,10 +3,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/server.ts
 import { unlinkSync } from "fs";
-import { join as join3 } from "path";
 import { createStorage, storageConfigFromEnv } from "@usegraft/assets";
-import { compile, compileStatic } from "@usegraft/compiler";
-import { GraftError as GraftError8 } from "@usegraft/contracts";
+import { compile, compileStatic, resolveContained as resolveContained4 } from "@usegraft/compiler";
+import { GraftError as GraftError10 } from "@usegraft/contracts";
 import {
   createFunctionsHandler,
   defineFunction,
@@ -27,7 +26,7 @@ var findDoc = (contentDir, collectionName, collection, slug) => findDocIn(conten
 // src/tools/approvals.ts
 import { GraftError as GraftError2 } from "@usegraft/contracts";
 import { decideApproval, listPendingApprovals } from "@usegraft/db";
-import { z } from "zod";
+import { z as z2 } from "zod";
 
 // src/tool-result.ts
 import { GraftError } from "@usegraft/contracts";
@@ -161,9 +160,9 @@ var ERROR_KNOWLEDGE = {
     meaning: "The Graft server (`graft serve`) has nothing mounted at the requested path \u2014 the request reached the right process but the wrong URL.",
     typicalCauses: [
       "A typo in the endpoint path (e.g. /api/fns instead of /api/fn/<name>)",
-      "Expecting the frontend app's routes on the headless runtime \u2014 graft serve hosts only the function, MCP, and health endpoints"
+      "Expecting the frontend app's routes on the headless runtime \u2014 graft serve hosts functions, MCP, authored-content reads, and health"
     ],
-    howToRecover: "Use POST /api/fn/<name> for typed functions, POST /api/mcp for the MCP Streamable HTTP surface, or GET /healthz for liveness. The error's details carry the path that missed."
+    howToRecover: "Use POST /api/fn/<name> for typed functions, POST /api/mcp for the MCP Streamable HTTP surface, GET /api/content/v1/documents or GET /api/content/v1/search for authored content, or GET /healthz for liveness. The error's details carry the path that missed."
   },
   AUTHORITY_MISMATCH: {
     code: "AUTHORITY_MISMATCH",
@@ -310,9 +309,10 @@ var ERROR_KNOWLEDGE = {
     meaning: "The operation is human-gated: a pending approval request was filed (details.approvalId) and the call will not run until a human approves it. Destructive functions are always gated; under the 'human' approval policy every mutation is.",
     typicalCauses: [
       "Calling a function marked `destructive: true` (deletes or irreversibly overwrites data)",
-      "Calling any mutation on a deployment whose approvalPolicy is 'human'"
+      "Calling any mutation on a deployment whose approvalPolicy is 'human'",
+      "Calling a destructive function over MCP at all \u2014 the 'unattended' policy that lifts this gate for a headless deployment is not part of the MCP surface, so there is no server setting that makes this tool call stop asking. That is deliberate, and not something to route around"
     ],
-    howToRecover: "Ask a human operator to run `graft approve <approvalId>` (they can also `graft deny` it). Once approved, retry the EXACT same call carrying the approval id \u2014 over MCP pass it as the `approval` tool argument; over raw HTTP send the `x-graft-approval: <approvalId>` header. Approvals are one-shot and bound to the exact input \u2014 never work around the gate."
+    howToRecover: "Ask a human operator to run `graft approve <approvalId>` (they can also `graft deny` it). Once approved, retry the EXACT same call carrying the approval id \u2014 over MCP pass it as the `approval` tool argument; over raw HTTP send the `x-graft-approval: <approvalId>` header. Approvals are one-shot and bound to the exact input \u2014 never work around the gate. If you are seeing this over MCP, the server did not ask your client directly: either the mount has not opted into elicited approvals (`approvalElicitation`, off by default and intended for a local server whose operator is present) or your client did not declare the elicitation capability. Both are ordinary \u2014 the gate is the same either way, only the way the human is reached differs."
   },
   APPROVAL_INVALID: {
     code: "APPROVAL_INVALID",
@@ -434,8 +434,14 @@ function explainCode(code) {
 }
 
 // src/tool-result.ts
-function ok(payload) {
-  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+var isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function ok(payload, links = []) {
+  const result = {
+    // Text first: a client that ignores the rest still gets the whole answer.
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }, ...links]
+  };
+  if (isPlainObject(payload)) result.structuredContent = payload;
+  return result;
 }
 function fail(error) {
   const explanation = ERROR_KNOWLEDGE[error.code];
@@ -453,14 +459,212 @@ function fail(error) {
     ]
   };
 }
-async function guarded(body) {
+async function guarded(body, linksFor) {
   try {
-    return ok(await body());
+    const payload = await body();
+    return ok(payload, linksFor?.(payload));
   } catch (error) {
     if (error instanceof GraftError) return fail(error);
     throw error;
   }
 }
+async function guardedResource(body) {
+  try {
+    return await body();
+  } catch (error) {
+    if (!(error instanceof GraftError)) throw error;
+    const explanation = ERROR_KNOWLEDGE[error.code];
+    throw new Error(
+      [error.message, error.fix && `Fix: ${error.fix}`, explanation?.howToRecover].filter(Boolean).join(" "),
+      { cause: error }
+    );
+  }
+}
+
+// src/tools/annotations.ts
+var READS = {
+  readOnlyHint: true,
+  openWorldHint: false
+};
+var WRITES = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: false
+};
+var DESTROYS = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: false
+};
+
+// src/tools/outputs.ts
+import { FunctionDescriptor, RegistryItemDescriptor, SchemaDescription } from "@usegraft/contracts";
+import { z } from "zod";
+var DocumentData = z.record(z.string(), z.unknown());
+var ChangeSet = z.object({
+  added: z.array(z.string()),
+  changed: z.array(z.string()),
+  removed: z.array(z.string()),
+  unchanged: z.number()
+});
+var listCollectionsOutput = {
+  branch: z.string(),
+  collections: z.array(
+    z.object({
+      name: z.string(),
+      description: z.string().optional(),
+      authority: z.string(),
+      fields: z.number()
+    })
+  )
+};
+var describeSchemaOutput = SchemaDescription.shape;
+var listFunctionsOutput = {
+  branch: z.string(),
+  functions: z.array(
+    z.object({
+      name: z.string(),
+      kind: z.string(),
+      description: z.string().optional(),
+      public: z.boolean().optional(),
+      destructive: z.boolean().optional(),
+      args: z.number()
+    })
+  )
+};
+var describeFunctionOutput = FunctionDescriptor.shape;
+var listRegistryOutput = {
+  items: z.array(
+    z.object({
+      name: z.string(),
+      type: z.string(),
+      description: z.string(),
+      registryDependencies: z.array(z.string()).optional()
+    })
+  )
+};
+var describeItemOutput = RegistryItemDescriptor.shape;
+var listPackagesOutput = {
+  packages: z.array(
+    z.object({
+      name: z.string(),
+      role: z.string(),
+      when: z.string(),
+      tier: z.enum(["static", "postgres", "either"]),
+      framework: z.string().optional(),
+      direct: z.boolean()
+    })
+  )
+};
+var listContentOutput = {
+  collection: z.string(),
+  documents: z.array(
+    z.object({
+      slug: z.string(),
+      sourcePath: z.string(),
+      data: DocumentData
+    })
+  )
+};
+var getContentOutput = {
+  collection: z.string(),
+  slug: z.string(),
+  sourcePath: z.string(),
+  data: DocumentData,
+  body: z.string()
+};
+var searchContentOutput = {
+  branch: z.string(),
+  /** The resolved overlay chain, leaf-first — which branches were searched. */
+  chain: z.array(z.string()),
+  query: z.string(),
+  hits: z.array(
+    z.object({
+      collection: z.string(),
+      slug: z.string(),
+      sourcePath: z.string(),
+      rank: z.number(),
+      snippet: z.string(),
+      data: DocumentData
+    })
+  )
+};
+var writeContentOutput = {
+  written: z.string(),
+  branch: z.string(),
+  /** Null when the content tree is not in a git checkout. */
+  gitSha: z.string().nullable(),
+  changes: ChangeSet
+};
+var listBranchesOutput = {
+  branches: z.array(
+    z.object({
+      name: z.string(),
+      parent: z.string().nullable(),
+      backend: z.string(),
+      status: z.string(),
+      createdAt: z.string(),
+      endpointHost: z.string().nullable()
+    })
+  )
+};
+var listCompilationsOutput = {
+  compilations: z.array(
+    z.object({
+      id: z.string(),
+      branchId: z.string(),
+      gitSha: z.string().nullable(),
+      docCount: z.number(),
+      added: z.number(),
+      changed: z.number(),
+      removed: z.number(),
+      createdAt: z.string()
+    })
+  )
+};
+var listApprovalsOutput = {
+  approvals: z.array(
+    z.object({
+      id: z.string(),
+      branchId: z.string(),
+      functionName: z.string(),
+      /** The canonical input the approval is bound to; jsonb, so open. */
+      input: z.unknown(),
+      requestedByKind: z.string(),
+      requestedById: z.string().nullable(),
+      correlationId: z.string().nullable(),
+      createdAt: z.string()
+    })
+  )
+};
+var decideApprovalOutput = {
+  id: z.string(),
+  status: z.string(),
+  decidedBy: z.string().nullable(),
+  functionName: z.string()
+};
+var putAssetOutput = {
+  key: z.string(),
+  contentType: z.string(),
+  bytes: z.number(),
+  url: z.string(),
+  /** A ready-to-paste `field.asset` frontmatter snippet. */
+  frontmatter: z.string()
+};
+var explainErrorOutput = {
+  code: z.string().optional(),
+  known: z.boolean().optional(),
+  meaning: z.string().optional(),
+  typicalCauses: z.array(z.string()).optional(),
+  howToRecover: z.string().optional(),
+  /** The `fix` off the actual error, which beats the general advice. */
+  specificFix: z.string().optional(),
+  message: z.string().optional(),
+  knownCodes: z.array(z.string()).optional(),
+  hint: z.string().optional()
+};
 
 // src/tools/approvals.ts
 var registerApprovalTools = (server, deps) => {
@@ -469,6 +673,8 @@ var registerApprovalTools = (server, deps) => {
     "list_approvals",
     {
       title: "List pending approvals",
+      outputSchema: listApprovalsOutput,
+      annotations: READS,
       description: "Pending human-gated approvals. Decide with decide_approval, Studio Approve/Deny, or `graft approve` / `graft deny`. Same data as GET /api/studio/v1/approvals.",
       inputSchema: {}
     },
@@ -494,10 +700,12 @@ var registerApprovalTools = (server, deps) => {
     "decide_approval",
     {
       title: "Approve or deny a pending approval",
+      outputSchema: decideApprovalOutput,
+      annotations: DESTROYS,
       description: "Record a decision on a pending approval (same as Studio Approve/Deny and `graft approve` / `graft deny`). The decision is attributed to the identity THIS connection authenticated as \u2014 there is no way to name a different decider \u2014 and a requester can never decide their own approval. Requires an authenticated caller and an owner DB role that can UPDATE approvals.",
       inputSchema: {
-        id: z.string().describe("Pending approval id from list_approvals"),
-        decision: z.enum(["approved", "denied"]).describe("approved or denied")
+        id: z2.string().describe("Pending approval id from list_approvals"),
+        decision: z2.enum(["approved", "denied"]).describe("approved or denied")
       }
     },
     ({ id, decision }) => guarded(async () => {
@@ -535,7 +743,7 @@ import { contentTypeFor, defaultKeyFor } from "@usegraft/assets";
 import { AssetRef } from "@usegraft/core";
 import { resolveContained } from "@usegraft/compiler";
 import { GraftError as GraftError3 } from "@usegraft/contracts";
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 var registerAssetTools = (server, deps) => {
   const { getStorage, options, requireScope } = deps;
   const uploadRoot = options.localUploadRoot;
@@ -543,17 +751,19 @@ var registerAssetTools = (server, deps) => {
     "put_asset",
     {
       title: "Upload an asset (image / binary)",
+      outputSchema: putAssetOutput,
+      annotations: DESTROYS,
       description: (uploadRoot ? "Upload a binary to the asset store and get the frontmatter reference for an `asset` field. Pass `path` (a file inside this project) OR `base64` + `key`. " : "Upload a binary to the asset store and get the frontmatter reference for an `asset` field. Pass `base64` + `key` \u2014 this server reads no files from its own disk. ") + "Refuses to overwrite an existing key unless overwrite: true \u2014 the store keeps no version history. Then reference the returned key from an asset field via write_content.",
       inputSchema: {
-        key: z2.string().optional().describe(
+        key: z3.string().optional().describe(
           'Asset key \u2014 a lowercase path like "pages/pricing/hero.png". Required with base64; defaults to assets/<filename> with path.'
         ),
-        path: z2.string().optional().describe(
+        path: z3.string().optional().describe(
           uploadRoot ? `Path to a file inside ${uploadRoot} (local/stdio agents).` : "Not available on this server \u2014 send the bytes as `base64` instead."
         ),
-        base64: z2.string().optional().describe("The file's bytes, base64-encoded (remote/HTTP agents)."),
-        contentType: z2.string().optional().describe("MIME type. Defaults to an inference from the key/path extension."),
-        overwrite: z2.boolean().optional().describe("Replace an existing binary at this key. Off by default.")
+        base64: z3.string().optional().describe("The file's bytes, base64-encoded (remote/HTTP agents)."),
+        contentType: z3.string().optional().describe("MIME type. Defaults to an inference from the key/path extension."),
+        overwrite: z3.boolean().optional().describe("Replace an existing binary at this key. Off by default.")
       }
     },
     ({ key: keyArg, path, base64, contentType, overwrite }) => guarded(async () => {
@@ -642,13 +852,15 @@ var registerAssetTools = (server, deps) => {
 
 // src/tools/branches.ts
 import { listBranches, listCompilations } from "@usegraft/db";
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var registerBranchTools = (server, deps) => {
   const { branchId, requireDb } = deps;
   server.registerTool(
     "list_branches",
     {
       title: "List branches",
+      outputSchema: listBranchesOutput,
+      annotations: READS,
       description: "List registered content branches (name, parent, backend, status). Same data as GET /api/studio/v1/branches and `graft branch`.",
       inputSchema: {}
     },
@@ -672,10 +884,12 @@ var registerBranchTools = (server, deps) => {
     "list_compilations",
     {
       title: "List compilations",
+      outputSchema: listCompilationsOutput,
+      annotations: READS,
       description: "Recent content projection trail rows (git SHA, added/changed/removed counts), newest first. Same data as GET /api/studio/v1/compilations and `graft compilations`.",
       inputSchema: {
-        branch: z3.string().optional().describe("Restrict to one branch id (default: all branches)"),
-        limit: z3.number().optional().describe("Max rows, newest first (default 20, max 100)")
+        branch: z4.string().optional().describe("Restrict to one branch id (default: all branches)"),
+        limit: z4.number().optional().describe("Max rows, newest first (default 20, max 100)")
       }
     },
     ({ branch, limit }) => guarded(async () => ({
@@ -704,17 +918,18 @@ var registerBranchTools = (server, deps) => {
 
 // src/tools/content.ts
 import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
-import { join as join2 } from "path";
 import {
   composeDocument,
   parseDocument as parseDocument2,
   readCollectionDocs,
+  resolveContained as resolveContained2,
+  SLUG_RE,
   writeDocumentFile
 } from "@usegraft/compiler";
 import { GraftError as GraftError5 } from "@usegraft/contracts";
 import { assertSafeMdx } from "@usegraft/mdx-safety";
 import { assertSearchQuery, scopeChain } from "@usegraft/db";
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 
 // src/tool-helpers.ts
 import { existsSync, readdirSync, readFileSync as readFileSync2, statSync } from "fs";
@@ -749,6 +964,26 @@ async function invokeFunction(handler, name, input, identity) {
   const data = body !== null && typeof body === "object" && "data" in body ? body.data : body;
   return { data, correlationId, status: response.status };
 }
+function filedApprovalId(error) {
+  if (!(error instanceof GraftError4) || error.code !== "DESTRUCTIVE_OP_REQUIRES_APPROVAL") {
+    return void 0;
+  }
+  const id = error.details?.approvalId;
+  return typeof id === "string" ? id : void 0;
+}
+async function invokeFunctionWithApproval(handler, name, input, identity, elicit) {
+  try {
+    return await invokeFunction(handler, name, input, identity);
+  } catch (error) {
+    const approvalId = filedApprovalId(error);
+    if (approvalId === void 0 || elicit === void 0 || identity.approval !== void 0) {
+      throw error;
+    }
+    const approved = await elicit({ approvalId, functionName: name, input });
+    if (approved === void 0) throw error;
+    return invokeFunction(handler, name, input, { ...identity, approval: approved });
+  }
+}
 var ASSET_FIELD_HINT = "Asset reference: the value is an object { key, alt? }. Upload the file with the put_asset tool first \u2014 its response includes the exact snippet to use here.";
 function teachAssetFields(fieldDescriptor) {
   const taught = {
@@ -814,155 +1049,205 @@ function assertSlugFree(contentDir, collectionName, collection, slug, targetSour
   }
 }
 
+// src/tools/resource-uri.ts
+var documentUri = (branchId, collection, slug) => `graft://${branchId}/${collection}/${slug}`;
+var schemaUri = (branchId) => `graft://${branchId}/schema`;
+var documentUriTemplate = (branchId) => `graft://${branchId}/{collection}/{slug}`;
+var documentLink = (branchId, collection, slug) => ({
+  type: "resource_link",
+  uri: documentUri(branchId, collection, slug),
+  name: `${collection}/${slug}`,
+  mimeType: "text/markdown"
+});
+
 // src/tools/content.ts
-var registerContentTools = (server, deps) => {
-  const {
-    branchId,
-    collections,
-    contentDir,
-    functions,
-    getDeleteHandler,
-    getScope,
-    options,
-    projectContent,
-    requireScope,
-    searchIndex,
-    staticIndexPath
-  } = deps;
+function assertSlugShape(slug, collection) {
+  if (SLUG_RE.test(slug)) return;
+  throw new GraftError5({
+    code: "INVALID_SLUG",
+    message: `Slug "${slug}" is not URL-safe.`,
+    fix: 'Slugs must be kebab-case: lowercase letters, digits, and single hyphens (e.g. "getting-started"). A slug names a file inside the collection directory, so it cannot contain "/", ".." or a drive letter.',
+    details: { slug, collection, pattern: SLUG_RE.source }
+  });
+}
+var registerContentReadTools = (server, deps) => {
+  const { branchId, collections, contentDir, getScope, searchIndex, staticIndexPath } = deps;
   server.registerTool(
     "list_content",
     {
       title: "List documents in a collection",
+      outputSchema: listContentOutput,
+      annotations: READS,
       description: "List every document in a collection, read from the authored MDX files (git is the source of truth). Returns slug, sourcePath, and frontmatter data.",
       inputSchema: {
-        collection: z4.string().describe("Collection name, as returned by list_collections")
+        collection: z5.string().describe("Collection name, as returned by list_collections")
       }
     },
-    ({ collection: name }) => guarded(() => {
-      const collection = requireCollection(collections, name);
-      const docs = readCollectionDocs(contentDir, name, collection);
-      return {
-        collection: name,
-        documents: docs.map((doc) => ({
-          slug: doc.slug,
-          sourcePath: doc.sourcePath,
-          data: doc.data
-        }))
-      };
-    })
+    ({ collection: name }) => guarded(
+      () => {
+        const collection = requireCollection(collections, name);
+        const docs = readCollectionDocs(contentDir, name, collection);
+        return {
+          collection: name,
+          documents: docs.map((doc) => ({
+            slug: doc.slug,
+            sourcePath: doc.sourcePath,
+            data: doc.data
+          }))
+        };
+      },
+      (payload) => payload.documents.map((doc) => documentLink(branchId, name, doc.slug))
+    )
   );
   server.registerTool(
     "get_content",
     {
       title: "Get one document",
+      outputSchema: getContentOutput,
+      annotations: READS,
       description: "Read a single document by collection + slug from the authored MDX files: validated frontmatter data, MDX body, and the file path to edit.",
       inputSchema: {
-        collection: z4.string().describe("Collection name"),
-        slug: z4.string().describe("Document slug (kebab-case)")
+        collection: z5.string().describe("Collection name"),
+        slug: z5.string().describe("Document slug (kebab-case)")
       }
     },
-    ({ collection: name, slug }) => guarded(() => {
-      const collection = requireCollection(collections, name);
-      const doc = findDoc(contentDir, name, collection, slug);
-      return {
-        collection: name,
-        slug: doc.slug,
-        sourcePath: doc.sourcePath,
-        data: doc.data,
-        body: doc.body
-      };
-    })
+    ({ collection: name, slug }) => guarded(
+      () => {
+        const collection = requireCollection(collections, name);
+        const doc = findDoc(contentDir, name, collection, slug);
+        return {
+          collection: name,
+          slug: doc.slug,
+          sourcePath: doc.sourcePath,
+          data: doc.data,
+          body: doc.body
+        };
+      },
+      // The document's own address, so a client that reached it by search or
+      // by guesswork can pin it as context without constructing the URI.
+      (payload) => [documentLink(branchId, name, payload.slug)]
+    )
   );
   server.registerTool(
     "search_content",
     {
       title: "Full-text search across content",
+      outputSchema: searchContentOutput,
+      annotations: READS,
       description: 'Search authored content by words, "quoted phrases", `or`, and -exclusions (websearch syntax). Searches the branch\'s effective content in the compiled Postgres index \u2014 on a preview branch that includes documents inherited from parent branches, with branch overrides winning \u2014 so results are as fresh as the last compile (write_content compiles automatically); every hit carries the sourcePath of the file to edit. Ranking weights slug matches over frontmatter over body.',
       inputSchema: {
-        query: z4.string().describe('What to find, e.g. pricing "free tier" -enterprise'),
-        collection: z4.string().optional().describe("Restrict to one collection (default: all registered collections)"),
-        limit: z4.number().optional().describe("Max hits, best-ranked first (default 20)")
+        query: z5.string().describe('What to find, e.g. pricing "free tier" -enterprise'),
+        collection: z5.string().optional().describe("Restrict to one collection (default: all registered collections)"),
+        limit: z5.number().optional().describe("Max hits, best-ranked first (default 20)")
       }
     },
-    ({ query, collection: name, limit }) => guarded(async () => {
-      if (name !== void 0) requireCollection(collections, name);
-      assertSearchQuery(query);
-      const collectionNames = name === void 0 ? Object.keys(collections) : [name];
-      const chain = staticIndexPath === void 0 ? scopeChain(await getScope()) : [branchId];
-      const hits = await searchIndex({ query, chain, collections: collectionNames, limit });
-      return {
-        branch: branchId,
-        chain,
-        query,
-        hits: hits.map(({ row, rank, snippet }) => ({
-          collection: row.collection,
-          slug: row.slug,
-          sourcePath: row.sourcePath,
-          rank,
-          snippet,
-          data: row.data
-        }))
-      };
-    })
+    ({ query, collection: name, limit }) => guarded(
+      async () => {
+        if (name !== void 0) requireCollection(collections, name);
+        assertSearchQuery(query);
+        const collectionNames = name === void 0 ? Object.keys(collections) : [name];
+        const chain = staticIndexPath === void 0 ? scopeChain(await getScope()) : [branchId];
+        const hits = await searchIndex({ query, chain, collections: collectionNames, limit });
+        return {
+          branch: branchId,
+          chain,
+          query,
+          hits: hits.map(({ row, rank, snippet }) => ({
+            collection: row.collection,
+            slug: row.slug,
+            sourcePath: row.sourcePath,
+            rank,
+            snippet,
+            data: row.data
+          }))
+        };
+      },
+      // A hit already knows its collection and slug; the link saves the
+      // client a get_content round trip to reach the document itself.
+      (payload) => payload.hits.map((hit) => documentLink(branchId, hit.collection, hit.slug))
+    )
   );
+};
+var registerContentWriteTools = (server, deps) => {
+  const {
+    branchId,
+    collections,
+    contentDir,
+    elicitApproval,
+    functions,
+    getDeleteHandler,
+    options,
+    projectContent,
+    requireScope
+  } = deps;
   server.registerTool(
     "write_content",
     {
       title: "Write a document (create or update)",
+      outputSchema: writeContentOutput,
+      annotations: WRITES,
       description: "Author or update a document: validates the data against the collection schema, writes <contentDir>/<collection>/<slug>.mdx, and compiles the content tree into the database. Returns exactly what changed. Git is the version history: commit the file afterwards if you have the server's checkout; remote callers can't and needn't \u2014 the checkout's operator owns the commit.",
       inputSchema: {
-        collection: z4.string().describe("Collection name"),
-        slug: z4.string().describe("Document slug \u2014 kebab-case; becomes the filename and the URL segment"),
-        data: z4.record(z4.string(), z4.unknown()).describe("Frontmatter data; must satisfy the collection schema (see describe_schema)"),
-        body: z4.string().optional().describe("MDX body (markdown). Defaults to empty.")
+        collection: z5.string().describe("Collection name"),
+        slug: z5.string().describe("Document slug \u2014 kebab-case; becomes the filename and the URL segment"),
+        data: z5.record(z5.string(), z5.unknown()).describe("Frontmatter data; must satisfy the collection schema (see describe_schema)"),
+        body: z5.string().optional().describe("MDX body (markdown). Defaults to empty.")
       }
     },
-    ({ collection: name, slug, data, body }) => guarded(async () => {
-      requireScope("write_content", "content:write");
-      const collection = requireCollection(collections, name);
-      if (collection.authority === "db-authoritative") {
-        throw new GraftError5({
-          code: "AUTHORITY_MISMATCH",
-          message: `Collection "${name}" is db-authoritative \u2014 its records live in Postgres, not as MDX files.`,
-          fix: `Write this data through the collection's function endpoint (POST /api/fn/<name>, see llms.txt) instead of write_content. write_content is only for file-authoritative collections.`,
-          details: { collection: name, authority: collection.authority }
-        });
-      }
-      const frontmatterSlug = data.slug;
-      if (frontmatterSlug !== void 0 && frontmatterSlug !== slug) {
-        throw new GraftError5({
-          code: "INVALID_SLUG",
-          message: `data.slug ("${String(frontmatterSlug)}") conflicts with the slug argument ("${slug}")`,
-          fix: "Omit `slug` from data \u2014 the slug argument names the file and the document.",
-          details: { slug, frontmatterSlug }
+    ({ collection: name, slug, data, body }) => guarded(
+      async () => {
+        requireScope("write_content", "content:write");
+        const collection = requireCollection(collections, name);
+        if (collection.authority === "db-authoritative") {
+          throw new GraftError5({
+            code: "AUTHORITY_MISMATCH",
+            message: `Collection "${name}" is db-authoritative \u2014 its records live in Postgres, not as MDX files.`,
+            fix: `Write this data through the collection's function endpoint (POST /api/fn/<name>, see llms.txt) instead of write_content. write_content is only for file-authoritative collections.`,
+            details: { collection: name, authority: collection.authority }
+          });
+        }
+        const frontmatterSlug = data.slug;
+        if (frontmatterSlug !== void 0 && frontmatterSlug !== slug) {
+          throw new GraftError5({
+            code: "INVALID_SLUG",
+            message: `data.slug ("${String(frontmatterSlug)}") conflicts with the slug argument ("${slug}")`,
+            fix: "Omit `slug` from data \u2014 the slug argument names the file and the document.",
+            details: { slug, frontmatterSlug }
+          });
+        }
+        assertSlugShape(slug, name);
+        const sourcePath = `${name}/${slug}.mdx`;
+        const fullPath = resolveContained2(contentDir, sourcePath, {
+          label: "document path"
         });
-      }
-      const sourcePath = `${name}/${slug}.mdx`;
-      const fullPath = join2(contentDir, ...sourcePath.split("/"));
-      assertSafeMdx(body ?? "", { label: `${name}/${slug}` });
-      const existingRaw = existsSync2(fullPath) ? readFileSync3(fullPath, "utf8") : void 0;
-      const raw = composeDocument(existingRaw, data, body ?? "");
-      parseDocument2(raw, collection, sourcePath);
-      assertSlugFree(contentDir, name, collection, slug, sourcePath);
-      writeDocumentFile(fullPath, raw);
-      const result = await projectContent();
-      return {
-        written: sourcePath,
-        branch: branchId,
-        gitSha: result.gitSha,
-        changes: result.changes
-      };
-    })
+        assertSafeMdx(body ?? "", { label: `${name}/${slug}` });
+        const existingRaw = existsSync2(fullPath) ? readFileSync3(fullPath, "utf8") : void 0;
+        const raw = composeDocument(existingRaw, data, body ?? "");
+        parseDocument2(raw, collection, sourcePath);
+        assertSlugFree(contentDir, name, collection, slug, sourcePath);
+        writeDocumentFile(contentDir, sourcePath, raw);
+        const result = await projectContent();
+        return {
+          written: sourcePath,
+          branch: branchId,
+          gitSha: result.gitSha,
+          changes: result.changes
+        };
+      },
+      // Where the thing it just wrote now lives.
+      () => [documentLink(branchId, name, slug)]
+    )
   );
   server.registerTool(
     "delete_content",
     {
       title: "Delete a document (human-gated)",
-      description: "Delete an authored document: removes <contentDir>/<collection>/<slug>.mdx and compiles, so the index soft-deletes it. DESTRUCTIVE and always human-gated \u2014 the first call files an approval and fails with its id; a human decides with `graft approve <id>` (or deny); then retry the SAME collection+slug with `approval: <id>` (the MCP form of the x-graft-approval header). Approvals are one-shot and bound to that exact input. Git is the version history: commit the deletion afterwards if you have the server's checkout; remote callers can't and needn't \u2014 the checkout's operator owns the commit.",
+      annotations: DESTROYS,
+      description: "Delete an authored document: removes <contentDir>/<collection>/<slug>.mdx and compiles, so the index soft-deletes it. DESTRUCTIVE and always human-gated \u2014 the first call files an approval and fails with its id; a human decides with `graft approve <id>` (or deny); then retry the SAME collection+slug with `approval: <id>` (the MCP form of the x-graft-approval header). Approvals are one-shot and bound to that exact input. On a server that has opted into elicited approvals AND a client that supports elicitation, you may instead be asked to confirm in-band and the call completes in one step \u2014 the gate is identical, only the way the human is reached differs, so do not treat either outcome as unusual. Git is the version history: commit the deletion afterwards if you have the server's checkout; remote callers can't and needn't \u2014 the checkout's operator owns the commit.",
       inputSchema: {
-        collection: z4.string().describe("Collection name"),
-        slug: z4.string().describe("Document slug to delete"),
-        approval: z4.string().optional().describe(
+        collection: z5.string().describe("Collection name"),
+        slug: z5.string().describe("Document slug to delete"),
+        approval: z5.string().optional().describe(
           "Approval id from a prior DESTRUCTIVE_OP_REQUIRES_APPROVAL response, after a human ran `graft approve <id>`."
         )
       }
@@ -978,31 +1263,34 @@ var registerContentTools = (server, deps) => {
           details: { collection: name, authority: collection.authority }
         });
       }
+      assertSlugShape(slug, name);
       findDoc(contentDir, name, collection, slug);
-      const { data, correlationId } = await invokeFunction(
+      const { data, correlationId } = await invokeFunctionWithApproval(
         getDeleteHandler(),
         "delete_content",
         { collection: name, slug },
-        { credential: options.defaultAuthorization, approval }
+        { credential: options.defaultAuthorization, approval },
+        elicitApproval
       );
       return { ...data, correlationId };
     })
   );
-  const uploadRoot = options.localUploadRoot;
 };
 
 // src/tools/errors.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 var registerErrorTools = (server, deps) => {
   void deps;
   server.registerTool(
     "explain_error",
     {
       title: "Explain a Graft error",
+      outputSchema: explainErrorOutput,
+      annotations: READS,
       description: "Given a GraftError code or its JSON, explain what it means, its typical causes, and how to recover. Use whenever a tool call or compile fails.",
       inputSchema: {
-        code: z5.string().optional().describe("An error code, e.g. SCHEMA_VALIDATION_FAILED"),
-        error: z5.string().optional().describe("A full GraftError JSON string, if you have one")
+        code: z6.string().optional().describe("An error code, e.g. SCHEMA_VALIDATION_FAILED"),
+        error: z6.string().optional().describe("A full GraftError JSON string, if you have one")
       }
     },
     ({ code, error }) => guarded(() => {
@@ -1039,23 +1327,215 @@ var registerErrorTools = (server, deps) => {
   );
 };
 
+// src/tools/packages.ts
+import { z as z7 } from "zod";
+
+// src/packages.ts
+var PACKAGE_KNOWLEDGE = {
+  "@usegraft/cli": {
+    name: "@usegraft/cli",
+    role: "The `graft` command: init, compile, dev, serve, migrate, merge, add.",
+    when: "Always. It scaffolds the project and compiles content into the index.",
+    tier: "either",
+    direct: true
+  },
+  "@usegraft/sdk-next": {
+    name: "@usegraft/sdk-next",
+    role: "Next.js adapter: typed reads in Server Components, plus route handlers.",
+    when: "You are on Next.js (App Router).",
+    tier: "either",
+    framework: "next",
+    direct: true
+  },
+  "@usegraft/sdk-astro": {
+    name: "@usegraft/sdk-astro",
+    role: "Astro adapter: typed reads in components, plus `graftRoute`.",
+    when: "You are on Astro.",
+    tier: "either",
+    framework: "astro",
+    direct: true
+  },
+  "@usegraft/sdk-sveltekit": {
+    name: "@usegraft/sdk-sveltekit",
+    role: "SvelteKit adapter: typed reads in load functions, plus route handlers.",
+    when: "You are on SvelteKit.",
+    tier: "either",
+    framework: "sveltekit",
+    direct: true
+  },
+  "@usegraft/sdk-react-router": {
+    name: "@usegraft/sdk-react-router",
+    role: "React Router adapter: typed reads in loaders and actions.",
+    when: "You are on React Router in framework mode, which runs a server.",
+    tier: "either",
+    framework: "react-router",
+    direct: true
+  },
+  "@usegraft/sdk-tanstack-start": {
+    name: "@usegraft/sdk-tanstack-start",
+    role: "TanStack Start adapter: typed reads in server functions and loaders.",
+    when: "You are on TanStack Start.",
+    tier: "either",
+    framework: "tanstack-start",
+    direct: true
+  },
+  "@usegraft/sdk-react": {
+    name: "@usegraft/sdk-react",
+    role: "Browser client: typed reads over the content API, with a provider and hooks.",
+    when: "You need reads in the browser \u2014 a search box, an editor preview, a widget on an already-rendered page. No database reaches this package.",
+    tier: "postgres",
+    framework: "react",
+    direct: true
+  },
+  "@usegraft/sdk-core": {
+    name: "@usegraft/sdk-core",
+    role: "The framework-agnostic read client the adapters are built on.",
+    when: "You are on a framework with no adapter, or you want the client directly.",
+    tier: "either",
+    direct: true
+  },
+  "@usegraft/content-api": {
+    name: "@usegraft/content-api",
+    role: "The HTTP content API: a handler to mount, and a reader to consume it.",
+    when: "Something reads content over HTTP rather than in-process \u2014 the browser client, or another service.",
+    tier: "either",
+    direct: true
+  },
+  "@usegraft/mcp": {
+    name: "@usegraft/mcp",
+    role: "The MCP server: authoring, schema introspection, functions and approvals as tools.",
+    when: "You want an agent to read and write content. `graft mcp` and `graft serve` both mount it.",
+    tier: "either",
+    direct: true
+  },
+  "@usegraft/studio": {
+    name: "@usegraft/studio",
+    role: "The editing UI: documents, compiles, commits, branches and approvals.",
+    when: "A human needs to edit without touching the repository.",
+    tier: "postgres",
+    direct: true
+  },
+  "@usegraft/core": {
+    name: "@usegraft/core",
+    role: "defineCollection, defineFunction, the functions handler, and the field primitives.",
+    when: "Always \u2014 it is what graft.config.ts imports to declare a schema.",
+    tier: "either",
+    direct: true
+  },
+  "@usegraft/db": {
+    name: "@usegraft/db",
+    role: "The Postgres schema and Drizzle handle for operational data.",
+    when: "You are on the Postgres tier. Never reaches a browser.",
+    tier: "postgres",
+    direct: true
+  },
+  "@usegraft/auth": {
+    name: "@usegraft/auth",
+    role: "Actor resolution: bearer tokens, OIDC issuers and scopes.",
+    when: "You are authenticating callers to functions, MCP or Studio.",
+    tier: "postgres",
+    direct: true
+  },
+  "@usegraft/assets": {
+    name: "@usegraft/assets",
+    role: "The S3-compatible asset store behind `graft asset put` and `put_asset`.",
+    when: "Documents reference images or files.",
+    tier: "either",
+    direct: true
+  },
+  "@usegraft/compiler": {
+    name: "@usegraft/compiler",
+    role: "Reads authored MDX and projects it into the content index.",
+    when: "Pulled in by the CLI. Install directly only to compile from your own code.",
+    tier: "either",
+    direct: false
+  },
+  "@usegraft/contracts": {
+    name: "@usegraft/contracts",
+    role: "Shared types, error codes and the content-index interface.",
+    when: "A dependency of everything. Install directly only to implement your own index reader.",
+    tier: "either",
+    direct: false
+  },
+  "@usegraft/mdx-safety": {
+    name: "@usegraft/mdx-safety",
+    role: "Refuses executable MDX in authored bodies, per the project's mdxTrust.",
+    when: "Pulled in by the compiler and MCP. Install directly only to check MDX yourself.",
+    tier: "either",
+    direct: false
+  },
+  "@usegraft/content-migrations": {
+    name: "@usegraft/content-migrations",
+    role: "Migrations for authored documents, as opposed to database rows.",
+    when: "A schema change needs existing MDX rewritten.",
+    tier: "either",
+    direct: true
+  },
+  "@usegraft/tokens": {
+    name: "@usegraft/tokens",
+    role: "Graft's design tokens as plain CSS custom properties.",
+    when: "You are restyling Studio, or want a UI that matches it. One CSS import, no JavaScript.",
+    tier: "either",
+    direct: true
+  },
+  "@usegraft/registry": {
+    name: "@usegraft/registry",
+    role: "The owned primitives `graft add` copies into a project.",
+    when: "Pulled in by the CLI. Browse the items with list_registry.",
+    tier: "either",
+    direct: false
+  }
+};
+function allPackages() {
+  return Object.values(PACKAGE_KNOWLEDGE);
+}
+
+// src/tools/packages.ts
+var registerPackageTools = (server, deps) => {
+  void deps;
+  server.registerTool(
+    "list_packages",
+    {
+      title: "List Graft packages",
+      outputSchema: listPackagesOutput,
+      annotations: READS,
+      description: "Which @usegraft/* package to install for a given framework or job: what each one is, when you need it, and which tier it requires. Filter by `framework` when the user is on a known one, or by `tier`. Use this before suggesting an install; use list_registry for copy-in primitives instead.",
+      inputSchema: {
+        framework: z7.enum(["next", "astro", "sveltekit", "react-router", "tanstack-start", "react"]).optional().describe("Only the adapter for this framework, plus the packages every project needs"),
+        tier: z7.enum(["static", "postgres"]).optional().describe("Only packages usable on this tier"),
+        includeIndirect: z7.boolean().optional().describe("Include packages pulled in as dependencies rather than installed directly")
+      }
+    },
+    ({ framework, tier, includeIndirect }) => guarded(() => {
+      let packages = allPackages();
+      if (!includeIndirect) packages = packages.filter((p) => p.direct);
+      if (framework) {
+        packages = packages.filter((p) => p.framework === void 0 || p.framework === framework);
+      }
+      if (tier) packages = packages.filter((p) => p.tier === "either" || p.tier === tier);
+      return { packages: packages.sort((a, b) => a.name.localeCompare(b.name)) };
+    })
+  );
+};
+
 // src/tools/functions.ts
 import { GraftError as GraftError6 } from "@usegraft/contracts";
-import { z as z6 } from "zod";
+import { z as z8 } from "zod";
 var registerFunctionTools = (server, deps) => {
-  const { functions, functionsByName, getFunctionsHandler, options } = deps;
+  const { elicitApproval, functions, functionsByName, getFunctionsHandler, options } = deps;
   server.registerTool(
     "run_function",
     {
       title: "Run a typed function",
-      description: "Invoke a defineFunction by name with a JSON input object. Same pipeline as POST /api/fn/<name>: Zod validation, access rules, rate limits, audit log, and the human gate for destructive ops. The server may already act with a configured identity (graft mcp uses GRAFT_DEV_TOKEN; over HTTP your connection's bearer is forwarded) \u2014 only pass authorization to override it. Pass approval after a human runs `graft approve <id>` for gated calls. Success returns { data, correlationId }; failures are GraftError JSON with a fix.",
+      annotations: DESTROYS,
+      description: "Invoke a defineFunction by name with a JSON input object. Same pipeline as POST /api/fn/<name>: Zod validation, access rules, rate limits, audit log, and the human gate for destructive ops. The server may already act with a configured identity (graft mcp uses GRAFT_DEV_TOKEN; over HTTP your connection's bearer is forwarded) \u2014 only pass authorization to override it. Pass approval after a human runs `graft approve <id>` for gated calls \u2014 or, where the server has opted into elicited approvals and your client supports elicitation, expect to be asked to confirm in-band and the call completes in one step. The gate is the same either way. Success returns { data, correlationId }; failures are GraftError JSON with a fix.",
       inputSchema: {
-        name: z6.string().describe("Function name (defineFunction name, not the export key)"),
-        input: z6.record(z6.string(), z6.unknown()).optional().describe("Input fields object; defaults to {}. See describe_function for the schema."),
-        authorization: z6.string().optional().describe(
+        name: z8.string().describe("Function name (defineFunction name, not the export key)"),
+        input: z8.record(z8.string(), z8.unknown()).optional().describe("Input fields object; defaults to {}. See describe_function for the schema."),
+        authorization: z8.string().optional().describe(
           "Bearer token override (with or without the 'Bearer ' prefix). Usually unnecessary \u2014 the server's configured identity applies when omitted."
         ),
-        approval: z6.string().optional().describe(
+        approval: z8.string().optional().describe(
           "Approval id from a prior DESTRUCTIVE_OP_REQUIRES_APPROVAL response (after `graft approve <id>`)."
         )
       }
@@ -1077,23 +1557,28 @@ var registerFunctionTools = (server, deps) => {
           details: { requested: name, available: [...functionsByName.keys()] }
         });
       }
-      return invokeFunction(getFunctionsHandler(), name, input ?? {}, {
-        credential: authorization ?? options.defaultAuthorization,
-        approval
-      });
+      return invokeFunctionWithApproval(
+        getFunctionsHandler(),
+        name,
+        input ?? {},
+        { credential: authorization ?? options.defaultAuthorization, approval },
+        elicitApproval
+      );
     })
   );
 };
 
 // src/tools/introspection.ts
 import { GraftError as GraftError7 } from "@usegraft/contracts";
-import { z as z7 } from "zod";
-var registerIntrospectionTools = (server, deps) => {
-  const { branchId, collections, functions, functionsByName } = deps;
+import { z as z9 } from "zod";
+var registerCollectionIntrospection = (server, deps) => {
+  const { branchId, collections } = deps;
   server.registerTool(
     "list_collections",
     {
       title: "List collections",
+      outputSchema: listCollectionsOutput,
+      annotations: READS,
       description: "List every registered content collection (name, description, authority, field count). Start here to learn what kinds of content this project has.",
       inputSchema: {}
     },
@@ -1110,10 +1595,15 @@ var registerIntrospectionTools = (server, deps) => {
       })
     }))
   );
+};
+var registerFunctionIntrospection = (server, deps) => {
+  const { branchId, collections, functions, functionsByName } = deps;
   server.registerTool(
     "describe_schema",
     {
       title: "Describe the content schema",
+      outputSchema: describeSchemaOutput,
+      annotations: READS,
       description: "Full schema introspection: every collection with its typed fields (name, type, optional, description), plus every registered function (kind, args, public/destructive). Documents also accept an optional kebab-case `slug` (defaults to the filename). Prefer list_functions / describe_function when you only need the function surface.",
       inputSchema: {}
     },
@@ -1131,6 +1621,8 @@ var registerIntrospectionTools = (server, deps) => {
     "list_functions",
     {
       title: "List functions",
+      outputSchema: listFunctionsOutput,
+      annotations: READS,
       description: "List every registered typed function (name, kind, public, destructive, short description). Use describe_function for the full input schema, then run_function to invoke. Mutations reject anonymous callers unless public: true; destructive functions always require human approval (graft approve).",
       inputSchema: {}
     },
@@ -1153,9 +1645,11 @@ var registerIntrospectionTools = (server, deps) => {
     "describe_function",
     {
       title: "Describe one function",
+      outputSchema: describeFunctionOutput,
+      annotations: READS,
       description: "Full introspection for one function: kind, args (name/type/optional/description), returns, public, destructive. Use this before run_function so the input object matches the schema.",
       inputSchema: {
-        name: z7.string().describe("Function name as returned by list_functions")
+        name: z9.string().describe("Function name as returned by list_functions")
       }
     },
     ({ name }) => guarded(() => {
@@ -1173,15 +1667,256 @@ var registerIntrospectionTools = (server, deps) => {
   );
 };
 
+// src/approval-elicitation.ts
+import { GraftError as GraftError8 } from "@usegraft/contracts";
+import { decideApproval as decideApproval2 } from "@usegraft/db";
+var INPUT_PREVIEW_LIMIT = 1e3;
+function describeCall(functionName, input) {
+  const rendered = JSON.stringify(input);
+  if (rendered === void 0) return functionName;
+  if (rendered.length <= INPUT_PREVIEW_LIMIT) return `${functionName} ${rendered}`;
+  return [
+    `${functionName} ${rendered.slice(0, INPUT_PREVIEW_LIMIT)}\u2026`,
+    "",
+    `\u26A0\uFE0F Input truncated (${rendered.length} characters). Run \`graft approvals\` to read it in full before deciding \u2014 the approval binds to the whole input, not the part shown here.`
+  ].join("\n");
+}
+function createApprovalElicitor(options) {
+  return async ({ approvalId, functionName, input }) => {
+    if (options.server.server.getClientCapabilities()?.elicitation === void 0) {
+      return void 0;
+    }
+    let result;
+    try {
+      result = await options.server.server.elicitInput({
+        message: [
+          `Approve this destructive call?`,
+          "",
+          describeCall(functionName, input),
+          "",
+          `It will be recorded as decided by ${options.decider.kind}:${options.decider.id}.`,
+          "The approval is one-shot and bound to exactly this input."
+        ].join("\n"),
+        requestedSchema: {
+          type: "object",
+          properties: {
+            approve: {
+              type: "boolean",
+              title: "Approve",
+              description: `Allow ${functionName} to run once, with exactly this input.`
+            }
+          },
+          required: ["approve"]
+        }
+      });
+    } catch {
+      return void 0;
+    }
+    if (result.action === "cancel") return void 0;
+    const approved = result.action === "accept" && result.content?.approve === true;
+    const row = await decideApproval2(
+      options.db(),
+      approvalId,
+      approved ? "approved" : "denied",
+      options.decider
+    );
+    if (!row) {
+      throw new GraftError8({
+        code: "APPROVAL_INVALID",
+        message: `Approval "${approvalId}" was no longer pending when the decision arrived.`,
+        fix: "Someone or something decided it while the prompt was open. Call the tool again to file a fresh approval.",
+        details: { id: approvalId, function: functionName }
+      });
+    }
+    return approved ? approvalId : void 0;
+  };
+}
+
+// src/tools/prompts.ts
+import { z as z10 } from "zod";
+import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
+import { readCollectionDocs as readCollectionDocs2 } from "@usegraft/compiler";
+var say = (text) => ({
+  messages: [{ role: "user", content: { type: "text", text } }]
+});
+var registerContentPrompts = (server, deps) => {
+  const { branchId, collections, contentDir } = deps;
+  const fileCollections = () => Object.values(collections).filter((collection) => collection.describe().authority !== "db-authoritative").map((collection) => collection.describe().name);
+  const migrationSteps = (name) => {
+    if (collections[name]?.describe().authority === "db-authoritative") {
+      return [
+        "This collection is db-authoritative: its records live in Postgres, not as MDX files. `graft compile` has nothing to say about them, and no file will fail to name the work.",
+        "1. Edit the collection in graft.config.ts (or under graft/) to the new shape.",
+        "2. Write `migrations/<seq>-<name>.ts` default-exporting defineDataMigration. It backfills data_records and writes its ledger row in ONE transaction, so a half-applied migration is not a state this can reach.",
+        "3. `graft migrate` is a dry run. `graft migrate --apply` is the operator's consent, and is theirs to give \u2014 propose the command, do not assume it.",
+        "4. Commit. The migration is a reviewable commit, which is the whole reason it is a file rather than a live edit."
+      ];
+    }
+    return [
+      "How migrations work here \u2014 they are code, not a console action:",
+      "1. Edit the collection in graft.config.ts (or under graft/) to the new shape.",
+      "2. `graft compile` now fails, once per document that no longer satisfies the schema. That is the point: the failure names every file to fix.",
+      "3. Write `migrations/<seq>-<name>.ts` default-exporting defineContentMigration. It transforms old-shape frontmatter, validates every output against the NEW schema, and rewrites the files all-or-nothing.",
+      "4. `graft migrate` is a dry run. `graft migrate --apply` is the operator's consent, and is theirs to give \u2014 propose the command, do not assume it.",
+      "5. Compile again, then commit. The migration is a reviewable commit, which is the whole reason it is a file rather than a live edit."
+    ];
+  };
+  const slugsIn = (name) => {
+    const collection = collections[name];
+    if (!collection) return [];
+    try {
+      return readCollectionDocs2(contentDir, name, collection).map((doc) => doc.slug);
+    } catch {
+      return [];
+    }
+  };
+  const fieldLines = (name) => {
+    const collection = collections[name];
+    if (!collection) return "(unknown collection)";
+    return collection.describe().fields.map((field2) => {
+      const optional = field2.optional ? " (optional)" : " (required)";
+      const description = field2.description ? ` \u2014 ${field2.description}` : "";
+      return `- ${field2.name}: ${field2.type}${optional}${description}`;
+    }).join("\n");
+  };
+  const collectionArg = completable(
+    z10.string().describe("Collection name"),
+    (value) => fileCollections().filter((name) => name.startsWith(value))
+  );
+  server.registerPrompt(
+    "author-document",
+    {
+      title: "Author a document",
+      description: "Write a new document into a collection, with that collection's actual field list already filled in.",
+      argsSchema: {
+        collection: collectionArg,
+        topic: z10.string().describe("What the document should be about")
+      }
+    },
+    ({ collection, topic }) => say(
+      [
+        `Author a new document in the "${collection}" collection of this Graft project. Topic: ${topic}`,
+        "",
+        "Frontmatter must satisfy these fields exactly:",
+        fieldLines(collection),
+        "",
+        "How to do it:",
+        "1. Choose a kebab-case slug. It becomes the filename and the URL segment.",
+        "2. Call write_content with the collection, the slug, the frontmatter as `data`, and the MDX body.",
+        "3. write_content validates against the schema and compiles in one step \u2014 a schema failure comes back with a fix, so read it and correct the data rather than retrying unchanged.",
+        "",
+        "Body rules: prose and Markdown. Components are allowed only with literal attributes \u2014 the MDX safety gate refuses `{expressions}` and `import`, because rendering evaluates them as JavaScript on the server.",
+        "",
+        "Git owns the version history. If you are working in the server's checkout, commit the file afterwards; if you are remote, the checkout's operator owns the commit and you do not need to."
+      ].join("\n")
+    )
+  );
+  server.registerPrompt(
+    "revise-document",
+    {
+      title: "Revise a document",
+      description: "Edit an existing document, with its current content and its address already attached.",
+      argsSchema: {
+        collection: collectionArg,
+        slug: completable(z10.string().describe("Document slug"), (value, context) => {
+          const chosen = context?.arguments?.collection;
+          const candidates = chosen ? slugsIn(chosen) : fileCollections().flatMap(slugsIn);
+          return candidates.filter((slug) => slug.startsWith(value));
+        }),
+        goal: z10.string().describe("What should change")
+      }
+    },
+    ({ collection, slug, goal }) => say(
+      [
+        `Revise "${collection}/${slug}" in this Graft project. Goal: ${goal}`,
+        "",
+        `Read it first: ${documentUri(branchId, collection, slug)} (or get_content).`,
+        "",
+        "Frontmatter fields for this collection:",
+        fieldLines(collection),
+        "",
+        "Then call write_content with the same collection and slug. Send the full frontmatter and body, not a patch \u2014 write_content replaces the document.",
+        "",
+        "Change only what the goal asks for. Frontmatter keys you are not changing must come back byte-identical: the writer preserves untouched lines, and a reformatted file is a diff the author has to review for nothing.",
+        "",
+        "If that write comes back SLUG_NOT_UNIQUE, the document is not where write_content would put it \u2014 it is a .md file, or it lives under a different filename and claims this slug in its frontmatter. write_content always targets <collection>/<slug>.mdx, so it cannot edit that file in place. The error names the path that owns the slug; report it rather than writing a second document with the same slug."
+      ].join("\n")
+    )
+  );
+  server.registerPrompt(
+    "fix-error",
+    {
+      title: "Recover from a Graft error",
+      description: "Turn a GraftError into the next action, with this build's recovery text already resolved.",
+      argsSchema: {
+        code: completable(
+          z10.string().describe("The error code, e.g. SCHEMA_VALIDATION_FAILED"),
+          (value) => Object.keys(ERROR_KNOWLEDGE).filter((code) => code.startsWith(value.toUpperCase()))
+        )
+      }
+    },
+    ({ code }) => {
+      const explanation = explainCode(code);
+      if (!explanation) {
+        return say(
+          [
+            `"${code}" is not a Graft error code.`,
+            "",
+            `Call explain_error with no arguments to list the ${Object.keys(ERROR_KNOWLEDGE).length} codes this build knows, or pass the full GraftError JSON as \`error\`.`,
+            "If it came from another system, resolve it there \u2014 Graft has nothing to say about it."
+          ].join("\n")
+        );
+      }
+      return say(
+        [
+          `Recover from ${code} in this Graft project.`,
+          "",
+          `What it means: ${explanation.meaning}`,
+          "",
+          "Usually because:",
+          ...explanation.typicalCauses.map((cause) => `- ${cause}`),
+          "",
+          `How to recover: ${explanation.howToRecover}`,
+          "",
+          "The failing call's own `fix` is more specific than this page and beats it wherever the two differ \u2014 this is the general lesson behind the code, that was the advice for the one failure."
+        ].join("\n")
+      );
+    }
+  );
+  server.registerPrompt(
+    "plan-migration",
+    {
+      title: "Plan a schema migration",
+      description: "Change a collection's shape without breaking the documents already written against it.",
+      argsSchema: {
+        collection: collectionArg,
+        change: z10.string().describe("The schema change, e.g. add a required `description`")
+      }
+    },
+    ({ collection, change }) => say(
+      [
+        `Plan a migration for the "${collection}" collection of this Graft project. Change: ${change}`,
+        "",
+        "Current fields:",
+        fieldLines(collection),
+        "",
+        ...migrationSteps(collection)
+      ].join("\n")
+    )
+  );
+};
+
 // src/tools/registry.ts
 import { describeItem, listItems, loadItem } from "@usegraft/registry";
-import { z as z8 } from "zod";
+import { z as z11 } from "zod";
 var registerRegistryTools = (server, deps) => {
   const { options } = deps;
   server.registerTool(
     "list_registry",
     {
       title: "List registry items",
+      outputSchema: listRegistryOutput,
+      annotations: READS,
       description: "List every owned primitive available to `graft add` \u2014 shadcn-style copy-in blocks / fields / access rules / bundles (name, type, one-line description, and any registry items it pulls in). Use describe_item for the full details, then install with `graft add <name>` from the CLI. MCP browses what exists; the CLI installs it.",
       inputSchema: {}
     },
@@ -1198,23 +1933,153 @@ var registerRegistryTools = (server, deps) => {
     "describe_item",
     {
       title: "Describe a registry item",
+      outputSchema: describeItemOutput,
+      annotations: READS,
       description: "Full details for one owned primitive: type, description, the files it writes into the project, npm dependencies to install, the registry items it pulls in first, and whether it ships an llms.txt fragment. Use list_registry for names; install with `graft add <name>` (CLI). MCP does not install.",
       inputSchema: {
-        name: z8.string().describe("Item name as returned by list_registry")
+        name: z11.string().describe("Item name as returned by list_registry")
       }
     },
     ({ name }) => guarded(() => describeItem(loadItem(name, options.registryRoot)))
   );
 };
 
+// src/tools/resources.ts
+import { readFileSync as readFileSync4 } from "fs";
+import { GraftError as GraftError9 } from "@usegraft/contracts";
+import { readCollectionDocs as readCollectionDocs3, resolveContained as resolveContained3 } from "@usegraft/compiler";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+var isFileAuthoritative = (authority) => authority !== "db-authoritative";
+var asString = (value) => typeof value === "string" && value !== "" ? value : void 0;
+var registerDocumentResources = (server, deps) => {
+  const { branchId, collections, contentDir } = deps;
+  const fileCollections = () => Object.values(collections).filter((collection) => isFileAuthoritative(collection.describe().authority)).map((collection) => collection.describe().name);
+  const allDocuments = () => {
+    const out = [];
+    for (const name of fileCollections()) {
+      try {
+        for (const doc of readCollectionDocs3(contentDir, name, collections[name])) {
+          out.push({
+            collection: name,
+            slug: doc.slug,
+            sourcePath: doc.sourcePath,
+            title: asString(doc.data.title),
+            description: asString(doc.data.description)
+          });
+        }
+      } catch {
+      }
+    }
+    return out;
+  };
+  server.registerResource(
+    "document",
+    new ResourceTemplate(documentUriTemplate(branchId), {
+      list: () => ({
+        resources: allDocuments().map((doc) => ({
+          uri: documentUri(branchId, doc.collection, doc.slug),
+          name: `${doc.collection}/${doc.slug}`,
+          title: doc.title ?? doc.slug,
+          description: doc.description ?? `Authored MDX at ${doc.sourcePath}`,
+          mimeType: "text/markdown"
+        }))
+      }),
+      // The URI variables autocomplete from what actually exists, and the slug
+      // list narrows to the collection already chosen — the context carries the
+      // variables filled in so far.
+      complete: {
+        collection: (value) => fileCollections().filter((name) => name.startsWith(value)),
+        slug: (value, context) => {
+          const chosen = context?.arguments?.collection;
+          return allDocuments().filter((doc) => chosen === void 0 || doc.collection === chosen).map((doc) => doc.slug).filter((slug) => slug.startsWith(value));
+        }
+      }
+    }),
+    {
+      title: "Authored document",
+      description: "One MDX document as authored, frontmatter and body, read from the content directory rather than the index \u2014 so it reflects the working tree, not the last compile. Attach it as context; edit it with write_content.",
+      mimeType: "text/markdown"
+    },
+    (uri, variables) => guardedResource(() => {
+      const collectionName = String(variables.collection);
+      const slug = String(variables.slug);
+      const collection = requireCollection(collections, collectionName);
+      if (!isFileAuthoritative(collection.describe().authority)) {
+        throw new GraftError9({
+          code: "AUTHORITY_MISMATCH",
+          message: `Collection "${collectionName}" is db-authoritative \u2014 its records live in Postgres, not as MDX files, so they have no document resource.`,
+          fix: "Read these through the collection's typed functions (see list_functions), not as a resource.",
+          details: { collection: collectionName, authority: collection.describe().authority }
+        });
+      }
+      const docs = readCollectionDocs3(contentDir, collectionName, collection);
+      const doc = docs.find((candidate) => candidate.slug === slug);
+      if (!doc) {
+        throw new GraftError9({
+          code: "DOCUMENT_NOT_FOUND",
+          message: `No document "${slug}" in collection "${collectionName}".`,
+          fix: `Known slugs: ${docs.map((d) => d.slug).join(", ") || "(none)"}. List the document resources, or author it with write_content.`,
+          details: { collection: collectionName, slug }
+        });
+      }
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "text/markdown",
+            // Contained rather than joined: the scan that produced
+            // sourcePath happily lists a symlink, and this mount can be the
+            // unauthenticated docs server, where following one would serve
+            // bytes from outside the content tree to anybody who asks.
+            text: readFileSync4(
+              resolveContained3(contentDir, doc.sourcePath, { label: "document source" }),
+              "utf8"
+            )
+          }
+        ]
+      };
+    })
+  );
+};
+var registerSchemaResource = (server, deps) => {
+  const { branchId, collections, functionsByName } = deps;
+  server.registerResource(
+    "schema",
+    schemaUri(branchId),
+    {
+      title: "Project schema",
+      description: "Every collection with its typed fields, and every registered function \u2014 the same payload as describe_schema. Attach it once instead of calling the tool each time.",
+      mimeType: "application/json"
+    },
+    (uri) => {
+      const description = {
+        collections: Object.values(collections).map((collection) => {
+          const descriptor = collection.describe();
+          return { ...descriptor, fields: descriptor.fields.map(teachAssetFields) };
+        }),
+        functions: [...functionsByName.values()].map((fn) => fn.describe())
+      };
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(description, null, 2)
+          }
+        ]
+      };
+    }
+  );
+};
+
 // src/server.ts
-function createGraftMcp(options) {
+function buildServer(options, register) {
   const { contentDir, collections } = options;
   const branchId = options.branchId ?? "main";
   const staticIndexPath = options.db === void 0 ? options.staticIndexPath : void 0;
   const maybeDb = options.db;
   if (maybeDb === void 0 && staticIndexPath === void 0) {
-    throw new GraftError8({
+    throw new GraftError10({
       code: "CONFIG_INVALID",
       message: "createGraftMcp needs an index: pass `db` (Postgres) or `staticIndexPath`.",
       fix: "Pass `db` from createDb(DATABASE_URL), or `staticIndexPath` pointing at the compiled artifact (.graft/index.db) for a static project."
@@ -1222,7 +2087,7 @@ function createGraftMcp(options) {
   }
   const requireDb = (feature, insteadDo) => {
     if (maybeDb !== void 0) return maybeDb;
-    throw new GraftError8({
+    throw new GraftError10({
       code: "NEEDS_DATABASE",
       message: `${feature} needs the Postgres index; this project serves a static index (${staticIndexPath}).`,
       fix: `${insteadDo} To move this project to the Postgres tier: set DATABASE_URL, change graft.config to \`export const index = "postgres"\`, run \`graft db migrate\`, then \`graft compile\`.`,
@@ -1233,7 +2098,7 @@ function createGraftMcp(options) {
     const actor = options.connectionActor;
     if (actor === void 0) {
       if (options.actor === void 0) return;
-      throw new GraftError8({
+      throw new GraftError10({
         code: "CONFIG_INVALID",
         message: `${tool} cannot be authorized: this server has an actor resolver but was given no connectionActor.`,
         fix: "Pass `connectionActor` alongside `actor` when building the server \u2014 createGraftMcpHandler does this for you from the bearer it verified. Without it every scope check passes and write tools are ungated.",
@@ -1242,7 +2107,7 @@ function createGraftMcp(options) {
     }
     if (actor.kind === "anonymous") return;
     if ((actor.scopes ?? []).includes(scope)) return;
-    throw new GraftError8({
+    throw new GraftError10({
       code: "UNAUTHORIZED",
       message: `${tool} requires the "${scope}" scope, and this credential does not carry it.`,
       fix: `Mint a token whose scope claim includes "${scope}" (for \`graft serve\`, add it to GRAFT_DEV_SCOPES). Content authoring, asset upload and approval decisions are deliberately separate from ordinary read scopes.`,
@@ -1252,7 +2117,7 @@ function createGraftMcp(options) {
   const requireDecider = () => {
     const actor = options.connectionActor;
     if (actor === void 0 || actor.kind === "anonymous" || !actor.id) {
-      throw new GraftError8({
+      throw new GraftError10({
         code: "UNAUTHORIZED",
         message: "decide_approval needs to know who is deciding, and this connection is not authenticated as anyone.",
         fix: "Connect with `Authorization: Bearer <token>` from a trusted issuer (or set GRAFT_DEV_TOKEN for `graft mcp`). Deciding anonymously would make the requester-cannot-decide check meaningless, so it is refused rather than attributed to a placeholder.",
@@ -1328,7 +2193,7 @@ function createGraftMcp(options) {
     handler: async ({ input }) => {
       const collection = requireCollection(collections, input.collection);
       const doc = findDoc(contentDir, input.collection, collection, input.slug);
-      unlinkSync(join3(contentDir, ...doc.sourcePath.split("/")));
+      unlinkSync(resolveContained4(contentDir, doc.sourcePath, { label: "document path" }));
       const result = await projectContent();
       return {
         deleted: doc.sourcePath,
@@ -1367,7 +2232,7 @@ function createGraftMcp(options) {
       try {
         return createStorage(storageConfigFromEnv());
       } catch (error) {
-        throw new GraftError8({
+        throw new GraftError10({
           code: "ENV_VAR_MISSING",
           message: error instanceof Error ? error.message : String(error),
           fix: "Set S3_ENDPOINT, S3_ACCESS_KEY, S3_SECRET_KEY, and S3_BUCKET in the MCP server's environment (.env), then retry.",
@@ -1397,21 +2262,53 @@ function createGraftMcp(options) {
     functionsByName,
     getFunctionsHandler,
     getDeleteHandler,
-    getStorage
+    getStorage,
+    // Absent unless the mount opted in. The default stays the out-of-band
+    // flow, which is the one a remote agent with no human attached must get.
+    elicitApproval: options.approvalElicitation ? createApprovalElicitor({
+      server,
+      db: () => requireDb(
+        "approval elicitation",
+        "Approvals gate destructive operations on operational data, which a static project does not have."
+      ),
+      decider: options.approvalElicitation.decider
+    }) : void 0
   };
-  registerIntrospectionTools(server, deps);
+  register(server, deps);
+  return server;
+}
+var FULL_SURFACE = (server, deps) => {
+  registerCollectionIntrospection(server, deps);
+  registerFunctionIntrospection(server, deps);
   registerFunctionTools(server, deps);
   registerRegistryTools(server, deps);
-  registerContentTools(server, deps);
+  registerContentReadTools(server, deps);
+  registerContentWriteTools(server, deps);
   registerAssetTools(server, deps);
   registerBranchTools(server, deps);
   registerApprovalTools(server, deps);
   registerErrorTools(server, deps);
-  return server;
+  registerPackageTools(server, deps);
+  registerDocumentResources(server, deps);
+  registerSchemaResource(server, deps);
+  registerContentPrompts(server, deps);
+};
+var DOCS_SURFACE = (server, deps) => {
+  registerCollectionIntrospection(server, deps);
+  registerContentReadTools(server, deps);
+  registerErrorTools(server, deps);
+  registerPackageTools(server, deps);
+  registerDocumentResources(server, deps);
+};
+function createGraftMcp(options) {
+  return buildServer(options, FULL_SURFACE);
+}
+function createDocsMcp(options) {
+  return buildServer({ ...options, functions: void 0 }, DOCS_SURFACE);
 }
 
 // src/http.ts
-import { GraftError as GraftError9 } from "@usegraft/contracts";
+import { GraftError as GraftError11 } from "@usegraft/contracts";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 function jsonRpcError(status, code, message, headers) {
   return Response.json({ jsonrpc: "2.0", error: { code, message }, id: null }, { status, headers });
@@ -1419,12 +2316,19 @@ function jsonRpcError(status, code, message, headers) {
 function createGraftMcpHandler(options) {
   const { actor: resolveActor, allowAnonymous, ...serverOptions } = options;
   if (resolveActor === void 0 && allowAnonymous !== true) {
-    throw new GraftError9({
+    throw new GraftError11({
       code: "CONFIG_INVALID",
       message: "createGraftMcpHandler was given no way to authenticate callers, and this endpoint serves content writes, asset uploads and approval decisions.",
       fix: "Pass `actor` \u2014 the @usegraft/auth `createActorResolver` seam, the same one the functions route uses. For a local dev server with no auth at all, pass `allowAnonymous: true` explicitly; never do that on anything reachable from a network."
     });
   }
+  if (serverOptions.approvalElicitation !== void 0) {
+    throw new GraftError11({
+      code: "CONFIG_INVALID",
+      message: "createGraftMcpHandler cannot use `approvalElicitation`: over HTTP the client being asked to approve is the agent that made the call.",
+      fix: "Drop `approvalElicitation` from this handler. Approvals over HTTP go through the out-of-band path \u2014 the call returns DESTRUCTIVE_OP_REQUIRES_APPROVAL with an id, a human runs `graft approve <id>`, and the caller retries with it. Elicitation is for a stdio server (`createGraftMcp` / `graft mcp --elicit-approvals`) whose operator is at the machine."
+    });
+  }
   return async (request) => {
     if (request.method !== "POST") {
       return jsonRpcError(405, -32e3, "Method not allowed: this server is stateless (POST only)", {
@@ -1436,7 +2340,7 @@ function createGraftMcpHandler(options) {
       try {
         actor = await resolveActor(request);
       } catch (err) {
-        const message = err instanceof GraftError9 ? `${err.message} ${err.fix ?? ""}`.trim() : "Unauthorized";
+        const message = err instanceof GraftError11 ? `${err.message} ${err.fix ?? ""}`.trim() : "Unauthorized";
         return jsonRpcError(401, -32001, message);
       }
       if (allowAnonymous !== true && actor.kind === "anonymous") {
@@ -1468,6 +2372,26 @@ function createGraftMcpHandler(options) {
     }
   };
 }
+function createDocsMcpHandler(options) {
+  return async (request) => {
+    if (request.method !== "POST") {
+      return jsonRpcError(405, -32e3, "Method not allowed: this server is stateless (POST only)", {
+        allow: "POST"
+      });
+    }
+    const server = createDocsMcp(options);
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: void 0,
+      enableJsonResponse: true
+    });
+    try {
+      await server.connect(transport);
+      return await transport.handleRequest(request);
+    } finally {
+      void server.close().catch(() => void 0);
+    }
+  };
+}
 
 // src/index.ts
 async function serveStdio(server) {
@@ -1483,6 +2407,8 @@ async function serveStdio(server) {
 }
 export {
   ERROR_KNOWLEDGE,
+  createDocsMcp,
+  createDocsMcpHandler,
   createGraftMcp,
   createGraftMcpHandler,
   explainCode,