---
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, landscape present since the last
   survey snapshot, and open flares — repair needs filed by expeditions.
   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. An Expedition launched from an accepted proposal records its charter
   before its first chart write: `log.append` with
   `meta: { "kind": "charter", "vessels": ["api"], "entries": 3 }` — the
   vessels and entries taken from the proposal's scope. The charter is a
   receipt, not a wish: it names what the Expedition promises to touch.
7. 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.
- Keep the charter you recorded at start (section 0): write only the
  vessels and entries it names. A repair need the charter does not name —
  an out-of-charter need — is filed as a flare, never fixed silently:
  `log.append` with
  `meta: { "kind": "flare", "vessel": "lib", "reason": "the stated reason", "evidence": "where you found it" }`,
  and the entry left untouched. The harbor queue turns every open flare
  into a repair proposal for that vessel; a decision — accepted or
  declined — closes it. If you write outside the charter anyway, the
  writes stay receipted and surface as overreach in the watch report and
  in `trust.report`: a broken charter is never invisible, but nothing is
  ever blocked.
- Close the charter when the Expedition ends with an outcome receipt
  naming the start receipt: `log.append` with
  `meta: { "kind": "charter-outcome", "charter": "r12" }`.
- 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. Fifteen 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 |
| `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):

```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 } }
{ "tool": "chart.export", "input": {} }
```