# PANDO — fewer ways to lose a thought

Notes apps die the same way every time: capture gets slower than forgetting.
Pando is the version with fewer moving parts and fewer ways to lose the
plot — plain markdown files, links that make themselves, a garden view where
your vault grows as a fern, and an MCP socket so Claude can actually use what
you know. **Zero dependencies.** Nothing leaves your machine unless you
explicitly turn on Claude enrichment. Built by one operator (HoldFern) who
kept losing good ideas to bad capture.

Free software under **AGPL-3.0** — see `LICENSE`. © 2026 Matt Barber.

## Quick start (Windows)

1. **EXTRACT the zip first.** Do not run anything from inside the archive —
   Windows will happily show you the files but nothing can run in there.
   Right-click the zip, Extract All, e.g. to `Documents\Pando`.
2. **Install Node.js LTS** (once). In an admin terminal:
   `winget install OpenJS.NodeJS.LTS` — or get the LTS installer from
   https://nodejs.org. Pando is zero-dependency, but it is a Node app;
   Node is the only thing it needs. Close and reopen your terminal afterward.
3. **Double-click `start.bat`** in the extracted folder. It checks for both of
   the above and tells you exactly what is missing if something is off.
4. **Open the URL it prints** — it contains your one-time session key and sets a
   secure cookie. After that, plain **http://127.0.0.1:7423** just works; bookmark it.

No `npm install`, no build step, no accounts. To use Pando from another browser
or after clearing cookies, use the printed URL again (the key lives in
`.brain/session.token`; delete that file to rotate it).

## The 60-second tour

| Do this | Get this |
|---|---|
| `Ctrl+K`, type a thought, Enter | Timestamped capture in `Inbox/` — zero friction |
| Write `[[Some Idea]]` in any note | A link — even before "Some Idea" exists (ghost links are tracked) |
| Open any note | Right rail: backlinks + **Related** picks, each with a *why* |
| **Consolidate** button | Vault health: orphans, most-wanted missing notes, duplicates, links that want to exist, themes |
| **Memory** button | Old-but-relevant notes resurfaced, "on this day", current focus |
| **Context** button | A ranked, provenance-tagged markdown briefing on any topic — copy into any AI |
| **Garden** button | Your whole vault as a fern — fronds are sections, leaves are notes; click in and each section grows as its own plant (monstera projects, bamboo dailies, succulent resources) with a leaf-rustle as you move. Snd toggle in the top bar. |
| **Today** button | Auto-created daily note |
| `history` in the note header | Every previous version of the note, restorable |

Archive replaces delete: nothing in Pando is ever destroyed.

## Your data, concretely

- `vault/` — your notes. Plain markdown. This folder **is** your brain; everything
  else is derived. It opens fine in Obsidian, VS Code, anything.
- `.brain/history/` — automatic snapshots of every overwritten version.
- `.brain/activity.jsonl` — your open/edit/capture timeline (powers resurfacing).
- `.brain/config.json` — settings, including the optional Claude API key.
- `.brain/session.token` — your local session key (delete to rotate).

**Backup = copy the folder.** Sync = put it in OneDrive/Syncthing/git — it's just files.

## Claude integration (optional, two ways)

**1. Enrichment in the UI** — add an Anthropic API key in Settings (stored only in
`.brain/config.json`, sent only to `api.anthropic.com`). Unlocks per-note
`ai·summary`, `ai·tags`, `ai·links` and "Ask Claude to prioritize" in Consolidate.
Written and code-reviewed but not live-tested in this build (needs your key).

**2. MCP — make Claude a client of your brain.** Add to
`claude_desktop_config.json` (Claude Desktop → Settings → Developer):

```json
{
  "mcpServers": {
    "pando": {
      "command": "node",
      "args": ["C:\\Users\\YOU\\Documents\\pando\\mcp-server.js"]
    }
  }
}
```

Claude gets 8 tools: `search_notes`, `read_note`, `write_note`, `capture_thought`,
`build_context`, `related_notes`, `consolidation_report`, `list_recent`.
Prefer Claude not write to your vault? Set env `PANDO_MCP_READONLY=1`.

## Security posture (v0.2 hardening)

- Binds **127.0.0.1 only** — hardcoded, not configurable. Remote access is a
  future feature with real auth, not a flag.
- **Session auth**: random persistent token → `HttpOnly` `SameSite=Strict`
  cookie; `Authorization: Bearer <token>` for scripts; timing-safe compares.
- **Host-header allowlist** — blocks DNS-rebinding attacks from web pages.
- **JSON-only writes** — blocks cross-site form/text CSRF.
- **CSP with per-boot nonce** on the UI, `X-Frame-Options: DENY`, `nosniff`.
- Path traversal blocked at one choke point; 2 MB note / 2.5 MB request caps.
- Zero dependencies = the supply chain is Node itself. No telemetry, ever.

Details and reporting: `SECURITY.md`. Run the 20-check battery yourself:
`node scripts/smoke.js`.

## Documentation

Full guides live in [`docs/`](docs/) — install, user manual, architecture, data &
security, Claude/MCP integration, public-launch security, maintenance, and the roadmap. Start at [docs/00-START-HERE.md](docs/00-START-HERE.md).

## FAQ

- **Change the port?** `set PANDO_PORT=8000` before starting.
- **Move the vault elsewhere?** Set `PANDO_ROOT=C:\path\to\folder`.
- **Edit notes in other apps?** Yes — Pando detects external changes and reindexes.
- **Phone?** Roadmap (BLUEPRINT.md). The vault syncs anywhere as plain files today.
- **Extend it?** Drop a JS file in `plugins/` (see `plugins/README.md`) or script
  the JSON API — the UI has no special powers. Contributions: `CONTRIBUTING.md`.

See **BLUEPRINT.md** for architecture and the upgrade roadmap.