# Repository design These are working decisions, subject to evidence from implementation and use. ## Purpose and vocabulary Build a quiet, keyboard-driven, text-oriented environment from understandable tools and standard interfaces. Humans and agents should use the same underlying resources. Use graphical applications where they fit. Consistency should reduce remembering, without forcing identical bindings or procedures everywhere. - **Host:** machine identity, hardware, and differences in selection. - **Profile:** a deliberate combination of capabilities. - **Capability:** behavior and necessary integration, potentially spanning NixOS and Home Manager, multiple applications, or several files. - **Facts:** genuinely shared identity and topology, not a bucket for all settings. - **Theme:** application-specific appearance, including native plugins and assets. Interaction and layout remain with capabilities. Kanagawa is selected; themes need not fit a palette-only abstraction. Retain the composition model. Introduce shared interfaces only for actual consumers. Capability boundaries matter more than one-module-per-file uniformity. Polaris and Zenith have identical intended use and should offer the same daily experience. Hardware remains host-specific. The workstation profile now imports a provisional `work` profile selecting company network/development integration, Garden tools, and work Git identity/token integration. Try this boundary in practice before treating it as settled. Generic editor and development tools remain shared. Existing host-only services do not automatically establish a desired difference between machines. ## Ownership Nix owns reproducible installation, integration, and deliberately selected settings. Applications own credentials, sessions, content, and preferences intentionally left interactive. Record feature-specific exceptions where they are implemented. Current layout: company root `~/yookr`, projects in `~/yookr/projects`, workbench in `~/yookr/workbench`; personal projects in `~/projects/{own,ext,forks}`; meeting notes in `~/sync/notes`. Workspace files remain user-owned. This repository owns the tools-only `devShells.x86_64-linux.workbench` environment and shares Garden package definitions with the workstation installation. It follows the same nixpkgs pin as the system. Requests, queries, analysis, findings, private context, runtime data, and the Python project lock remain in the writable workbench. The ordinary workspace `.envrc` files select this environment; credential loading and mounts remain unchanged pending a separate design decision. Repositories should hold their code and necessary documentation, not absorb general company material. Work is mostly project-based and notes mostly meetings; no new note taxonomy, outer project containers, or company-wide editor search is assumed. ## Existing experience and constraints These useful decisions and operational cautions are carried forward from earlier work. They are starting evidence, not fresh runtime verification. - Niri workspaces remain flexible. Herdr supplies agent workspace organization; choose agents and arrange panes manually. Preset layouts and launchers were unwanted. Super belongs to Niri, Ctrl+Alt to direct Herdr actions, and Ctrl navigation to Neovim; native prefix bindings remain available. Earlier Herdr bindings were accepted in use; later additions lack a fresh acceptance report. Configuration and help own the binding reference, rather than a duplicate table. - Herdr configuration is Home Manager-owned in `modules/capabilities/ai.nix`. After activation reload with Ctrl+Alt+Shift+R (or Ctrl+B then Shift+R). The existing Home Manager `.bak` mechanism can preserve previous regular files. No fixed agent team or agent-workflow evaluation program is selected. - Handy provides local plain dictation, mainly English with occasional Dutch. Preferences, models, and recordings remain application-owned. Start push-to-talk from idle; D and Super must be on the same keyboard. A short-lived listener handles releases around Handy's toggle commands. Nix grants active-user keyboard event access for this integration. Cloud/LLM cleanup is deferred. - Native Garden/kubectl/K9s replaced custom workbench inventory helpers. Reusable HTTP material is grouped by service and SQL by database. Named targets and editor indicators help orientation but are not access controls. Mail retrieval remains unresolved; no new ingestion or semantic index was selected. - Dadbod working queries persist under `stdpath('data')/db_ui/working`; saving there does not promote work to reusable repository material. Saved-query storage also contains connection state and must stay out of Git. See `modules/capabilities/neovim/lua-config/lua/plugins/database.lua`. - Prior human credential delivery exposes both test/live environments with normal editor startup. Per-connection launchers and per-selection decryption were rejected. Separate read-only agent credentials were desired but unavailable; isolation was deferred. Credential delivery is reopened for discussion, while existing access boundaries remain in force. - SharePoint sync is currently Zenith-only. Its hourly unit uses two configured rclone company remotes, private file permissions, and a deletion limit per invocation. `X-SwitchMethod = "keep-old"` prevents activation restarting and waiting for an in-flight sync; later timer runs use the updated unit. See `modules/capabilities/sharepoint-reference.nix`. Remote setup, sync completeness, and the full activation fix need confirmation when this area is reviewed. ## Knowledge and maintenance README owns navigation and commands; AGENTS owns repository collaboration rules; this document owns durable reasoning; current-work owns resumable state. Keep implementation details near code and use Git instead of chronological handoffs. Archived plans are historical sources, not authority. A unified validation command is wanted to prevent repeated agent improvisation. It must include new and modified working-tree files without changing the Git index, format, evaluate, and build every host for a full configuration batch. Targeted iteration and lightweight documentation checks are accepted. The priority is low agent token cost, not minimum elapsed time: one invocation, concise results, and saved failure logs. Use `just validate` backed by one repository script. Validate a temporary snapshot of tracked and non-ignored new files using working-tree contents; leave the index untouched. Git ignores remain the file-inclusion boundary. Build success does not establish activation or interactive acceptance.