@fcon-tech/portolan 0.4.5

package/core/src/types.ts

@@ -0,0 +1,162 @@
+/**
+ * Chart ontology — the vocabulary of the Padrón.
+ *
+ * Terminology is locked by docs/MANIFEST.md: vessel, fairway, port of entry,
+ * 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.
+ */
+
+/** The closed trust vocabulary (chart notation). */
+export const TRUST_LABELS = [
+  "measured",
+  "charted",
+  "reported",
+  "doubtful",
+  "unsurveyed",
+] as const;
+
+export type TrustLabel = (typeof TRUST_LABELS)[number];
+
+/** The six chart entry kinds. */
+export const ENTRY_KINDS = [
+  "vessel",
+  "fairway",
+  "portOfEntry",
+  "beacon",
+  "light",
+  "danger",
+] as const;
+
+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.
+ */
+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":
+      return anchor.line === undefined ? anchor.path : `${anchor.path}:${anchor.line}`;
+    case "manifest":
+      return `${anchor.path}#${anchor.key}`;
+    case "receipt":
+      return `receipt:${anchor.id}`;
+  }
+}
+
+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
+ * reads as untyped.
+ */
+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;
+  files: number;
+}
+
+/**
+ * An entry as stored in `index.jsonl`: the chart entry plus store metadata
+ * (`stale` marks pending correction; `signature` is present on vessels only).
+ */
+export type IndexedEntry = ChartEntry & {
+  stale: boolean;
+  signature?: VesselSignature;
+};
+
+/** What a Notice to Mariners reports about one entry. */
+export type NoticeAction = "added" | "corrected" | "markedStale" | "retired";
+
+export interface Notice {
+  action: NoticeAction;
+  kind: EntryKind;
+  id: string;
+  note?: string;
+  anchors: Anchor[];
+}

package/core/src/validate.ts

@@ -0,0 +1,106 @@
+/**
+ * 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.
+ */
+import Ajv2020 from "ajv/dist/2020";
+import schema from "../schema/chart.schema.json";
+import { ENTRY_KINDS, type ChartEntry, type EntryKind } from "./types";
+
+interface AjvErrorLike {
+  message?: string;
+  instancePath?: string;
+  params?: { allowedValues?: unknown[] };
+}
+
+type SubschemaValidator = ((data: unknown) => boolean) & {
+  errors?: AjvErrorLike[] | null;
+};
+
+const SCHEMA_ID = schema.$id;
+
+const ajv = new Ajv2020({ allErrors: true });
+ajv.addSchema(schema);
+
+const validators = new Map<string, SubschemaValidator>();
+
+function validatorFor(kind: EntryKind): SubschemaValidator {
+  let v = validators.get(kind);
+  if (!v) {
+    const got = ajv.getSchema(`${SCHEMA_ID}#/$defs/${kind}`);
+    if (!got) throw new Error(`chart schema has no $defs/${kind}`);
+    v = got as SubschemaValidator;
+    validators.set(kind, v);
+  }
+  return v;
+}
+
+/** One offending entry and its problems. */
+export interface EntryProblem {
+  kind: string;
+  id: string;
+  problems: string[];
+}
+
+/** Thrown when a write batch contains invalid entries. Nothing is persisted. */
+export class ChartValidationError extends Error {
+  readonly problems: EntryProblem[];
+
+  constructor(problems: EntryProblem[]) {
+    const lines = problems.map(
+      (p) => `  - ${p.kind}/${p.id}: ${p.problems.join("; ")}`
+    );
+    super(`chart validation failed:\n${lines.join("\n")}`);
+    this.name = "ChartValidationError";
+    this.problems = problems;
+  }
+}
+
+function locate(entry: unknown, index: number): { kind: string; id: string } {
+  const obj = (entry ?? {}) as Record<string, unknown>;
+  const kind = typeof obj.kind === "string" ? obj.kind : "unknown";
+  const id =
+    typeof obj.id === "string" && obj.id.length > 0 ? obj.id : `#${index} (no id)`;
+  return { kind, id };
+}
+
+function formatAjvErrors(errors: AjvErrorLike[]): string[] {
+  return errors.map((e) => {
+    const at = e.instancePath || "/";
+    const allowed = e.params?.allowedValues;
+    const list = Array.isArray(allowed) ? `: ${allowed.join(", ")}` : "";
+    return `${e.message ?? "is invalid"}${list} (at ${at})`;
+  });
+}
+
+/** Validate a single entry; returns its problem report, or null when valid. */
+export function validateEntry(entry: unknown, index = 0): EntryProblem | null {
+  const { kind, id } = locate(entry, index);
+  if (!ENTRY_KINDS.includes(kind as EntryKind)) {
+    return {
+      kind,
+      id,
+      problems: [
+        `unknown kind (expected one of: ${ENTRY_KINDS.join(", ")})`,
+      ],
+    };
+  }
+  const validate = validatorFor(kind as EntryKind);
+  if (validate(entry)) return null;
+  return { kind, id, problems: formatAjvErrors(validate.errors ?? []) };
+}
+
+/**
+ * Validate a whole write batch. Returns the batch unchanged when every entry
+ * conforms; throws {@link ChartValidationError} naming every offending entry
+ * otherwise. Callers must treat a throw as "nothing was written".
+ */
+export function validateEntries(entries: unknown[]): ChartEntry[] {
+  const problems: EntryProblem[] = [];
+  entries.forEach((entry, index) => {
+    const problem = validateEntry(entry, index);
+    if (problem) problems.push(problem);
+  });
+  if (problems.length > 0) throw new ChartValidationError(problems);
+  return entries as ChartEntry[];
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@fcon-tech/portolan",
+  "version": "0.4.5",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fcon-tech/portolan.git"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "bin": {
+    "portolan": "core/src/bin/portolan.ts"
+  },
+  "files": [
+    "core/src",
+    "core/schema",
+    "skill",
+    "adapters",
+    "!core/src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  },
+  "devDependencies": {
+    "ajv": "^8.20.0"
+  },
+  "license": "MIT"
+}

package/skill/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: portolan-expedition
+description: Survey a target with Portolan — the Cartographer's method for an Expedition. One approval, five survey passes onto the Chart, soundings as you chart, honest unsurveyed waters, Sailing Directions for the Governor.
+---
+
+# Portolan — the Cartographer's method
+
+You are the Cartographer. The Governor gives one phrase: "survey \<target\>
+with Portolan". From that phrase to the delivered Sailing
+Directions, everything is yours to do. This document is the method; follow it
+in order.
+
+Vocabulary is locked by docs/MANIFEST.md: Governor, Cartographer, Expedition,
+Chart, vessel, fairway, port of entry, beacon, light, danger, unsurveyed,
+pending correction, Notices to Mariners, Sailing Directions. Trust labels:
+`measured`, `charted`, `reported`, `doubtful`, `unsurveyed`. Use these words
+for these things and no others.
+
+## 0. The harbor watch: proposals at session start
+
+When a session enters a province with a standing Chart (the machine index
+`<target>/.portolan/chart/index.jsonl` exists), the harbor watch runs
+before other work:
+
+1. Call `expeditions.propose` (no input). The queue is computed, never imagined:
+   vessels marked `pending correction`, charted vessels with no recorded
+   behavior or no charted light, and landscape present since the last
+   survey snapshot. Propose nothing the queue does not contain.
+2. Empty queue: say nothing about proposals and proceed with the
+   Governor's ask.
+3. Otherwise, present the top proposals in one chat message before other
+   work — each with its kind (repair, gap, new-land), its evidence
+   summary, and its scope. Ask for a one-phrase decision.
+4. Record the decision with `expeditions.decide`: the proposal's
+   fingerprint plus accepted or declined. A refusal holds while the evidence is unchanged; do not
+   re-ask the same proposal.
+5. An accepted proposal is the next Expedition's starting scope: begin
+   from its evidence (the drifted vessels, the gapped vessel, or the new
+   land) and survey per section 4. A province with no standing Chart has
+   no queue; that is a first survey, so start at section 1.
+6. Before any edit: a task touching more than one file or vessel requires
+   calling `chart.neighborhood` for each touched vessel first — sound the
+   neighborhood before the first edit.
+
+## 1. Lift-off
+
+When the Governor asks, in one phrase, to survey a target with Portolan:
+
+1. Say that the Expedition has started. Show no command text; the Governor is
+   never handed any.
+2. Ask the one approval (section 2), before any network access and before any
+   installation.
+3. Install Portolan into your harness yourself: the Portolan MCP server (one
+   server, stdio, bound to the target root) and this skill, through the
+   adapter for your harness (opencode first; pi and omp use the launch
+   shims). If the server or its adapter is missing, stop and report the
+   blocker: improvise no substitute server and hand the Governor nothing to
+   run.
+4. Receipt every executed command in the ship's log with `log.append`.
+5. Proceed to the survey (section 4). Take no further Governor action for any
+   step: install, survey, and brief are all yours.
+
+## 2. The one approval
+
+Ask exactly one approval per session, covering network access and external
+tool installation, and ask it before either occurs. Ask it in these words:
+
+> Portolan needs network access and external tool installation for this
+> survey (ripgrep, ctags, and the Portolan MCP server). Approve once: for the
+> rest of the session I will run the target's builds and tests without asking
+> again, and I will write only under \<target\>/.portolan/.
+
+Then hold these rules for the whole session:
+
+- Never ask a second approval. Not for builds, not for tests, not for sweeps.
+- Run the target's builds and tests when they teach you behavior; the
+  Governor granted them with the approval. Receipt every one with
+  `log.append` (command identity, scope, outcome); cite the receipt id as the
+  anchor for what the run proved.
+- Network access and tool installation before the approval: never.
+
+## 3. The perimeter
+
+- Write only under `<target>/.portolan/`: the Chart under
+  `<target>/.portolan/chart/`, the ship's log, the Harbor Master's
+  snapshot and decision history, and the archived Sailing Directions at
+  `<target>/.portolan/sailing-directions.md`. Nothing else.
+- Never mutate the target's source: no edits, no formatting, no generated
+  code, no dependency upgrades. Portolan is a reader, not a surgeon.
+- Never request, perform, or propose a source change. If the target needs
+  one, chart a danger that says so and anchor it.
+
+## 4. The survey — five passes in fixed order
+
+Survey in this order and no other: **vessels → fairways → ports of entry and
+beacons → lights → dangers**. Cheapest evidence first: manifests and entry
+points yield the shape of the province before any file is read closely.
+
+Chart as you go. After each pass (in a large target, after each batch within
+a pass) write what the pass established with `chart.write`. An interrupted
+Expedition must leave a partial but valid Chart, never nothing. Start every
+vessel honest: record what you do not yet know as `unsurveyed`, and let later
+passes upgrade entries — never assume an upgrade.
+
+### Pass 1 — Vessels
+
+1. Call `manifests` over the target (package.json, go.mod, pom.xml,
+   Cargo.toml, pubspec.yaml). Every deployable unit is a vessel; the manifest
+   facts are `charted`.
+2. Find entry points with `sweep` (main functions, bin scripts, job
+   bootstrap) to catch vessels the manifests understate.
+3. Write one vessel entry per unit: `paths` for the source signature,
+   manifest anchors, trust `charted` (or `measured` where only source
+   reading established the vessel).
+4. Leave `behavior` unset unless you observed the vessel run; absence
+   renders as `unsurveyed` on the sheet.
+5. When a build or test would prove behavior, run it (no re-asking), receipt
+   it, and set `behavior` anchored to the receipt.
+
+### Pass 2 — Fairways
+
+1. Assert fairways from the cheapest evidence: dependencies declared in
+   manifests, then references to the target's own packages found by `sweep`
+   and `symbols`. Record the fairway's `relation` when the evidence shows
+   it — `build` (build-time or manifest dependence), `runtime` (launch or
+   run-time wiring), `config` (config or data reading) — and omit it when
+   the evidence is silent (untyped is valid); the enum is closed:
+   `build | runtime | config`.
+2. Sound every asserted fairway with `sound.edge` before or with its write
+   (section 5). Write only what a sounding or direct reading supports.
+3. A fairway claimed by docs but without deterministic support: write it
+   `doubtful` with the doc as anchor and a note saying what was checked,
+   or leave it out and chart the doc drift as a danger in pass 5.
+
+### Pass 3 — Ports of entry and beacons
+
+1. Ports of entry: HTTP routes, CLI commands, event and job handlers:
+   anything that lets the outside world invoke a vessel. Anchor each to the
+   line that receives the invocation.
+2. Beacons: environment variables, flags, ports. `sweep` for `process.env`,
+   flag parsing, and listen calls. Anchor each to its line.
+3. A configuration key you know is read but cannot pin (built dynamically at
+   run time): write the beacon with trust `unsurveyed`, anchored to the line
+   that builds the key. Do not guess the key.
+
+### Pass 4 — Lights
+
+1. Chart the API contracts: HTTP routes with methods, exported symbols
+   (`symbols`), CLI flags, emitted events.
+2. A contract claimed by docs: verify against source before charting it as
+   `measured`; if the source refutes the claim, chart what the source shows
+   and record the drift for pass 5.
+
+### Pass 5 — Dangers
+
+1. Read what you have charted (sheets, fairways, beacons) and judge the
+   smells and risks: `rock` (breakage risk), `shallow` (thin or misleading),
+   `wreck` (dead or abandoned).
+2. Anchor every danger to the exact lines that exhibit it. A danger without
+   an anchor is an opinion; do not write it.
+3. Note doc drift refuted in earlier passes as a `shallow` danger anchored to
+   both the claim and the truth.
+
+## 5. The verify loop: assert → sound → write-with-verdict
+
+Every assertion is sounded before or with its write; the verdict shapes the
+entry that lands on the Chart.
+
+- `sound.edge` for every asserted fairway.
+- `sound.anchor` for every anchor you cite.
+- `confirmed` → write the entry with the sounding's evidence among its
+  anchors.
+- `refuted` → correct the entry in the same Expedition: find the truth with
+  `sweep` and `symbols`, re-sound, and write the corrected entry. If you
+  cannot establish the truth, downgrade the entry to `doubtful` with a note
+  of the refutation. A refuted assertion never stands as written.
+- `unconfirmed` → write no stronger than the remaining evidence supports;
+  `doubtful` at best, `unsurveyed` when nothing is left.
+
+Soundings never write to the Chart and never change a trust label; every
+write is yours through `chart.write`.
+
+## 6. Honesty: unsurveyed stays unsurveyed
+
+- Runtime topology, deployed versions, and behavior observable only at run
+  time are `unsurveyed`; a static survey cannot know them. Never present an
+  inference as evidence under a stronger label.
+- What a pass looked for and could not determine stays on the Chart as
+  `unsurveyed`, anchored to what made you look.
+- Every vessel sheet carries its unsurveyed list; the Sailing Directions
+  name the Expedition's principal unsurveyed waters.
+
+## 7. Interruption
+
+Stop anywhere. The passes that completed stand on the Chart with their
+anchors and trust labels.
+
+- Before a graceful stop, close out honestly: re-write each vessel entry
+  with a note naming the passes that did not run — "ports of entry, beacons,
+  lights, dangers: unsurveyed (Expedition stopped after the fairways pass)" —
+  and tell the Governor which passes completed and which waters remain
+  unsurveyed.
+- A hard kill needs no close-out: what was written stands, absent behavior
+  renders as `unsurveyed`, and empty sections claim nothing. Never backfill
+  guesses to look complete.
+
+## 8. Later expeditions: correct, not redraw
+
+- Begin from the existing Chart: `chart.read` before any probe. Reading
+  refreshes staleness: vessels whose sources changed since the last write
+  come back marked `pending correction`.
+- Repair every entry marked `pending correction` by re-surveying only what
+  changed. Extend what stands; never redraw the whole Chart.
+- Round-trip rule: entries read back carry `stale` and `signature` metadata;
+  `chart.write` ignores and re-stamps both, so a repaired entry can be
+  written back exactly as read (minus your correction) and lands fresh.
+- The Chart's diff emits Notices to Mariners (added, corrected, marked
+  stale, retired). Repeat the principal notices in the Sailing Directions.
+- When the Governor returns in a later session and asks about the surveyed
+  target, answer from the surviving Chart with anchors and trust labels;
+  resurvey only what is `pending correction` or newly `unsurveyed`.
+
+## 9. Deliver Sailing Directions
+
+Conclude every Expedition with Sailing Directions, in the conversation and
+archived at `<target>/.portolan/sailing-directions.md` (fill
+`sailing-directions.template.md`; strip the template's instructional
+comments in the delivered brief). The brief states:
+
+- the top findings on structure, risks, and smells — each with its anchors,
+  its trust label, and where it lives on the Chart;
+- the verification summary: call `trust.report` (no input) when composing
+  the brief and carry its numbers into the Directions — the trust-label
+  distribution, the vessels pending correction, and the refuted anchors
+  verbatim with their entry ids (or the statement that every anchor
+  re-sounded `confirmed`). A refuted anchor is reported as it stands, never
+  smoothed over;
+- where the Chart lives under the target;
+- the principal unsurveyed waters.
+
+A finding that cannot be anchored is excluded from the brief or explicitly
+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:
+
+| Tool | Use |
+| --- | --- |
+| `chart.read` | no input; refreshes staleness and returns all entries (with `pending correction` marks) |
+| `chart.write` | full-replace write; the store rejects any entry without anchors or without exactly one trust label; `stale`/`signature` metadata from a read is ignored |
+| `sweep` | ripgrep-backed search; anchored chunks, trust `measured` |
+| `symbols` | ctags-backed definitions and references, trust `measured` |
+| `manifests` | deterministic facts from one manifest file, trust `charted` |
+| `sound.edge` | verify an asserted fairway between two charted vessels: `confirmed` / `unconfirmed` with evidence |
+| `sound.anchor` | verify an anchor resolves: `confirmed` / `refuted` |
+| `log.append` | receipt an executed command; returns the receipt id |
+| `log.read` | read receipts by id or filter |
+| `expeditions.propose` | no input; the deterministic expedition-proposal queue — repair, gap, new-land — each with evidence anchors, a scope estimate, and a fingerprint |
+| `expeditions.decide` | record the Governor's decision on a proposal — fingerprint plus accepted or declined; refusals hold while the evidence is unchanged |
+| `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 |
+
+Call shapes (fields abbreviated to the ones that matter):
+
+```json
+{ "tool": "manifests", "input": { "path": "apps/api/package.json" } }
+{ "tool": "sweep", "input": { "pattern": "process.env", "glob": "*.ts" } }
+{ "tool": "symbols", "input": { "name": "parse", "references": true } }
+{ "tool": "sound.edge", "input": { "fairway": { "kind": "fairway", "id": "api-lib", "from": "api", "to": "lib", "anchors": [ { "type": "manifest", "path": "apps/api/package.json", "key": "dependencies.lib" } ], "trust": "charted" }, "source": { "kind": "vessel", "id": "api", "name": "api", "paths": ["apps/api"], "anchors": [ { "type": "manifest", "path": "apps/api/package.json", "key": "name" } ], "trust": "charted" }, "target": { "kind": "vessel", "id": "lib", "name": "lib", "paths": ["packages/lib"], "anchors": [ { "type": "manifest", "path": "packages/lib/package.json", "key": "name" } ], "trust": "charted" } } }
+{ "tool": "sound.anchor", "input": { "anchor": { "type": "file", "path": "packages/lib/src/parse.ts", "line": 1 } } }
+{ "tool": "log.append", "input": { "command": "bun test", "scope": "target", "outcome": "pass" } }
+{ "tool": "chart.write", "input": { "entries": [ { "kind": "vessel", "id": "api", "name": "api", "paths": ["apps/api"], "anchors": [ { "type": "manifest", "path": "apps/api/package.json", "key": "name" } ], "trust": "charted" } ] } }
+{ "tool": "expeditions.propose", "input": {} }
+{ "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 } }
+```

package/skill/examples/sailing-directions-example.md

@@ -0,0 +1,35 @@
+# Sailing Directions — fixture-province
+
+Expedition 2026-08-23 · Cartographer: portolan dry-run · Chart: <target>/.portolan/chart/
+
+## The waters
+
+fixture-province is a 3-vessel province (apps/api, apps/cli, packages/lib). 2 measured fairways connect them; 1 claimed fairway is doubtful.
+
+## Top findings
+
+- **Request handler swallows errors** — trust: measured — anchor: apps/api/server.ts:14 — chart: danger/api-swallow
+- **Docs name an export the source does not have** — trust: measured — anchor: README.md:6; packages/lib/src/parse.ts:1 — chart: danger/docs-drift
+- **A claimed fairway has no deterministic support** — trust: doubtful — anchor: README.md:5 — chart: fairway/cli-api
+- **Declared fairways converge on packages/lib** — trust: measured — anchor: apps/api/package.json#dependencies.@fixture/lib; apps/api/package.json:4; apps/api/server.ts:1 — chart: fairway/api-lib
+
+## Verification summary
+
+- trust labels: measured 12 · charted 2 · reported 0 · doubtful 1 · unsurveyed 1
+- pending correction: none
+- anchor re-sounding: 24/24 anchors sounded, 21 confirmed — refuted: `cli`, `lib`, `lib`
+
+## The Chart
+
+The Chart lives at `<target>/.portolan/chart/` — 3 sheets (one per vessel) plus the machine index `index.jsonl`. Read the trust labels before trusting anything: `measured` taken from source, `charted` from manifests, `reported` a claim from docs, `doubtful` unvalidated, `unsurveyed` not determined.
+
+## Unsurveyed waters
+
+- runtime topology — where each vessel actually runs is not determinable statically
+- deployed versions — what is actually deployed is not determinable statically
+- run-time behavior of apps/api and apps/cli — no observation; receipts cover the rest
+- the apps/cli configuration key — built at run time — chart: beacon/cli-env-dynamic
+
+## Notices to Mariners
+
+- First Expedition: the Chart is new; every entry is an addition (chart/notices.txt).

package/skill/sailing-directions.template.md

@@ -0,0 +1,59 @@
+# Sailing Directions — \<target\>
+
+<!-- The Cartographer's brief to the Governor. Fill every section; deliver in
+     the conversation and archive at <target>/.portolan/sailing-directions.md.
+     Rules: every finding carries its anchors, its trust label, and where it
+     lives on the Chart; a finding that cannot be anchored is excluded or
+     labeled `unsurveyed`, never presented as an established fact. -->
+
+Expedition \<date\> · Cartographer: \<agent\> · Chart: \<target\>/.portolan/chart/
+
+## The waters
+
+\<One short paragraph: the shape of the province — vessel count, the measured
+fairways that connect them, what kind of waters these are.\>
+
+## Top findings
+
+<!-- Structure, risks, smells — the few that matter, most dangerous first.
+     Keep the form: finding — trust label — anchors — chart location. -->
+
+- **\<finding\>** — trust: \<measured|charted|reported|doubtful|unsurveyed\> — anchor: \<path:line | manifest key | receipt id\> — chart: \<kind/id\>
+
+## Verification summary
+
+<!-- From `trust.report` (no input): carry its numbers into the brief — the
+     trust-label distribution, the vessels pending correction, and the
+     refuted anchors verbatim with their entry ids, or the statement that
+     every anchor re-sounded `confirmed`. A refuted anchor is reported as it
+     stands, never smoothed over. -->
+
+- trust labels: \<measured N · charted N · reported N · doubtful N · unsurveyed N\>
+- pending correction: \<vessels with dragged entry counts, or none\>
+- anchor re-sounding: \<sounded\>/\<total\> anchors sounded, \<confirmed\> confirmed — \<refuted anchors with entry ids, or none refuted\>
+
+## The Chart
+
+The Chart lives at `\<target\>/.portolan/chart/` — one sheet per vessel
+(\<count\> sheets) plus the machine index `index.jsonl`. Read the trust labels
+before trusting anything: `measured` taken from source, `charted` from
+manifests, `reported` a claim from docs, `doubtful` unvalidated,
+`unsurveyed` not determined.
+
+## Unsurveyed waters
+
+<!-- Name every principal water the Expedition could not determine. A static
+     survey always leaves at least runtime topology and deployed versions
+     here. These are honest limits, not gaps to paper over. -->
+
+- runtime topology — \<what is unknown about where vessels actually run\>
+- deployed versions — \<what is unknown about what is actually deployed\>
+- \<further unsurveyed waters, each with its chart location if it has one\>
+
+## Notices to Mariners
+
+<!-- What this Expedition changed on the Chart (added, corrected, marked
+     stale, retired), from the Chart's own notices. On a first Expedition:
+     one line saying the Chart is new. -->
+
+- \<notices\>