souveraine-lens

A wry mind-graph lens over a git-backed markdown vault. A sibling of souveraine-web: the system webview (WebKitGTK), no second engine, no connection to the server.

• Plain markdown files, [[wikilinks]], optional YAML-ish frontmatter (description, tags, anything else round-tripped verbatim).
• The vault is git — every save is a commit, the archive is the truth.
• The graph is a hand-rolled force layout on a canvas; no dependencies, no network. A mirror should be hand-made.

Run

cargo run --release -- --vault ~/vault

First run inits the vault as a git repo with an index.md home note. Point any markdown directory at it — the lens asks no format of its own.

• drag nodes, wheel to zoom, drag the void to pan
• click a node to open the note, double-click the void to plant a new one
• Notes lists the garden; search filters it; drag a note onto a folder to move it; Sync pushes to the remote (ssh/gpg credentials are the user's own, like the substrate's memfs sync)
• the tree button opens the switcher: the garden, then every agent's memory, read-only. Amend… opens one of those for five minutes against your own lockscreen credential, and every write lands in her history saying so

The seam

This process holds no connection to the server. The page is one embedded document; every piece of data arrives over the IPC bridge and the bridge is the only conversation. Your thoughts live on your disk and in your git — the lens is a surface over them, not a home for them.

The limb

The shell drives this process over a unix socket, the rig's own pattern:

souveraine-lens --vault ~/vault --ipc $XDG_RUNTIME_DIR/souveraine/lens.sock

• down: {"op":"eval","script":"..."}, {"op":"state"} (micro-state: the freshest notes and the git truth, one payload), {"op":"open","rel":"..."} (open a note in the lens window), {"op":"create","title":"..."} (plant a note), {"op":"quit"} — one JSON object per line
• up: stdout lines, one JSON object per line — note_opened, note_saved, note_created, synced, state — so the sidebar hears what the garden does without ever reaching into the vault itself

The vault stays the one thing with no other readers.

Package

On a push to primary, CI has separate x86_64 and AArch64 package jobs. Each assembles a signed souveraine-lens pacman package, checks the emitted package against SouveraineOS's distribution manifest, then publishes into the shared edge archive (Fimeg/souveraine). A machine with the matching repository configured and the house key trusted installs it by name:

sudo pacman -Syu souveraine-lens

The package owns /usr/bin/souveraine-lens, the desktop entry and the icon; the vault remains a home-directory git tree pacman never touches. The design argument lives in DESIGN.md.

Current proof, 2026-08-24: x86_64 r20 is signed, indexed and installed as 0.1.r20.gf8c9df352be3-1; AArch64 r20 is signed and indexed. A later source commit is not installed merely because it exists. AArch64 package proof is also not evidence of an installed or running AArch64 Lens.