@fcon-tech/portolan 0.4.5 → 0.5.0

package/README.md

@@ -65,9 +65,12 @@ bun install -g @fcon-tech/portolan    # or: npm i -g @fcon-tech/portolan
 # your agent installs Portolan itself from one phrase:
 survey <target> with Portolan
 
-# serve the fourteen MCP tools to your harness:
+# serve the fifteen MCP tools to your harness:
 portolan serve --target /path/to/province
 
+# the Chart's machine layer as one JSON document (docs/formats.md):
+portolan export --target /path/to/province
+
 # the atlas for a surveyed province (map + graph + dossier + ledger):
 portolan chartroom render --target /path/to/province
 
@@ -94,7 +97,7 @@ bun core/src/server/main.ts --target /path/to/province    # dev path
 
 | Path | What lives there |
 | --- | --- |
-| `core/` | the Chart store, the fourteen MCP tools (stdio server), the Harbor, the Chart Room renderer |
+| `core/` | the Chart store, the fifteen MCP tools (stdio server), the Harbor, the Chart Room renderer |
 | `skill/` | the Cartographer's expedition method, as a harness-loadable skill |
 | `adapters/` | opencode installer + expedition launcher, pi/omp shims, drop-in night-watch crontab |
 | `acceptance/` | the sea-trial gate: the whole loop graded against a real corpus |

package/adapters/README.md

@@ -4,7 +4,7 @@ How the one Portolan MCP server reaches a harness. Adapters are launch
 configuration only: they configure how the server is launched and add no
 behavior of their own — no tool filtering, no traffic parsing, no
 per-harness code paths. Two harnesses connecting through different adapters
-see the same fourteen tools, the same results, and the same errors as a
+see the same fifteen tools, the same results, and the same errors as a
 direct launch (`openspec/specs/harness/spec.md`: "The served tools are
 harness-agnostic").
 
@@ -39,7 +39,7 @@ writes (shape verified against opencode's own `opencode mcp add`):
 ```
 
 After installing, `opencode mcp list` shows `portolan connected`, and every
-session can call all fourteen served tools.
+session can call all fifteen served tools.
 
 The opencode adapter also ships the night watch's expedition launcher
 (`adapters/opencode/expedition-launcher`) — see "The night watch" below.

package/core/schema/chart.schema.json

@@ -1,19 +1,33 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://portolan.dev/core/chart.schema.json",
+  "version": "0.1.0",
   "title": "Portolan Chart entry",
-  "description": "One entry of the Chart (the Padrón): vessel, fairway, port of entry, beacon, light, or danger. Every entry carries at least one anchor and exactly one trust label from the closed vocabulary. This schema is the published contract for Cartographer agents; core/src/types.ts mirrors it.",
+  "description": "One entry of the Chart (the Padrón): vessel, fairway, port of entry, beacon, light, or danger. Every entry carries at least one anchor and exactly one trust label from the closed vocabulary (a standalone $ref to trust-vocabulary.schema.json — register both files). Entries as stored in index.jsonl additionally carry the store's `stale` marker, and vessels its `signature`; a hand-supplied write carries neither, the store stamps them. This schema is the published contract for Cartographer agents; core/src/types.ts mirrors it.",
   "$ref": "#/$defs/chartEntry",
   "$defs": {
     "trustLabel": {
-      "description": "Closed trust vocabulary (chart notation): measured, charted, reported, doubtful, unsurveyed.",
-      "enum": ["measured", "charted", "reported", "doubtful", "unsurveyed"]
+      "$ref": "https://portolan.dev/core/trust-vocabulary.schema.json"
     },
     "fairwayRelation": {
       "description": "Optional closed relation vocabulary on a fairway: build, runtime, config. A fairway without a relation stays valid and reads as untyped.",
       "enum": ["build", "runtime", "config"]
     },
     "entryId": { "type": "string", "minLength": 1 },
+    "stale": {
+      "description": "Store metadata on entries as stored: true when the anchored sources drifted since the last survey — the entry is pending correction (Notices to Mariners). Never hand-supplied; the store stamps it.",
+      "type": "boolean"
+    },
+    "signature": {
+      "description": "Store metadata on vessels as stored: cheap tree signature over the vessel's paths, re-stamped by the store on every write. Never hand-supplied.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["hash", "files"],
+      "properties": {
+        "hash": { "type": "string", "minLength": 1 },
+        "files": { "type": "integer", "minimum": 0 }
+      }
+    },
     "anchor": {
       "oneOf": [
         {
@@ -63,9 +77,11 @@
         "name": { "type": "string", "minLength": 1 },
         "behavior": { "type": "string" },
         "paths": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "signature": { "$ref": "#/$defs/signature" },
         "note": { "type": "string" },
         "anchors": { "$ref": "#/$defs/anchors" },
-        "trust": { "$ref": "#/$defs/trustLabel" }
+        "trust": { "$ref": "#/$defs/trustLabel" },
+        "stale": { "$ref": "#/$defs/stale" }
       }
     },
     "fairway": {
@@ -80,7 +96,8 @@
         "relation": { "$ref": "#/$defs/fairwayRelation" },
         "note": { "type": "string" },
         "anchors": { "$ref": "#/$defs/anchors" },
-        "trust": { "$ref": "#/$defs/trustLabel" }
+        "trust": { "$ref": "#/$defs/trustLabel" },
+        "stale": { "$ref": "#/$defs/stale" }
       }
     },
     "portOfEntry": {
@@ -94,7 +111,8 @@
         "protocol": { "type": "string", "minLength": 1 },
         "note": { "type": "string" },
         "anchors": { "$ref": "#/$defs/anchors" },
-        "trust": { "$ref": "#/$defs/trustLabel" }
+        "trust": { "$ref": "#/$defs/trustLabel" },
+        "stale": { "$ref": "#/$defs/stale" }
       }
     },
     "beacon": {
@@ -109,7 +127,8 @@
         "key": { "type": "string", "minLength": 1 },
         "note": { "type": "string" },
         "anchors": { "$ref": "#/$defs/anchors" },
-        "trust": { "$ref": "#/$defs/trustLabel" }
+        "trust": { "$ref": "#/$defs/trustLabel" },
+        "stale": { "$ref": "#/$defs/stale" }
       }
     },
     "light": {
@@ -123,7 +142,8 @@
         "name": { "type": "string", "minLength": 1 },
         "note": { "type": "string" },
         "anchors": { "$ref": "#/$defs/anchors" },
-        "trust": { "$ref": "#/$defs/trustLabel" }
+        "trust": { "$ref": "#/$defs/trustLabel" },
+        "stale": { "$ref": "#/$defs/stale" }
       }
     },
     "danger": {
@@ -137,7 +157,8 @@
         "category": { "enum": ["rock", "shallow", "wreck"] },
         "note": { "type": "string", "minLength": 1 },
         "anchors": { "$ref": "#/$defs/anchors" },
-        "trust": { "$ref": "#/$defs/trustLabel" }
+        "trust": { "$ref": "#/$defs/trustLabel" },
+        "stale": { "$ref": "#/$defs/stale" }
       }
     },
     "chartEntry": {

package/core/schema/graph-export.schema.json

@@ -0,0 +1,203 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://portolan.dev/core/graph-export.schema.json",
+  "title": "Portolan adjacency graph export",
+  "version": "0.1.0",
+  "description": "The chart.export document: the Chart's machine layer rendered as nodes and edges, consumable without the MCP server. Arithmetic over charted bytes only — no timestamps anywhere (the ship's log carries the when), no derived rollups (no top-level `vessels` list — every node carries its vessel; no dangling-endpoint `issues[]` — a raw edge id already states the fact), no invented nodes. Nodes mirror the charted entries field-for-field plus `stale`; the store's `signature` stays in the Chart. Trust labels $ref trust-vocabulary.schema.json — register both files.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["format", "version", "nodes", "edges", "truncated", "omitted"],
+  "properties": {
+    "format": {
+      "description": "The format name; a consumer dispatches on it.",
+      "const": "portolan-adjacency"
+    },
+    "version": {
+      "description": "The graph-export schema version this document was produced against.",
+      "type": "string",
+      "minLength": 1
+    },
+    "nodes": {
+      "description": "Every charted entry that is not a fairway, rendered whole: the entry's charted fields as-is plus staleness.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/node" }
+    },
+    "edges": {
+      "description": "Every charted fairway. The arrays are disjoint: nodes and edges together draw exactly the charted entries.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/edge" }
+    },
+    "truncated": {
+      "description": "True when the export byte budget cut entries; `omitted` then names every cut vessel.",
+      "type": "boolean"
+    },
+    "omitted": {
+      "description": "The loud truncation report: one record per vessel with entries cut, empty when nothing was cut.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["vessel", "entries"],
+        "properties": {
+          "vessel": { "type": "string", "minLength": 1 },
+          "entries": {
+            "description": "How many of that vessel's entries were cut.",
+            "type": "integer",
+            "minimum": 1
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "entryId": { "type": "string", "minLength": 1 },
+    "trustLabel": {
+      "$ref": "https://portolan.dev/core/trust-vocabulary.schema.json"
+    },
+    "stale": {
+      "description": "Pending correction: true when the anchored sources drifted since the last survey. Carried as-is, never hidden.",
+      "type": "boolean"
+    },
+    "anchor": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "path"],
+          "properties": {
+            "type": { "const": "file" },
+            "path": { "type": "string", "minLength": 1 },
+            "line": { "type": "integer", "minimum": 1 }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "path", "key"],
+          "properties": {
+            "type": { "const": "manifest" },
+            "path": { "type": "string", "minLength": 1 },
+            "key": { "type": "string", "minLength": 1 }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "id"],
+          "properties": {
+            "type": { "const": "receipt" },
+            "id": { "type": "string", "minLength": 1 }
+          }
+        }
+      ]
+    },
+    "anchors": {
+      "description": "An entry without at least one anchor does not ship.",
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/anchor" }
+    },
+    "node": {
+      "oneOf": [
+        { "$ref": "#/$defs/vessel" },
+        { "$ref": "#/$defs/portOfEntry" },
+        { "$ref": "#/$defs/beacon" },
+        { "$ref": "#/$defs/light" },
+        { "$ref": "#/$defs/danger" }
+      ]
+    },
+    "vessel": {
+      "description": "A charted vessel, rendered whole: the charted fields as-is plus `stale`. The store's `signature` is not exported.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "name", "paths", "anchors", "trust", "stale"],
+      "properties": {
+        "kind": { "const": "vessel" },
+        "id": { "$ref": "#/$defs/entryId" },
+        "name": { "type": "string", "minLength": 1 },
+        "behavior": { "type": "string" },
+        "paths": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "note": { "type": "string" },
+        "anchors": { "$ref": "#/$defs/anchors" },
+        "trust": { "$ref": "#/$defs/trustLabel" },
+        "stale": { "$ref": "#/$defs/stale" }
+      }
+    },
+    "portOfEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "vessel", "protocol", "anchors", "trust", "stale"],
+      "properties": {
+        "kind": { "const": "portOfEntry" },
+        "id": { "$ref": "#/$defs/entryId" },
+        "vessel": { "$ref": "#/$defs/entryId" },
+        "protocol": { "type": "string", "minLength": 1 },
+        "note": { "type": "string" },
+        "anchors": { "$ref": "#/$defs/anchors" },
+        "trust": { "$ref": "#/$defs/trustLabel" },
+        "stale": { "$ref": "#/$defs/stale" }
+      }
+    },
+    "beacon": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "vessel", "surface", "key", "anchors", "trust", "stale"],
+      "properties": {
+        "kind": { "const": "beacon" },
+        "id": { "$ref": "#/$defs/entryId" },
+        "vessel": { "$ref": "#/$defs/entryId" },
+        "surface": { "enum": ["env", "flag", "port"] },
+        "key": { "type": "string", "minLength": 1 },
+        "note": { "type": "string" },
+        "anchors": { "$ref": "#/$defs/anchors" },
+        "trust": { "$ref": "#/$defs/trustLabel" },
+        "stale": { "$ref": "#/$defs/stale" }
+      }
+    },
+    "light": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "vessel", "name", "anchors", "trust", "stale"],
+      "properties": {
+        "kind": { "const": "light" },
+        "id": { "$ref": "#/$defs/entryId" },
+        "vessel": { "$ref": "#/$defs/entryId" },
+        "name": { "type": "string", "minLength": 1 },
+        "note": { "type": "string" },
+        "anchors": { "$ref": "#/$defs/anchors" },
+        "trust": { "$ref": "#/$defs/trustLabel" },
+        "stale": { "$ref": "#/$defs/stale" }
+      }
+    },
+    "danger": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "vessel", "category", "note", "anchors", "trust", "stale"],
+      "properties": {
+        "kind": { "const": "danger" },
+        "id": { "$ref": "#/$defs/entryId" },
+        "vessel": { "$ref": "#/$defs/entryId" },
+        "category": { "enum": ["rock", "shallow", "wreck"] },
+        "note": { "type": "string", "minLength": 1 },
+        "anchors": { "$ref": "#/$defs/anchors" },
+        "trust": { "$ref": "#/$defs/trustLabel" },
+        "stale": { "$ref": "#/$defs/stale" }
+      }
+    },
+    "edge": {
+      "description": "A charted fairway as an edge. No `kind` tag — nodes and edges are disjoint by construction; `relation` stays absent when the fairway is untyped.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "from", "to", "anchors", "trust", "stale"],
+      "properties": {
+        "id": { "$ref": "#/$defs/entryId" },
+        "from": { "$ref": "#/$defs/entryId" },
+        "to": { "$ref": "#/$defs/entryId" },
+        "relation": { "enum": ["build", "runtime", "config"] },
+        "anchors": { "$ref": "#/$defs/anchors" },
+        "trust": { "$ref": "#/$defs/trustLabel" },
+        "stale": { "$ref": "#/$defs/stale" }
+      }
+    }
+  }
+}

package/core/schema/receipt.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://portolan.dev/core/receipt.schema.json",
+  "title": "Portolan ship's-log receipt",
+  "version": "0.1.0",
+  "description": "One line of <target>/.portolan/log.jsonl — the append-only receipt the log writes per executed command (core/src/tools/log.ts). The writer is authoritative (design D3): this schema documents what log.ts writes, ids are monotonic and citable as chart anchors, and no field outside the six named ones may appear.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "command", "outcome", "recordedAt"],
+  "properties": {
+    "id": {
+      "description": "Monotonic, assigned by the log: r1, r2, ... — citable as a receipt anchor.",
+      "type": "string",
+      "pattern": "^r\\d+$"
+    },
+    "command": {
+      "description": "Command identity, e.g. `sweep pattern=UserService`.",
+      "type": "string"
+    },
+    "scope": {
+      "description": "What was surveyed, e.g. the module or path scope. Optional — short probes may carry none.",
+      "type": "string"
+    },
+    "outcome": {
+      "description": "Outcome, e.g. `ok: 3 chunks` or `error: missing binary ctags`.",
+      "type": "string"
+    },
+    "recordedAt": {
+      "description": "ISO timestamp of the append (the log writes Date.prototype.toISOString).",
+      "type": "string"
+    },
+    "meta": {
+      "description": "Free-form command metadata (counts, notes, cited receipts). Open object: the log does not constrain keys or value shapes.",
+      "type": "object"
+    }
+  }
+}

package/core/schema/trust-vocabulary.schema.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://portolan.dev/core/trust-vocabulary.schema.json",
+  "title": "Portolan trust vocabulary",
+  "version": "0.1.0",
+  "description": "The closed trust vocabulary (chart notation): exactly five labels, one per claim. measured: taken from source directly; charted: from manifests/metadata; reported: from docs/commits/tickets — claims, not facts; doubtful: evidence present, could not be validated; unsurveyed: no usable evidence, never faked. Single source of the enum (design D2): chart.schema.json references this file by $id, and a validator needs both files registered.",
+  "enum": ["measured", "charted", "reported", "doubtful", "unsurveyed"]
+}

package/core/src/bin/portolan.ts

@@ -4,23 +4,30 @@
  * It routes to the existing entry points; it implements nothing itself:
  *
  *   portolan serve --target <province root>      → server/main.ts (MCP over stdio)
+ *   portolan export [--target <province root>]   → tools/export.ts (chartExport)
  *   portolan chartroom <render|review> …        → chartroom/cli.ts
  *   portolan harbor <propose|watch|run> …       → harbor/cli.ts
  *
  * `serve` runs in-process (same parse, same server wiring as main.ts);
  * the CLIs are spawned with inherited stdio so their behavior — output,
- * exit codes — is indistinguishable from running them directly.
+ * exit codes — is indistinguishable from running them directly. `export`
+ * also runs in-process, over the same core function the served chart.export
+ * tool calls (design D6: MCP and CLI cannot diverge); it prints the
+ * document pretty-printed (two spaces, trailing newline), the same shape
+ * the harbor CLI prints its JSON in, and it appends no ship's-log receipt —
+ * receipts are the served tools' discipline, never a CLI side effect.
  */
 import { resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
-const SUBCOMMANDS = ["serve", "chartroom", "harbor"] as const;
+const SUBCOMMANDS = ["serve", "export", "chartroom", "harbor"] as const;
 
 const usage = `usage: portolan <command> [args]
 
 commands:
   serve      run the Portolan MCP server (stdio)
+  export     adjacency graph export of the Chart (JSON to stdout)
   chartroom  Chart Room CLI (render | review)
   harbor     harbor CLI (propose | watch | run)`;
 
@@ -54,6 +61,34 @@ async function serve(rest: readonly string[]): Promise<void> {
   await server.connect(new StdioServerTransport());
 }
 
+async function exportJson(rest: readonly string[]): Promise<void> {
+  // Same parse shape as `serve`, over the args after the `export` subcommand;
+  // the same chartExport the served chart.export tool calls (design D6).
+  const { parseArgs } = await import("node:util");
+  const { chartExport, ExportError } = await import("../tools/export");
+
+  const { values } = parseArgs({
+    args: rest,
+    allowPositionals: false,
+    options: {
+      target: { type: "string", default: process.cwd() },
+    },
+  });
+  try {
+    const doc = chartExport(resolve(values.target as string));
+    console.log(JSON.stringify(doc, null, 2));
+  } catch (err) {
+    // The honest errors (no Chart, fairways alone over budget): name them on
+    // stderr, exit nonzero, never print a document. No receipt is appended —
+    // this path never touches the ship's log, on success or rejection.
+    if (err instanceof ExportError) {
+      console.error(err.message);
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+
 /** Run one of the existing CLI scripts with the remaining args, verbatim. */
 function runCli(script: string, args: string[]): never {
   const child = spawn(process.execPath, [script, ...args], { stdio: "inherit" });
@@ -70,6 +105,8 @@ async function dispatch(argv: readonly string[]): Promise<void> {
   switch (command) {
     case "serve":
       return serve(rest);
+    case "export":
+      return exportJson(rest);
     case "chartroom":
       return runCli(srcPath("../chartroom/cli.ts"), rest);
     case "harbor":

package/core/src/index.ts

@@ -16,6 +16,7 @@ export * from "./tools/manifests";
 export * from "./tools/log";
 export * from "./tools/sound";
 export * from "./tools/neighborhood";
+export * from "./tools/export";
 export * from "./harbor/errors";
 export * from "./harbor/fingerprint";
 export * from "./harbor/snapshot";

package/core/src/server/registry.ts

@@ -17,6 +17,7 @@ import { symbols } from "../tools/symbols";
 import { readManifest } from "../tools/manifests";
 import { appendReceipt, readReceipt, readReceipts } from "../tools/log";
 import { neighborhood, NEIGHBORHOOD_CAPS, NEIGHBORHOOD_DEFAULTS, type NeighborhoodParams } from "../tools/neighborhood";
+import { chartExport, EXPORT_MAX_BYTES } from "../tools/export";
 import { soundAnchor, soundEdge } from "../tools/sound";
 import { trustReport } from "../tools/trust-report";
 import { computeProposals, decide } from "../harbor/proposals";
@@ -583,9 +584,42 @@ export const TOOL_TABLE: ToolSpec[] = [
       return response;
     },
   },
+  {
+    name: "chart.export",
+    description:
+      "Export the province's whole machine layer as one self-describing adjacency document (format " +
+      "portolan-adjacency, schema-versioned): every charted entry drawn as a node — the charted fields " +
+      "as-is plus staleness — or an edge (fairways: from/to, relation when charted), each carrying its " +
+      "anchors and trust label un-upgraded; no timestamps, no derived rollups, nothing a charted entry " +
+      `does not state. Byte-budgeted (${EXPORT_MAX_BYTES} bytes): an oversized chart truncates loudly, ` +
+      "naming every omitted vessel with its cut entry count. Staleness is refreshed before serving " +
+      "exactly as chart.read refreshes it; read-only toward the sources and the Chart beyond that " +
+      "staleness refresh — a rejected call writes nothing, not even the refresh — and each successful " +
+      "call appends exactly one ship's-log receipt. " +
+      "A province with no Chart is an honest error naming the absence, never a fabricated document.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    handler: (_args, ctx) => {
+      // The one write this call makes: exactly one ship's-log receipt, through
+      // the same append path log.append serves. A rejected call (no Chart) is
+      // thrown by the builder and never reaches this line, so a rejection
+      // leaves no receipt.
+      const doc = chartExport(ctx.targetRoot);
+      appendReceipt(ctx.targetRoot, {
+        command: "chart.export",
+        scope: "adjacency graph",
+        outcome:
+          `ok: ${doc.nodes.length} node${doc.nodes.length === 1 ? "" : "s"}, ` +
+          `${doc.edges.length} edge${doc.edges.length === 1 ? "" : "s"}` +
+          (doc.truncated
+            ? `, truncated: ${doc.omitted.length} vessel${doc.omitted.length === 1 ? "" : "s"} omitted`
+            : ""),
+      });
+      return doc;
+    },
+  },
 ];
 
-/** The served Portolan tool names, in table order (the harness capability's fourteen). */
+/** The served Portolan tool names, in table order (the harness capability's fifteen). */
 export const TOOL_NAMES = TOOL_TABLE.map((spec) => spec.name);
 
 /**

package/core/src/tools/export.ts

@@ -0,0 +1,275 @@
+/**
+ * `chart.export`: the province's adjacency graph export in one
+ * deterministic document (openspec/changes/formats-pass, design D4 + D5;
+ * specs/tools/spec.md + specs/formats/spec.md).
+ *
+ * The document is arithmetic over the Chart's machine layer and nothing
+ * else: every non-fairway entry is drawn as a node — the charted fields
+ * as-is plus `stale`, the store's `signature` aside — and every fairway as
+ * an edge (from/to vessel ids, the relation when charted, anchors, trust,
+ * stale). Nothing is invented, decorated, or re-graded: `doubtful` and
+ * `unsurveyed` pass through un-upgraded, a fairway endpoint without a
+ * charted vessel is stated by the raw edge id alone, and there are no
+ * timestamps and no derived rollups (no top-level `vessels` list, no
+ * dangling-endpoint `issues[]`) — the ship's log carries the when. The
+ * document names its format (`portolan-adjacency`) and the graph-export
+ * schema version it was produced against, read from the schema file itself
+ * (design D1: the version lives in the schema file).
+ *
+ * Staleness follows chart.read semantics: refreshed before answering, so
+ * pending correction is visible, never hidden. That refresh is the only
+ * write the builder may cause (nothing on unchanged signatures); the
+ * builder itself appends nothing and mutates nothing else — the served
+ * handler owns the single ship's-log receipt per call. A rejected call
+ * writes nothing, not even the refresh: the byte-budget feasibility
+ * precheck runs before the refresh, so an over-budget refusal never moves
+ * the Chart.
+ *
+ * The export is byte-budgeted (EXPORT_MAX_BYTES; bytes alone — the export
+ * takes no query parameters). An oversized chart is cut whole-vessel: from
+ * the tail of the id-ascending vessel order, one vessel at a time, until
+ * the serialized document fits, removing each cut vessel's own node and
+ * every node it owns, while the fairways stay drawn. The cut is loud:
+ * `truncated` plus `omitted`, naming every cut vessel with its cut entry
+ * count — never a silent prefix — and it is measured over a running total
+ * (each vessel's serialized contribution computed once), not by
+ * re-serializing the document per cut. If the fairways alone exceed the
+ * budget there is no honest cut left, and the builder refuses by name
+ * instead of serving over budget. A province with no Chart is an honest
+ * ExportError naming the absence, never a fabricated document.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import graphExportSchema from "../../schema/graph-export.schema.json";
+import type {
+  Anchor,
+  BeaconEntry,
+  ChartEntry,
+  DangerEntry,
+  FairwayRelation,
+  IndexedEntry,
+  LightEntry,
+  PortOfEntryEntry,
+  TrustLabel,
+  VesselEntry,
+} from "../types";
+import { INDEX_FILE, chartDir, readChart } from "../chart-store";
+import { refreshStaleness } from "../staleness";
+
+/** The document's self-named format (graph-export.schema.json's const). */
+const FORMAT = "portolan-adjacency" as const;
+
+/** The graph-export schema version this document is produced against. */
+const GRAPH_EXPORT_VERSION: string = graphExportSchema.version;
+
+/**
+ * The export's byte budget over the compact serialized document — the bytes
+ * a consumer receives. Fixed: the export takes no query parameters to
+ * inflate or shrink it (design D5 dropped the records half in favor of
+ * bytes alone).
+ */
+export const EXPORT_MAX_BYTES = 262_144;
+
+/** Raised for every rejection of this tool: no Chart, no honest cut. */
+export class ExportError extends Error {
+  constructor(message: string) {
+    super(`export: ${message}`);
+    this.name = "ExportError";
+  }
+}
+
+/** A charted fairway as an edge: no `kind` tag, `relation` absent when untyped. */
+export interface GraphExportEdge {
+  id: string;
+  from: string;
+  to: string;
+  relation?: FairwayRelation;
+  anchors: Anchor[];
+  trust: TrustLabel;
+  stale: boolean;
+}
+
+/**
+ * A charted non-fairway entry, rendered whole: the charted fields as-is
+ * plus `stale`, the store's `signature` omitted — typed exactly as the
+ * charted entry minus its store signature; the per-kind shapes the document
+ * must satisfy are pinned by graph-export.schema.json, not by this alias.
+ * The union stays distributed: `Omit` over the entry union as a whole would
+ * collapse it to the common keys alone (a vessel's `paths`, a beacon's
+ * `surface` and `key`, a danger's `category` — all erased).
+ */
+type NodeOf<T extends ChartEntry> = Omit<T & { stale: boolean }, "signature">;
+export type GraphExportNode =
+  | NodeOf<VesselEntry>
+  | NodeOf<PortOfEntryEntry>
+  | NodeOf<BeaconEntry>
+  | NodeOf<LightEntry>
+  | NodeOf<DangerEntry>;
+
+/** What `chart.export` returns: the self-describing adjacency document. */
+export interface GraphExport {
+  format: typeof FORMAT;
+  version: string;
+  nodes: GraphExportNode[];
+  edges: GraphExportEdge[];
+  truncated: boolean;
+  /** The loud cut report: one record per vessel with entries cut; empty when whole. */
+  omitted: Array<{ vessel: string; entries: number }>;
+}
+
+/** The vessel an entry hangs from: a vessel is its own owner. */
+type DrawnNode = { owner: string; node: GraphExportNode };
+
+/** The charted fairways as edges, in entry order: no `kind` tag, `relation` absent when untyped. */
+function edgesOf(entries: IndexedEntry[]): GraphExportEdge[] {
+  const edges: GraphExportEdge[] = [];
+  for (const entry of entries) {
+    if (entry.kind !== "fairway") continue;
+    edges.push({
+      id: entry.id,
+      from: entry.from,
+      to: entry.to,
+      ...(entry.relation !== undefined ? { relation: entry.relation } : {}),
+      anchors: entry.anchors,
+      trust: entry.trust,
+      stale: entry.stale,
+    });
+  }
+  return edges;
+}
+
+/**
+ * `chart.export`: the province's adjacency document. Deterministic — no
+ * timestamps, no map-order leakage: two runs over an unchanged province
+ * return the same document in the same order.
+ */
+export function chartExport(targetRoot: string): GraphExport {
+  const indexPath = join(chartDir(targetRoot), INDEX_FILE);
+  if (!existsSync(indexPath)) {
+    throw new ExportError(
+      `no chart at ${indexPath} — nothing to export; survey the province and write the Chart first`,
+    );
+  }
+
+  // Feasibility precheck, before any write: the fairways alone bound the
+  // document from below (every cut removes only vessels' nodes). If they
+  // already exceed the budget there is no honest cut left, and the export
+  // refuses before the staleness refresh can move the Chart — a rejected
+  // call writes nothing at all.
+  const precheck: GraphExport = {
+    format: FORMAT,
+    version: GRAPH_EXPORT_VERSION,
+    nodes: [],
+    edges: edgesOf(readChart(targetRoot)),
+    truncated: false,
+    omitted: [],
+  };
+  if (Buffer.byteLength(JSON.stringify(precheck), "utf8") > EXPORT_MAX_BYTES) {
+    throw new ExportError(
+      `the chart's fairways alone exceed the export budget of ${EXPORT_MAX_BYTES} bytes — ` +
+        `no vessel left to cut, and the export refuses to serve over budget`,
+    );
+  }
+
+  // chart.read semantics: staleness is refreshed before answering. On
+  // unchanged signatures the refresh writes nothing at all; when it writes,
+  // that is the builder's only possible write — and it runs only after the
+  // precheck above has accepted the call.
+  refreshStaleness(targetRoot);
+  const entries = readChart(targetRoot);
+
+  const nodes: DrawnNode[] = [];
+  const edges = edgesOf(entries);
+  /** Owner vessel id -> how many of its entries are nodes (itself included). */
+  const owned = new Map<string, number>();
+  for (const entry of entries) {
+    if (entry.kind === "fairway") continue;
+    // The charted fields as-is: the entry, its store signature aside.
+    const { signature: _signature, ...node } = entry;
+    const owner = entry.kind === "vessel" ? entry.id : entry.vessel;
+    nodes.push({ owner, node });
+    owned.set(owner, (owned.get(owner) ?? 0) + 1);
+  }
+
+  const owners = [...owned.keys()].sort();
+  const cut = new Set<string>();
+  const assemble = (): GraphExport => ({
+    format: FORMAT,
+    version: GRAPH_EXPORT_VERSION,
+    nodes: nodes.filter(({ owner }) => !cut.has(owner)).map(({ node }) => node),
+    edges,
+    truncated: cut.size > 0,
+    omitted: owners
+      .filter((id) => cut.has(id))
+      .map((id) => ({ vessel: id, entries: owned.get(id)! })),
+  });
+
+  // The budget is measured on the compact serialization — the bytes a
+  // consumer receives for the document itself. Each owner's serialized
+  // contribution is computed once; the document total is then a running
+  // sum over the kept/cut sets — the skeleton already carries the two
+  // `[`…`]` array pairs, and a filled array keeps its own pair — plus the
+  // arrays' commas — so the cut is O(vessels), not O(vessels × bytes)
+  // re-serializations.
+  const nodeBytes = new Map<string, number>();
+  for (const { owner, node } of nodes) {
+    nodeBytes.set(owner, (nodeBytes.get(owner) ?? 0) + Buffer.byteLength(JSON.stringify(node), "utf8"));
+  }
+  const omittedBytes = new Map<string, number>(
+    owners.map((id) => [id, Buffer.byteLength(JSON.stringify({ vessel: id, entries: owned.get(id)! }), "utf8")]),
+  );
+  const skeletonBytes = (truncated: boolean): number =>
+    Buffer.byteLength(
+      JSON.stringify({ format: FORMAT, version: GRAPH_EXPORT_VERSION, nodes: [], edges, truncated, omitted: [] }),
+      "utf8",
+    );
+  const totalBytes = (
+    keptBytes: number,
+    keptCount: number,
+    cutBytes: number,
+    cutCount: number,
+    truncated: boolean,
+  ): number => {
+    const commas = (count: number): number => (count > 0 ? count - 1 : 0);
+    return skeletonBytes(truncated) + keptBytes + cutBytes + commas(keptCount) + commas(cutCount);
+  };
+
+  let keptBytes = 0;
+  for (const bytes of nodeBytes.values()) keptBytes += bytes;
+  let keptCount = nodes.length;
+  let cutBytes = 0;
+  let cutCount = 0;
+  let overBudget = totalBytes(keptBytes, keptCount, cutBytes, cutCount, false) > EXPORT_MAX_BYTES;
+  if (overBudget) {
+    // Whole-vessel cut from the tail of the id-ascending order — never a
+    // partial vessel, never a silent prefix. Fairways stay drawn: a raw
+    // edge id states its endpoints, so an edge whose far vessel was cut is
+    // still charted truth (design D4).
+    for (let i = owners.length - 1; i >= 0 && overBudget; i--) {
+      const id = owners[i]!;
+      cut.add(id);
+      keptBytes -= nodeBytes.get(id) ?? 0;
+      keptCount -= owned.get(id)!;
+      cutBytes += omittedBytes.get(id)!;
+      cutCount += 1;
+      overBudget = totalBytes(keptBytes, keptCount, cutBytes, cutCount, true) > EXPORT_MAX_BYTES;
+    }
+    if (overBudget) {
+      throw new ExportError(
+        `the chart's fairways alone exceed the export budget of ${EXPORT_MAX_BYTES} bytes — ` +
+          `no vessel left to cut, and the export refuses to serve over budget`,
+      );
+    }
+  }
+  // The served bytes are the real serialization, not the running estimate:
+  // one full assembly pins the cut to the honest count (and is the paranoid
+  // re-check after the refresh, whose flag flips can move edge bytes).
+  const doc = assemble();
+  if (Buffer.byteLength(JSON.stringify(doc), "utf8") > EXPORT_MAX_BYTES) {
+    throw new ExportError(
+      `the serialized export exceeds the export budget of ${EXPORT_MAX_BYTES} bytes — ` +
+        `the export refuses to serve over budget`,
+    );
+  }
+  return doc;
+}

package/core/src/tools/log.ts

@@ -21,7 +21,7 @@ import {
   unlinkSync,
 } from "node:fs";
 import { join } from "node:path";
-import type { Anchor } from "../types";
+import type { Anchor, Receipt } from "../types";
 
 export const SHIPS_LOG_FILE = "log.jsonl";
 export const LOG_LOCK_FILE = "log.lock";
@@ -36,19 +36,13 @@ export function logFile(targetRoot: string): string {
   return join(targetRoot, ".portolan", SHIPS_LOG_FILE);
 }
 
-export interface Receipt {
-  /** Stable, monotonic, citable as an anchor: r1, r2, ... */
-  id: string;
-  /** Command identity, e.g. `sweep pattern=UserService`. */
-  command: string;
-  /** What was surveyed, e.g. the module or path scope. */
-  scope?: string;
-  /** Outcome, e.g. `ok: 3 chunks` or `error: missing binary ctags`. */
-  outcome: string;
-  /** ISO timestamp of the append. */
-  recordedAt: string;
-  meta?: Record<string, unknown>;
-}
+/**
+ * The receipt type is generated from core/schema/receipt.schema.json
+ * (formats-pass, design D7) and lives in ../types; the writer stays
+ * authoritative (D3) — if a field the writer needs is missing there, the
+ * schema follows the writer, never this file.
+ */
+export type { Receipt } from "../types";
 
 export type ReceiptInput = Omit<Receipt, "id" | "recordedAt"> & {
   /** Callers normally let the log assign ids; a replayed id is checked. */

package/core/src/types.generated.ts

@@ -0,0 +1,126 @@
+/**
+ * Generated from the chart, trust-vocabulary, and receipt schemas under
+ * core/schema/ by scripts/gen-types.ts — do not edit by hand; schema wins
+ * (formats-pass, design D7). Regenerate with `bun run scripts/gen-types.ts`;
+ * a committed copy that differs from today's schemas fails the drift guard
+ * in core/src/formats.test.ts.
+ */
+
+/** The closed trust vocabulary (chart notation): exactly five labels, one per claim. measured: taken from source directly; charted: from manifests/metadata; reported: from docs/commits/tickets — claims, not facts; doubtful: evidence present, could not be validated; unsurveyed: no usable evidence, never faked. Single source of the enum (design D2): chart.schema.json references this file by $id, and a validator needs both files registered. */
+type TrustLabel = "measured" | "charted" | "reported" | "doubtful" | "unsurveyed";
+
+/** Optional closed relation vocabulary on a fairway: build, runtime, config. A fairway without a relation stays valid and reads as untyped. */
+type FairwayRelation = "build" | "runtime" | "config";
+
+export type Anchor =
+  | { type: "file"; path: string; line?: number }
+  | { type: "manifest"; path: string; key: string }
+  | { type: "receipt"; id: string };
+
+export interface VesselEntry {
+  kind: "vessel";
+  id: string;
+  name: string;
+  behavior?: string;
+  paths: string[];
+  /** Store metadata on vessels as stored: cheap tree signature over the vessel's paths, re-stamped by the store on every write. Never hand-supplied. */
+  signature?: { hash: string; files: number };
+  note?: string;
+  /** An entry without at least one anchor does not ship. */
+  anchors: Anchor[];
+  trust: TrustLabel;
+  /** Store metadata on entries as stored: true when the anchored sources drifted since the last survey — the entry is pending correction (Notices to Mariners). Never hand-supplied; the store stamps it. */
+  stale?: boolean;
+}
+
+export interface FairwayEntry {
+  kind: "fairway";
+  id: string;
+  from: string;
+  to: string;
+  /** Optional closed relation vocabulary on a fairway: build, runtime, config. A fairway without a relation stays valid and reads as untyped. */
+  relation?: FairwayRelation;
+  note?: string;
+  /** An entry without at least one anchor does not ship. */
+  anchors: Anchor[];
+  trust: TrustLabel;
+  /** Store metadata on entries as stored: true when the anchored sources drifted since the last survey — the entry is pending correction (Notices to Mariners). Never hand-supplied; the store stamps it. */
+  stale?: boolean;
+}
+
+export interface PortOfEntryEntry {
+  kind: "portOfEntry";
+  id: string;
+  vessel: string;
+  protocol: string;
+  note?: string;
+  /** An entry without at least one anchor does not ship. */
+  anchors: Anchor[];
+  trust: TrustLabel;
+  /** Store metadata on entries as stored: true when the anchored sources drifted since the last survey — the entry is pending correction (Notices to Mariners). Never hand-supplied; the store stamps it. */
+  stale?: boolean;
+}
+
+export interface BeaconEntry {
+  kind: "beacon";
+  id: string;
+  vessel: string;
+  surface: "env" | "flag" | "port";
+  key: string;
+  note?: string;
+  /** An entry without at least one anchor does not ship. */
+  anchors: Anchor[];
+  trust: TrustLabel;
+  /** Store metadata on entries as stored: true when the anchored sources drifted since the last survey — the entry is pending correction (Notices to Mariners). Never hand-supplied; the store stamps it. */
+  stale?: boolean;
+}
+
+export interface LightEntry {
+  kind: "light";
+  id: string;
+  vessel: string;
+  name: string;
+  note?: string;
+  /** An entry without at least one anchor does not ship. */
+  anchors: Anchor[];
+  trust: TrustLabel;
+  /** Store metadata on entries as stored: true when the anchored sources drifted since the last survey — the entry is pending correction (Notices to Mariners). Never hand-supplied; the store stamps it. */
+  stale?: boolean;
+}
+
+export interface DangerEntry {
+  kind: "danger";
+  id: string;
+  vessel: string;
+  category: "rock" | "shallow" | "wreck";
+  note: string;
+  /** An entry without at least one anchor does not ship. */
+  anchors: Anchor[];
+  trust: TrustLabel;
+  /** Store metadata on entries as stored: true when the anchored sources drifted since the last survey — the entry is pending correction (Notices to Mariners). Never hand-supplied; the store stamps it. */
+  stale?: boolean;
+}
+
+export type ChartEntry =
+  | VesselEntry
+  | FairwayEntry
+  | PortOfEntryEntry
+  | BeaconEntry
+  | LightEntry
+  | DangerEntry;
+
+/** One line of <target>/.portolan/log.jsonl — the append-only receipt the log writes per executed command (core/src/tools/log.ts). The writer is authoritative (design D3): this schema documents what log.ts writes, ids are monotonic and citable as chart anchors, and no field outside the six named ones may appear. */
+export interface Receipt {
+  /** Monotonic, assigned by the log: r1, r2, ... — citable as a receipt anchor. */
+  id: string;
+  /** Command identity, e.g. `sweep pattern=UserService`. */
+  command: string;
+  /** What was surveyed, e.g. the module or path scope. Optional — short probes may carry none. */
+  scope?: string;
+  /** Outcome, e.g. `ok: 3 chunks` or `error: missing binary ctags`. */
+  outcome: string;
+  /** ISO timestamp of the append (the log writes Date.prototype.toISOString). */
+  recordedAt: string;
+  /** Free-form command metadata (counts, notes, cited receipts). Open object: the log does not constrain keys or value shapes. */
+  meta?: { [key: string]: unknown };
+}

package/core/src/types.ts

@@ -5,8 +5,18 @@
  * beacon, light, danger, anchor, trust label, pending correction, Notices to
  * Mariners. Every entry carries at least one anchor and exactly one trust
  * label; the store rejects writes that omit either.
+ *
+ * Split (formats-pass, design D7): the entry, anchor, and receipt structural
+ * types are generated whole from core/schema/*.schema.json into
+ * ./types.generated and re-exported here — schema wins, the mirror cannot
+ * drift. This file keeps the hand-written runtime constants and the types
+ * the schemas do not own (the store's indexed view, Notices to Mariners).
  */
 
+import type { Anchor, ChartEntry } from "./types.generated";
+
+export * from "./types.generated";
+
 /** The closed trust vocabulary (chart notation). */
 export const TRUST_LABELS = [
   "measured",
@@ -31,15 +41,8 @@ export const ENTRY_KINDS = [
 export type EntryKind = (typeof ENTRY_KINDS)[number];
 
 /**
- * An anchor ties a claim to evidence: a file path (with optional line), a
- * manifest key, or a receipt id from the ship's log.
+ * Render an anchor as a compact, human-readable string.
  */
-export type Anchor =
-  | { type: "file"; path: string; line?: number }
-  | { type: "manifest"; path: string; key: string }
-  | { type: "receipt"; id: string };
-
-/** Render an anchor as a compact, human-readable string. */
 export function formatAnchor(anchor: Anchor): string {
   switch (anchor.type) {
     case "file":
@@ -51,30 +54,6 @@ export function formatAnchor(anchor: Anchor): string {
   }
 }
 
-interface EntryBase {
-  /** Stable identifier, unique across the chart. */
-  id: string;
-  /** At least one anchor is mandatory. */
-  anchors: Anchor[];
-  /** Exactly one trust label is mandatory. */
-  trust: TrustLabel;
-  /** Free-form qualification; never a substitute for evidence. */
-  note?: string;
-}
-
-/** A deployable unit. */
-export interface VesselEntry extends EntryBase {
-  kind: "vessel";
-  name: string;
-  /**
-   * What the vessel does at runtime. Absent behavior is rendered as
-   * `unsurveyed` on the sheet — absence stays visible, never omitted.
-   */
-  behavior?: string;
-  /** Source paths (relative to the target root) covered by the tree signature. */
-  paths: string[];
-}
-
 /**
  * The closed relation vocabulary on a fairway — the senses the anchors can
  * actually support. Optional: a fairway without a relation stays valid and
@@ -84,57 +63,6 @@ export const FAIRWAY_RELATIONS = ["build", "runtime", "config"] as const;
 
 export type FairwayRelation = (typeof FAIRWAY_RELATIONS)[number];
 
-/** A typed dependency edge between two vessels. */
-export interface FairwayEntry extends EntryBase {
-  kind: "fairway";
-  from: string;
-  to: string;
-  /** When known: what kind of dependence the edge is. */
-  relation?: FairwayRelation;
-}
-
-/** An entry point into a vessel (http endpoint, cli, event, job, ...). */
-export interface PortOfEntryEntry extends EntryBase {
-  kind: "portOfEntry";
-  vessel: string;
-  /** Short protocol family, e.g. "http", "cli", "gradle task". */
-  protocol: string;
-}
-
-/** A configuration surface: env var, flag, or port. */
-export interface BeaconEntry extends EntryBase {
-  kind: "beacon";
-  vessel: string;
-  surface: "env" | "flag" | "port";
-  /** The configured key, e.g. "PORT", "--verbose", "8080". */
-  key: string;
-}
-
-/** An API contract surface: endpoint, exported symbol, CLI flag, event. */
-export interface LightEntry extends EntryBase {
-  kind: "light";
-  vessel: string;
-  /** The contract's name, e.g. "GET /api/users" or "export function parse()". */
-  name: string;
-}
-
-/** A smell or risk. Categories per the locked glossary: rock / shallow / wreck. */
-export interface DangerEntry extends EntryBase {
-  kind: "danger";
-  vessel: string;
-  category: "rock" | "shallow" | "wreck";
-  /** What the danger is. */
-  note: string;
-}
-
-export type ChartEntry =
-  | VesselEntry
-  | FairwayEntry
-  | PortOfEntryEntry
-  | BeaconEntry
-  | LightEntry
-  | DangerEntry;
-
 /** Cheap tree signature over a vessel's paths (see design.md, decision 3). */
 export interface VesselSignature {
   hash: string;

package/core/src/validate.ts

@@ -1,10 +1,16 @@
 /**
  * Chart entry validation — ajv (draft 2020-12) against
  * core/schema/chart.schema.json, with entry-locating errors: every problem
- * names the offending entry's kind and id.
+ * names the offending entry's kind and id. The chart schema's trust label
+ * $refs trust-vocabulary.schema.json by $id (design D2), so both files are
+ * registered here; any standalone compile of the chart schema needs the
+ * vocabulary registered too. `version` is the format-version annotation on
+ * each schema file (design D1) — ajv strict mode rejects unknown keywords,
+ * so it is declared as an annotation keyword instead of dropping strictness.
  */
 import Ajv2020 from "ajv/dist/2020";
 import schema from "../schema/chart.schema.json";
+import trustVocabulary from "../schema/trust-vocabulary.schema.json";
 import { ENTRY_KINDS, type ChartEntry, type EntryKind } from "./types";
 
 interface AjvErrorLike {
@@ -20,6 +26,8 @@ type SubschemaValidator = ((data: unknown) => boolean) & {
 const SCHEMA_ID = schema.$id;
 
 const ajv = new Ajv2020({ allErrors: true });
+ajv.addKeyword("version");
+ajv.addSchema(trustVocabulary);
 ajv.addSchema(schema);
 
 const validators = new Map<string, SubschemaValidator>();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fcon-tech/portolan",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "Portolan: an MCP server that charts codebases - Chart store, Harbor expeditions, Chart Room. Runs on Bun; requires ripgrep and ctags on PATH (wrapped, not bundled).",
   "type": "module",
   "mcpName": "io.github.fcon-tech/portolan",

package/skill/SKILL.md

@@ -243,7 +243,7 @@ labeled `unsurveyed`, never presented as an established fact.
 
 ## 10. Tool desk
 
-One MCP server over stdio, bound to the target root at launch. Fourteen tools:
+One MCP server over stdio, bound to the target root at launch. Fifteen tools:
 
 | Tool | Use |
 | --- | --- |
@@ -261,6 +261,7 @@ One MCP server over stdio, bound to the target root at launch. Fourteen tools:
 | `chart.render` | no input; renders the Chart Room — the one-file visual export of this province's waters (archipelago map + dependency graph, every trust label visible) at `<target>/.portolan/chart-room.html`. When the Governor asks to *see* the landscape ("show me the province" or similar, in any language), call it and point to the file; say plainly that the picture renders only what the Chart holds, and nothing more |
 | `trust.report` | no input; the verification summary — trust-label distribution, per-kind counts, staleness refreshed first, every chart anchor re-sounded deterministically with refuted ones named, ship's-log tail; feeds the Sailing Directions |
 | `chart.neighborhood` | one vessel's neighborhood in one call: the charted fairways touching it (direction `in`/`out`/`both`, depth 1–3) with trust labels, anchors, and staleness, plus the touched vessels ranked by fan-in with their ports of entry; budgeted (`maxEdges`, `maxBytes`) and a budget cut is stated loudly; `verify: true` re-sounds every edge and names the refuted ones; read-only toward the Chart, and each call receipts itself in the ship's log |
+| `chart.export` | no input; the whole Chart as one self-describing adjacency document (format `portolan-adjacency`): every charted entry as a node or edge carrying its anchors, trust label, and staleness; byte-budgeted, and a cut is reported loudly naming the omitted vessels with their counts; staleness refreshed first, as chart.read; read-only toward the Chart, and each call receipts itself in the ship's log |
 
 Call shapes (fields abbreviated to the ones that matter):
 
@@ -276,4 +277,5 @@ Call shapes (fields abbreviated to the ones that matter):
 { "tool": "expeditions.decide", "input": { "fingerprint": "64-hex from expeditions.propose", "decision": "accepted" } }
 { "tool": "trust.report", "input": {} }
 { "tool": "chart.neighborhood", "input": { "vessel": "api", "direction": "both", "depth": 1 } }
+{ "tool": "chart.export", "input": {} }
 ```

package/skill/verify/checks.ts

@@ -152,7 +152,7 @@ check("harbor 5.1", "SKILL.md teaches the harbor watch at session start", () =>
   ]) {
     assert(text.includes(phrase), `the harbor teaching omits "${phrase}"`);
   }
-  assert(/Fourteen tools:/.test(text), "the tool desk does not count fourteen tools");
+  assert(/Fifteen tools:/.test(text), "the tool desk does not count fifteen tools");
   assert(text.includes('"tool": "trust.report", "input": {}'), "no call shape for trust.report");
   assert(
     text.includes("call `trust.report` (no input) when composing"),