docs: replace viridian plan with the current design
Supersedes both the June server-centric plan and the unmerged
Automerge-replica rewrite.
Assisted-by: Claude Opus 5.5 via Claude Code
diff --git a/docs/ideas/viridian-design.md b/docs/ideas/viridian-design.md
new file mode 100644
index 0000000..1053fd3
--- /dev/null
+++ b/docs/ideas/viridian-design.md
@@ -0,0 +1,259 @@
+# Viridian design
+
+## Scope
+
+This document records the current goals and design for viridian, a
+personal knowledge system with a `viri` CLI and a native iOS app. It
+covers the goal, the node and component model, storage and sync, gardens
+and the cross-garden link rule, the leak check, editing, queries,
+publishing, and the first buildable slice.
+
+It doesn't cover the query language, the public authoring web UI's
+feature set, POSSE syndication, assets, archiving, semantic clustering,
+the work garden's own infrastructure, or a web or macOS app, which may
+come later. Those are deferred, and the
+unsettled ones are listed under [open questions](#open-questions).
+
+This is a design record for the author, who is also the implementer. It
+assumes familiarity with markdown, git, jujutsu's change ids,
+[Automerge][automerge], SQLite, and Tailscale.
+
+[automerge]: https://automerge.org/
+
+## Goal
+
+Viridian exists to give notes structure that can be queried. The notes
+in `archive/notes` already hold structured data by hand. For example, a
+restaurant note carries `url` and `address` frontmatter, `#restaurant
+#seattle` tags, and dated sections about visits. A separate "seattle
+restaurants" note lists restaurants by hand and has drifted out of step
+with the per-restaurant notes. Viridian should replace a list like that
+with a query.
+
+Capture from anywhere, including a phone, matters but ranks below
+structure. Daily journaling is not a goal, and the journal pages in
+`archive/journal` don't need a model of their own.
+
+## Nodes, components, and entries
+
+Everything in viridian is a **node**. Every node has a fixed core: a
+change id, a garden, a slug, and a creation time. A node also carries
+zero or more components.
+
+A **component** is a named piece of data attached to a node. The
+**body** is the one unstructured component: the node's markdown text. A
+node has at most one body, and a node without one, such as a bookmark,
+is valid. Most imported notes carry a body and nothing else.
+
+Every other component is a named group of short, typed fields, such as
+`restaurant` with `url`, `address`, and `status`. Each one has a schema,
+declared up front, and viri-core validates every component against its
+schema on every write. Schemas validate components, not whole nodes, so
+a node can carry several components or none. Long-form text belongs in
+the body, not in a field, so a recipe's instructions go in its body.
+
+The model follows the entity component system (ECS) pattern, with a
+node as the entity. The processes that act on components, such as the
+indexer, the site build, and the leak check, are its systems.
+
+A node may also be an **entry**: an immutable, timestamped node attached
+to a parent node by the parent's change id. Entries record the history
+of a subject, while the parent stays freely editable.
+
+Node ids are jujutsu-style random change ids, displayed by their
+shortest unique prefix. Body files are named `<change-id> <slug>.viri`,
+and links reference only the change id, so a slug can change without
+breaking links. Importing the archive migrates each legacy 12-digit
+timestamp id to a new change id and rewrites the links that use it. The
+old ids are not kept as aliases.
+
+## Storage
+
+The body is stored apart from everything else. This document calls a
+node's core fields and its other components its **metadata**. Bodies and
+metadata live in separate stores with separate sync engines. The
+following table shows where each kind of data lives:
+
+| Data | Store | Sync |
+|---|---|---|
+| Bodies | One git repo of `.viri` files per garden | git push and fetch |
+| Metadata (core fields, other components, typed relationships) | Automerge, one document per node, plus one root document per garden that lists its nodes | Automerge sync |
+| Query index | SQLite, one per device | Not synced; rebuilt from the other two |
+
+Metadata owns a node's identity and existence. A node exists when its
+metadata document exists, and deleting a node writes a tombstone to its
+metadata. A device that holds a body file without the matching metadata
+hides the file until the metadata arrives. A device that holds metadata
+without the body yet shows the node with its body pending.
+
+Because each node has its own metadata document, a garden's root
+document is the access boundary. A process given only the public root
+never receives personal metadata. The cost is that Automerge can't
+change several documents atomically, so an operation such as creating an
+entry and linking it to its parent spans two documents.
+
+Keeping bodies in git means concurrent body edits from two devices
+surface as git conflicts instead of merging character by character.
+
+## Devices and sync
+
+Every device holds full copies of the gardens it can see and syncs them
+whenever it reaches a peer. An always-on server is one of those peers,
+not an authority. It relays git and Automerge changes between devices
+that are rarely online together, builds the static site, and hosts the
+public authoring web UI.
+
+The following table shows what each device holds and how it's used:
+
+| Device | Gardens held | Interface |
+|---|---|---|
+| Personal laptop | Personal, public | `viri` CLI, `viri edit`, and jj on garden working copies |
+| iPhone | Personal, public | Native iOS app |
+| Server | Personal, public | Sync relay, site build, and authoring web UI |
+| Work laptop | Work only | A browser for editing public through the authoring web UI |
+
+The iOS app is a SwiftUI shell over viri-core, a Rust crate exposed
+through UniFFI. viri-core embeds the git and Automerge libraries, so the
+CLI and the app share one implementation of sync, schemas, and
+validation.
+
+## Gardens and scope
+
+A **garden** is a set of nodes with a single scope that governs both
+which devices sync it and who can see it. The following table shows the
+three gardens:
+
+| Garden | Copies held by | Served to |
+|---|---|---|
+| Personal | Personal laptop, iPhone, server | Your devices, over Tailscale |
+| Public | Personal laptop, iPhone, server | The internet, as a static site |
+| Work | The work machine | The work machine only |
+
+The personal garden's git remote and Automerge relay are reachable only
+over the tailnet, so the network enforces personal's scope. The public
+garden's git repo may live on an internet-facing forge.
+
+The work laptop can't join the tailnet or run custom tooling. It edits
+public through the authoring web UI, which is the only internet-facing
+write surface.
+
+References flow only toward more available gardens:
+
+```
+ personal work most private, incomparable
+ \ /
+ public most available; the sink
+```
+
+`personal → public` and `work → public` links resolve. Links from public
+to anything private, and links between personal and work, are not
+allowed.
+
+## The leak check
+
+The leak check enforces the link rule and the garden boundaries. It
+fails when any of the following is true:
+
+- A public node's body or metadata references a non-public change id.
+- A garden's root document lists a node from another garden.
+- The site build reads anything outside the public garden.
+
+A private change id in public content is an error even though the id
+itself is opaque, because the link text beside it is free-form.
+
+viri-core implements one checker, which runs in these places:
+
+- On every `viri edit` save
+- As `viri check`, run by hand
+- As a local pre-push hook on the public garden's repo
+- In the static site build, which fails closed
+
+Pushes to the public forge are not checked on the server. A leak in a
+hand commit that skips the pre-push hook is readable on the forge until
+the site build catches it. A CI check on the forge may close that gap
+later.
+
+## Editing
+
+`viri edit <change-id>` writes the node to a tempfile as YAML
+frontmatter (the node's other components) followed by the body. An LSP
+flags schema errors while you edit.
+
+On save, viri-core validates the frontmatter against the schemas. If it
+validates, viri-core applies the metadata as Automerge changes, writes
+the body to the garden's working copy, and commits it with a message
+built from the change id and slug. If it doesn't validate, viri writes
+nothing and reopens the editor with the errors as YAML comments at the
+top. Quitting without fixing the errors keeps the buffer in a recovery
+file and changes nothing.
+
+Metadata is edited only through `viri edit` or the iOS app. A body may
+also be edited directly in a garden's working copy and committed by hand
+with jj. Hand edits bypass save-time validation, which is why the leak
+check also runs before pushes and in the site build.
+
+When a fetch produces a body conflict, viri marks the node as
+conflicted. You resolve it with `viri edit` or with jj on the laptop.
+
+## Schema changes
+
+Schema migrations are manual. Before running one, you confirm that every
+device has synced; viri doesn't track devices or enforce this. If a
+device writes against the old schema after a migration, cleaning up
+that data is up to you.
+
+## Links
+
+Links inside a body reference a node by change id only, for example
+`[harissa](viri:kxrvwzpm)`. Typed relationships, such as "recommended
+by" and "source," are component fields in metadata, validated by schema.
+
+## Queries
+
+Automerge stores documents but can't query across them, so each device
+keeps a SQLite index built from two sources: the metadata documents,
+and links parsed out of bodies. The index is disposable. It's never
+edited, synced, or backed up, and losing it means rebuilding it.
+
+## Publishing
+
+The server builds a static site from the public garden alone. A
+published node's URL is `/<short-change-id>/<slug>`. The site resolves
+it by change id, so a stale slug redirects to the current one. URLs from
+the old blog posts in the archive are not preserved.
+
+## First slice
+
+The first buildable slice runs on the laptop only, against the personal
+garden, with no sync. It includes:
+
+- viri-core and the `viri` CLI
+- Declared schemas and validation
+- Automerge metadata stored locally
+- Bodies in a git repo
+- The SQLite index
+- `viri edit`, with validation
+- `viri query`
+- An import of `archive/notes`
+
+This slice tests structure and query against real data before any sync,
+iOS, LSP, site, or web UI work. With only one garden, the leak check
+waits until public exists.
+
+## Open questions
+
+- Where schemas live. They are assumed to be documents in the metadata
+ store, so a new component syncs to every device without a rebuild.
+- The query language exposed by `viri query`.
+- The public authoring web UI's feature set and login mechanism.
+- How entry immutability holds up against hand edits to bodies in git,
+ and whether `viri check` flags edited entries.
+- How the iOS app presents sync conflicts.
+- Which git library viri-core uses. `git2` supports push; whether
+ gitoxide does is unverified.
+- How renames work, given that a slug change renames the body file in
+ git.
+- The work garden's infrastructure, since the work machine can't run
+ custom tooling.
+- POSSE syndication: platforms, which nodes syndicate, and whether
+ replies flow back.
diff --git a/docs/plans/2026-06-20-viridian-design.md b/docs/plans/2026-06-20-viridian-design.md
deleted file mode 100644
index 768a653..0000000
--- a/docs/plans/2026-06-20-viridian-design.md
+++ /dev/null
@@ -1,160 +0,0 @@
-# Viridian design
-
-## Scope
-
-This document records the core architecture for viridian: a personal
-knowledge system with a `viri` CLI and a web UI, served from a single
-always-on personal server. It covers the storage model, the node/entry
-distinction, the garden/scope model, the cross-garden link rule, and how
-devices reach the system.
-
-It does **not** cover features still in early brainstorming: entity types
-and components (the ECS idea), tags and relationship semantics, static
-site generation specifics, assets, archiving, semantic clustering, the
-work garden's own infrastructure, or the `viri edit` LSP projection beyond
-a sketch. Those build on the foundation here and are deferred.
-
-This is a design record for the author, who is also the implementer. It
-assumes familiarity with markdown, SQLite, jujutsu's change ids, and
-Tailscale.
-
-## Architecture: one authoritative server, many clients
-
-Viridian is server-centric. A single always-on personal server holds the
-authoritative store; phones and laptops are clients that reach it over the
-network. There is no peer-to-peer replication and no multi-master sync.
-
-This reverses an earlier peer-sync direction. Earlier plans gave each
-machine a co-equal authoritative store and tried to reconcile them, which
-is a distributed-systems project (CRDTs, op logs, replicated databases).
-Adding phone access made co-equal per-machine stores untenable — a phone
-will not run a CLI, a database replica, and an LSP editor — and a single
-authoritative server removes the reconciliation problem entirely.
-
-The server holds the **personal** and **public** gardens together: prose
-as `<change-id> <slug>.viri` files on disk, and metadata — identity,
-entry/parent links, components, tags, relationships — in SQLite. Both live
-on the same machine, so there is no cross-store sync to manage. The
-SQLite database is authoritative for metadata and is backed up alongside
-the files.
-
-## Access follows the visibility order at the network layer
-
-Each garden's scope determines how it is served, so the visibility order
-becomes largely a network property rather than application logic:
-
-- **Personal** is the `viri` API and web UI, served **only on the
- Tailscale tailnet**. Your personal laptop and phone reach it; the public
- internet cannot route to it. Tailscale supplies device identity, so
- private access needs no separate authentication system.
-- **Public** is served two ways from the same server-side garden: a
- read-only static site on the **public internet**, and an authenticated
- authoring web UI, also on the internet, for editing public content from a
- device that is not on the tailnet.
-- **Work** stays isolated on the work machine, never on the server or the
- phone. It references public, nothing more.
-
-The work laptop drives the authenticated authoring path. It cannot join the
-tailnet and cannot run custom tooling, but it has a browser and can reach
-the internet, so it edits public through the authenticated web UI. This
-adds a single internet-facing write surface for public, where before the
-internet saw only the read-only site. Because the author is a single user,
-the login stays minimal — single-user OIDC or one password over HTTPS, with
-no user-management system. Personal has no internet write surface and no
-route from the internet at all.
-
-## Clients
-
-Each device gets the interface its capabilities and trust level allow:
-
-- **Personal laptop** runs the rich loop — the `viri` CLI, the LSP, and the
- majjit-style editing projection — against the server over the tailnet,
- most likely through a local working copy it checks out and pushes back,
- since the LSP needs files on disk. It can author both personal and public.
-- **Phone** uses the web UI over Tailscale for personal (reading and quick
- capture) and the static site over the internet for public. It keeps no
- local store.
-- **Work laptop** uses the authenticated public authoring web UI over the
- internet. Editing public from work is browser-only: no CLI and no LSP, so
- the rich editing loop stays on the personal laptop. The work laptop never
- reaches personal.
-
-Storage is uniform across every garden: server-side prose files plus a
-co-located SQLite database. The web UI and the static site are different
-front ends onto that one storage model, not different models.
-
-## Nodes and entries
-
-Everything in viridian is a **node**, stored as a `<change-id> <slug>.viri`
-file. There is one kind of node. By default a node is mutable and
-evergreen: you garden it, rewriting freely, and its history is not
-significant.
-
-A node may also be an **entry**. An entry attaches to a parent node and
-records a timestamped moment in that subject's history. Being an entry is a
-property a node takes on, not a separate kind of file — in the ECS sense, a
-component. Entries are immutable and append-only: you add a new entry
-rather than editing an existing one. An entry is still a full node, so it
-can carry its own links, types, and even its own entries.
-
-The first daily workflow is capturing an entry against a subject: open a
-node (a person, a project, a topic) and append a timestamped entry. The
-entry is its own node with its own change id, referencing its parent by the
-parent's change id.
-
-Change ids follow jujutsu's model: globally unique and stable. In the
-filename the change id leads and a single space separates it from the slug,
-so a parser splits on the first space and the slug may contain its own
-hyphens. The slug is human sugar that may drift as you rename; links always
-reference the stable change id, never the slug. The `.viri` file holds
-prose only — markdown body, no frontmatter — because metadata is
-authoritative in SQLite, not in the file. The `.viri` extension drives
-editor and LSP filetype association.
-
-## Gardens and scope
-
-A **garden** is a set of nodes with a single **scope** that governs both
-where it is served and who can see it — one concept, not two:
-
-| Garden | Authoritative location | Served to |
-|---|---|---|
-| personal | the server | your devices, over Tailscale |
-| public | the server | the internet, as a static site |
-| work | the work machine | the work machine only |
-
-## The cross-garden link rule
-
-Scopes form a partial order by availability. References flow only toward
-more-available gardens:
-
-```
- personal work most private, incomparable
- \ /
- public most available; the sink
-```
-
-A node may link to gardens at least as available as its own. `personal →
-public` and `work → public` resolve; `public →` anything private and
-`personal ↔ work` do not. A link resolves only when the consumer can reach
-the target garden; otherwise it degrades to plain text. The network
-topology enforces this: a public-internet visitor cannot route to the
-personal garden, so a leaking link is unreachable by construction.
-
-## Open questions
-
-- **Offline capture.** Server-centric means online-centric: off the tailnet
- or with the server down, you cannot capture to personal. Decide whether
- offline capture matters; if so, clients need a local outbox that syncs
- when reachable.
-- **Laptop client model.** Pure API client versus a local working copy the
- laptop checks out and pushes back, and how the LSP editing loop fits.
-- **Out-of-band edits.** The reconcile rule when prose files on the server
- are changed outside `viri`.
-- **The `viri edit` projection.** How the LSP-backed editable view merges
- metadata and prose and writes changes back.
-- **Public authoring UI scope.** How much of the editing model the
- browser-only public authoring UI exposes, given it has no LSP, and the
- exact login mechanism (single-user OIDC versus a password).
-- **Deferred features.** Entity types and components, tags and relationship
- semantics, static site generation, assets, archiving, and semantic
- clustering.