paper-mono 0.62.2 → 0.62.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release notes
 
+## 0.62.3 — 2026-08-28
+
+- Added `paper_list_files` so the specialist can resolve open and recently accessed Paper files by name instead of depending on the frontmost document.
+- Added `paper files --limit 200` and explicit `--file <file-id>` targeting across deterministic reads without changing Paper Desktop focus.
+- Updated the runtime workflow to discover named sources first, preserve exact `fileId` across reads, and ask the operator only when returned names are genuinely ambiguous.
+
 ## 0.62.2 — 2026-08-28
 
 - Made fresh-cache `npx --yes paper-mono` startup fast by carrying the Pi runtime in the public artifact and reducing npm's install closure to four small runtime dependencies.

package/DEPENDENCIES.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "paper-mono-dependencies.v1",
-  "package": "paper-mono@0.62.2",
+  "package": "paper-mono@0.62.3",
   "external": [
     {
       "name": "@silvia-odwyer/photon-node",

package/bin/chunks/{chunk-ZIII3ND7.js → chunk-7OKHV2KG.js}

@@ -7620,6 +7620,7 @@ import { dirname as dirname2, isAbsolute as isAbsolute2 } from "node:path";
 var PAPER_MCP_URL = "http://127.0.0.1:29979/mcp";
 var TIMEOUT_MS = 3e4;
 var PAPER_DESKTOP_TOOL_NAMES = {
+  paper_list_files: "list_files",
   paper_get_basic_info: "get_basic_info",
   paper_get_selection: "get_selection",
   paper_get_node_info: "get_node_info",
@@ -8053,6 +8054,8 @@ var PAPER_TREE_DEFAULT_DEPTH = 4;
 var PAPER_TREE_MIN_DEPTH = 1;
 var PAPER_TREE_MAX_DEPTH = 8;
 var PAPER_COMPUTED_STYLES_MAX_NODE_IDS = 50;
+var PAPER_FILES_DEFAULT_LIMIT = 50;
+var PAPER_FILES_MAX_LIMIT = 200;
 function highVolumeReadBudget(retryGuidance) {
   return { ...PAPER_HIGH_VOLUME_RESPONSE_LIMITS, retryGuidance };
 }
@@ -8090,6 +8093,13 @@ function boundedComputedStyleNodeIds(value) {
   }
   return value;
 }
+function boundedFileLimit(value) {
+  if (value === void 0) return PAPER_FILES_DEFAULT_LIMIT;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > PAPER_FILES_MAX_LIMIT) {
+    throw new TypeError(`paper_list_files limit must be an integer from 1 through ${PAPER_FILES_MAX_LIMIT}.`);
+  }
+  return value;
+}
 function providerArgsForTool(def, args) {
   const { _fixture: _ignoredFixture, dryRun: _ignoredDryRun, fileId: rawFileId, ...toolArgs } = args;
   const mappedArgs = def.mapArgs ? def.mapArgs(toolArgs) : toolArgs;
@@ -8849,10 +8859,26 @@ var paperTokenTypeSchema = import_typebox.Type.Union([
 ]);
 var paperMcpTools = [
   // ── Read tools ──────────────────────────────────────────────────────────
+  createPaperTool({
+    name: "paper_list_files",
+    label: "Paper: List Files",
+    description: "List Paper files that are open or recently accessed in the active team, newest first. Use this before asking the operator for a file ID, then pass a matched result's id as fileId to every file-scoped read. This does not change the focused Paper file.",
+    parameters: import_typebox.Type.Object({
+      limit: import_typebox.Type.Optional(
+        import_typebox.Type.Integer({
+          minimum: 1,
+          maximum: PAPER_FILES_MAX_LIMIT,
+          default: PAPER_FILES_DEFAULT_LIMIT,
+          description: `Maximum files to return (default ${PAPER_FILES_DEFAULT_LIMIT}; maximum ${PAPER_FILES_MAX_LIMIT})`
+        })
+      )
+    }),
+    mapArgs: (args) => ({ limit: boundedFileLimit(args.limit) })
+  }),
   createPaperTool({
     name: "paper_get_basic_info",
     label: "Paper: Get Basic Info",
-    description: "Get file name, page name, node count, and list of artboards with dimensions from the currently open Paper file.",
+    description: "Get file name, page name, node count, and artboards from an explicit Paper file, without requiring it to be focused. Omit fileId only when the current MCP target is intentional.",
     parameters: import_typebox.Type.Object({ fileId: optionalFileIdSchema })
   }),
   createPaperTool({

package/bin/chunks/{chunk-ICDPC6EL.js → chunk-DV5A4MYH.js}

@@ -19,6 +19,7 @@ function resolvePaperWorkflowMode(auditOnly, copilot) {
   return "reference-to-code";
 }
 var PAPER_TOOL_SAFETY_CLASSIFICATIONS = Object.freeze({
+  paper_list_files: "read-only",
   paper_get_basic_info: "read-only",
   paper_get_selection: "read-only",
   paper_get_node_info: "read-only",
@@ -61,6 +62,7 @@ var PAPER_MUTATION_TOOL_NAMES = [
   "paper_delete_nodes"
 ];
 var PAPER_TOOL_IDS = Object.freeze([
+  "paper_list_files",
   "paper_get_basic_info",
   "paper_get_selection",
   "paper_get_node_info",
@@ -107,12 +109,13 @@ Arguments:
   -- messages...                     Treat following option-shaped text as specialist prompt input
 
 Commands:
-  ${APP_NAME} show|info [--json]      Show the open Paper document
-  ${APP_NAME} selection [--json]      Show the current Paper selection
-  ${APP_NAME} tree [--json]           Show the open document tree
-  ${APP_NAME} node <id> [options]      Inspect node info, children, or JSX
-  ${APP_NAME} screenshot --out <file> Save a node or single-selection screenshot
-  ${APP_NAME} doctor [--json]          Check all 27 Paper tools and reachability
+  ${APP_NAME} files [--limit <1-200>] [--json]       List open and recent Paper files
+  ${APP_NAME} show|info [--file <id>] [--json]       Show an explicit or current Paper document
+  ${APP_NAME} selection [--file <id>] [--json]       Show a Paper file's current selection
+  ${APP_NAME} tree [--file <id>] [--json]            Show a Paper document tree
+  ${APP_NAME} node <id> [--file <id>] [options]      Inspect node info, children, or JSX
+  ${APP_NAME} screenshot --out <file> [--file <id>]  Save a node or single-selection screenshot
+  ${APP_NAME} doctor [--json]                         Check all 28 Paper tools and reachability
 
 Options:
   --about-json                       Print identity, privacy, lock, workflow, and provenance receipts

package/bin/chunks/{doctor-TOH2BSQ6.js → doctor-MUUZ6CJM.js}

@@ -8,7 +8,7 @@ import {
   resolveMonoAgentHome,
   resolveMonoContractRef,
   resolvePaperAgentHome
-} from "./chunk-ZIII3ND7.js";
+} from "./chunk-7OKHV2KG.js";
 import {
   PACKAGE_DISTRIBUTION,
   VERSION,

package/bin/chunks/{main-HS6FSCUI.js → main-3L2ZQP4E.js}

@@ -34,7 +34,7 @@ import {
   PAPER_TOOL_SAFETY_CLASSIFICATIONS,
   printHelp,
   resolvePaperWorkflowMode
-} from "./chunk-ICDPC6EL.js";
+} from "./chunk-DV5A4MYH.js";
 import {
   invalidPaperArgument,
   safeArgumentForDiagnostic
@@ -44,7 +44,7 @@ import {
   paperTools,
   renderPaperToolInventoryXml,
   resolvePaperAgentHome
-} from "./chunk-ZIII3ND7.js";
+} from "./chunk-7OKHV2KG.js";
 import {
   APP_NAME,
   CONFIG_DIR_NAME,
@@ -187574,7 +187574,7 @@ Eleven package-owned mutating Paper operations are exposed behind the runtime ap
 - paper_revise_artboard replaces only one artboard's children and screenshots the result
 - paper_delete_nodes deletes only listed IDs and descendants after naming them, then verifies they are absent
 
-Pass fileId on every Paper tool call, including reads. Read schemas keep fileId optional for provider compatibility, but omitting it follows that MCP session's most recently opened file and is unsafe when several files or agents are active. Every receipted mutation requires fileId and refuses to infer the frontmost file; its internal preflight, write, and verification calls preserve that same ID.
+Use paper_list_files whenever the user names a file that is not already identified, requests comparisons across files, or refers to another Paper file. It lists open and recently accessed files without changing focus; use the matched result's id as fileId. Pass fileId on every file-scoped Paper tool call, including reads; paper_list_files is the global discovery exception. Read schemas keep fileId optional for provider compatibility, but omitting it follows that MCP session's most recently opened file and is unsafe when several files or agents are active. Every receipted mutation requires fileId and refuses to infer the frontmost file; its internal preflight, write, and verification calls preserve that same ID.
 
 Page creation and switching require explicit file IDs plus an explicit page name or page ID; never infer a page target, merge creation with opening, or treat a successful create receipt as proof that the page is active. Direct page-control CLI commands are disabled: invoke these tools only after the exact page operation appears in an approved brief. Paper Desktop has no delete_page, rename_page, or reorder_pages calls, so page cleanup/order remains an upstream limit. For dry-run-capable artboard/node/token mutations, always run with dryRun=true first and require confirm=true for the live call. Existing source targets additionally require the exact action-specific sourceAcknowledgement described by the tool schema. Session provenance is process- and file-local, so a restarted runtime or explicit file switch treats all existing nodes as source work.
 
@@ -187605,15 +187605,16 @@ Note: start_working_on_nodes does NOT exist \u2014 do not call it.
 ${guidelinesSection}## Workflows
 
 Snapshot/reference \u2192 Code:
-1. resolve the exact fileId, call paper_get_basic_info to confirm file identity and artboard IDs, and pass that fileId to every following Paper call
-2. use paper_get_selection when the operator points at a selection; otherwise begin with a bounded tree summary or targeted node search (tree depth defaults to 4 and must remain 1 through 8)
-3. call paper_get_screenshot on one exact artboard or node and start with scale 1
-4. call paper_get_jsx for that subtree and paper_get_computed_styles for only the nodes needed for the current decision (maximum 50 IDs)
-5. summarize the reference's structure, hierarchy, spacing, typography, color, and interaction implications before reading the next subtree
-6. emit one valid paper-implementation-brief.v1 block bound to the exact Paper file/page/artboard/nodes, typed move destinations (or an empty array), any exact page-create/open arguments, destination cwd and paths, permitted commands, acceptance criteria, and verification plan; do not mutate yet
-7. wait for the user's exact standalone APPROVE PAPER BRIEF <brief-id> phrase; ordinary agreement, prior approval, or the selected node is not authorization
-8. implement only the approved brief by adapting those findings through the destination product's design system; do not copy the reference's brand or CSS wholesale
-9. run independent product VQA in the destination's real route, viewport, auth state, and interaction loop; a Paper screenshot proves the reference, not the shipped product
+1. if the requested source file is not already identified, call paper_list_files and resolve it by exact name; ask the operator only when multiple returned files remain ambiguous
+2. call paper_get_basic_info with that exact fileId to confirm file identity and artboard IDs, and pass the same fileId to every following file-scoped Paper call; explicit reads do not require the file to be focused
+3. use paper_get_selection when the operator points at a selection; otherwise begin with a bounded tree summary or targeted node search (tree depth defaults to 4 and must remain 1 through 8)
+4. call paper_get_screenshot on one exact artboard or node and start with scale 1
+5. call paper_get_jsx for that subtree and paper_get_computed_styles for only the nodes needed for the current decision (maximum 50 IDs)
+6. summarize the reference's structure, hierarchy, spacing, typography, color, and interaction implications before reading the next subtree
+7. emit one valid paper-implementation-brief.v1 block bound to the exact Paper file/page/artboard/nodes, typed move destinations (or an empty array), any exact page-create/open arguments, destination cwd and paths, permitted commands, acceptance criteria, and verification plan; do not mutate yet
+8. wait for the user's exact standalone APPROVE PAPER BRIEF <brief-id> phrase; ordinary agreement, prior approval, or the selected node is not authorization
+9. implement only the approved brief by adapting those findings through the destination product's design system; do not copy the reference's brand or CSS wholesale
+10. run independent product VQA in the destination's real route, viewport, auth state, and interaction loop; a Paper screenshot proves the reference, not the shipped product
 
 Code \u2192 Design / imported reference \u2192 Design:
 1. read the codebase, or confirm that the operator has already imported the web reference through the external Paper Snapshot extension

package/bin/chunks/{owner-commands-VZECUCWE.js → owner-commands-XXVPK5WS.js}

@@ -14,6 +14,7 @@ var PAPER_NODE_PLACEHOLDER = "replace-with-node-id";
 var PAPER_NO_SCREENSHOT_SELECTION = "No Paper node is selected. Select exactly one node in Paper or pass --node <node-id>.";
 var PAPER_AMBIGUOUS_SCREENSHOT_SELECTION = "Multiple Paper nodes are selected. Select exactly one node in Paper or pass --node <node-id>.";
 var OWNER_DESKTOP_TOOL_NAMES = Object.freeze({
+  paper_list_files: "list_files",
   paper_get_basic_info: "get_basic_info",
   paper_get_selection: "get_selection",
   paper_get_node_info: "get_node_info",
@@ -25,14 +26,15 @@ var OWNER_DESKTOP_TOOL_NAMES = Object.freeze({
 var SUPPORTED_IMAGE_MIME_TYPES = /* @__PURE__ */ new Set(["image/png", "image/jpeg", "image/webp"]);
 var STRICT_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
 var ownerRequestId = 1;
-var READ_COMMANDS = /* @__PURE__ */ new Set(["show", "info", "selection", "tree", "node", "screenshot"]);
+var READ_COMMANDS = /* @__PURE__ */ new Set(["files", "show", "info", "selection", "tree", "node", "screenshot"]);
 var READ_COMMAND_HELP = {
-  show: "Usage: paper show [--json]\nShow basic information about the open Paper document.\n",
-  info: "Usage: paper info [--json]\nAlias for `paper show`.\n",
-  selection: "Usage: paper selection [--json]\nShow the current Paper selection.\n",
-  tree: "Usage: paper tree [--json]\nShow a bounded summary of the open document tree.\n",
-  node: "Usage: paper node <nodeId> [--children | --jsx] [--json]\nInspect one Paper node.\n",
-  screenshot: "Usage: paper screenshot --out <file> [--node <nodeId>] [--json]\nSave a node or single-selection screenshot using Paper's returned image format.\n"
+  files: "Usage: paper files [--limit <1-200>] [--json]\nList open and recently accessed Paper files.\n",
+  show: "Usage: paper show [--file <file-id>] [--json]\nShow basic information about an explicit or current Paper document.\n",
+  info: "Usage: paper info [--file <file-id>] [--json]\nAlias for `paper show`.\n",
+  selection: "Usage: paper selection [--file <file-id>] [--json]\nShow a Paper file's current selection.\n",
+  tree: "Usage: paper tree [--file <file-id>] [--json]\nShow a bounded summary of a Paper document tree.\n",
+  node: "Usage: paper node <nodeId> [--file <file-id>] [--children | --jsx] [--json]\nInspect one Paper node.\n",
+  screenshot: "Usage: paper screenshot --out <file> [--file <file-id>] [--node <nodeId>] [--json]\nSave a node or single-selection screenshot using Paper's returned image format.\n"
 };
 function providerError(result) {
   if (!result || typeof result !== "object" || Array.isArray(result)) return void 0;
@@ -173,6 +175,14 @@ function paperText(result) {
   const text = paperContentParts(result).filter((part) => part.type === "text").map((part) => part.text).join("\n");
   return text || JSON.stringify(result, null, 2);
 }
+function paperJson(result) {
+  const text = paperText(result);
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { result };
+  }
+}
 function selectedNodeIds(result) {
   let selection;
   try {
@@ -213,6 +223,47 @@ function assertNoArguments(command, args) {
     invalidPaperArgument(`${command} does not accept '${safeArgumentForDiagnostic(args[0] ?? "")}'.`);
   }
 }
+function parseFilesArgs(args) {
+  let limit = 50;
+  let seenLimit = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    const [flag, inlineValue] = arg.includes("=") ? arg.split(/=(.*)/s, 2) : [arg, void 0];
+    if (flag !== "--limit") {
+      invalidPaperArgument(`files does not accept '${safeArgumentForDiagnostic(arg)}'.`);
+    }
+    if (seenLimit) throw new TypeError("--limit may be provided only once.");
+    const value = inlineValue ?? args[index + 1];
+    if (inlineValue === void 0) index += 1;
+    if (!value || value.startsWith("--")) throw new TypeError("--limit requires a value.");
+    limit = Number(value);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200) {
+      throw new TypeError("--limit must be an integer from 1 through 200.");
+    }
+    seenLimit = true;
+  }
+  return { limit };
+}
+function stripFileFlag(args) {
+  let fileId;
+  const remaining = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    const [flag, inlineValue] = arg.includes("=") ? arg.split(/=(.*)/s, 2) : [arg, void 0];
+    if (flag !== "--file") {
+      remaining.push(arg);
+      continue;
+    }
+    if (fileId) throw new TypeError("--file may be provided only once.");
+    const value = inlineValue ?? args[index + 1];
+    if (inlineValue === void 0) index += 1;
+    if (!value || value.startsWith("--")) throw new TypeError("--file requires a Paper file ID or URL.");
+    fileId = value;
+  }
+  return { args: remaining, ...fileId ? { fileId } : {} };
+}
 function parseNodeArgs(args) {
   let nodeId;
   let children = false;
@@ -308,7 +359,7 @@ async function requirePaperResult(callTool, toolName, args) {
   return response.result;
 }
 function writeReadResult(result, json, writeOutput) {
-  writeOutput(json ? `${JSON.stringify({ result }, null, 2)}
+  writeOutput(json ? `${JSON.stringify(paperJson(result), null, 2)}
 ` : `${paperText(result)}
 `);
 }
@@ -327,19 +378,26 @@ async function handleOwnerReadCommand(argv, io = {}) {
     return true;
   }
   const parsed = stripJsonFlag(argv.slice(1));
+  if (command === "files") {
+    const files = parseFilesArgs(parsed.args);
+    writeReadResult(await requirePaperResult(callTool, "paper_list_files", files), parsed.json, writeOutput);
+    return true;
+  }
+  const scoped = stripFileFlag(parsed.args);
+  const fileArgs = scoped.fileId ? { fileId: scoped.fileId } : {};
   if (command === "show" || command === "info") {
-    assertNoArguments(command, parsed.args);
-    writeReadResult(await requirePaperResult(callTool, "paper_get_basic_info", {}), parsed.json, writeOutput);
+    assertNoArguments(command, scoped.args);
+    writeReadResult(await requirePaperResult(callTool, "paper_get_basic_info", fileArgs), parsed.json, writeOutput);
     return true;
   }
   if (command === "selection") {
-    assertNoArguments(command, parsed.args);
-    writeReadResult(await requirePaperResult(callTool, "paper_get_selection", {}), parsed.json, writeOutput);
+    assertNoArguments(command, scoped.args);
+    writeReadResult(await requirePaperResult(callTool, "paper_get_selection", fileArgs), parsed.json, writeOutput);
     return true;
   }
   if (command === "tree") {
-    assertNoArguments(command, parsed.args);
-    const basicInfo = await requirePaperResult(callTool, "paper_get_basic_info", {});
+    assertNoArguments(command, scoped.args);
+    const basicInfo = await requirePaperResult(callTool, "paper_get_basic_info", fileArgs);
     let rootNodeId;
     try {
       rootNodeId = JSON.parse(paperText(basicInfo)).rootNodeId;
@@ -349,26 +407,26 @@ async function handleOwnerReadCommand(argv, io = {}) {
     if (typeof rootNodeId !== "string" || !rootNodeId.trim()) {
       throw new TypeError("Paper get_basic_info returned no rootNodeId for the tree summary.");
     }
-    const result2 = await requirePaperResult(callTool, "paper_get_tree_summary", { nodeId: rootNodeId });
+    const result2 = await requirePaperResult(callTool, "paper_get_tree_summary", { ...fileArgs, nodeId: rootNodeId });
     writeReadResult(result2, parsed.json, writeOutput);
     return true;
   }
   if (command === "node") {
-    const node = parseNodeArgs(parsed.args);
-    const result2 = await requirePaperResult(callTool, node.toolName, { nodeId: node.nodeId });
+    const node = parseNodeArgs(scoped.args);
+    const result2 = await requirePaperResult(callTool, node.toolName, { ...fileArgs, nodeId: node.nodeId });
     writeReadResult(result2, parsed.json, writeOutput);
     return true;
   }
-  const screenshot = parseScreenshotArgs(parsed.args);
+  const screenshot = parseScreenshotArgs(scoped.args);
   let screenshotNodeId = screenshot.nodeId;
   if (!screenshotNodeId) {
-    const selection = await requirePaperResult(callTool, "paper_get_selection", {});
+    const selection = await requirePaperResult(callTool, "paper_get_selection", fileArgs);
     const nodeIds = selectedNodeIds(selection);
     if (nodeIds.length === 0) throw new TypeError(PAPER_NO_SCREENSHOT_SELECTION);
     if (nodeIds.length !== 1) throw new TypeError(PAPER_AMBIGUOUS_SCREENSHOT_SELECTION);
     screenshotNodeId = nodeIds[0];
   }
-  const result = await requirePaperResult(callTool, "paper_get_screenshot", { nodeId: screenshotNodeId });
+  const result = await requirePaperResult(callTool, "paper_get_screenshot", { ...fileArgs, nodeId: screenshotNodeId });
   const images = paperContentParts(result).filter(
     (part) => part.type === "image"
   );

package/bin/chunks/{tool-contract-5H55QIEJ.js → tool-contract-A7BQH6PV.js}

@@ -13,7 +13,7 @@ import {
   renderPaperToolInventoryXml,
   resolvePaperAgentHome,
   resolvePaperContractRef
-} from "./chunk-ZIII3ND7.js";
+} from "./chunk-7OKHV2KG.js";
 import "./chunk-U4I455JM.js";
 import "./chunk-QPVBM6BW.js";
 export {

package/bin/paper.js

@@ -8,7 +8,7 @@ import {
   STANDARD_TOOL_IDS,
   printHelp,
   resolvePaperWorkflowMode
-} from "./chunks/chunk-ICDPC6EL.js";
+} from "./chunks/chunk-DV5A4MYH.js";
 import {
   invalidPaperArgument,
   safeArgumentForDiagnostic
@@ -29,7 +29,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 var STANDARD_LOCKED_TOOL_IDS = /* @__PURE__ */ new Set(["read", "grep", "find", "ls"]);
-var OWNER_READ_COMMANDS = /* @__PURE__ */ new Set(["show", "info", "selection", "tree", "node", "screenshot"]);
+var OWNER_READ_COMMANDS = /* @__PURE__ */ new Set(["files", "show", "info", "selection", "tree", "node", "screenshot"]);
 function resolveModulePath(specifier) {
   return fileURLToPath(import.meta.resolve(specifier));
 }
@@ -71,7 +71,7 @@ async function createAboutJson(options = {}) {
     PAPER_TOOL_SCHEMA_HASHES,
     paperToolContract,
     resolvePaperAgentHome
-  } = await import("./chunks/tool-contract-5H55QIEJ.js");
+  } = await import("./chunks/tool-contract-A7BQH6PV.js");
   const packageLoadErrors = [];
   const paperEntry = fileURLToPath(import.meta.url);
   const monoForkRuntime = resolveReportedModule("@creative-int/mono/fork-runtime", paperEntry, packageLoadErrors);
@@ -170,7 +170,7 @@ function specialistAboutOptions(args) {
 }
 function printDoctorHelp() {
   process.stdout.write(
-    "Usage: paper doctor [--json]\nCheck the 27-tool contract and live Paper Desktop reachability.\n"
+    "Usage: paper doctor [--json]\nCheck the 28-tool contract and live Paper Desktop reachability.\n"
   );
 }
 function assertOnly(args, accepted, command) {
@@ -187,7 +187,7 @@ async function runSpecialist(args) {
   const [undiciModule, { registerBunOAuthFlows }, { main: runSpecialistMain }] = await Promise.all([
     import("./chunks/undici-EMZDFWT4.js"),
     import("./chunks/bun-oauth-JJSCAKFO.js"),
-    import("./chunks/main-HS6FSCUI.js")
+    import("./chunks/main-3L2ZQP4E.js")
   ]);
   const undiciRuntime = typeof undiciModule.EnvHttpProxyAgent === "function" ? undiciModule : undiciModule.default;
   const { EnvHttpProxyAgent, setGlobalDispatcher } = undiciRuntime;
@@ -229,7 +229,7 @@ async function main(args) {
       const rejected = normalizedArgs[1] ?? normalizedArgs[2] ?? "extra arguments";
       invalidPaperArgument(`doctor does not accept '${safeArgumentForDiagnostic(rejected)}'.`);
     }
-    const { createPaperToolDoctorReport, paperDoctorExitCode, renderPaperToolDoctorReport } = await import("./chunks/doctor-TOH2BSQ6.js");
+    const { createPaperToolDoctorReport, paperDoctorExitCode, renderPaperToolDoctorReport } = await import("./chunks/doctor-MUUZ6CJM.js");
     const report = await createPaperToolDoctorReport();
     process.stdout.write(
       normalizedArgs[1] === "--json" ? `${JSON.stringify(report, null, 2)}
@@ -239,7 +239,7 @@ async function main(args) {
     return;
   }
   if (!isCompatibilityMonoRoute && OWNER_READ_COMMANDS.has(normalizedArgs[0] ?? "")) {
-    const { handleOwnerReadCommand } = await import("./chunks/owner-commands-VZECUCWE.js");
+    const { handleOwnerReadCommand } = await import("./chunks/owner-commands-XXVPK5WS.js");
     if (await handleOwnerReadCommand(normalizedArgs)) return;
   }
   if (normalizedArgs[0] === "page") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paper-mono",
-  "version": "0.62.2",
+  "version": "0.62.3",
   "description": "Local-first Paper Desktop design-to-code specialist for agents and humans",
   "type": "module",
   "license": "MIT",

package/tool-walk/fixtures.json

@@ -1,6 +1,28 @@
 {
   "schemaVersion": "paper-tool-walk-fixtures.v1",
   "cases": [
+    {
+      "id": "paper-list-files",
+      "tool": "paper_list_files",
+      "mode": "fixture",
+      "safety": "read",
+      "input": {
+        "limit": 50,
+        "_fixture": {
+          "content": [
+            {
+              "type": "text",
+              "text": "{\"files\":[{\"id\":\"file-poke\",\"name\":\"poke\",\"updatedAt\":1787639688831},{\"id\":\"file-paper\",\"name\":\"paper\",\"updatedAt\":1787961946457}]}"
+            }
+          ]
+        }
+      },
+      "expect": {
+        "status": ["pass"],
+        "summaryIncludes": "file-poke",
+        "maxBytes": 49152
+      }
+    },
     {
       "id": "paper-get-basic-info",
       "tool": "paper_get_basic_info",

package/tool-walk/mono-safety-card.json

@@ -1,20 +1,48 @@
 {
   "schemaVersion": "mono-safety-card.v1",
-  "cardId": "paper:sha256:b53fab419474899ca25a0b84546025fbe758920be3dcddc5dd1e6fd97bf242b8",
+  "cardId": "paper:sha256:17c5b377d51ae3cbe81c2691a67e42da2b57c2b741c1eec6063239c857bf3724",
   "specialist": "paper",
-  "contractHash": "sha256:b53fab419474899ca25a0b84546025fbe758920be3dcddc5dd1e6fd97bf242b8",
+  "contractHash": "sha256:17c5b377d51ae3cbe81c2691a67e42da2b57c2b741c1eec6063239c857bf3724",
   "status": "pass",
   "conjunctive": true,
-  "verifiedAt": "2026-08-28T22:55:46.054Z",
+  "verifiedAt": "2026-08-29T01:48:42.859Z",
   "verificationSource": "pnpm -C packages/mono safety:verify (L1 engine over executable tool-walk fixtures)",
   "summary": {
-    "tools": 27,
-    "passed": 27,
+    "tools": 28,
+    "passed": 28,
     "failed": 0,
-    "cases": 35,
+    "cases": 36,
     "autoFails": 0
   },
   "tools": [
+    {
+      "tool": "paper_list_files",
+      "status": "pass",
+      "declaredModes": [
+        "mock"
+      ],
+      "coveredModes": [
+        "mock"
+      ],
+      "cases": [
+        {
+          "id": "paper_list_files-mock-safety",
+          "tool": "paper_list_files",
+          "mode": "mock",
+          "status": "pass",
+          "outputBytes": 259,
+          "outputLines": 9,
+          "effects": {
+            "networkAttempts": [],
+            "providerCalls": [],
+            "filesystemWrites": [],
+            "externalMutations": [],
+            "confirmation": "not-applicable"
+          },
+          "violations": []
+        }
+      ]
+    },
     {
       "tool": "paper_get_basic_info",
       "status": "pass",

package/tool-walk/safety-fixtures.json

@@ -2,6 +2,15 @@
   "schemaVersion": "mono-safety-fixtures.v1",
   "specialist": "paper",
   "cases": [
+    {
+      "id": "paper_list_files-mock-safety",
+      "tool": "paper_list_files",
+      "mode": "mock",
+      "input": {
+        "sourceFixtureRef": "./tool-walk/fixtures.json#paper-list-files",
+        "execution": "recorded-tool-walk"
+      }
+    },
     {
       "id": "paper_get_basic_info-mock-safety",
       "tool": "paper_get_basic_info",

package/tools.contract.json

@@ -6,6 +6,7 @@
   "domain": {
     "comment": "REQ: Paper Desktop design-to-code agent CLI powered by the Paper MCP bridge at http://127.0.0.1:29979/mcp.",
     "toolIds": [
+      "paper_list_files",
       "paper_get_basic_info",
       "paper_get_selection",
       "paper_get_node_info",
@@ -36,11 +37,71 @@
     ]
   },
   "tools": [
+    {
+      "id": "paper_list_files",
+      "version": 1,
+      "label": "Paper: List Files",
+      "description": "List Paper files that are open or recently accessed in the active team, newest first. Use this before asking the operator for a file ID, then pass a matched result's id as fileId to every file-scoped read. This does not change the focused Paper file.",
+      "handlerRef": "./src/core/tools/paper-mcp.ts#paperTools",
+      "sourcePack": null,
+      "demandRefs": [
+        "mono-fleet-era:paper-tool-contract",
+        "audit:paper-cross-file-reads"
+      ],
+      "safety": "read",
+      "requires": {
+        "allOf": [
+          "Paper Desktop running at http://127.0.0.1:29979/mcp"
+        ],
+        "anyOf": [],
+        "cli": [
+          "paper"
+        ],
+        "endpoint": [],
+        "optional": false
+      },
+      "inputSchemaRef": "./src/core/tools/paper-mcp.ts",
+      "output": {
+        "envelope": "mono-tool-result.v1",
+        "maxBytes": 49152,
+        "maxItems": 200
+      },
+      "doctorProbe": "endpoint",
+      "cases": [
+        "./tool-walk/fixtures.json#paper-list-files"
+      ],
+      "cliFallback": "paper files --limit 200 --json",
+      "guidelines": [
+        "Use before asking the operator for a Paper file ID or URL.",
+        "Resolve an exact file name, then pass its id as fileId to every file-scoped read without changing focus."
+      ],
+      "safetyContract": {
+        "modes": [
+          "mock"
+        ],
+        "guarantees": {
+          "mock": {
+            "networkSpend": "forbidden",
+            "filesystemWrites": "none",
+            "filesystemRoots": [],
+            "externalMutations": "forbidden",
+            "requiresConfirmation": false
+          }
+        },
+        "fixtureRefs": [
+          "./tool-walk/safety-fixtures.json#paper_list_files-mock-safety"
+        ],
+        "outputBudget": {
+          "maxBytes": 49152,
+          "maxLines": 1200
+        }
+      }
+    },
     {
       "id": "paper_get_basic_info",
       "version": 1,
       "label": "Paper: Get Basic Info",
-      "description": "Get file name, page name, node count, and list of artboards with dimensions from the currently open Paper file.",
+      "description": "Get file name, page name, node count, and artboards from an explicit Paper file, without requiring it to be focused. Omit fileId only when the current MCP target is intentional.",
       "handlerRef": "./src/core/tools/paper-mcp.ts#paperTools",
       "sourcePack": null,
       "demandRefs": [
@@ -71,7 +132,7 @@
       ],
       "cliFallback": null,
       "guidelines": [
-        "Use as the first read when grounding in the open Paper file.",
+        "Use after paper_list_files to ground an exact file without requiring it to be focused.",
         "If Paper Desktop is not running, fall back to fixtures or ask the operator to open a file."
       ],
       "safetyContract": {