Metadata-Version: 2.4
Name: si-cartographer
Version: 0.1.0
Summary: Charts the workspace as graphed knowledge. The agent that thinks with its pen.
Author: SuperInstance
License-Expression: MIT
Keywords: knowledge-graph,procedural-memory,wiki,chart,exo-filed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# cartographer

*The agent that charts the workspace as graphed knowledge.*

---

The **cartographer** doesn't run tasks. The cartographer **charts** them.

Every solution becomes a reusable script. Every dead-end becomes a hazard note. Every cross-repo connection becomes an edge on the knowledge graph. The graph is exo-filed (markdown + JSON) so humans and agents can both read it.

## The maritime role

The **deckhand** (sibling: [`able-bodied-crew`](https://github.com/SuperInstance/able-bodied-crew)) runs tasks — indexes, retrieves, batches, executes.

The **cartographer** charts — documents solutions, maps hazards, draws coastlines, writes chronicles. Pen-on-paper. Thinks with its pen.

```
Deckhand runs the task → solves the problem → calls Cartographer
Cartographer charts the solution → writes the script → notes hazards
Next time the same problem appears → Cartographer finds the chart → Deckhand runs the known-good script
```

## What it does

- **KnowledgeGraph** — nodes (repos, concepts, scripts, hazards) and edges (references, dependencies, solved-by). Stored as JSON + markdown. No database.
- **ChartMaker** — writes reusable scripts, hazard notes (what NOT to do), and procedure docs. Tests scripts automatically.
- **CoastlineBuilder** — generates maps at three zoom levels: 1000ft (fleet at a glance), 100ft (each repo in detail), 10ft (file-level for one repo)
- **Navigator** — given a problem, finds the nearest documented solution or hazard
- **Chronicler** — writes daily chronicles (the thinking-with-pen record)

## Install

```bash
pip install si-cartographer
```

## Use

```bash
# Build knowledge graph from workspace
cartographer graph /path/to/workspace

# Generate coastline maps
cartographer coastline /path/to/workspace

# Find a solution
cartographer navigate "How do I publish to PyPI?"

# Write to the chronicle
cartographer chronicle --section "PyPI" --message "Published si-cartographer v0.1.0"
```

## License

MIT

---

*Built by SuperInstance. The cartographer charts the rocks so the deckhand doesn't hit them.*
