docs: add web UI design spec

docs/superpowers/specs/2026-06-01-web-ui-design.md

@@ -0,0 +1,235 @@
+# Archivr Web UI Design
+
+## Summary
+
+Archivr's first web UI should open directly to the archive itself: a dense, explicit table of saved entries. The interface should take structural inspiration from ArchiveBox's useful index view, but avoid its older visual treatment and noisy control surface. The tone is a warm archive ledger: serious, fast, preservation-oriented, and modern through restraint.
+
+The first implementation is also a foundational refactor. Archivr should become a Rust workspace with reusable archive logic in `archivr-core`, the current command-line behavior in a CLI crate, and a separate `archivr-server` crate for the web server.
+
+## Product Direction
+
+The home surface is the `Archive` view. It shows saved entries immediately, not a dashboard, capture workflow, or triage queue.
+
+The approved UI direction:
+
+- Use an explicit dense table for entries.
+- Use a warm archive-ledger shell with modern spacing, color, and interaction details.
+- Keep all table text sans-serif.
+- Keep `+ Capture` visible but secondary.
+- Make search the dominant power object.
+- Do not put a tag field beside search.
+- Do not put maintenance controls such as re-snapshot, delete, reset, or bulk action strips beside search.
+- Use a right-side contextual rail for selected-entry information, not as the primary filter system.
+- Leave exact row-click and entry-opening behavior unresolved for now.
+
+The first table should expose practical archive columns such as added time, title, type, size, and original URL. Technical artifact details should be quieter than the entry title and source.
+
+## Search
+
+Search is a major future feature and should be treated as one of Archivr's signature capabilities. For this first slice, search can be a basic server-backed query field or placeholder, but the UI should reserve visual prominence for it.
+
+Search is expected to absorb much of the functionality that might otherwise live in a filter sidebar. The right rail should not become the main filtering interface.
+
+The full search grammar, ranking behavior, saved searches, facets, and advanced search interactions are deferred to a later focused design pass.
+
+## Multi-Archive Model
+
+Archivr should support one web server mounting many independent archives.
+
+Each archive remains portable and self-contained:
+
+```text
+some-archive/
+  .archivr/
+    archivr.sqlite
+    store_path
+    name
+```
+
+The web server has its own registry/config state that points to mounted archive directories:
+
+```text
+server state:
+  personal -> /path/to/personal/.archivr
+  family   -> /path/to/family/.archivr
+  research -> /path/to/research/.archivr
+```
+
+This means Archivr should not merge all archive entries into one global archive database. Instead, the server chooses a mounted archive, opens that archive's own DB, and queries entries/runs/artifacts from there.
+
+The web UI should include an archive switcher once more than one archive is mounted.
+
+## Workspace Architecture
+
+Move toward a Rust workspace:
+
+```text
+crates/
+  archivr-core/
+  archivr-cli/
+  archivr-server/
+```
+
+`archivr-core` owns reusable archive behavior:
+
+- archive directory discovery/opening
+- archive DB schema and access
+- store path handling
+- entry, artifact, blob, source identity, run, user, setting, and tag domain operations
+- archive-scoped query APIs used by CLI and server
+
+`archivr-cli` owns command-line UX:
+
+- argument parsing
+- terminal output
+- process exit behavior
+- invoking `archivr-core` operations
+
+`archivr-server` owns web-server behavior:
+
+- mounted archive registry/config
+- archive switcher data
+- HTTP routes
+- static frontend assets or frontend build integration
+- local development server behavior
+- request routing to the selected archive
+
+The server state must stay clearly separate from each mounted archive's DB.
+
+## Navigation
+
+Use a small top navigation model:
+
+```text
+[Archive Switcher]  Archive  Runs  Admin        + Capture
+```
+
+`Archive` is the main entry table.
+
+`Runs` is archive job history, failures, and progress.
+
+`Admin` is for mounted archive configuration, instance/server settings, and later user management.
+
+`+ Capture` is a button, not a top-level workspace. It can open a capture dialog or page later.
+
+Do not add `Public` as a top-level nav item in the first design. Public/private/unlisted are entry visibility states inside an archive. Public archive publishing UI is deferred.
+
+Do not add top-level `Tags` navigation yet. Tags should be queryable/searchable and appear in entry context, but the first UI does not need a separate tag management workspace.
+
+## Tags
+
+Use the product term `tags` or `hierarchical tags`.
+
+The current `taxonomy` naming should be renamed before UI work builds on it:
+
+```text
+taxonomy_nodes             -> tags
+entry_taxonomy_assignments -> entry_tag_assignments
+```
+
+Proposed tag columns:
+
+```text
+tags.id
+tags.tag_uid
+tags.parent_tag_id
+tags.name
+tags.slug
+tags.full_path
+```
+
+Examples:
+
+```text
+/sciences/computer-science/compilers
+/family/recipes/georgian
+/research/ai/evals
+```
+
+Avoid user-facing words such as taxonomy and categories. Internally, code and schema should also move to tag terminology while the project is still early.
+
+## Data Flow
+
+The UI talks to `archivr-server`. The server resolves the selected mounted archive, then calls `archivr-core` against that archive's DB and store path.
+
+Initial API shape:
+
+```text
+GET /api/archives
+GET /api/archives/:archive_id/entries
+GET /api/archives/:archive_id/entries/:entry_uid
+GET /api/archives/:archive_id/runs
+```
+
+The main page loads entries for the selected archive, renders the dense table, and fills the contextual right rail from the selected entry.
+
+Search initially filters or queries entries through the server. The search internals can become more powerful later without changing the high-level UI shape.
+
+## First Implementation Scope
+
+Must have:
+
+- Convert repo toward a Rust workspace.
+- Extract reusable archive DB/store/domain logic into `archivr-core`.
+- Keep existing CLI behavior working through `archivr-cli` or an equivalent transitional CLI crate.
+- Add `archivr-server` as a separate crate.
+- Server can register or mount multiple archive directories.
+- Web UI can switch archives.
+- Main page shows the selected archive's entries in the approved dense table layout.
+- Right rail is contextual and can show selected entry metadata/artifacts.
+- Runs page shows archive run history.
+- Rename taxonomy schema/code language to hierarchical tags.
+
+Should not have yet:
+
+- Full OP search implementation.
+- Full browser capture workflow.
+- Full production authentication/session/permission model.
+- Public archive publishing UI.
+- Final row-click/open behavior.
+- Full tag management UI.
+
+Authentication is deferred except for whatever minimal local-only guard is needed to run the first web UI safely. The production auth/session/permission model needs a separate design pass covering login, sessions, roles, public/private/unlisted access, and multi-archive permissions.
+
+## Testing
+
+Core tests:
+
+- Move existing archive DB tests into `archivr-core`.
+- Test creating hierarchical tag paths.
+- Test assigning an entry to the deepest tag.
+- Test ancestor tag queries still find assigned entries.
+- Test opening an existing archive path returns its DB, store path, and name.
+
+Server tests:
+
+- Mount registry can add/list archives.
+- Invalid archive paths are rejected.
+- Entry list endpoint queries the selected archive.
+- Two mounted archives with separate DBs do not leak entries into each other.
+
+UI/smoke tests:
+
+- Server starts.
+- Archive table page loads.
+- Archive switcher changes selected archive.
+- Selecting an entry can populate the right context rail when that behavior is implemented.
+- Runs page loads.
+
+Before claiming UI work complete, verify the table in a browser at desktop and mobile widths for density, legibility, overflow, and right-rail behavior.
+
+## Open Decisions
+
+- Exact row-click/open behavior.
+- Exact search grammar and advanced search interactions.
+- Browser capture workflow.
+- Public archive publishing UI.
+- Production authentication/session/permission model.
+- Final visual polish.
+
+## Risks
+
+- The workspace refactor will touch many files, so implementation should be staged carefully.
+- Renaming taxonomy to tags should happen before UI work to avoid building on the wrong vocabulary.
+- Server registry state must stay clearly separate from archive DB state.
+- The table can easily feel old if the implementation copies ArchiveBox styling too closely instead of using the approved archive-ledger direction.