SouveraineOS/docs/tasks/77-lens-garden.md

77 — The lens: a human-first garden over a git vault

Status: r21 is signed, archived and installed on x86_64; the same source is packaged for AArch64 but not device-exercised. Last checked 2026-08-25. Owner: Rook, under Casey's direction. Repo: ~/Projects/souveraine-lens (gitea Fimeg/souveraine-lens, branch primary).

Origin: the 2026-08-15 session (ses_ffb2ae46…). Casey asked why the lens was not installed on the laptop, then: "make it into a proper package… overhaul everything please… Lens is built for the human first… the agent is coming alongside to help the human… not use it for its own space." Then, on the garden itself: folder/subcategory support — "Project SouveraineOS → Souveraine the Agent / Souveraine the Substrate → their components, as I understand them, not just how the Agent understands them" — and "dump ideas down and have them analyzed by my agent for connections."

The shape — decided

• Human-first. The lens is for a person (several, eventually). The agent never lives here; it comes alongside as a guest over the limb — open a note, plant one on a human's behalf, read events over the socket. The vault is never synced into the SouveraineOS docs tree.
• The vault is files, git is the archive. ~/vault, markdown + frontmatter (description, tags, anything else round-tripped), [[wikilinks]] as the linking grammar, every save/plant a git commit.
• Zero dependency, no network. One embedded page (src/ui.rs); the only conversation is the IPC bridge. The force layout is hand-rolled.
• The seam. Page → process: graph note save create sync status. Process → page: window.__lens.reply/open/refresh/sync/create.
• The limb. --ipc <sock>: the shell drives the process (eval state open create quit), the process emits one-line events (note_opened, note_saved, note_created, synced) so a sidebar hears without reaching into the vault.
• Folders (this session): a note may live in any folder under the vault — real directories, not a tag layer, so the files stay legible to git and to Casey directly. The rail grows a folder tree; the plant dialog takes a folder; a capture line plants a thought straight into inbox/. Folder paths are guarded so nothing can climb out of the vault.
• Idea capture → connections. The dump surface is the inbox. The analysis for connections is the substrate agent's job over the limb, not a lens feature — the lens shows links and backlinks; the agent is the one who walks the vault and proposes joins. Prior art: the Cloister folder tree (docs/substrate/tasks/tui-memory-browser.md), the Archivist synthesis pass (souveraine/src/core/archivist/mod.rs), and the OpenCode Memory System's association accelerator (~/Downloads/Memory stuff/docs/PRD.md §5.7).

Acceptance

• Lens UI overhauled (two themes, [[ linking, backlinks, palette, guide).
• Packaging source exists: PKGBUILD + .desktop + icon + two CI package paths + edge publisher.
• Folder/subcategory support + inbox capture (commit 61cf534).
• Edge publisher executable (commit c71c7e4) — fixes run 1632's exit 126.
• r21 (0.1.r21.gf01a2fcb2b1e-1) is signed in the internal souveraine-x86_64 archive and installed as a pacman-owned x86_64 binary on the laptop; pacman -Qkk reports 17 files and 0 altered files.
• Internal edge repo DB wiring exposes souveraine-lens by name.
• The distribution manifest owns souveraine-lens for x86_64 and AArch64, and both producer jobs refuse artifacts outside that contract.
• CI run 2180 built, signed and published x86_64 and AArch64 r21 packages; AArch64 remains package proof, not installation or runtime proof.
• The exact r21 SHA passed the public-candidate source gates in run 2195.
• Exercise r21 from a newly started packaged process on the laptop; verify folder tree, capture → inbox, linking, named agents, amend step-up, and link-preserving moves.

Evidence

• souveraine-lens/DESIGN.md is the in-repo system argument (garden, seam, face, limb, delivery).
• Prior-art docs read: 73-self-dashboard.md (lens skeleton precedent), 68-shared-household-state.md, FIRST-CLASS-APPS.md, SHARED-STATE-ARCHITECTURE.md; kiyoshi (~/Projects/references/kiyoshi/) is the visual reference — sampled, not copied.
• Gitea Actions run 2180 is green on primary at f01a2fcb2b1e; its edge release contains r21 packages and detached archive signatures for both architectures. Run 2195 is green on the exact public candidate SHA.
• On 2026-08-25, the package signature verified against the Souveraine archive key. pacman -Q reported souveraine-lens 0.1.r21.gf01a2fcb2b1e-1, and pacman -Qkk reported 17 files with 0 altered files.
• Lens processes already running during the upgrade were deliberately left alone. They retain their old in-memory image until Casey reopens them; the r21 package is installed, not yet newly launched and exercised.
• The internal public candidate exists and is green. No anonymous Lens Forge repository exists yet; publication remains owned by the central rail.

Remaining work

1. Reopen the packaged r21 process and exercise its UI and limb on the laptop.
2. Do not infer AArch64 install or runtime behavior from the green cross-package path; exercise it on a declared AArch64 target when that deployment is wanted.
3. Project souveraine-lens to the public Forge through the central publication rail before changing Cargo or PKGBUILD source URLs to a public repository.
4. The shared-task lane when TASK-68's authority shape lands (the agent assigns human tasks through the vault; the lens surfaces them as notes).
5. The "agent analyzes dumped ideas for connections" lane — substrate-side, over the limb; not built.

Connections

• 73-self-dashboard — the lens skeleton is the Gatehouse precedent.
• 68-shared-household-state — the authority shape the lens's task lane will implement.
• 69-agent-usage-session-daemon — "shell services are projections of one socket" is the limb's shape.
• substrate tui-memory-browser.md + archivist/mod.rs — the Cloister and the synthesis pass this garden samples.