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`](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

<!-- markdownlint-disable MD013 -->

| 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 |

<!-- markdownlint-enable MD013 -->

## 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,
  reclaiming their paths on activation. Manual shortcut regeneration may replace
  one until the next activation 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/<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.

<!-- markdownlint-disable MD013 -->

- 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).

<!-- markdownlint-enable MD013 -->