paper-mono 0.62.0 → 0.62.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release notes
 
+## 0.62.1 — 2026-08-28
+
+- Made bare `paper` and `npx paper-mono` the canonical specialist launch paths across help, workflow metadata, clean-room release proof, and public documentation.
+- Kept `paper mono` as a compatibility-only route without exposing it in primary onboarding or help.
+- Let Pi load project instructions, skills, cwd, and generic tool guidance exactly once, while preserving repository-relative provider metadata for Pi-loaded context.
+
 ## 0.62.0 — 2026-08-28
 
 - Added equivalent public `paper` and `paper-mono` binaries with deterministic Paper reads, screenshots, diagnostics, and the guarded specialist.

package/DEPENDENCIES.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "paper-mono-dependencies.v1",
-  "package": "paper-mono@0.62.0",
+  "package": "paper-mono@0.62.1",
   "external": [
     {
       "name": "@earendil-works/pi-agent-core",

package/README.md

@@ -12,11 +12,10 @@ Open a terminal in the destination repository root before starting the specialis
 
 ```bash
 npm install -g paper-mono
-paper doctor
-paper mono
+paper
 ```
 
-On first use, enter `/login` inside `paper mono` and choose a supported model provider. Then tell Paper Mono which reference and destination surface to inspect.
+On first use, enter `/login` inside `paper` and choose a supported model provider. Then tell Paper Mono which reference and destination surface to inspect.
 
 The default workflow is deliberately gated:
 
@@ -40,19 +39,19 @@ It is not a hosted design service, a Paper replacement, a Chrome automation tool
 Reference-to-code is the default. Two explicit alternatives are available:
 
 ```bash
-paper mono --audit-only
-paper mono --copilot
+paper --audit-only
+paper --copilot
 ```
 
 - `--audit-only` is permanently read-only and can never unlock mutation.
 - `--copilot` can propose guarded work inside Paper, but the same brief approval boundary still applies.
 
-`paper mono --list-models` is a model-inventory helper, not a fourth workflow.
+`paper --list-models` is a model-inventory helper, not a fourth workflow.
 
 For a one-command trial without a global install, use:
 
 ```bash
-npx paper-mono mono
+npx paper-mono
 ```
 
 `npx` uses npm-managed cache and Paper Mono may create normal local state under `~/.paper/agent`; it only avoids a global package install. The package exposes equivalent `paper` and `paper-mono` binaries. Documentation uses `paper` as the canonical command.
@@ -75,33 +74,32 @@ paper selection --json
 paper tree --json
 paper node "replace-with-node-id" --json
 paper screenshot --out reference --json
-paper mono --help
 ```
 
-Machine-readable commands emit JSON without decorative stdout. Screenshot exports require an explicit `--node` or exactly one current selection, append the verified image extension when needed, and refuse to overwrite an existing path. Deterministic owner commands reject unknown subcommands, and the specialist rejects unsupported flags, invalid option values, path-like `--session` values, and conflicting session actions with a nonzero exit and an actionable error. Bare positional text on `paper mono` is prompt input. Use `paper mono -- --version` or the same `--` terminator for prompt text that looks like an option. The short `paper` specialist form reserves the owner command words `show`, `info`, `selection`, `tree`, `node`, `screenshot`, `doctor`, `page`, and `help`; use `paper mono` when prompt text could be mistaken for one of them.
+Machine-readable commands emit JSON without decorative stdout. Screenshot exports require an explicit `--node` or exactly one current selection, append the verified image extension when needed, and refuse to overwrite an existing path. Deterministic owner commands reject unknown subcommands, and the specialist rejects unsupported flags, invalid option values, path-like `--session` values, and conflicting session actions with a nonzero exit and an actionable error. Positional text on `paper` is prompt input unless its first word is a reserved owner command: `show`, `info`, `selection`, `tree`, `node`, `screenshot`, `doctor`, `page`, or `help`. Put `--` before option-shaped or reserved-word prompt text; for example, `paper -- --version` or `paper -- info about this layout`.
 
 ## Model authentication
 
-Run `paper mono`, enter `/login`, and choose a provider. You may instead use that provider's documented environment variable. `paper mono --list-models` shows available model IDs; Paper Mono never prints credential values in diagnostics.
+Run `paper`, enter `/login`, and choose a provider. You may instead use that provider's documented environment variable. `paper --list-models` shows available model IDs; Paper Mono never prints credential values in diagnostics.
 
 Credentials, settings, and sessions stay under `~/.paper/agent` by default. Set `PAPER_CODING_AGENT_DIR` before the first run to use another local directory. `--session <id>` accepts a verified session ID only; public v1 rejects path-like values before session activation. Use `--fork <path-or-id>` when you explicitly intend to import a transcript into a new session scoped to the current project. `--session-dir <dir>` overrides session storage and lookup only; it may place transcripts outside the agent home and uses the runtime's explicit-directory lookup instead of Paper Mono's hardened implicit-session verification path. Use only a directory you trust. A resumed session is mutation-locked again until the current brief is reconfirmed.
 
 Resume a previous interactive session with:
 
 ```bash
-paper mono -r
+paper -r
 ```
 
 ## Privacy and network boundaries
 
 Paper document reads travel over the loopback MCP endpoint at `127.0.0.1`. Paper Mono disables the inherited install ping, automatic version polling, provider-attribution telemetry, and executable downloader before startup; it adds no product telemetry or hidden backend and does not silently phone home. The public TUI also disables inherited `/debug`, `/export`, `/import`, and `/share` commands, so a locked session cannot write a raw debug log or export, replace itself from a file, or send a transcript to an external sharing service. Generated provider metadata names the current project as `<repository-root>` and uses repository-relative labels for attached and context files; Paper Mono does not add the absolute local project path to the model request. User-authored prompts, attached file contents, imported instructions, tool results, or approved commands can still contain paths. Prompts, relevant code/reference context, and tool results needed for reasoning are sent to the model provider you select, so that provider's privacy and retention terms apply.
 
-Use `PAPER_OFFLINE=1` or `paper mono --offline` to disable startup network operations. Local deterministic Paper reads remain available, but model work still requires a reachable configured provider unless you use a local one.
+Use `PAPER_OFFLINE=1` or `paper --offline` to disable startup network operations. Local deterministic Paper reads remain available, but model work still requires a reachable configured provider unless you use a local one.
 
 ## Compatibility and current limits
 
 - Node.js 22.19.0 or newer is required.
-- `fd` (or `fdfind`) and `rg` must already be executable on `PATH` before `paper mono` starts. Missing tools fail with install guidance in both default and offline modes; Paper Mono does not acquire them.
+- `fd` (or `fdfind`) and `rg` must already be executable on `PATH` before `paper` starts. Missing tools fail with install guidance in both default and offline modes; Paper Mono does not acquire them.
 - Paper Desktop must be running with a document open for live MCP reads.
 - Clean-room installation and offline CLI behavior are exercised on Apple-silicon macOS with Node.js 22.23.1. That receipt does not claim live Paper Desktop integration on any operating system. The package declares no OS restriction, but Linux and Windows live integration remain unproven.
 - A static Snapshot cannot prove original motion, hidden application state, backend behavior, or inaccessible assets. The brief labels those details as unknown instead of inventing them.
@@ -112,7 +110,7 @@ Use `PAPER_OFFLINE=1` or `paper mono --offline` to disable startup network opera
 
 - **Paper is closed or no file is open:** open Paper Desktop and a document, then rerun `paper doctor --json`. Reinstallation is unnecessary.
 - **MCP is unreachable:** confirm the document is open and that another process is not interfering with `127.0.0.1:29979`, then rerun doctor. Restart Paper only if the local endpoint still does not recover.
-- **Model authentication is missing:** start `paper mono`, enter `/login`, or configure the selected provider's documented environment variable. A missing key should produce guidance, not a stack trace.
+- **Model authentication is missing:** start `paper`, enter `/login`, or configure the selected provider's documented environment variable. A missing key should produce guidance, not a stack trace.
 - **The Snapshot is too large:** select or name one artboard, rerun bounded inspection, use scale 1, and request JSX/styles for a smaller subtree. Paper Mono suppresses over-budget rich parts whole; it never returns partial JSON, JSX, or base64.
 - **The wrong file, page, or artboard is active:** run `paper info --json` and `paper selection --json`, switch to the intended target in Paper, and request a fresh brief. Existing approval does not carry across target drift.
 - **The imported structure is malformed or incomplete:** provide a narrower node or screenshot and let the brief record unsupported details explicitly.

package/bin/chunks/{chunk-I4P43IZS.js → chunk-2LMM23SZ.js}

@@ -1,8 +1,7 @@
 import {
   APP_NAME,
-  OWNER_COMMAND,
   PUBLIC_PROMISE
-} from "./chunk-BGKLQ5Y6.js";
+} from "./chunk-E2KMZMUC.js";
 
 // src/workflow-contract.ts
 var PAPER_IMPLEMENTATION_BRIEF_SCHEMA_VERSION = "paper-implementation-brief.v1";
@@ -93,13 +92,13 @@ var PAPER_TOOL_IDS = Object.freeze([
 // src/owner-help.ts
 var STANDARD_TOOL_IDS = ["read", "bash", "edit", "write", "grep", "find", "ls"];
 function printHelp() {
-  process.stdout.write(`${OWNER_COMMAND} - Paper Desktop design-to-code specialist
+  process.stdout.write(`${APP_NAME} - Paper Desktop design-to-code specialist
 
 ${PUBLIC_PROMISE}
 
 Usage:
-  ${OWNER_COMMAND} [options] [@files...] [messages...]
   ${APP_NAME} [options] [@files...] [messages...]
+  ${APP_NAME} <command> [options]
 
 Arguments:
   @file                              Attach a regular file contained by the current repository
@@ -113,7 +112,6 @@ Commands:
   ${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
-  ${OWNER_COMMAND} [options]           Start the guarded design-to-code specialist
 
 Options:
   --about-json                       Print identity, privacy, lock, workflow, and provenance receipts

package/bin/chunks/{chunk-UHVY2TIH.js → chunk-ADX5NGJT.js}

@@ -1,7 +1,7 @@
 import {
   getAgentDir,
   getPackageDir
-} from "./chunk-BGKLQ5Y6.js";
+} from "./chunk-E2KMZMUC.js";
 
 // src/tool-contract.ts
 import { createHash as createHash2 } from "node:crypto";
@@ -3237,7 +3237,7 @@ function assertPaperContractFixturesExist() {
   assertMonoContractFixturesExist(paperLoadedToolContract);
 }
 function assertPaperContractIdentity(contract) {
-  if (contract.specialist !== "paper" || contract.ownerCommand !== "paper mono" || contract.agentHome !== "~/.paper/agent") {
+  if (contract.specialist !== "paper" || contract.ownerCommand !== "paper" || contract.agentHome !== "~/.paper/agent") {
     throw new Error("Paper tools.contract.json identity does not match the owner runtime.");
   }
 }

package/bin/chunks/{chunk-BGKLQ5Y6.js → chunk-E2KMZMUC.js}

@@ -18,7 +18,6 @@ function getPackageDir() {
 }
 var manifest = JSON.parse(readFileSync(join(getPackageDir(), "package.json"), "utf8"));
 var APP_NAME = manifest.piConfig?.name ?? "paper";
-var OWNER_COMMAND = "paper mono";
 var PUBLIC_PROMISE = "Turn a Paper reference into a sharp implementation brief, get explicit approval, then carry it faithfully into production code.";
 var IDENTITY_DOMAIN = "Paper Desktop design-to-code workflows";
 var CONFIG_DIR_NAME = manifest.piConfig?.configDir ?? ".paper";
@@ -43,7 +42,6 @@ function getAgentDir() {
 export {
   getPackageDir,
   APP_NAME,
-  OWNER_COMMAND,
   PUBLIC_PROMISE,
   IDENTITY_DOMAIN,
   CONFIG_DIR_NAME,

package/bin/chunks/{doctor-7DE4ASQO.js → doctor-67I6GAUY.js}

@@ -7,12 +7,12 @@ import {
   resolveMonoAgentHome,
   resolveMonoContractRef,
   resolvePaperAgentHome
-} from "./chunk-UHVY2TIH.js";
+} from "./chunk-ADX5NGJT.js";
 import {
   PACKAGE_DISTRIBUTION,
   VERSION,
   getPackageDir
-} from "./chunk-BGKLQ5Y6.js";
+} from "./chunk-E2KMZMUC.js";
 import "./chunk-ZX4GFXSY.js";
 
 // src/doctor.ts
@@ -315,7 +315,7 @@ async function createPaperToolDoctorReport(options = {}) {
         };
       }
       if (kind === "cli") {
-        if (name === "paper mono" && reachable.endpointReachable && !reachable.ok) {
+        if (name === paperLoadedToolContract.contract.ownerCommand && reachable.endpointReachable && !reachable.ok) {
           return {
             ok: false,
             detail: `live Paper Desktop tool contract failed: ${reachable.detail}`

package/bin/chunks/{main-NQIGPQXK.js → main-ZALCRUBF.js}

@@ -5,13 +5,13 @@ import {
   PAPER_TOOL_SAFETY_CLASSIFICATIONS,
   printHelp,
   resolvePaperWorkflowMode
-} from "./chunk-I4P43IZS.js";
+} from "./chunk-2LMM23SZ.js";
 import {
   assertPaperToolContractHandshake,
   paperTools,
   renderPaperToolInventoryXml,
   resolvePaperAgentHome
-} from "./chunk-UHVY2TIH.js";
+} from "./chunk-ADX5NGJT.js";
 import {
   APP_NAME,
   CONFIG_DIR_NAME,
@@ -19,7 +19,7 @@ import {
   VERSION,
   applyPaperPrivacyDefaults,
   getAgentDir
-} from "./chunk-BGKLQ5Y6.js";
+} from "./chunk-E2KMZMUC.js";
 import {
   invalidPaperArgument,
   safeArgumentForDiagnostic
@@ -20508,7 +20508,7 @@ var toolDescriptions = {
   find: "Find files by glob pattern (respects .gitignore)",
   ls: "List directory contents"
 };
-function buildSystemPrompt2(options = {}) {
+function composePaperSystemPrompt(options, composition) {
   const {
     customPrompt,
     selectedTools,
@@ -20521,6 +20521,7 @@ function buildSystemPrompt2(options = {}) {
     toolInventoryXml
   } = options;
   const projectRoot = resolve5(cwd ?? process.cwd());
+  const includeHarnessScaffolding = composition === "standalone";
   const now = /* @__PURE__ */ new Date();
   const dateTime = now.toLocaleString("en-US", {
     weekday: "long",
@@ -20542,7 +20543,7 @@ ${appendSystemPrompt}` : "";
     if (appendSection) {
       prompt2 += appendSection;
     }
-    if (contextFiles.length > 0) {
+    if (includeHarnessScaffolding && contextFiles.length > 0) {
       prompt2 += "\n\n# Project Context\n\n";
       prompt2 += "Project-specific instructions and guidelines:\n\n";
       for (const { path: filePath, content } of contextFiles) {
@@ -20553,13 +20554,15 @@ ${content}
 `;
       }
     }
-    const customPromptHasRead = !selectedTools || selectedTools.includes("read");
+    const customPromptHasRead = includeHarnessScaffolding && (!selectedTools || selectedTools.includes("read"));
     if (customPromptHasRead && skills.length > 0) {
       prompt2 += formatPromptSkills(skills);
     }
     prompt2 += `
 Current date and time: ${dateTime}`;
-    prompt2 += "\nCurrent working directory: repository root (use repository-relative paths)";
+    if (includeHarnessScaffolding) {
+      prompt2 += "\nCurrent working directory: repository root (use repository-relative paths)";
+    }
     return prompt2;
   }
   const tools = selectedTools ?? ["read", "bash", "edit", "write"];
@@ -20572,6 +20575,10 @@ Current date and time: ${dateTime}`;
     return description ? `- ${toolName}: ${description}` : void 0;
   }).filter((line) => line !== void 0).join("\n");
   const availableTools = toolsList.length > 0 ? toolsList : "(none)";
+  const availableToolsSection = includeHarnessScaffolding ? `
+
+Available tools:
+${availableTools}` : "";
   const guidelinesList = [];
   const hasBash = tools.includes("bash");
   const hasEdit = tools.includes("edit");
@@ -20608,6 +20615,10 @@ Current date and time: ${dateTime}`;
     guidelinesList.push(...normalizedGuidelines);
   }
   const guidelines = guidelinesList.map((g) => `- ${g}`).join("\n");
+  const guidelinesSection = includeHarnessScaffolding ? `Guidelines:
+${guidelines}
+
+` : "";
   let prompt = `You are Paper, a design-to-code agent that bridges design files with production codebases.
 
 ${PUBLIC_PROMISE}
@@ -20615,9 +20626,7 @@ ${PUBLIC_PROMISE}
 You operate inside the Paper agent harness, which connects to the Paper Desktop app via its MCP server. Paper Desktop is a web-technology-based design tool \u2014 its designs are DOM-based, which means you can read and understand their structure natively.
 
 Your primary job is to translate between design and code: reading designs to inform implementation, building code that matches designs precisely, and writing back to design files when needed.
-
-Available tools:
-${availableTools}
+${availableToolsSection}
 
 ## CRITICAL: Paper operator mutation rules (MUST follow)
 
@@ -20662,10 +20671,7 @@ ${toolInventoryXml}
 ` : ""}
 Note: start_working_on_nodes does NOT exist \u2014 do not call it.
 
-Guidelines:
-${guidelines}
-
-## Workflows
+${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
@@ -20708,7 +20714,7 @@ Paper Desktop documentation:
   if (appendSection) {
     prompt += appendSection;
   }
-  if (contextFiles.length > 0) {
+  if (includeHarnessScaffolding && contextFiles.length > 0) {
     prompt += "\n\n# Project Context\n\n";
     prompt += "Project-specific instructions and guidelines:\n\n";
     for (const { path: filePath, content } of contextFiles) {
@@ -20719,14 +20725,19 @@ ${content}
 `;
     }
   }
-  if (hasRead && skills.length > 0) {
+  if (includeHarnessScaffolding && hasRead && skills.length > 0) {
     prompt += formatPromptSkills(skills);
   }
   prompt += `
 Current date and time: ${dateTime}`;
-  prompt += "\nCurrent working directory: repository root (use repository-relative paths)";
+  if (includeHarnessScaffolding) {
+    prompt += "\nCurrent working directory: repository root (use repository-relative paths)";
+  }
   return prompt;
 }
+function buildPaperRuntimePrompt(options = {}) {
+  return composePaperSystemPrompt(options, "runtime");
+}
 
 // src/runtime.ts
 var paperCliConfig = {
@@ -20819,9 +20830,9 @@ function providerSafePaperSystemPrompt(prompt, projectRoot) {
   }).replace(/<location>([^<]+)<\/location>/g, (element, path6) => {
     const relativeLabel = providerSafeProjectPathLabel(path6, projectRoot);
     return relativeLabel ? `<location>${relativeLabel}</location>` : element;
-  }).replace(/ location="([^"]+)"/g, (attribute, path6) => {
+  }).replace(/ (location|path)="([^"]+)"/g, (attribute, name, path6) => {
     const relativeLabel = providerSafeProjectPathLabel(path6, projectRoot);
-    return relativeLabel ? ` location="${relativeLabel}"` : attribute;
+    return relativeLabel ? ` ${name}="${relativeLabel}"` : attribute;
   });
 }
 function stableJsonValue(value) {
@@ -22800,11 +22811,8 @@ function buildPaperPromptBody(options = {}) {
     "ls",
     ...paperTools.map((tool) => tool.name)
   ];
-  return buildSystemPrompt2({
-    cwd: options.cwd,
+  return buildPaperRuntimePrompt({
     selectedTools: [...selectedTools],
-    contextFiles: options.contextFiles ?? [],
-    skills: options.skills ?? [],
     toolInventoryXml: renderPaperToolInventoryXml()
   });
 }
@@ -23255,7 +23263,7 @@ async function main(args) {
   applyPaperPrivacyDefaults();
   if (args[0] === "page") {
     throw new TypeError(
-      "Direct page control is disabled. Start `paper mono --copilot`, inspect the target, approve its exact brief, and use the gated Paper page tools."
+      "Direct page control is disabled. Start `paper --copilot`, inspect the target, approve its exact brief, and use the gated Paper page tools."
     );
   }
   const firstPass = parseArgs(args);

package/bin/chunks/{tool-contract-ZWFZSYL4.js → tool-contract-YVICOYA2.js}

@@ -12,8 +12,8 @@ import {
   renderPaperToolInventoryXml,
   resolvePaperAgentHome,
   resolvePaperContractRef
-} from "./chunk-UHVY2TIH.js";
-import "./chunk-BGKLQ5Y6.js";
+} from "./chunk-ADX5NGJT.js";
+import "./chunk-E2KMZMUC.js";
 import "./chunk-ZX4GFXSY.js";
 export {
   PAPER_DOMAIN_TOOL_NAMES,

package/bin/paper.js

@@ -7,7 +7,7 @@ import {
   STANDARD_TOOL_IDS,
   printHelp,
   resolvePaperWorkflowMode
-} from "./chunks/chunk-I4P43IZS.js";
+} from "./chunks/chunk-2LMM23SZ.js";
 import {
   APP_NAME,
   BUNDLED_PACKAGE_VERSIONS,
@@ -16,7 +16,7 @@ import {
   VERSION,
   applyPaperPrivacyDefaults,
   getAgentDir
-} from "./chunks/chunk-BGKLQ5Y6.js";
+} from "./chunks/chunk-E2KMZMUC.js";
 import {
   invalidPaperArgument,
   safeArgumentForDiagnostic
@@ -70,7 +70,7 @@ async function createAboutJson(options = {}) {
     PAPER_TOOL_SCHEMA_HASHES,
     paperToolContract,
     resolvePaperAgentHome
-  } = await import("./chunks/tool-contract-ZWFZSYL4.js");
+  } = await import("./chunks/tool-contract-YVICOYA2.js");
   const packageLoadErrors = [];
   const paperEntry = fileURLToPath(import.meta.url);
   const monoForkRuntime = resolveReportedModule("@creative-int/mono/fork-runtime", paperEntry, packageLoadErrors);
@@ -185,15 +185,15 @@ function argumentsBeforeOptionTerminator(args) {
 async function runSpecialist(args) {
   const [{ EnvHttpProxyAgent, setGlobalDispatcher }, { main: runSpecialistMain }] = await Promise.all([
     import("undici"),
-    import("./chunks/main-NQIGPQXK.js")
+    import("./chunks/main-ZALCRUBF.js")
   ]);
   setGlobalDispatcher(new EnvHttpProxyAgent());
   await runSpecialistMain(args);
 }
 async function main(args) {
   applyPaperPrivacyDefaults();
-  const isMonoRoute = args[0] === "mono";
-  const normalizedArgs = isMonoRoute ? args.slice(1) : [...args];
+  const isCompatibilityMonoRoute = args[0] === "mono";
+  const normalizedArgs = isCompatibilityMonoRoute ? args.slice(1) : [...args];
   if (normalizedArgs[0] === "help") normalizedArgs[0] = "--help";
   const optionArgs = argumentsBeforeOptionTerminator(normalizedArgs);
   if (normalizedArgs[0] === "--help" || normalizedArgs[0] === "-h") {
@@ -202,9 +202,7 @@ async function main(args) {
     return;
   }
   if (optionArgs.includes("--about-json")) {
-    let aboutOptions = {};
-    if (isMonoRoute) aboutOptions = specialistAboutOptions(normalizedArgs);
-    else assertOnly(normalizedArgs, ["--about-json"], "--about-json");
+    const aboutOptions = specialistAboutOptions(normalizedArgs);
     process.stdout.write(`${JSON.stringify(await createAboutJson(aboutOptions))}
 `);
     return;
@@ -226,7 +224,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-7DE4ASQO.js");
+    const { createPaperToolDoctorReport, paperDoctorExitCode, renderPaperToolDoctorReport } = await import("./chunks/doctor-67I6GAUY.js");
     const report = await createPaperToolDoctorReport();
     process.stdout.write(
       normalizedArgs[1] === "--json" ? `${JSON.stringify(report, null, 2)}
@@ -235,13 +233,13 @@ async function main(args) {
     process.exitCode = paperDoctorExitCode(report);
     return;
   }
-  if (!isMonoRoute && OWNER_READ_COMMANDS.has(normalizedArgs[0] ?? "")) {
+  if (!isCompatibilityMonoRoute && OWNER_READ_COMMANDS.has(normalizedArgs[0] ?? "")) {
     const { handleOwnerReadCommand } = await import("./chunks/owner-commands-MWXW2KMM.js");
     if (await handleOwnerReadCommand(normalizedArgs)) return;
   }
   if (normalizedArgs[0] === "page") {
     throw new TypeError(
-      "Direct page control is disabled. Start `paper mono --copilot`, inspect the target, approve its exact brief, and use the gated Paper page tools."
+      "Direct page control is disabled. Start `paper --copilot`, inspect the target, approve its exact brief, and use the gated Paper page tools."
     );
   }
   await runSpecialist(normalizedArgs);

package/docs/cli.md

@@ -4,8 +4,8 @@
 
 - Node.js 22.19.0 or newer
 - Paper Desktop with an open document for live reads and Paper workflows
-- A supported model-provider login for `paper mono`
-- User-installed `fd` (or `fdfind`) and `rg` on `PATH` for `paper mono`
+- A supported model-provider login for `paper`
+- User-installed `fd` (or `fdfind`) and `rg` on `PATH` for `paper`
 
 Install the search tools before starting the specialist: `brew install fd ripgrep` on macOS, or `apt install fd-find ripgrep` on Debian or Ubuntu. Missing tools produce the same actionable failure in default and offline modes. Paper Mono never downloads executable dependencies automatically.
 
@@ -52,23 +52,23 @@ paper doctor --json
 
 ## Specialist
 
-`paper mono` starts the interactive design-to-code specialist. It supports persisted sessions, print/text/JSON modes, model selection, and the guarded reference-to-code, audit-only, and Paper-copilot workflows.
+`paper` starts the interactive design-to-code specialist. It supports persisted sessions, print/text/JSON modes, model selection, and the guarded reference-to-code, audit-only, and Paper-copilot workflows.
 
 Run it from the destination repository root. The current working directory is recorded locally as the brief's project boundary, constrains approved edit/write paths, and is where approved commands launch. Generated model-request metadata renders that boundary as `<repository-root>` and labels context files relative to it instead of adding the absolute local project path. `@file` arguments accept only regular files contained by that repository after symlink resolution; attached contents become provider-bound prompt context under a repository-relative label. User-authored prompts, attached contents, imported instructions, tool results, and approved commands can still contain paths. Shell approval is an exact command-string gate, not an operating-system sandbox; review absolute paths, parent traversal, redirection, subprocesses, and package lifecycle scripts before approval.
 
 ```bash
-paper mono --help
-paper mono --audit-only
-paper mono --copilot
-paper mono --continue
-paper mono --resume
-paper mono --list-models
-paper mono --audit-only --about-json
+paper --help
+paper --audit-only
+paper --copilot
+paper --continue
+paper --resume
+paper --list-models
+paper --audit-only --about-json
 ```
 
-`paper mono --about-json` is a non-mutating argument and configuration metadata receipt; it does not initialize a runtime session. Combine it with `--audit-only`, `--copilot`, `--continue`, or `--resume` to inspect the selected workflow, requested session action, default lock contract, privacy defaults, and provenance without opening an interactive session.
+`paper --about-json` is a non-mutating argument and configuration metadata receipt; it does not initialize a runtime session. Combine it with `--audit-only`, `--copilot`, `--continue`, or `--resume` to inspect the selected workflow, requested session action, default lock contract, privacy defaults, and provenance without opening an interactive session.
 
-Bare positional text after `paper mono` is prompt input, not a subcommand. Use `--` when prompt text itself begins with a hyphen: `paper mono -- --version` sends `--version` as prompt text rather than printing package metadata. The shorter `paper [options] [messages...]` form shares the specialist route only when it does not match an owner command. Its reserved owner words are `show`, `info`, `selection`, `tree`, `node`, `screenshot`, `doctor`, `page`, and `help`; use `paper mono` for unambiguous prompt text.
+Positional text after `paper` is prompt input unless its first word is a reserved owner command. Use `--` to send option-shaped or reserved-word prompt text: `paper -- --version` sends `--version` as prompt text rather than printing package metadata, and `paper -- info about this layout` sends the whole phrase to the specialist. The reserved owner words are `show`, `info`, `selection`, `tree`, `node`, `screenshot`, `doctor`, `page`, and `help`.
 
 The public interactive runtime deliberately disables inherited `/debug`, `/export`, `/import`, and `/share` commands. They are absent from command autocomplete and are intercepted before upstream debug-log, file-writing, session-replacement, or network-sharing handlers can run. The global Shift+Ctrl+D debug shortcut is intercepted by the same boundary. Use the documented local session directory for your own backup process; Paper Mono does not provide a raw transcript debug, export, import, or share path in public v1.
 
@@ -83,6 +83,8 @@ The default agent home is `~/.paper/agent`. Override it with `PAPER_CODING_AGENT
 - Unknown deterministic subcommands and unsupported specialist flags identify the rejected input and point back to `paper --help`. Invalid option values and conflicting `--continue` / `--resume` actions fail the same way.
 - Interactive startup remains available for `/login`; headless or non-interactive model execution with a missing provider key exits nonzero with login/environment guidance and no runtime stack trace.
 
+The historical `paper mono` owner-router spelling remains accepted for compatibility, but bare `paper` is the public and documented specialist entry point.
+
 ## Troubleshooting
 
 ### Paper closed or no file open
@@ -95,7 +97,7 @@ Paper Mono expects Paper's local MCP endpoint at `http://127.0.0.1:29979/mcp`. C
 
 ### Missing model authentication
 
-Start `paper mono`, enter `/login`, and choose a provider, or configure that provider's documented environment variable. Use `paper mono --list-models` to confirm the model ID. Do not paste keys into prompts, issue reports, or `paper doctor` output.
+Start `paper`, enter `/login`, and choose a provider, or configure that provider's documented environment variable. Use `paper --list-models` to confirm the model ID. Do not paste keys into prompts, issue reports, or `paper doctor` output.
 
 ### Missing fd or rg
 

package/docs/runtime.md

@@ -22,6 +22,7 @@ The approval gate is runtime enforcement, not a prompt convention: unapproved pr
 - Paper reads use Paper Desktop's loopback MCP server at `127.0.0.1`; Paper Mono does not upload a document to its own backend.
 - Credentials, settings, and sessions live under `~/.paper/agent` by default. `PAPER_CODING_AGENT_DIR` selects another local directory. `--session <id>` accepts a verified session ID only; path-like values are rejected before activation. `--fork <path-or-id>` explicitly imports a transcript into a new session scoped to the current project. `--session-dir <dir>` overrides session storage and lookup, may place transcripts outside the agent home, and uses the runtime's explicit-directory lookup instead of Paper Mono's hardened implicit-session verification path. Use only a trusted directory; package uninstall does not remove it.
 - Explicit `@file` inputs are limited to regular files contained by the destination repository after symlink resolution. Their contents, or processed image data, are added to the prompt context sent to the selected model provider under repository-relative labels. Generated system, context, and approval metadata renders the local project as `<repository-root>` instead of adding its absolute path. User-authored prompts, attached contents, imported instructions, tool results, or approved commands can still contain paths.
+- Prompt composition follows one ownership chain: Paper supplies Paper-specific doctrine, the shared Mono/Pi chassis supplies active-tool guidance, and Pi's resource loader supplies project instructions, skills, and cwd once. Generated path metadata from every layer is normalized before provider requests.
 - Prompts, relevant project/reference context, and tool results needed for reasoning are sent to the model provider selected by the user. That provider's privacy, retention, and billing terms apply.
 - Paper Mono does not print credential values in diagnostics. It forces inherited install telemetry, automatic version polling, and provider-attribution telemetry off before specialist startup, and adds no product telemetry or silent phone-home service.
 - Inherited `/debug`, `/export`, `/import`, and `/share` TUI commands are removed from autocomplete and intercepted before dispatch. The global Shift+Ctrl+D debug shortcut is intercepted as well. A public Paper Mono session cannot use those paths to write or replace a transcript or upload it to Radius or GitHub Gist.
@@ -30,7 +31,7 @@ The approval gate is runtime enforcement, not a prompt convention: unapproved pr
 
 ## Authentication
 
-Run `paper mono`, enter `/login`, and choose a supported provider. Provider environment variables are also accepted where supported by the runtime. `paper mono --list-models` displays available model IDs. Interactive startup remains available so you can enter `/login`; headless or non-interactive model execution without credentials exits nonzero with guided instructions instead of a stack trace.
+Run `paper`, enter `/login`, and choose a supported provider. Provider environment variables are also accepted where supported by the runtime. `paper --list-models` displays available model IDs. Interactive startup remains available so you can enter `/login`; headless or non-interactive model execution without credentials exits nonzero with guided instructions instead of a stack trace.
 
 Never share `~/.paper/agent/auth.json`, provider keys, or unredacted session transcripts in support reports.
 

package/package.json

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

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

@@ -1,11 +1,11 @@
 {
   "schemaVersion": "mono-safety-card.v1",
-  "cardId": "paper:sha256:763820199b4f59b9673bfa24a94661ef8c10020f157a1987faf0fc5a018d0c9a",
+  "cardId": "paper:sha256:b53fab419474899ca25a0b84546025fbe758920be3dcddc5dd1e6fd97bf242b8",
   "specialist": "paper",
-  "contractHash": "sha256:763820199b4f59b9673bfa24a94661ef8c10020f157a1987faf0fc5a018d0c9a",
+  "contractHash": "sha256:b53fab419474899ca25a0b84546025fbe758920be3dcddc5dd1e6fd97bf242b8",
   "status": "pass",
   "conjunctive": true,
-  "verifiedAt": "2026-08-26T17:36:42.243Z",
+  "verifiedAt": "2026-08-28T22:55:46.054Z",
   "verificationSource": "pnpm -C packages/mono safety:verify (L1 engine over executable tool-walk fixtures)",
   "summary": {
     "tools": 27,

package/tools.contract.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "mono-tools.v1",
   "specialist": "paper",
-  "ownerCommand": "paper mono",
+  "ownerCommand": "paper",
   "agentHome": "~/.paper/agent",
   "domain": {
     "comment": "REQ: Paper Desktop design-to-code agent CLI powered by the Paper MCP bridge at http://127.0.0.1:29979/mcp.",
@@ -54,7 +54,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -114,7 +114,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -174,7 +174,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -234,7 +234,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -294,7 +294,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -354,7 +354,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -414,7 +414,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -474,7 +474,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -534,7 +534,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -594,7 +594,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -654,7 +654,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -714,7 +714,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -772,7 +772,7 @@
         "allOf": [],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [
           "http://127.0.0.1:29979/mcp"
@@ -834,7 +834,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -895,7 +895,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -966,7 +966,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -1028,7 +1028,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -1090,7 +1090,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -1161,7 +1161,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -1232,7 +1232,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -1302,7 +1302,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -1362,7 +1362,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -1420,7 +1420,7 @@
         "allOf": [],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -1481,7 +1481,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -1552,7 +1552,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -1622,7 +1622,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false
@@ -1693,7 +1693,7 @@
         ],
         "anyOf": [],
         "cli": [
-          "paper mono"
+          "paper"
         ],
         "endpoint": [],
         "optional": false