# Workflow system execution Source: [`../workflow-discovery.md`](../workflow-discovery.md) The declarative workflow core is complete; pilots remain. This file is the living handoff for operational constraints and external gates; implementation history is available in Git. ## Activation boundary Only the user may switch or activate configurations. Agents must not run `nixos-rebuild switch`, Home Manager activation, or an equivalent command that changes the active generation. Evaluation and builds are allowed; after a successful build, provide the exact activation command and wait for the user. This boundary includes changes described as user-level, harmless, temporary, or necessary for live verification. A direct Home Manager activation previously restarted Kitty and closed the user's terminal session. ## Execution discipline - Advance all safe independent work before asking the user to act. - Batch declarative changes behind user-controlled activation. - Consolidate empirical, credential, hardware, and approval gates only after no autonomous work remains. - Keep repositories and worktrees outside `~/sync`; synchronize authored artifacts instead. - Keep GitHub and other repository remotes strictly read-only. - Treat Yookr production source as read-only. Dev-tooling changes are allowed; `yookr-workbench` is the only repository whose own source may be changed for these pilots. ## Current checkpoint - State: declarative core complete and active; pilots remain. - Branch: `chore/workflow-system`. - Validation: `nix flake check --no-build --quiet`, all three no-link system builds, generated Zenith and Polaris Niri validation, and all six companion flake evaluations passed on 2026-09-06. The updated data-science shell exposes Python 3.14.7 and its full project check passes. The expected dirty-tree and unknown `modules` warnings were emitted. - Live state: Walker project and terminal actions, daily notes, stable web apps, Evolution D-Bus activation, the Zenith VPN, invocation-scoped GitHub and Context7 credentials, Pinta, and Orion transcription passed their completed pilots. The corrected Actual, WhatsApp, and Outlook launchers all started successfully, and the labeled RabbitMQ test/live bookmarks are present. ## Active pilot gates These gates do not block work on each other. - Supply approved test RabbitMQ management credentials at runtime, then verify the Nix-provided client without installing it permanently: ```console RABBITMQADMIN_BASE_URI=https://test.rabbitmq.yookr.org nix run --quiet nixpkgs#rabbitmqadmin-ng -- show overview RABBITMQADMIN_BASE_URI=https://test.rabbitmq.yookr.org nix run --quiet nixpkgs#rabbitmqadmin-ng -- queues list ``` Export `RABBITMQADMIN_USERNAME` and `RABBITMQADMIN_PASSWORD` from the approved credential source first; do not place their values in documentation or shell history. Keep publishing, getting, and purge visibly interactive in the management UI. - Supply one real Yookr S3 task, a least-privileged remote, and explicit permission for any upload. `rclone` is installed; no remote or wrapper is preconfigured. - The test GET image exposes `/full-api-docs/openapi.json`. The 2026-09-06 refresh reached it successfully but validation found a dangling `#/components/schemas/ReadParameters` reference. Have the application owner correct and deploy the generated document, then rerun the refresh; do not modify production source during this workflow. - Provide current API user credentials before the planned login and harmless administrator read. The recovered legacy service credentials returned 401 and were not repurposed. - Add workbench database connections and a Marimo-to-HTML report only when a real cross-system investigation gives them durable value. - Keep Bruno, DBeaver, and PIM clients until their separate pilots decide them. - Wait for a real Monday ticket before adding anything beyond native GitHub, Herdr, Git, and worktree workflows. The Herdr pilot passes only when short, long, and approval-blocked sessions have accurate attention state; detach and reattach preserve output; one Claude or Pi fallback works; and each completed event produces exactly one notification. Create two independently writing, non-overlapping task worktrees under `~/dev/work/.worktrees//`, explicitly authorize each `.envrc`, and confirm paths are predictable, dirty removal is refused, and the branches remain for review. If a component fails, fall back independently to native agent sessions and Codex TUI notifications or native `git worktree add/list/remove`; do not add a wrapper or Worktrunk yet. ## Deferred pilots - During a docked Zenith session, capture the external display's stable identity and test the two-output `Super+A` exchange. The current recorded session exposed only `eDP-1`. - Resume Evolution only when the user chooses to configure the personal, old-personal, university, work, and Radicale accounts. Keep Thunderbird and Outlook until the daily-use gate passes. - On Android, complete the DAVx5/Radicale and Tasks.org pilots, including default accounts, recurrence, reminders, and Microsoft To Do within documented limits. - Do not replicate the workstation workflow on Polaris until the user resumes the procedure below. The Niri pilot is two-output-only. It passes when the active workspaces exchange physical outputs, both arrivals are active, original names are preserved, and focus returns to the original physical output. Any temporary names must be collision-free and restored on success or failure; missing output or workspace state must leave the session unchanged. Keep the helper only after repeated reliable swaps with an acceptable visible transition. ## Deferred Polaris replication Do not access or test Polaris unless the user resumes this deferred replication. Zenith's result remains representative meanwhile. 1. Activate this NixOS configuration so `networkmanager-openvpn` is installed. 2. Restrict `~/sync/yookr-vpn.ovpn` to mode 0600. 3. Import it with `nmcli connection import type openvpn file ~/sync/yookr-vpn.ovpn`. 4. Rename the connection to `Yookr VPN`, disable autoconnect, and add `data-ciphers=AES-256-CBC`. 5. Connect with `nmcli connection up "Yookr VPN"`. 6. Create mode-0600 `~/.config/yookr/github-read-only.token` without a trailing newline, then verify a new shell can run `gh project list --owner yookrdev`. 7. Create mode-0600 `~/.config/context7/api-key` without a trailing newline, restart Codex after activation, and run one Context7 lookup. Replication passes only when the VPN has the expected route and DNS behavior, reaches a test service, reconnects after disconnect and suspend, and survives a reboot without autoconnecting. The two credential files must remain mode 0600; the fresh-shell GitHub read and restarted-Codex Context7 lookup must both work. ## Durable implementation decisions - Active work repositories live under `~/dev/work`, archives under `.archive`, and worktrees under `.worktrees`. Repository trees never enter Syncthing. - Participating repositories expose non-mutating direnv shells, minimal flake checks, native commands through `just`, concise `AGENTS.md`, and machine-local credential inputs. - `yookr-data-science/conf/local/credentials.yml` is an approved narrow application-owned exception to the external credential-file default: Kedro's named credential dataset resolves it from the native ignored `conf/local` hierarchy. Keep it untracked and mode 0600. - `yookr-data-science` follows ordinary `nixos-unstable`, like the other companion repositories; it needs no `devenv-nixpkgs` compatibility input. - `yookr-workbench` starts with cross-system work only; isolation and additional tools wait for observed needs. - Walker's native Elephant menu scans repository roots and calls one Nix-owned `open-project` command. Rare menu changes take effect at login. - Home Manager declares the three stable Vivaldi launcher paths with forced ownership. Vivaldi's manual `Create shortcuts` action can replace one until a changed Home Manager generation reclaims it; repeating a no-op activation need not relink it. This accepted edge case does not justify filtering, immutable files, or a watcher because that action is not part of normal use. - Kitty and Neovim are the sole declared terminal and editor. Retired duplicate applications and global language runtimes stay absent unless a concrete owner appears. - The fine-grained GitHub token and Context7 key stay in mode-0600 machine-local files and are exposed only to their callers. Secrets do not enter Nix or broad process environments. - `sync/notes` is the single notebook owner. Daily notes, meetings, and raw transcripts have separate paths, and agents do not create issues or ingest transcripts automatically. - Orion is the sole transcription owner. It waits for file settlement, validates media, archives originals, and publishes an unlabeled transcript when diarization fails. - Evolution remains a deferred presentation-layer pilot. Microsoft 365 and Radicale remain the data authorities; Thunderbird and Outlook remain available. - GitHub and every other repository remote stay read-only. Local files, commits, fetches, clones, and worktrees remain available. - Yookr production source stays read-only during workflow pilots. Changes to development tooling are allowed, and `yookr-workbench` remains the explicit source-code exception. ## Next step Collect all inputs for the active pilots, then run them in the order RabbitMQ, OpenAPI/API, workbench, S3, and Herdr.