Build a map
A map is learned, not hand-written. Portolan discovers what a site can do, turns each finding into a candidate op, and publishes only the ops that pass on a live run. No OpenAPI file or hand-authored JSON is required.
Start from the live app
portolan map build --site herbie \
--url http://localhost:3000 \
--start "npm run dev" \
--verify --publishPortolan opens the app in Chromium (the same DOM and CDP surface DevTools uses), walks same-origin pages, and turns what it finds into drafts:
- every page becomes a URL-only state like
/p/:id; - every navigation link becomes a
urlread op; - every form becomes a typed op: inputs become params, the submit button becomes a
uistep, and a GET form also gets the cheaperurlroute.
Discovery never submits a form. Writes publish only when re-verified with --verify-writes or proven by a recorded run.
The command writes two reviewable files next to the map versions:
maps/herbie/
draft.json candidate ops, provenance, and observed params
tasks.json what discovery could not know (missing params, outcome checks)
v1.json published, verified opsPages behind auth
Sign in once in a visible browser and reuse that session. Portolan never sees the password:
portolan auth login --url https://careerkor.com/sign-in \
--out ./portolan/auth.json
portolan map build --site careerkor \
--url https://careerkor.com/dashboard \
--storage-state ./portolan/auth.json \
--verify --publishThe same file works for portolan verify, portolan compile, and the MCP runtime (PORTOLAN_STORAGE_STATE or storageState in the config). A different account or an expired session means a new file.
Update the map when the app changes
portolan map update --site herbie --url http://localhost:3000 --verify --publishAn update keeps ops that rediscovery did not see, replaces ops it did see after verification passes, and publishes a new version. A session pins a version, so an update never changes the meaning of an in-flight call.
If the app has no link or form to start from, record one run instead:
open_url(url, intent) → explore session + fallback scope
view() / act() / read() → the task, recorded
fallback_done(scope_id) → saves the traceThen portolan map build --site herbie compiles the trace into candidates.
Coverage: the capability ledger
A crawl finds pages, not every capability. map build therefore writes capabilities.json next to the map: every link, form, and button it saw on every visited page, marked mapped, missing, excluded, or stale.
portolan map coverage --site careerkor --maps ./portolan/maps
# careerkor: 27 mapped, 48 missing, 51 excluded, 0 stale (36% of actionable)
portolan map capability set --site careerkor --maps ./portolan/maps \
--id pricing.button.choose_pro --status excluded --reason "requires a paid plan"The ledger is the reviewable contract:
mappedonly when a verified op covers that exact trigger;missingis the work queue;excludedrequires a reason (destructive, credit-spending, obsolete);- a manual decision has
source: "manual"and survives rediscovery; - code-derived capabilities (
source: "code") cover things the crawl cannot see.
Use --require-complete to refuse publication while anything is missing or stale:
portolan map build ... --require-complete --verify --publishportolan init installs skills/portolan-map/SKILL.md, the companion skill that tells a coding agent how to work the ledger until it is complete.
Optional: hand-written seed
For a precise contract you can still write maps/<site>/v0.json by hand and verify it:
Initialize
portolan init ./my-site --site storeThis writes portolan.config.json, an egress policy at policies/store.json, and the maps/ and skills/ directories.
Write the operations
Create maps/store/v0.json with states, operations, and their schemas. A minimal operation:
{
"name": "search",
"effect": "read",
"params": {
"type": "object",
"properties": { "query": { "type": "string" } },
"required": ["query"]
},
"returns": {
"type": "object",
"properties": { "results": { "type": "array" } }
},
"impls": [
{ "tier": "url", "route": "/search?q={query}", "extract": { "kind": "none" } }
]
}The full field reference is Map format v0.
Verify
Verification runs each operation against a live site on a fresh session. Every operation needs at least three param sets:
{
"search": [
{ "query": "shirt" },
{ "query": "linen" },
{ "query": "coat" }
]
}portolan verify --map maps/store/v0.json --params store.params.json --base-url https://store.exampleEach operation is reported per tier. A failed verification never publishes.
Compile from traces
Collect fallback traces from real runs, then compile them into a new map version:
portolan compile run-1.json run-2.json \
--map maps/store/v0.json \
--base-url https://store.example \
--outcome-checks store.outcomes.jsonThe compiler proposes candidates, verifies them, and publishes a new version. The map is versioned: a session pins one version, so a publish never changes the meaning of a call in flight.
Export a skill
portolan export-skills --map maps/store/v1.json --out skills --trace run-1.jsonThe exporter writes skills/portolan-store/ with SKILL.md and references/ops.md. It refuses to write an invalid skill or one that looks like it contains a secret. See Skills.
The loop
hand-written ops → verify → trace real runs → compile → verify → publish
▲ │
└──── repair on drift ◀───┘When a site changes, a drift run reports what broke. Repair proposes new implementations, verifies them, and publishes a new version. Writes are never duplicated: the ledger records the outcome before the next attempt.