lux/docs/workflow-discovery.md

# Workflow system blueprint

Status: authoritative design; discovery complete, implementation tracked in
[`plans/workflow-system.md`](plans/workflow-system.md)

Last revised: 2026-09-05

This document is the source of truth for streamlining the workstation and the
surrounding Yookr workflow. It records the intended system, the changes needed
to reach it, the trials that must precede conditional decisions, and work that
is deliberately deferred. Historical exploration and rejected alternatives are
not retained unless they prevent a likely wrong turn.

Remaining uncertainty is empirical rather than conceptual. Every unsettled
choice below has a bounded pilot, a pass condition, and a fallback; it is not an
invitation to resume general tool discovery.

## Governing intent

Build a quiet, keyboard-first control plane over development, investigation,
operations, agents, and personal knowledge. The goal is a small coherent set of
interfaces, not one application pretending to do every job.

The governing rules are:

- Give each intention one canonical owner. A native CLI may remain as a
  troubleshooting substrate without becoming a second documented workflow.
- Standardize vocabulary, entry points, and lifecycle boundaries. Do not force
  unlike workloads onto the same implementation merely for visual uniformity.
- Put frequent actions on direct keys and make less frequent actions
  discoverable through the surface that owns them.
- Keep stable packages, services, integration, and durable preferences under
  Nix. Keep application databases, caches, sessions, trust, credentials, and
  other mutable state with the application that owns them.
- Prefer supported application layers and native file formats. Add adapters or
  wrappers only for a demonstrated gap.
- Repositories own reproducible development context, executable project
  documentation, and artifacts specific to their code or schema. Global state
  is reserved for genuinely cross-project or personal material.
- Select an environment per operation. Do not rely on a long-lived ambient
  production context.
- Keep destructive or production actions more deliberate than navigation and
  read-only inspection.
- Promote automation only after the underlying manual workflow has repeated and
  can be verified. A pilot is not yet a permanent abstraction.
- Prefer maintained free and open-source software. A paid tool is acceptable
  only when it has an unusually strong, non-reproducible advantage.
- Optimize conceptual complexity and review burden, not package count or line
  count in isolation.

The principal vocabulary is:

- scope: `work`, `own`, `ext`, or `forks`;
- Yookr domain: a service/product repository, data science,
  `traceability-data-model`, or the cross-system `yookr-workbench`;
- environment: exactly `local`, `test`, or `live`;
- intention: develop, inspect, query, review, operate, or deploy;
- status: **selected**, **pilot**, **retire after migration**, or **deferred**.

These coordinates compose. They are not stages in a mandatory linear process.

### Explicit exception

Credentials and `.env` files normally stay outside Git, the Nix store, and
broad synchronization. The existing secret-bearing `yookr-vpn.ovpn` is a
user-accepted exception: it may remain in Syncthing for use on Zenith and
Polaris. Restrict the source file to the user where Syncthing permits, never
print or commit its contents, and import it into each machine's root-owned
NetworkManager connection store. Do not generalize this exception.

## Target ownership model

<!-- markdownlint-disable MD013 -->

| Intention | Canonical surface | Owner and status |
| --- | --- | --- |
| Find applications, projects, or open windows | Walker/Elephant | **Selected**; applications plus an Elephant Lua project menu |
| Search personal passwords globally | Walker with `rbw` | **Selected** for personal Vaultwarden; company Bitwarden remains in its browser extension |
| Navigate tabs, history, bookmarks, and browser commands | Vivaldi Quick Commands (`F2`) | **Selected**; Vivaldi remains the only bookmark authority |
| Arrange windows and displays | Niri | **Selected**; dynamic workspaces and no application-specific display roles |
| Work in a terminal | Kitty | **Selected**; no routine Kitty tiling or second terminal implementation |
| Edit related files and views | Neovim | **Selected**; buffers and temporary splits, without automatic session restoration |
| Enter a repository environment | `direnv` with `nix-direnv` | **Selected**; tracked `.envrc` and a default flake development shell |
| Discover non-obvious project actions | `just --list` | **Selected** for participating repositories; recipes delegate to native tools |
| Run actively edited first-party code | Native processes, optionally Process Compose | **Selected** for fast reload and debugger access |
| Run a container-only repository stack | Rootless Podman Compose | **Selected**; foreground, explicit, and scoped to the work session |
| Run a persistent containerized user service | Rootless Podman Quadlet | **Selected**; user systemd owns lifecycle and logs |
| Run a durable host service | NixOS module and systemd | **Selected** when a maintained native module fits |
| Exercise APIs | Kulala and `xh` | **Selected**; JetBrains-compatible `.http` files are the durable artifact |
| Query databases | Dadbod and native driver CLIs | **Selected**; named machine-local connections and repository-owned queries |
| Investigate across Yookr services | `yookr-workbench` | **Selected**, initially local to Zenith |
| Connect the Yookr VPN | Noctalia Network control center | **Pilot** NetworkManager/OpenVPN migration; OpenVPN 3 remains the fallback until both hosts pass |
| Inspect test Kubernetes | `just k8s test` to Gardenctl and `k9s` | **Selected**; isolated session and unchanged parent shell |
| Inspect or operate RabbitMQ | Official management UI | **Selected**; `rabbitmqadmin` is the terminal fallback |
| Browse S3-compatible storage | `rclone` | **Pilot**; explicit read/list/copy commands before interactive mutation surfaces |
| Capture and find notes | `zk` through Neovim | **Selected**; one synchronized Markdown notebook and one daily intake path |
| Present work/personal PIM on desktop | Evolution | **Pilot**; server authorities do not change during evaluation |
| Present personal PIM on Android | DAVx5, aCalendar+, Google Contacts, Tasks.org | **Pilot**; the server authorities remain unchanged |
| Give agents durable project context | `AGENTS.md` and project commands | **Selected**; concise facts, invariants, architecture pointers, and checks |
| Run top-level interactive agents | Herdr | **Pilot** for persistence, attention state, notifications, and worktrees |
| Maintain conversation state and internal subagents | Each native agent, primarily Codex | **Selected**; Herdr does not mirror internal subagents |
| Review local changes | LazyGit in the task checkout | **Selected**; Git remains branch/worktree truth |
| Review a pull request | `gh` for metadata/diff, then a review worktree when needed | **Pilot**; do not add another review application yet |

<!-- markdownlint-enable MD013 -->

## Change program

The phases below are dependency ordered. Each change appears once; trial details
live in the evaluation section rather than being restated throughout the plan.

### Phase 1: reconcile state and ownership

#### Repositories and paths

- Before moving any repository, inspect its dirty state, linked worktrees,
  destination collisions, and authored path consumers. Move registered
  worktrees with `git worktree move` where possible and run
  `git worktree repair` after changing a repository root. Do not apply a broad
  filesystem move to unchecked repositories.
- Reconcile the divergent dirty copies of `yookr-dashboard-new` under `~/sync`
  and `~/work/repos` before moving or deleting either. Establish the
  authoritative commit and preserve unique tracked, untracked, ignored, local
  data, and secret inputs deliberately. A general archive operation must not
  choose between these copies implicitly.
- Consolidate source repositories under the existing XDG projects root:
  `~/dev/work/<repository>`. Do not keep the accidental `~/work` root, the
  intermediate `repos/` directory, or a permanent compatibility symlink.
- Keep these work repositories active: `aggregation-api`, `prediction-api`,
  `rules-service`, `yookr-api`, `yookr-dashboard`, `yookr-dashboard-new`,
  `yookr-data-science`, `yookr-management-svelte-redo`, and
  `traceability-data-model` (currently `schemas`). Add `yookr-workbench` when
  its pilot begins.
- Rename `schemas` to `traceability-data-model` during the move. Update authored
  path consumers; generated Codex, shell, and Herdr histories may remain
  historical.
- Move every other repository from the current work inventory intact to
  `~/dev/work/.archive`. This includes `yookr-management-new`,
  `yookr-management-svelte`, `yookr-dashboard-new.old`, `pipelines.old`,
  `yookr-dashboard-new.zip`, `rules-service-hex`,
  `yookr-data-science-no-kedro`, and tutorial repositories. Do not infer active
  status from a product-looking name.
- Archive the small `~/work/rabbitmq` scratch project. Remove the empty legacy
  `.data/mongodb` directory only after a final emptiness check; do not move the
  global `.data` directory into the source tree.
- Make Git identity rules explicit and non-overlapping: work identity below
  `~/dev/work`, personal identity below `~/dev/own`, `~/dev/ext`, and
  `~/dev/forks`. Update the old `~/work` conditional include.
- Treat work/personal labels as identity and navigation boundaries, not privacy
  boundaries. Non-secret work material may synchronize to the Pixel and Orion;
  source checkouts, credentials, and runtime state do not belong in the broad
  `~/sync` tree.
- Remove stale path-bound Codex trust and obsolete approval entries after the
  move. Update the transitional Bruno workspace path only if Bruno still needs
  it during migration.

#### Nix and mutable application state

- Preserve the existing host/profile/capability structure, typed facts,
  flake-parts composition, Home Manager integration, and primary-tool
  indirection. No repository-wide architecture migration is justified.
- Keep flakes and `nh os switch` as the normal activation path. Keep Neovim's
  Lua, wrapper, plugins, language servers, and formatters store-backed; accept
  the measured rebuild cost rather than adding an out-of-store fast path.
- Do not prototype Hjem/Rum, replace flakes with `npins`, or add a separate Home
  Manager activation wrapper. These do not address the accepted ownership
  model.
- Remove the unused `nixpkgs-stable` input and its dead local binding. Let
  Noctalia follow the root Nixpkgs input if the pinned configuration evaluates
  unchanged; describe this as dependency-graph hygiene, not a latency fix.
- Retire or rewrite the stale root `PLAN.md` after checking whether it contains
  unfinished Neovim work. It must not continue to claim that Helix is active.
- Keep Flatpak enabled as an intentionally available installation facility, but
  add no declarative Flatpak manager, remotes, or applications while it has no
  consumers.
- Continue declaring Noctalia's stable policy through Nix. When behavior differs
  from the declaration, inspect its writable XDG state as a second supported
  application layer; keep only genuinely local runtime state there rather than
  adding another synchronization mechanism.

#### Codex configuration ownership

- Rotate the exposed Context7/MCP credential and replace plaintext headers with
  an environment-backed header or supported credential mechanism.
- Generate stable Codex defaults at `/etc/codex/config.toml`: MCP endpoints,
  approval defaults, notifications when Codex owns them, and other durable
  cross-machine preferences. Official precedence makes this a lower-precedence
  default layer.
- Leave `~/.codex/config.toml` writable and machine-local for project trust and
  unavoidable local settings. Review non-trust keys occasionally: promote a
  deliberate cross-machine preference to Nix, retain generated/machine state,
  and remove accidental overrides. Do not add a drift daemon.
- Keep global `AGENTS.md`, intentional rules, and user-authored skills under
  Nix/Home Manager. Keep authentication, conversations, databases, caches,
  downloaded plugins/skills, and generated Herdr integrations untracked.
- Remove the stale `~/.config/codex` tree; its preservation audit found no unique
  authored material worth migrating.

### Phase 2: establish the project contract and Yookr workbench

#### Common repository contract

Participating repositories expose the same concepts without copying an empty
directory taxonomy:

- A tracked `.envrc` enters the default flake development shell and selects only
  non-secret local defaults. Activation must not perform `uv sync`, start
  services, fetch data, or do other mutating/network work.
- `flake.nix` owns reproducible dependencies, packages, checks, and the
  formatter. A flake app remains only when it is an actual runnable or
  distributable program.
- `just --list` is the documented index of non-obvious human and agent tasks.
  Recipes delegate to native commands and omit trivial one-off operations; the
  native CLI remains available for diagnosis without becoming a second catalog.
- Install `just` as a workstation bootstrap tool and include it in participating
  development shells so the repository remains portable.
- `AGENTS.md` records architecture pointers, invariants, project commands, and
  required checks. It stays factual and concise; it does not duplicate generic
  global behavior.
- Service-owned `.http` examples and schema-owned `.sql` files live beside the
  code or schema they describe. Generated views, caches, and scratch results are
  not durable sources.
- Environment selection is per operation. Kulala selects a buffer environment,
  Dadbod selects a visibly named connection, and recipes accept an explicit
  argument such as `just k8s test`.
- Secrets enter at runtime from the service's approved source or a user-only
  machine file outside all checkouts, initially
  `~/.config/yookr/<repository>.env`. A tracked `.envrc` may load that stable
  path with `dotenv_if_exists`.
- A new worktree behaves like a fresh clone. Recreate dependencies, caches,
  generated files, and build output; do not copy ignored state from a main
  checkout. Require an explicit `direnv allow` for each worktree.
- Do not pre-allocate branch-derived ports, databases, Compose projects, or
  container names. Add targeted isolation only after a real task exposes a
  collision.

First prove this contract in `rules-service`, paired with the API workflow in
`yookr-api` and the database workflow in `traceability-data-model`. Only after
two repositories reveal genuinely repeated files should a small native Nix
flake-template repository be extracted. Language-native initializers continue
to own language source layout.

Repository-specific corrections are part of the pilots:

- In `rules-service`, add a README, flake, `.envrc`, `justfile`, and concise
  `AGENTS.md`; document the local run path; correct the obsolete environment
  example; use `test`, not `dev`, for the deployed test environment. Do not
  encode the transitional rollout as a durable `deploy` recipe.
- In `traceability-data-model`, rename the repository and make destructive
  schema recreation an explicitly named reset action rather than the ordinary
  `dev` path.
- In `yookr-data-science`, default ordinary fetching away from live, remove
  `uv sync` from shell activation, keep the deployable soil-moisture pipeline,
  and move only generic cross-system exploration to the workbench.
- In `yookr-dashboard-new`, preserve the useful visible Process Compose
  lifecycle. Expose it through `just dev` when the project adopts the common
  contract instead of maintaining a workflow-only flake app in parallel.

#### Workload lifecycle

- Run actively edited first-party code natively.
- Use Process Compose only for two or more native or mixed foreground processes
  that need one visible lifecycle, dependency graph, and log view.
- Use rootless Podman Compose for a wholly containerized repository stack. Keep
  support stacks manual, foreground, and scoped to a work session; preserve
  named volumes between runs and make running state visible to Podman tools.
- Use Quadlet for persistent containerized user services and NixOS modules for
  durable host services when a good module exists. Do not nest lifecycle tools
  merely to obtain another status screen.
- Configure Podman's external Compose provider deterministically. Do not use
  Compose dotenv behavior as the secret contract.

#### `yookr-workbench`

Create a minimal `yookr-workbench` on Zenith before adding workbench-owned API,
database, or Kubernetes commands. Keep it without a remote while proving its
contents. It owns only cross-system work:

- curated cross-service `.http` requests;
- operational queries and MongoDB scripts that do not belong to one service;
- explicit local/test investigation commands;
- the Garden/Kubernetes entry point;
- uv-managed Marimo analyses, disposable experiments, and report exports.

It does not own service OpenAPI specifications, schema migrations, deployable
model code, general bookmarks, RabbitMQ URLs, or copied application state.
Scratch work is promoted to its nearest durable owner or deleted. Unrelated
personal Dadbod scratch stays under XDG data.

Use Marimo's Python files as the analysis source. Ignore raw/local data and
scratch output. Share source notebooks with technical readers, self-contained
HTML as the faithful general report, browser-produced PDF when the delivery
channel favors it, and individual SVG/PNG files only when a figure is itself the
deliverable. Do not add a notebook hub or report server.

Production data may be used on a developer machine; this streamline adds no
separate anonymization or local-retention policy. Raw datasets and
secret-bearing output still remain outside Git and broad synchronization.

#### API and database workflow

- Make Kulala and `xh` the editor/CLI pair. Keep hand-curated `.http` files as
  durable examples; use `kulala-fmt` OpenAPI conversion only to seed a migration
  or produce a disposable view.
- Commit non-secret `local`, `test`, and `live` metadata in
  `http-client.env.json`. Keep credentials in ignored
  `http-client.private.env.json` or runtime environment variables. Make
  `local` the default environment; keep test/live selection explicit and
  visible per buffer. Kubernetes being test-only does not remove explicit live
  HTTP access.
- Use Yookr API as the first proof. Support the sibling service-owned
  `openapi.yaml` and ignored snapshots fetched from test/live
  `/full-api-docs/openapi.json`. Authenticate through ordinary login and run a
  harmless administrator-authorized read.
- Compare local and network specifications semantically with `oasdiff`. A
  network refresh writes and validates an ignored cache; it never overwrites a
  checked-in contract automatically. Do not add timestamped archives or polling.
- Add `just openapi` to a service only when that repository has a reproducible
  generation command. A service repository remains authoritative for its
  specification; the workbench does not collect copied specs.
- Use Dadbod UI's machine-local named connection store, normally
  `~/.local/share/db_ui/connections.json`, instead of the current single
  `DATABASE_URL` assumption. Name entries
  `<environment>-<service-or-domain>-<engine>`, for example
  `test-rules-mysql`, `test-prediction-mysql`, and
  `local-traceability-postgres`.
- Support PostgreSQL, MySQL/MariaDB, and MongoDB while the migration requires all
  three. Keep relational artifacts as `.sql` and MongoDB artifacts in their
  native JavaScript format. Durable queries belong in repositories; DBUI saved
  queries are personal scratch.
- Prefer read-only credentials for workbench inspection where available.
  Dadbod is not itself a safety boundary. Intentional schema or data mutations
  belong in an owning repository or an explicitly reviewed operation.
- Populate connection URLs manually. Do not extract Kubernetes Secrets or build
  a Bitwarden-to-Dadbod translation layer before manual connection management
  demonstrates a real cost.

#### Kubernetes, RabbitMQ, S3, and SharePoint

- Install `networkmanager-openvpn` on Polaris and Zenith, import the accepted
  VPN profile separately as a root-owned connection with autoconnect disabled,
  give it the same visible name on both machines, and use Noctalia's built-in
  Network control center. Retain OpenVPN 3 until the migration gate passes on
  both hosts.
- Package official `gardenctl` and `gardenlogin` releases through Nix, use the
  nixpkgs OIDC plugin, remove duplicate binaries from `~/.garden` and
  `~/.local/bin`, and replace handwritten Zsh initialization with
  `gardenctl rc zsh`. Keep Garden configuration and kubeconfigs mutable and
  private outside the store.
- Implement `just k8s test` in the workbench. It creates a fresh
  `GCTL_SESSION_ID`, targets Garden `leafcloud-test`, project `ryxtdg8ydl`, shoot
  `test`, derives `KUBECONFIG`, and opens `k9s` in the foreground. The parent
  shell remains unchanged. Use explicit `kubectl --namespace` for exceptional
  terminal work; do not guess a namespace.
- Do not expose live Kubernetes or a deploy command. Image construction and GHCR
  publication remain in GitHub Actions while the team release process is
  unresolved.
- Use the official RabbitMQ management UI for inspection, publishing/getting,
  and purge. Put `https://test.rabbitmq.yookr.org` and
  `https://rabbitmq.yookr.org` in a Vivaldi operations bookmark folder with
  explicit test/live labels rather than duplicating them as workbench recipes or
  Walker actions. Keep `rabbitmqadmin` for exact terminal operations; purge
  remains visibly interactive.
- Pilot one machine-local `rclone` S3 remote using the least-privileged available
  credentials. Begin with `lsd`, `lsjson`, `tree`, and explicit read/copy
  operations. Do not expose `rclone ncdu` initially because its interface also
  deletes and has no read-only mode.
- Reuse `rclone`'s OneDrive backend for a later SharePoint browse/download pilot
  before considering a second SharePoint tool. Do not introduce continuous sync
  or a mount until the real access pattern and company consent are known.

#### Pull-request review

- Use `gh pr view` for metadata/checks and `gh pr diff` for a quick read-only
  review.
- Create a dedicated review worktree when local navigation, tests, or agent
  assistance are needed, then use LazyGit in that checkout.
- Add no PR dashboard or wrapper until repeated reviews expose a specific gap.

### Phase 3: simplify global navigation and desktop interaction

#### Walker and project opening

- Keep Walker/Elephant as the global discovery surface and Niri direct bindings
  for the most frequent intentions. Keep `z <project>` as the shell fast path;
  it is another invocation surface over the filesystem, not another catalog.
- Use Elephant's native dynamic Lua menu support as `menus:projects`. Scan Git
  roots across `~/dev/work`, `~/dev/own`, `~/dev/ext`, and `~/dev/forks`; exclude
  `.archive` and every worktree root. Show one flat result set with scope labels.
- Have each result invoke one Nix-owned `open-project` command. It opens an
  interactive Kitty shell at the repository root, starts Neovim, and returns to
  a usable prompt after Neovim exits. It restores no buffers, layouts, or
  services.
- Treat `yookr-workbench` as an ordinary project result. Do not generate a
  desktop entry per repository or maintain a separate project registry.
- Retain Elephant's shipped provider defaults/prefixes instead of copying them
  into Nix. Keep the current `?` Bitwarden prefix as the local exception.
  Clipboard and credentials remain prefixed; quiet navigation providers may
  participate in unprefixed search.
- Do not include bookmarks in Walker until a maintained provider can read
  Vivaldi live. Elephant's one-time CSV import would create a second authority.

#### Browser ownership

- Keep one neutral Vivaldi profile. Work/personal cookie and history isolation
  has no demonstrated value; rename the misleading `Work` profile if visible.
- Use Vivaldi Quick Commands for tabs, history, bookmarks, and browser commands.
  Keep vertical tabs. Do not initially add Vivaldi workspaces, pinned tabs, Web
  Panels, command chains, or another Chromium browser.
- Keep Actual, WhatsApp, and Outlook as web apps. Vivaldi owns installation,
  identity, authentication, permissions, and sync. After capturing each app ID,
  Home Manager owns one stable desktop entry invoking current Vivaldi with
  `--profile-directory=Default --app-id=<id>`; suppress the duplicate
  Vivaldi-generated launcher. Reuse the known Actual ID
  `ahoihnifhakgijcmjlhbcgehigihinlo` and WhatsApp ID
  `hnpfjngllnobngcgfapefoaidbinmjnm`; capture Outlook's ID after installing it.
  This prevents stale Nix-store paths.
- Keep a small Speed Dial beginning with ChatGPT and the Yookr GitHub
  organization. Google remains the search engine rather than a bookmark.
- Sync durable bookmarks/Speed Dials, supported settings, extensions, and web
  apps between Zenith and Polaris. Keep open tabs and history local. Passwords
  remain Bitwarden-owned.
- Use Bitwarden's multi-account browser extension for personal Vaultwarden and
  company Bitwarden. Walker's `rbw` provider remains personal-only; do not copy
  company secrets, create another browser profile, or build a private adapter.

#### Niri vocabulary

- Design for two general-purpose displays with dynamic workspaces. Do not pin
  applications, roles, or content to a monitor. On Zenith, place the external
  widescreen to the right and focus it initially once its stable identity has
  been captured during a docked session.
- Keep `Super+H/J/K/L` for focus and `Super+Alt+H/J/K/L` for frequent
  window/column movement. Keep `Super+U/I` for workspace navigation, the
  corresponding deliberate move/reorder operations, useful mouse-wheel
  bindings, and touchpad gestures.
- Remove arrow-key duplicates, Page Up/Down aliases, numbered-workspace
  bindings, first/last-column jumps, centering, maximize-to-edges, direct
  compositor quit, monitor power-off, and the unused hotkey-overlay binding.
- Remove the NixOS-config terminal, NixOS-switch, edit-secrets, and color-picker
  shortcuts and their shortcut-only scripts. Underlying terminal commands stay.
- Consolidate screenshots on Niri's interactive `Super+S` UI. Keep
  `Super+O` overview, `Super+Q` close, and `Super+Ctrl+L` lock.
- Keep `Super+R` preset width cycling, one incremental resize family, column
  maximize, and fullscreen. Retain stacking/consume-expel actions, tabbed
  columns, toggle floating, and focus switching between floating and tiling as
  secondary capabilities.
- Replace the fragile mutable-index `Super+A` helper only through the bounded
  pilot below. Niri 26.04 actions accept a workspace index or name, not stable
  IPC workspace IDs, and have no atomic active-workspace swap.

### Phase 4: make the agent workflow coherent

#### Context, skills, and client boundaries

- Keep Codex primary and Claude Code/Pi as experimental fallbacks without fixed
  specializations or forced feature parity.
- Share repository `AGENTS.md`, concise global guidance, project commands,
  user-authored skills where natively supported, and verified MCP endpoint
  facts. Keep client-specific model/UI settings, approvals, authentication,
  trust, and runtime state native.
- Centralize MCP endpoint facts in the Nix AI capability only after Codex and
  Claude both consume them, then render thin native configurations. Pi has no
  native MCP owner and should not receive a wrapper for cosmetic parity. Remove
  generic Home Manager `programs.mcp` output if it remains unused.
- Do not create a prompt-template menu or demonstration skills. Promote a
  procedure only after it has stable inputs, outputs, and verification.
- Create the instruction-only `nixos-maintainer` skill as the first demonstrated
  candidate. It inspects repository instructions and the complete current
  owner, prefers native options and existing patterns, researches
  version-sensitive choices, keeps mutable state outside the store, makes
  focused idiomatic edits, formats them, and performs the smallest meaningful
  no-switch validation for affected hosts. Switching a generation requires a
  separate explicit request. Add scripts only after a deterministic repeated
  operation appears.

#### Top-level agents and worktrees

- Pilot Herdr as owner of top-level Codex, Claude, and Pi processes, cross-agent
  attention state, detach/reattach, desktop notifications, and the normal
  create/open/list/remove worktree flow.
- Start or attach Herdr on demand. Do not add a supervised login service: the
  client already starts a persistent background session. Stop it deliberately
  with `herdr server stop`. Keep ordinary terminals, Neovim, dev processes, and
  LazyGit outside Herdr.
- Configure Herdr as the sole notification owner during the pilot. If it fails,
  use Codex's built-in TUI notifications before an external notify command.
- Use one workspace per active checkout or cross-repository investigation and
  one pane per top-level agent. Internal Codex subagents remain in Codex.
- Let Herdr use Git worktrees as its substrate. For the first work-only pilot,
  place them under `~/dev/work/.worktrees/<repository>/<branch-slug>` and exclude
  that tree from Walker. Use an explicit path for other identity scopes until a
  scope-preserving convention is proven.
- Do not install Worktrunk initially. Herdr 0.8.2 covers the proposed basic
  lifecycle and leaves branches intact for human review. Revisit Worktrunk only
  for demonstrated needs such as richer cross-worktree state, shell switching,
  CI/PR views, process cleanup, or integration-aware branch removal. Keep native
  `git worktree list`, `repair`, and `prune` as maintenance escape hatches.
- Defer `codex agents`. Codex 0.153.4 exposes it, but local diagnostics show
  ephemeral app-server mode and daemon bootstrap that assumes a standalone
  managed install rather than the Nix-store binary. Do not add a second mutable
  Codex installation or custom daemon workaround.

#### Task lifecycle

- Use one primary writer per checkout. It may delegate bounded independent
  read-heavy work; concurrently running internal subagents do not edit the same
  checkout. Confirmed read-only investigations may share a checkout and need no
  branch or worktree. Sequence tasks expected to overlap in files or behavior.
- Use `feat/<issue>-<slug>`, `fix/<issue>-<slug>`, or
  `chore/<issue>-<slug>`, omitting the issue when none exists. Reuse the slug for
  the checkout, Herdr label, and optional execution plan.
- Keep setup explicit: create the worktree, review and authorize `.envrc`, then
  start the agent there. Do not add hooks, copy ignored files, launch agents from
  Walker, or hide these state changes in a wrapper.
- Use Codex `/plan` when design is uncertain, then one `/goal` containing the
  outcome, constraints, and verification for substantial execution. A goal is a
  persistent target, not a milestone hierarchy.
- For genuinely substantial multi-session work, keep one living
  `docs/plans/<task-slug>.md` in the branch and reference it from the goal. Record
  scope/non-goals, architectural facts, verifiable milestones, progress,
  discoveries, decisions, evidence, and the exact next step. Link to source
  instead of copying logs. Move lasting knowledge to normal docs/ADR at the end
  and delete a transient plan when it has no continuing value.
- Let the primary agent make local commits at meaningful verified or resumption
  boundaries, not mechanically after every milestone. It does not push, merge,
  open a pull request, or mutate GitHub without an explicit request.
- End on a checked, locally committed branch with a handoff covering outcome,
  verification, limitations, and unresolved decisions. Review with LazyGit in
  the task worktree. The user chooses publication, integration, revision, or
  abandonment; remove the checkout only afterward.

### Phase 5: consolidate notes, PIM, and transcription

#### Notes and meeting knowledge

- Consolidate both notebooks into `~/sync/notes` on one fully synchronized node
  with no concurrent writers. Preserve authored notes/images and merge the two
  `todo.md` files deliberately. Stop generating `~/sync/work/notes`.
- Use `daily/YYYY-MM-DD.md` as the unclassified intake path, with no title prompt
  or required frontmatter. Use a `zk` group/alias for idempotent daily-note
  creation. Keep ordinary titled notes at the notebook root until use justifies
  another collection.
- Bind unused `Mod+N` to a small Nix-owned command that opens today's note at the
  append position in a dedicated Kitty/Neovim window and closes with Neovim.
- Store planned meetings as dated files under `meetings/` and raw transcripts
  separately under `transcripts/`. A person curates decisions/context into the
  meeting note. During the Monday development meeting, the team cooperatively
  decides and creates issues, which the meeting note then links. Agents do not
  create issues or automatically ingest transcripts into daily notes.
- Keep Markdown/zk as notes authority. Personal actionable tasks belong in
  Radicale VTODO, private/email-derived work follow-ups in Microsoft To Do, and
  shared development work in GitHub issues. Link Markdown context instead of
  duplicating it into another task database.

#### PIM authority and presentation

- The PIM foundation must remain free of charge, with open-source components
  preferred. Paid services such as Morgen are excluded from this role.
- Keep Microsoft 365 authoritative for work/university mail, calendar, people,
  and Microsoft To Do. Keep Radicale authoritative for personal CalDAV
  calendars/VTODO and CardDAV contacts. Clients may present both but do not copy
  data between authorities or create a bidirectional bridge.
- Pilot Evolution with all four active mail identities: personal, old personal,
  university, and work. Use its Microsoft 365 account type for Microsoft
  identities, not legacy Exchange/EWS. Connect personal accounts and Radicale
  through native IMAP/SMTP, CalDAV, CardDAV, and VTODO.
- Keep Thunderbird and the Outlook Vivaldi app throughout the pilot. Change no
  authority until consent and daily behavior pass. If Evolution passes its
  gate, make it the canonical desktop PIM and retire Thunderbird. Keep Outlook
  as the Microsoft-native fallback, not a second general PIM workflow.
- Keep Radicale rather than adding Baikal or Nextcloud. A larger groupware stack
  does not solve Microsoft federation and no personal web UI is required.
- On Android, use DAVx5 as the sole Radicale adapter. aCalendar+ and Google
  Contacts consume Android providers; Tasks.org consumes DAVx5/OpenTasks and may
  separately connect to Microsoft To Do. Do not configure Radicale twice.
- Use free/F-Droid DAVx5 and Tasks.org builds. Account for Tasks.org's Microsoft
  To Do limits--partial recurrence, one reminder, no attachments, and no manual
  ordering--and give each collection one notification owner. Test Outlook's
  optional calendar/contact export and correct default accounts.
- Before removing the last independent PIM copy, test restoration of Radicale
  collections and authentication data. Keep broader Orion backup redesign out
  of scope.

#### Meeting transcription

- Use Fossify Voice Recorder on the Pixel and Syncthing directly to Orion. Orion
  becomes the always-on transcription owner; this does not reopen general
  backup, CI, builder, or agent-offload design.
- First observe a real recording transfer. Fossify writes directly to its final
  filename while recording, so a Syncthing/path event alone does not prove the
  meeting ended. Prefer an automatic post-record move to a dedicated inbox if
  available; otherwise require an unchanged size/mtime settlement period plus
  media readability/duration validation.
- Once completion detection is proven, refactor the Zenith/Vulkan module for
  Orion's CPU `whisper-cpp` runtime and one inbox/processing/archive/failed tree.
  Use an event-triggered path/service pair to wake an idempotent scanner instead
  of polling every two minutes.
- Keep the multilingual model and automatic language handling. Run diarization
  by default, but publish an unlabeled transcript when Whisper succeeds and
  diarization fails; record the partial failure instead of withholding it.
- Write transcripts under `~/sync/notes/transcripts` and preserve originals in
  the recordings archive. The transcript is the quiet success signal;
  systemd state/logs expose failures. Add no desktop notification.
- Validate with a Dutch/English meeting, preferably with code switching, and
  require completion by the next morning. Consider a GPU worker only if Orion
  misses that service level. Syncthing replication is not backup.

### Phase 6: retire duplicate applications and dead configuration

Perform removals after the corresponding migration or pilot.

- After valuable definitions are migrated, remove Postman, HTTPie, Posting, and
  Resterm. Keep Kulala and `xh`; keep Bruno only through the HTTP pilot and
  remove it if no indispensable capability appears.
- Remove Rainfrog, dblab, Harlequin, Tabularis, DbGate, pgAdmin, Beekeeper
  Studio, MongoDB Compass, pgModeler, and tbls. Remove the Harlequin profile.
  Keep Dadbod and wrapper-local clients; keep DBeaver only through the database
  pilot and remove it if no GUI-only need emerges.
- Remove global `usql` and MariaDB. Keep PostgreSQL, MariaDB, and `mongosh` only
  in the Neovim wrapper or repository environments that own them.
- Search once for an application/plugin that shells out to npm. If found,
  declare Node with that owner; otherwise remove global Node.js and Bun and keep
  language runtimes in repository flakes.
- Remove Zed and the inactive Helix module, cache settings, and flake input.
  Keep Neovim. Retain Jujutsu as a **deferred** experiment with no assigned
  workflow until a concrete use case exists.
- Remove inactive Foot modules and keep Kitty as the only terminal.
- Remove Obsidian, Planify, and Calcure after note/PIM ownership is in place;
  none owns data that needs migration.
- If Evolution passes, remove Khal, Todoman, and local `pimsync`. Keep Noctalia
  as a read-oriented calendar glance surface. Add no terminal PIM client without
  a demonstrated operation.
- Install Pinta beside GIMP for its bounded trial. Remove GIMP only if Pinta
  covers the workload; otherwise remove Pinta and retain GIMP.
- Retain Spotify, OnlyOffice, Nautilus, imv, Sioyek, mpv, qBittorrent, and
  Discord. Keep Nautilus as graphical file manager/directory default and
  `xdg-desktop-portal-gnome` with GTK fallback as file chooser. Do not add
  Thunar, Dolphin, Nemo, or another file manager without a concrete gap.

## Evaluation gates

### Project contract and workbench

Pass when a fresh checkout of each pilot repository can enter its environment,
discover relevant commands, run checks, and reach a useful local state using
only tracked configuration plus documented machine-local inputs. Confirm no
shell activation mutates state and a new worktree reads no ignored files from
another checkout. Extract templates only after two pilots share real boilerplate.

Run two representative development servers and test suites concurrently using
their native behavior. Continue deferring branch-derived ports, databases, and
container-project names only if endpoints remain discoverable and no actual
resource collision appears; otherwise add isolation only for the observed
conflict.

For the workbench, prove one authenticated Yookr API read, one named connection
for every needed database engine, isolated `just k8s test`, and one
Marimo-to-HTML report. Publish or expand it only after those artifacts confirm
the boundary.

### Herdr and worktrees

Exercise short and long Codex sessions, an approval-blocked session,
detach/reattach, one Claude or Pi fallback, and two independently writing task
worktrees. Evaluate runtime/attention, notifications, and worktree handling as
separate components, retaining only those that pass. Attention state must be
accurate, exactly one notification must be delivered, paths must be predictable,
dirty removal must be refused, branches must remain for review, and layout
overhead must cost less than the polling/navigation it replaces. If Herdr's
runtime or notification role fails, retain native agent sessions and Codex TUI
notifications. If its worktree role fails, use native
`git worktree add/list/remove`; compare Worktrunk only after that ceremony
becomes repeated friction.

### Agent conventions

Test the instruction-only `nixos-maintainer` skill with representative prompts
that add, change, remove, and diagnose a capability, plus unrelated prompts that
must not trigger it. Pass when it follows repository ownership, makes focused
edits, performs appropriate no-switch validation, and leaves switching to an
explicit request.

Separately, give a fresh Codex session only the repository, its `AGENTS.md`, and
a living execution plan from a substantial paused task. Promote the convention
only if it can identify the exact next step and resume correctly without chat
history or copied logs.

### S3 and SharePoint

On one real Yookr task, configure a machine-local, least-privileged S3 remote and
prove target selection, listing, download, and an explicitly authorized upload
without accidental mutation. Pass when native `rclone` commands are clear and
auditable enough that no interactive browser is needed; otherwise remove the
pilot configuration and package. Keep SharePoint deferred until company consent
and a real browse/download case exist.

### Pull-request review gate

Exercise one `gh pr view`/`gh pr diff` review and one review worktree with local
navigation or tests. Pass when metadata, checks, local verification, LazyGit,
and optional agent assistance are reachable without another review UI. If it
fails, record the exact missing operation before evaluating one maintained
alternative.

### Evolution and Android PIM

Pass Evolution only after all four accounts prove send/receive, folder behavior,
search, offline mail, invitations, recurrence exceptions, contacts/GAL,
Microsoft To Do recurrence/reminders, and acceptable daily UX. Confirm tenant
consent and one notification owner per collection. If it fails, retain
Thunderbird plus Outlook PWA and keep Radicale clients native.

On Android, prove two-way Radicale calendar/contact/task synchronization,
Microsoft To Do within documented limits, clear collection labels, correct
default accounts, recurrence, reminders, and Outlook export where permitted.
If DAVx5 fails, keep personal Radicale data in the existing desktop/native
clients and Outlook as the Microsoft 365 Android client. If only Tasks.org's
Microsoft integration fails, keep Tasks.org for personal VTODO through DAVx5
and use Outlook for Microsoft tasks. Neither failure changes server authority.

### NetworkManager VPN

Install `networkmanager-openvpn`, import the profile separately on Polaris and
Zenith with autoconnect disabled, and use Noctalia's existing Network control
center as the only desktop toggle. Pass after route, DNS, test-service access,
suspend/resume, reconnect, and reboot work on both machines. Remove OpenVPN 3
only after both pass.

### Niri active-workspace exchange

Pilot a two-output-only helper that assigns collision-free temporary names to
both active workspaces, preserves original names, moves each named workspace to
the other output, makes both arrivals active, restores names, and returns focus
to the original physical output. It remains non-atomic and must restore names
on failure where possible. Keep it only if repeated swaps are reliable and the
visible transition is acceptable; otherwise retain the current shortcut
temporarily and track a native Niri action rather than growing the wrapper.

Capture Zenith's external display identity before encoding right-hand placement
and initial focus.

### Pinta

Reproduce recent edits covering clipboard/open, selection, crop/resize/canvas,
text/drawing/shapes, layers/transparency, basic adjustments, and PNG/JPEG export.
If every required operation works, select Pinta and remove GIMP. Otherwise
remove Pinta and keep GIMP; do not retain both indefinitely.

### Transcription

Observe whether Syncthing transfers a growing Fossify recording and prove the
completion protocol before automation. Then validate one real Dutch/English
meeting end to end: recording, completed-file detection, transfer, CPU
transcription, diarization fallback, archive, and Markdown by the next morning.
Remove Zenith's timer only after Orion passes.

### Stable web-app launchers

Capture the Outlook app ID, replace stale generated launchers for Actual and
WhatsApp, and verify every Walker result starts current Vivaldi with the intended
app/profile after a NixOS upgrade and Vivaldi Sync cycle. Expose one launcher per
app.

## Deferred work

- Design the team release process: intentional releases, immutable
  commit-addressed images, explicit revision promotion, rollout verification,
  rollback evidence, and Kubernetes-native base/overlay composition before a
  heavier GitOps platform. Do not encode mutable `:latest` rollout as a
  canonical workstation action.
- Establish service-owned OpenAPI generation, publication, provenance, and
  consumer-refresh policy. Existing local/network drift calls for review, not
  automatic overwrite.
- Adopt a company-wide infrastructure secret source when Yookr chooses one.
  Until then, keep manually supplied machine-local inputs and do not assume that
  Bitwarden Secrets Manager is available merely because Password Manager is.
- Publish `yookr-workbench` privately when sharing becomes useful; do not create
  a temporary synchronization path.
- Pilot SharePoint browse/download through `rclone` after Microsoft consent is
  known. Continuous sync and mounts require a separate demonstrated need.
- Revisit Walker bookmark search only with a live Vivaldi reader, and company
  credential search only with maintained multi-vault support or repeated cost.
- Revisit Worktrunk only after a concrete Herdr worktree gap. Revisit
  `codex agents` after Nix-managed daemon startup works without a second mutable
  installation.
- Build a formal agent evaluation harness only after representative tasks and
  concrete configurations exist. Compare repeated runs on correctness, human
  intervention, review burden, conceptual complexity, wall time, and token use;
  structured agent output is telemetry, not the quality judgment. Controlled
  Codex evaluations consume `codex exec --json`; they never parse the
  interactive TUI or mutable internal databases.
- Add Walker-to-agent launching only after the explicit Herdr/worktree sequence
  becomes repetitive enough to define a stable contract.
- Keep remote Herdr, builders, CI runners, agent offload, and general Orion
  backup redesign out of scope until a concrete bottleneck justifies them.
- Add a report server, notebook hub, Nextcloud groupware/Notes, terminal PIM
  client, or meeting-summary skill only after a missing capability is proven.
- Add branch-derived ports, databases, container projects, or other concurrency
  isolation only after an observed resource collision.
- Add LocalSend, OCR, dictation, global clipboard remapping, a second hotkey-help
  surface, or other distribution-inspired conveniences only after repeated use
  gives them a clear owner.

## Reference baseline

Implementation must recheck fast-moving interfaces against the pinned version.

<!-- 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 environments](https://kulala.app/usage/environments), [Kulala](https://github.com/mistweaverco/kulala.nvim), [Dadbod](https://github.com/tpope/vim-dadbod), [Dadbod UI](https://github.com/kristijanhusak/vim-dadbod-ui/blob/master/doc/dadbod-ui.txt), [RabbitMQ management](https://www.rabbitmq.com/docs/management), [rclone S3](https://rclone.org/s3/), [rclone OneDrive/SharePoint](https://rclone.org/onedrive/).
- Desktop: [Walker providers](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/), [Vivaldi Sync](https://help.vivaldi.com/desktop/tools/sync/), [Niri IPC](https://niri-wm.github.io/niri/IPC.html), [Niri actions](https://niri-wm.github.io/niri/niri_ipc/enum.Action.html), [Pinta guide](https://www.pinta-project.com/user-guide/).
- Agents: [Codex configuration precedence](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence), [Codex long-running work](https://learn.chatgpt.com/docs/long-running-work), [Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents), [Codex notifications](https://learn.chatgpt.com/docs/config-file/config-advanced#notifications), [Herdr configuration](https://herdr.dev/docs/configuration/), [Herdr CLI](https://herdr.dev/docs/cli-reference/), [Git worktrees](https://git-scm.com/docs/git-worktree), [Worktrunk](https://worktrunk.dev/).
- PIM/knowledge: [Evolution account types](https://help.gnome.org/evolution/intro-account-types.html), [Evolution Microsoft 365 implementation](https://gitlab.gnome.org/GNOME/evolution-ews/-/tree/master/src/Microsoft365), [Radicale](https://radicale.org/v3.html), [DAVx5](https://manual.davx5.com/introduction.html), [Tasks.org with DAVx5](https://tasks.org/docs/sync_davx5/), [Tasks.org Microsoft To Do](https://tasks.org/docs/sync_microsoft/), [`zk` daily journal](https://github.com/zk-org/zk/blob/main/docs/tips/daily-journal.md).
- Infrastructure: [Gardenctl v2](https://gardener.cloud/docs/gardenctl-v2/), [NetworkManager `nmcli`](https://networkmanager.pages.freedesktop.org/NetworkManager/NetworkManager/nmcli.html), [NetworkManager keyfiles](https://networkmanager.dev/docs/api/latest/nm-settings-keyfile.html), [Syncthing synchronization](https://docs.syncthing.net/users/syncing), [Fossify recorder implementation](https://github.com/FossifyOrg/Voice-Recorder/blob/main/app/src/main/kotlin/org/fossify/voicerecorder/services/RecorderService.kt).

<!-- markdownlint-enable MD013 -->