Establish repository foundation and shared work environment

docs/design.md

@@ -0,0 +1,107 @@
+# 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.