Portolan is a local, read-only codebase navigation kit for AI agents and engineering leaders.
It runs on your machine, reads local files, and writes bounded evidence artifacts before an agent answers questions: what repositories were visible, what relationships and duplicate/configuration surfaces were found, what looks like technical debt, and what is still unknown.
Portolan is not a coding harness, readiness gate, service catalog, observability platform, modernization engine, or replacement for Cursor, Claude, Sourcegraph, Backstage, or enterprise code-intelligence tools. It is a local evidence layer an agent can use before making claims.
Use Portolan when you want an agent to answer questions like:
- What is in this repo or local software landscape?
- What dependencies and relationships are visible from local evidence?
- Where are duplicate source/config files?
- What env vars, ports, manifests, workflows, feature flags, or secret references are visible?
- What technical-debt candidates can be backed by local evidence?
- What is unknown, missing, or not assessed?
Portolan is especially useful when the target is messy, multi-repo, legacy, or partly black-box.
The main workflow creates a context pack for an agent:
portolan context prepare --root <target-root> --out <output-dir>/context --profile cursorTypical output:
<output-dir>/context/
agent-brief.md
answer-contract.md
query-plan.md
evidence-index.jsonl
repos.json
tool-registry.json
oss-plan.json
gaps.jsonl
When you need a fuller map, run:
portolan map --root <target-root> --out <output-dir>/mapTypical output:
<output-dir>/map/
run.json
coverage.json
summary.json
graph-index.json
graph.json
findings.jsonl
map.md
Start with summary.json, graph-index.json, findings.jsonl, and map.md.
Open the full graph.json only when you need detail.
For bounded agent questions against an existing map bundle, use:
portolan query findings --bundle <output-dir>/map --kind relationships --limit 20
portolan query gaps --bundle <output-dir>/map --limit 20Use these query commands before loading graph.json when you need finding
records, weak evidence states, or stable portolan:// references.
After the v0.1.0 tag is published, install the first public source-first
release with Go:
# Requires the published v0.1.0 tag. If this fails, use the source-checkout
# route below until the tag is available.
go install github.com/fcon-tech/portolan/cmd/portolan@v0.1.0
portolan --versionThis command fetches the public module source and builds the CLI locally. It does not install a prebuilt Portolan binary.
Until that tag exists, or if you cannot or should not fetch modules through
go install, clone the source checkout and build the repo-local binary:
git clone https://github.com/fcon-tech/portolan.git
cd portolan
scripts/bootstrap-portolan
.portolan/bin/portolan --version
.portolan/bin/portolan --help
.portolan/bin/portolan context prepare --root <target-root> --out <output-dir>/context --profile cursor
.portolan/bin/portolan map --root <target-root> --out <output-dir>/mapPortolan does not publish downloadable prebuilt binaries yet. You need the Go
version declared in go.mod for the source bootstrap.
If bootstrap fails because Go or cached modules are missing, see
Troubleshooting. Allow network dependency
download only when you mean to:
PORTOLAN_BOOTSTRAP_ALLOW_NETWORK=1 scripts/bootstrap-portolanIf you are developing Portolan itself, you can also use:
go run ./cmd/portolan context prepare --root <target-root> --out <output-dir>/context --profile cursor
go run ./cmd/portolan map --root <target-root> --out <output-dir>/map
go run ./cmd/portolan query gaps --bundle <output-dir>/map --limit 20Use --force only when you intentionally want to replace an existing Portolan
output directory.
If you are not sure which document to open first, start with the Documentation Onboarding route. It points humans, agents, Cursor operators, OpenCode operators, and release reviewers to the maintained surface for each workflow.
For a public Apache Bigtop walkthrough with redacted example artifacts, see Public Demo: Apache Bigtop.
These routes are current and boundary-limited. Some public surfaces are initial community infrastructure rather than proof of broad adoption or support.
- Install: use the Quick Start above.
- Demo: see Public Demo: Apache Bigtop.
- Product claims: read Product Claims before reusing public wording.
- Contribute: read Contributing before opening issues or pull requests.
- Security: report sensitive vulnerabilities through Security, not public issues.
- Support: see Support for public support boundaries.
If you are asking an AI agent to use Portolan, point it at the user-agent docs:
- Documentation Onboarding
- Agent Quickstart
- Agent Quickstart, Russian
- Install
- Install, Russian
- Install Prompt
- Install Prompt, Russian
- Config
- Examples
- Troubleshooting
Developer agents working on this repository should follow AGENTS.md.
The safest reusable instruction is the copyable prompt block in docs/agent/INSTALL-PROMPT.md. Fill in the three absolute paths and send that block to the agent.
For a shorter run, send this to the agent:
Install and use Portolan from PORTOLAN_PATH on TARGET_PATH. Write artifacts to
OUTPUT_PATH. Follow docs/agent/INSTALL-PROMPT.md, preserve unknown /
cannot_verify / not_assessed, and cite local artifact paths for every material
claim.
For a Russian-language agent run, use docs/agent/INSTALL-PROMPT.ru.md.
Give the agent absolute local paths for PORTOLAN_PATH, TARGET_PATH, and
OUTPUT_PATH. Do not add target-specific expected findings to the prompt.
Portolan does not turn missing evidence into confidence. Results preserve evidence states:
source-visible: visible in source files.metadata-visible: visible in local metadata, manifests, or exported tool output.runtime-visible: visible in supplied local runtime observations.claim-only: stated by a human or tool, but not verified locally.unknown: no usable evidence was available.cannot_verify: evidence was present, but Portolan could not validate it.
Reports may also use not_assessed when a surface was not checked or the
detector is not implemented.
Current safe product wording lives in Product Claims.
The v0.1.0 release surface is ready for public testing when local checks pass;
it does not imply GitHub popularity, external adoption, merge approval, or broad
ecosystem validation.
Important limits:
- The validated Cursor comparison is headless Cursor on one fixed local Bigtop target, not UI Cursor/Composer generally.
- Local repository count does not prove complete inherited-estate coverage.
- Runtime service topology is not assessed unless supported local runtime observations are supplied, and partial observations do not prove complete topology.
- Portolan has a documented untrusted-artifact boundary and focused tests for selected local CLI risks; this is not a broad security certification.
- Exact duplicate source/config clusters are supported; near-clone detection needs local jscpd-style evidence.
- Syft/CycloneDX component identity evidence has been validated for the fixed
Bigtop target; Semgrep is a first-class local producer path with a local
config and explicit output; Repomix is a first-class local producer path;
Graphify is a first-class local producer path through a read-only staging
copy; Graphify node-link import with source-backed
EXTRACTEDverification, SCIP/Serena-style JSON symbol-index import, and Repomix file-inventory import are validated. These OSS tools are accepted local dependencies in the workflow when installed and explicitly requested; broad OSS producer value remains evidence-specific.
English:
- Documentation Onboarding
- Product Claims
- Release Guide
- Product Boundary
- Evidence Model
- Relationship Detection
- Runtime Observations
- Security Threat Model
- OSS Composition
- Demo Status
- Contributing
- Security Policy
- Support
- Product Backlog
- SpecKit Workflow
Russian:
For repository development:
go test -count=1 ./...
jq empty schema/*.json
git diff --check