lux/docs/workflow-discovery.md

Workflow system blueprint

Status: declarative core implemented; pilots remain. Current gates and the operational handoff live in plans/workflow-system.md.

This document is the durable design for the workstation and surrounding Yookr workflow. Implementation history belongs in Git.

Governing intent

Build a quiet, keyboard-first control plane over development, investigation, operations, agents, and personal knowledge. Keep the system small and give each intention one canonical owner.

• Standardize vocabulary and entry points without forcing unlike workloads onto one implementation.
• Put frequent actions on direct keys and less frequent actions on their owning discovery surface.
• Keep stable packages, services, integration, and durable preferences in Nix. Keep credentials, sessions, databases, caches, and other mutable state with their owning application.
• Prefer native file formats and supported application layers. Add wrappers only for demonstrated gaps.
• Repositories own reproducible development context, executable project documentation, and code-specific artifacts.
• Select local, test, or live per operation; do not depend on an ambient production context.
• Make production and destructive actions more deliberate than navigation and read-only inspection.
• Promote automation only after the manual workflow repeats and can be verified.
• Optimize conceptual complexity and review burden, not package count or line count in isolation.

The main coordinates are scope (work, own, ext, or forks), Yookr domain, environment (local, test, or live), and intention (develop, inspect, query, review, operate, or deploy).

Ownership model

Intention	Canonical owner
Find applications, projects, or windows	Walker/Elephant and direct Niri bindings
Search personal passwords	Walker with rbw; company Bitwarden stays in its browser extension
Navigate browser state	Vivaldi Quick Commands
Arrange windows and displays	Niri dynamic workspaces
Work in a terminal	Kitty
Edit related files and views	Neovim
Enter a repository environment	direnv with nix-direnv
Discover project actions	just --list
Run edited first-party code	Native processes, optionally Process Compose
Run a container-only project stack	Rootless Podman Compose
Run a persistent containerized user service	Rootless Podman Quadlet
Run a durable host service	NixOS modules and systemd
Exercise APIs	Kulala and xh, with tracked .http files
Query databases	Dadbod and native driver CLIs
Investigate across Yookr systems	yookr-workbench
Connect the Yookr VPN	NetworkManager/OpenVPN through Noctalia
Inspect test Kubernetes	just k8s test using Gardenctl and read-only K9s
Inspect RabbitMQ	Official management UI; rabbitmqadmin for exact terminal operations
Browse S3-compatible storage	Native rclone commands
Capture and find notes	zk through Neovim in one synchronized Markdown notebook
Present work and personal PIM	Evolution pilot beside Thunderbird and Outlook
Present personal PIM on Android	DAVx5, aCalendar+, Google Contacts, and Tasks.org
Give agents durable project context	AGENTS.md and project commands
Run top-level agents	Herdr on demand
Maintain conversation state and subagents	Each native agent, primarily Codex
Review local changes	LazyGit in the task checkout
Review pull requests	gh, then a review worktree when local checks are useful

Repository contract

Active work repositories live under ~/dev/work; inactive repositories live under ~/dev/work/.archive, and worktrees under ~/dev/work/.worktrees. Repositories and worktrees never live under ~/sync.

Participating repositories use the following small contract:

• A tracked .envrc enters the default flake development shell without starting services, fetching data, or mutating the checkout.
• flake.nix owns reproducible dependencies, checks, packages, and formatting.
• just --list indexes non-obvious tasks and delegates to native commands.
• AGENTS.md contains concise project facts, invariants, architecture pointers, and checks without duplicating global guidance.
• Service-owned .http and schema-owned .sql files stay beside their owner; generated views, caches, and scratch output do not become durable sources.
• Secrets enter at runtime from an approved source or a user-only file outside checkouts, initially ~/.config/yookr/<repository>.env.
• A new worktree behaves like a fresh clone and requires its own explicit direnv allow.
• Branch-derived ports, databases, and container names are added only after a real collision.

Use Process Compose only when multiple foreground processes benefit from one visible lifecycle. Use Podman Compose for wholly containerized project stacks, Quadlet for persistent user containers, and NixOS modules for durable host services. Do not nest lifecycle tools for another status screen.

yookr-workbench owns cross-system API requests, operational queries, the Garden/Kubernetes entry point, and Marimo investigations. It does not collect service OpenAPI specifications, schema migrations, deployable model code, or copied application state.

Interaction and knowledge boundaries

• Walker scans the four repository roots, excludes .archive and .worktrees, and invokes one Nix-owned open-project command. The command opens Kitty at the repository root, starts Neovim, and leaves a shell after Neovim exits.
• Vivaldi remains the bookmark and web-app authority. Home Manager owns stable launchers for Actual, WhatsApp, and Outlook without duplicating browser state. Its Operations folder owns visibly labeled test/live RabbitMQ bookmarks; terminal inspection uses the Nix-provided rabbitmqadmin-ng on demand.
• Niri keeps dynamic general-purpose workspaces and a compact navigation and movement vocabulary. The two-output active-workspace exchange remains a bounded pilot.
• Codex is primary; Claude Code and Pi are fallbacks. Herdr owns persistence and attention for top-level sessions, while each agent owns its internal state.
• Use one primary writer per checkout. Subagents may perform bounded independent read-heavy work, but overlapping changes are sequenced.
• Substantial multi-session work may keep one living docs/plans/<task-slug>.md; lasting knowledge moves to normal documentation and transient execution history is removed when finished.
• ~/sync/notes is the Markdown/zk authority. Daily intake uses daily/YYYY-MM-DD.md; planned meetings and raw transcripts use meetings/ and transcripts/ respectively.
• Microsoft 365 remains authoritative for work/university PIM and Radicale for personal CalDAV, VTODO, and CardDAV. Clients present those authorities without bridging or copying them.
• Fossify records on Android and Syncthing delivers completed recordings to Orion. Orion owns event-driven CPU transcription, diarization fallback, archival, and Markdown publication.

Safety boundaries

GitHub and all other remotes are read-only. Local commits, clones, fetches, and worktrees are allowed; remote mutation requires a separate change to policy.

Credentials and .env files normally stay outside Git, the Nix store, and broad synchronization. The accepted yookr-vpn.ovpn is a narrow exception for Zenith and Polaris: keep it user-restricted and import it into NetworkManager without printing or committing its contents.

yookr-data-science/conf/local/credentials.yml is a separate application-owned exception: Kedro resolves its named credential dataset through the conventional ignored conf/local hierarchy. Keep the file untracked and mode 0600; do not generalize the exception to other repositories.

Only the user activates a NixOS or Home Manager generation. Agents may evaluate and build configurations, then provide an activation command.

Remaining pilots

• Verify the labeled RabbitMQ test/live bookmarks and a read-only test overview plus queue listing through an invocation-scoped rabbitmqadmin-ng run.
• Add workbench database connections and a Marimo report only for a real cross-system investigation.
• Configure an S3 remote only for a real task with least-privileged credentials and explicit upload authorization.
• Rerun the Yookr OpenAPI refresh after the deployed image exposes /full-api-docs/openapi.json; run authenticated API checks only with current user credentials.
• Run the complete Herdr notification, fallback-agent, and safe worktree pilot with a real Monday ticket.
• Keep Bruno, DBeaver, and existing PIM clients until their independent gates are resolved.

Deferred pilots

• Capture Zenith's external display identity during a docked session and test the two-output Super+A exchange, including name and focus restoration on failure.
• Resume Evolution and Android PIM only when the user chooses to run those daily use pilots.
• Replicate the proven workstation workflow on Polaris only when the user resumes its machine-local VPN and credential procedure.

Deferred work

• Define the team release process and OpenAPI publication policy before encoding deployment automation.
• Adopt a company-wide infrastructure secret source only after Yookr selects one.
• Publish yookr-workbench only when sharing becomes useful.
• Pilot SharePoint browse/download through rclone after Microsoft consent.
• Revisit Worktrunk, codex agents, Walker-to-agent launching, formal agent evaluation, remote builders, CI runners, and agent offload only after a concrete gap appears.
• Add report servers, notebook hubs, groupware, terminal PIM, meeting summaries, concurrency isolation, OCR, dictation, clipboard remapping, or additional convenience surfaces only after repeated use establishes an owner.

Reference baseline

Recheck fast-moving interfaces against their pinned versions before changing them.

• Projects: Nix flake templates, nix-direnv, just manual, Podman Compose, Quadlet, Marimo.
• APIs/data: Kulala, Dadbod, RabbitMQ management, rclone S3, rclone OneDrive/SharePoint.
• Desktop: Walker, Elephant menus, Vivaldi web apps, Niri IPC.
• Agents: Codex configuration, Codex long-running work, Herdr, Git worktrees.
• PIM/knowledge: Evolution account types, Radicale, DAVx5, Tasks.org, zk daily journal.
• Infrastructure: Gardenctl, NetworkManager, Syncthing.