lux/docs/plans/workflow-system.md

# Workflow system execution

Source: [`../workflow-discovery.md`](../workflow-discovery.md)

The declarative workflow implementation is complete. 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.

## Current checkpoint

- State: declarative implementation and autonomous verification complete.
- Branch: `chore/workflow-system`.
- Validation: `nix flake check --no-build --quiet` plus no-link Zenith and Orion
  system builds passed on 2026-09-06 after Orion became the sole transcription
  owner. 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.

## External or deferred gates

These gates do not block work on each other.

- 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.
- 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.
- Deploy a GET image exposing `/full-api-docs/openapi.json`, then rerun
  `just openapi-refresh test`.
- 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.

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

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

## Next step

Continue an external pilot only when its real input arrives. Otherwise no workflow
implementation action remains.