# Workflow system blueprint Status: declarative core implemented; pilots remain. Current gates and the operational handoff live in [`plans/workflow-system.md`](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/.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 declares stable launchers for Actual, WhatsApp, and Outlook without duplicating browser state and reclaims their paths when a changed Home Manager generation is deployed. Manual shortcut regeneration may replace one meanwhile and is an accepted unused edge case. 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/.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. Yookr production source is also read-only during these pilots. Development tooling may be changed, and `yookr-workbench` is the explicit source-code exception. Credentials and `.env` files normally stay outside Git, the Nix store, and broad synchronization. Machine-local Yookr credentials use the approved user-key SOPS authority at `~/.config/yookr/credentials.yaml`; callers expose only the fields they need. Original plaintext sources remain until their consumers are verified and removal is explicitly approved. 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 - Visually confirm the two MariaDB examples in Dadbod. The workbench environment, four SOPS-derived Dadbod connections, both MongoDB connections, all four read-only example-query runs, and Kulala response chaining already passed. Add a Marimo report only for a real cross-system investigation. - Add another ephemeral read-only rclone remote only when credentials for a new Leafcloud project become available. Irristaud listing has passed; do not upload. - Use the reviewed local Yookr OpenAPI contract while the accepted malformed generated test document remains deployed. - Finish only the notification and detach/reattach observations for the Herdr pilot. Its Codex/Claude fallback, attention states, local branches, parallel non-overlapping plans, and dirty-removal guard passed with issue 197; the plans show that implementation belongs outside the dashboard repository. - 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](https://nix.dev/manual/nix/latest/command-ref/new-cli/nix3-flake-init), [nix-direnv](https://github.com/nix-community/nix-direnv), [just manual](https://just.systems/man/en/), [Podman Compose](https://docs.podman.io/en/latest/markdown/podman-compose.1.html), [Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html), [Marimo](https://docs.marimo.io/). - APIs/data: [Kulala](https://kulala.app/), [Dadbod](https://github.com/tpope/vim-dadbod), [RabbitMQ management](https://www.rabbitmq.com/docs/management), [rclone S3](https://rclone.org/s3/), [rclone OneDrive/SharePoint](https://rclone.org/onedrive/). - Desktop: [Walker](https://walkerlauncher.com/docs/providers), [Elephant menus](https://github.com/abenz1267/elephant/tree/master/internal/providers/menus), [Vivaldi web apps](https://help.vivaldi.com/desktop/miscellaneous/progressive-web-apps/), [Niri IPC](https://niri-wm.github.io/niri/IPC.html). - Agents: [Codex configuration](https://learn.chatgpt.com/docs/config-file/config-basic), [Codex long-running work](https://learn.chatgpt.com/docs/long-running-work), [Herdr](https://herdr.dev/docs/configuration/), [Git worktrees](https://git-scm.com/docs/git-worktree). - PIM/knowledge: [Evolution account types](https://help.gnome.org/evolution/intro-account-types.html), [Radicale](https://radicale.org/v3.html), [DAVx5](https://manual.davx5.com/introduction.html), [Tasks.org](https://tasks.org/docs/), [`zk` daily journal](https://github.com/zk-org/zk/blob/main/docs/tips/daily-journal.md). - Infrastructure: [Gardenctl](https://gardener.cloud/docs/gardenctl-v2/), [NetworkManager](https://networkmanager.pages.freedesktop.org/NetworkManager/NetworkManager/nmcli.html), [Syncthing](https://docs.syncthing.net/users/syncing).