diff --git a/PLAN.md b/PLAN.md deleted file mode 100644 index 6f5cc5f..0000000 --- a/PLAN.md +++ /dev/null @@ -1,190 +0,0 @@ -# Neovim redesign and cleanup plan - -## Governing intent - -Make Neovim the primary editor and turn its configuration into a small, readable, cohesive system. Refactoring, simplification, runtime performance, reliability and UX are equal deliverables; do not bolt new plugins onto the current structure. - -Use Helix's philosophy as the decision framework throughout implementation, including unforeseen choices: - -- Prefer a few orthogonal concepts over aliases and special cases. -- Make related commands symmetric, mnemonic and context-aware. -- Provide one canonical interface for each task; hide plugin identity. -- Make first use behave like later use; load order must not affect behavior. -- Keep the screen quiet and reveal information when relevant or requested. -- Prefer native Neovim behavior when it fits this model. -- Remove code, configuration and plugins that do not justify their complexity. - -These principles govern the detailed plan. If a minor implementation detail conflicts with them, choose the simpler coherent solution and report the deviation. If resolving a conflict changes the user-facing command model, dependencies or scope, stop and request a plan amendment. Do not use this discretion to expand scope. - -## Context and scope - -- Neovim module: `modules/capabilities/neovim/default.nix`. -- Lua root: `modules/capabilities/neovim/lua-config`. -- `modules/profiles/host-base.nix` currently selects `primary-editor-helix`; therefore the active shell has no `nvim`. -- Locked versions include Neovim 0.12.4 and Kulala 6.29.0. Target them; add no older-version compatibility. -- Retain `nix-wrapper-modules`, `lz.n` and the custom Svelte Treesitter grammar. -- First-class languages: Nix, TypeScript/JavaScript, Svelte, Rust and Python. -- Also retain Lua, JSON, CSS, HTML, Astro, Typst, TOML, YAML, Markdown/`zk` and snippets. Remove Dafny. -- Add Oil, Grug-far, Dadbod UI, SQL completion, Kulala request/environment/import support and `zk-nvim`. -- Add YAML/JSON schema support and automatic web-tag closing/renaming. -- Exclude sessions, embedded-terminal workflow beyond leaving terminal mode, Git porcelain, debugging, test runners, AI tooling and graphical ER modeling. -- Preserve unrelated worktree changes, including `modules/capabilities/desktop-defaults.nix` if still modified. - -Known defects and cleanup targets: - -- Nix plugin groups and Lua modules do not share a clear capability structure; Kulala is in `ui.lua`, while `lsp.lua` also owns Telescope loading, diagnostics and breadcrumbs. -- `options.lua` contains mappings and an autocmd. -- Telescope dependency arrays and manual `trigger_load` calls are duplicated. Code-action UI changes after Telescope first loads. -- Treesitter starts through three overlapping events. -- Navic uses a global callback evaluated by winbars. -- LSP attach callbacks recreate shared autocmd groups. -- `project.nvim` changes global cwd; `direnv.vim` runs on every buffer entry although the launching shell owns the environment. -- Dadbod is absent; Kulala installs global mappings; several installed plugins lack explicit setup. - -## Required structure and code quality - -Before editing, inventory every Neovim option, mapping, autocmd, plugin, runtime package and server. Delete duplicates, unused entries and configuration that restates defaults. - -Align Nix plugin groups with these Lua modules: - -- `init.lua`: ordered `require` calls only. -- `options.lua`: options only. -- `keymaps.lua`: plugin-independent mappings and intentional default removals. -- `autocmds.lua`: editor-wide autocmds. -- `plugins/editing.lua`: mini.ai/surround/pairs/icons, indentation detection, Treesitter, text objects, rainbow delimiters, automatic tag handling and Grug-far. -- `plugins/navigation.lua`: Telescope, FZF, `ui-select` and Oil. -- `plugins/diagnostics.lua`: native diagnostic presentation and Trouble. -- `plugins/lsp.lua`: servers, attach/detach behavior and Navic attachment. -- `plugins/completion.lua`, `formatting.lua`, `ui.lua`, `database.lua`, `http.lua`, `notes.lua`: one concern each. - -Enforce these rules: - -- One owner per option, mapping, autocmd and plugin setup. -- Keep plugin-backed mappings in their plugin specification; declare Which-key groups centrally. -- Give every lazy plugin an explicit `keys`, `cmd`, `ft` or `event` trigger. Only dependency entries may omit one. -- Use `lz.n` declaratively. Remove scattered `trigger_load` wrappers. -- Create each augroup once and scope buffer behavior with `buffer = args.buf`. -- Keep state local; add no `_G` callbacks. -- Add a helper only when at least two capabilities use it and it reduces conceptual complexity. -- Comments explain non-obvious constraints or decisions, not syntax. Delete commented-out code. -- Prefer current native APIs and defaults. Add no speculative guards, fallbacks or compatibility layers. -- Move Kanagawa setup into `ui.lua`; delete the generated Lua string and `_kanagawa-theme.nix`. Use `nix-info` only for Nix expressions and store paths. -- Group Nix packages by capability/language and remove obsolete entries. - -## Interaction model - -| Task | Canonical interface | -| --- | --- | -| Filesystem operations | Oil editable directory buffer | -| Files, text, symbols, references, diagnostics, commands | Telescope | -| Project-wide text or regex replacement | Grug-far | -| Syntax movement/selection in the current buffer | Treesitter | -| Code relationships and semantic refactors | LSP; Telescope renders result collections | -| Persistent diagnostics/promoted results | Trouble | -| Database inspection/queries | Dadbod UI | -| HTTP requests | Kulala | -| Note capture and discovery | `zk-nvim`; Telescope renders note collections | - -Use buffers, not tabs or sessions, as the open-file model. Root project searches at `vim.fs.root(0, { ".git" })`, falling back to the process cwd; never change cwd implicitly. Keep Telescope's default result behavior. Provide one Telescope action that sends results to quickfix and opens Trouble. - -Keep LSP rename and code actions as the semantic project-wide refactoring interface. Use Grug-far for explicit text or regular-expression replacement; do not add an integration layer between them. - -Make Oil the directory handler. `e` opens the current file's directory. Keep filesystem-change confirmation. - -## Keymap and discovery contract - -Set `` to space and `` to comma. Every custom mapping needs an action-oriented `desc`. Remove displaced plugin/native aliases. - -- `g…`: `gd` definition, `gD` declaration, `gr` references, `gI` implementation, `gy` type definition, `gO` document symbols, `K` hover. -- `[x`/`]x`: previous/next diagnostic `d`, Git hunk `h`, function `f`, class/type `c`, parameter `a`. Replace conflicting defaults for these exact keys as one family. -- `s…`: Telescope project files/grep, cursor word, current buffer, recent files, workspace symbols, diagnostics, help, commands, keymaps and resume. -- `c…`: `ca` code action, `cr` rename, `cf` format, `cR` project-wide replacement. Remove displaced `gr*` LSP mappings. -- `d…`: persistent workspace/buffer diagnostics. Remove `x…` Trouble and location-list diagnostic mappings. -- `b…`: buffer picker/delete. Remove the duplicate `` picker. -- `q…`: database workspace; `qo` toggles Dadbod UI. -- `r…`: global HTTP facilities, including the scratchpad. -- `n…`: central notes; `nn` captures, `nf` finds notes and `nt` finds tags. Inside a `zk` note, `ni` inserts a link. -- `u…`: UI toggles only. -- `gl`: diagnostic details; ``: window focus; ``: leave terminal mode. -- Keep native `gg`, `G` and word motions. Do not alias `ge` to end-of-file. Replace native mappings only as part of a complete family. - -Provide operator-pending and visual Treesitter objects: `if/af` function, `ic/ac` class/type, `ia/aa` parameter, `ii/ai` conditional, `il/al` loop, `ib/ab` block. Retain `ci` grammar and make structural bracket movements repeatable. - -Context-local mappings: - -- SQL: `,r` execute query/selection, `,s` save query, `,p` edit bind parameters. -- HTTP: `,r` execute request at cursor, `,a` execute file, `,e` select environment. -- Dadbod drawer/output: keep normal motions and ``; describe local mutation/refresh actions instead of adding globals. - -Configure Which-key with the `helix` preset and automatic normal, visual, select and operator-pending triggers. Enable its operator, motion, text-object, window, navigation, `g`, `z`, mark, register and spelling documentation. Define groups once without duplicating mappings. Use Telescope keymap, command and help pickers as the full-catalog fallback; do not remap single-key built-ins only to display them. - -## Feature changes - -### Editing, navigation and UI - -- Stop configuring `mini.files`; add `pkgs.vimPlugins.oil-nvim`. -- Remove `project.nvim`, `direnv.vim` and `mini.indentscope`. -- Start Treesitter once on `FileType` for normal file buffers. Configure text objects and rainbow delimiters explicitly. -- Add `nvim-ts-autotag` for Svelte, Astro, HTML, JSX and TSX only. -- Retain mini.ai/surround/pairs/icons and indentation detection. Benchmark `mini.hipatterns`; retain hex/TODO highlighting only if it adds no measurable scrolling cost. -- Configure Grug-far as the only project-wide text/regex replacement interface. Open it with the cursor word or visual selection when available and retain its editable-buffer workflow. -- Reduce Gitsigns to signs, hunk navigation and preview. -- Keep Kanagawa Wave and colorful semantic completion. Use opaque surfaces and one border style for popups. -- Use absolute line numbers, no tabline and markers only for tabs, trailing spaces and non-breaking spaces. -- Use one global statusline containing mode, branch, filename, diagnostics, filetype, location and a truncated Navic breadcrumb when available. Remove diff/LSP-status duplication and all winbars. - -### LSP, completion and formatting - -- Remove the Dafny package/server. Keep current servers for retained languages. -- Add `yaml-language-server` (`yamlls`) and `SchemaStore.nvim` for schema-aware YAML and JSON completion and validation. Disable LSP formatting in favor of Conform. -- Remove `oxfmt` as an LSP; invoke Conform's `oxfmt` CLI formatter. -- Remove `typst-preview.nvim`, `websocat` and their `nix-info` settings. Invoke the locked Tinymist server's preview commands. -- Enable supported inlay hints by default with one toggle. Retain semantic tokens unless profiling identifies them as a bottleneck. -- Show diagnostics through signs, underlines and severity sorting. Remove virtual lines; use `gl` for text. -- Install one buffer-local document-highlight autocmd set on attach; remove it on detach without affecting other buffers. -- Ensure every Telescope-backed LSP action and `telescope-ui-select` works on first invocation. -- Retain Blink, colorful-menu and friendly-snippets with `/` selection. Use Blink's native `vim.snippet` support and convert the custom Nix snippets to VS Code JSON; remove LuaSnip. -- Define one Conform pipeline per filetype. Prefer packaged CLIs; use LSP formatting only as an explicit fallback. Run one Ruff fix plus Ruff format for Python and one Oxfmt pass for supported web files. -- Keep format-on-save synchronous with a finite timeout; keep manual formatting asynchronous. - -### Databases and HTTP - -- Add `vim-dadbod`, `vim-dadbod-ui`, `vim-dadbod-completion` and `blink-compat`; load them on database commands/filetypes only. -- Add wrapper-local `postgresql`, `mariadb` and `mongosh`. PostgreSQL is primary; retain MySQL and MongoDB adapters. -- Integrate relational SQL completion into Blink through `blink.compat`; do not enable it for MongoDB. -- Expose schemas, tables, views, constraints/index helpers, saved queries, results and relational foreign-key jumps. -- Use `DATABASE_URL` as the default project connection when set. Never store credentials in Nix or committed files. Store ad-hoc saved queries under XDG data; keep schema/migration SQL in projects. -- Treat MongoDB as collection/document exploration, not relational navigation. -- Move Kulala from `ui.lua` to `http.lua`; load it on `http`/`rest` files and explicit commands only. Disable its global mappings. -- Add wrapper-local `kulala-core`, `kulala-fmt`, `curl`, `jq` and `openssl`. Pass the packaged core path through `nix-info`; disable backend downloads. -- Use the Nix-provided `http` Treesitter grammar; disable Kulala parser downloads/builds. -- Use JetBrains-compatible `.http` files. Commit non-secret `http-client.env.json`; keep credentials in ignored `http-client.private.env.json` or shell/direnv variables. -- Support conversion with `kulala-fmt convert --from openapi --to http -o `. Add no editor wrapper until repeated use justifies it. - -### Notes - -- Add wrapper-local `zk` and `zk-nvim` with Telescope as its picker. Let `zk-nvim` start `zk lsp` only for Markdown buffers inside a notebook; do not also configure `zk` through `nvim-lspconfig`. -- Set `ZK_NOTEBOOK_DIR` to `~/sync/notes`. Global capture and discovery always target this notebook; new notes use its existing filename and template rules and never prompt for a directory. -- Use the standard LSP mappings to follow links, find backlinks and preview linked notes. Add only the three global mappings and notebook-local insert-link mapping defined above. - -### Nix integration - -Keep the wrapper self-contained; do not rely on login-shell packages. Align Nix groups with the Lua structure and delete unused declarations. After validation, change `host-base.nix` to `primary-editor-neovim` and remove its Helix cache import; retain the optional Helix capability. - -## Performance and reliability - -1. Before refactoring, build the current wrapper without switching the running system. Record median headless startup time over repeated runs. Profile scrolling in representative large Nix, TypeScript/Svelte, Rust and Python buffers with LSP attached. -2. Remove known hot-path duplication: repeated Treesitter starts, winbar evaluation, virtual-line layout changes, unused visual scanners, the formatter-only LSP and the separate Typst preview process layer. -3. Re-profile after editing/navigation, LSP and UI changes. Add no size thresholds, caches, debounce wrappers or feature cutoffs without a measured problem. -4. Keep inlay hints, semantic tokens and required servers unless measurements identify a specific offender. -5. Temporary files, non-file buffers, inaccessible parent directories and files outside Git repositories must not change cwd or emit configuration errors. - -## Verification and completion - -- Run `nix fmt`, `nix flake check --no-build` and no-switch builds for `zenith`, `polaris` and `orion`. -- Run the built wrapper headlessly with no arguments and with Nix, TypeScript, JavaScript, Svelte, Rust and Python files. Run `:checkhealth`; resolve errors from configured providers instead of suppressing them. -- In fresh processes, test every semantic mapping, code action before any other Telescope command, Trouble promotion, Oil directory handling, Grug-far replacement, YAML/JSON schemas, automatic tag handling, central note capture/discovery, native Tinymist preview, SQL completion/query actions and Kulala request/environment actions. -- Open a temporary prompt file outside a project and confirm no workspace, cwd or access error. -- With disposable data, test Oil multi-create/rename/move/copy/delete, Dadbod against PostgreSQL, MySQL/MongoDB client and adapter loading, a local Kulala request and a small OpenAPI conversion. -- Repeat startup and attached-LSP scrolling measurements; report before/after results and any remaining bottleneck. -- Apply the governing Helix principles throughout, not only at final review. Completion requires no duplicate mapping/setup, misplaced capability, lazy plugin that fails on first action or retained code without a current purpose. diff --git a/docs/plans/workflow-system.md b/docs/plans/workflow-system.md new file mode 100644 index 0000000..dc08826 --- /dev/null +++ b/docs/plans/workflow-system.md @@ -0,0 +1,47 @@ +# Workflow system execution + +Source: [`../workflow-discovery.md`](../workflow-discovery.md) + +Apply the global and repository-local `AGENTS.md` files and the ponytail skill +at full intensity throughout. Preserve user work, prefer native capabilities, +and add no abstraction without a demonstrated repeated need. + +## Current checkpoint + +- Tranche: bootstrap and repository ownership reconciliation +- State: active +- Branch: `chore/workflow-system` +- Baseline: `nix flake check --no-build --quiet` passed on 2026-09-05; only + the existing dirty-tree and unknown `modules` output warnings were emitted. +- Next: checkpoint this plan and the discovery document, then reconcile the two + `yookr-dashboard-new` copies before moving repositories. + +## Progress + +| Batch | State | Evidence or blocker | +| --- | --- | --- | +| Bootstrap and repository ownership | Active | Inventory captured; dashboard reconciliation audit running | +| Declarative workstation foundation | Pending | Depends on canonical paths | +| Repository contracts and workbench | Pending | Depends on repository reconciliation | +| Desktop, agents, notes, PIM, transcription | Pending | Independent pilots follow foundation changes | +| Conditional retirement and completion | Pending | Requires per-pilot evidence | + +## Repository checkpoints + +| Repository | Branch | Commit | Purpose | +| --- | --- | --- | --- | +| NixOS configuration | `chore/workflow-system` | Pending | Discovery and execution baseline | + +## Human actions + +- None currently. Consequential moves, destructive cleanup, credentials, + activation, and empirical pilot decisions will be surfaced here before use. + +## Decisions and discoveries + +- Use `/home/kiri/work/repos/yookr-dashboard-new` as the reconciliation base; + its `feat/gogv2` head is 17 commits newer than the sync copy and matches its + remote-tracking branch. +- Preserve the sync copy until authored changes and raw/generated data have + been classified. Do not commit its database dump. +- Run independent pilots in parallel, but gate every retirement separately. diff --git a/docs/workflow-discovery.md b/docs/workflow-discovery.md new file mode 100644 index 0000000..4b77652 --- /dev/null +++ b/docs/workflow-discovery.md @@ -0,0 +1,817 @@ +# Workflow system blueprint + +Status: authoritative design; discovery complete, implementation pending + +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 + + + +| 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 | + + + +## 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/`. 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/.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 + `--`, 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 ` 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=`; 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//` 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/-`, `fix/-`, or + `chore/-`, 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/.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. + + + +- 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). + +