updates

docs/design.md

@@ -1,107 +1,136 @@
 # Repository design
 
-These are working decisions, subject to evidence from implementation and use.
+Working decisions, open to evidence from implementation and use.
 
-## Purpose and vocabulary
+## Model and ownership
 
 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.
+and standard interfaces. Humans and agents use the same underlying resources.
+Graphical applications are deliberate choices where they fit. Streamline existing
+workflows rather than requiring a new way of working.
 
-- **Host:** machine identity, hardware, and differences in selection.
+- **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.
+- **Capability:** behavior and necessary integration, potentially spanning several
+  applications, NixOS and Home Manager.
+- **Facts:** shared identity and topology consumed in multiple places.
+- **Theme:** application-specific appearance, including plugins and assets.
+  Interaction and layout belong to capabilities.
 
-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 the same intended daily use. The `work` profile on both is
+a provisional ownership boundary, not a different workstation variant. Steam and
+LAN SSH on Polaris, and laptop power/firmware management on Zenith, are deliberate.
+Orion owns shared services. Tailnet administration supplements existing access;
+public Orion SSH closes only after private access is verified. Web services stay public.
 
-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.
+Nix owns reproducible installation, integration and selected settings. Applications
+own credentials, sessions, content and deliberately interactive preferences. No
+plaintext secrets enter Git, Nix evaluation or store outputs. Company credentials
+use a separate encrypted SOPS document in this private Gitea repository and the
+existing per-machine age keys. Credential availability is not operational authority.
 
-## Ownership
+## Coding and composition conventions
 
-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.
+Use a flat set of capability owners: `name.nix` when self-contained, otherwise
+`name/default.nix` with its scripts, assets and operational notes beside it. Put
+manually imported Nix helpers under that owner's `_support/` so import-tree does
+not discover them. Host hardware helpers remain private to their host.
 
-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.
+Discovery publishes modules; explicit imports select behavior. Prefer existing
+NixOS/Home Manager options and direct module imports. Introduce a shared option or
+helper only for actual consumers. Use kebab-case owner/module names that describe
+purpose. NixOS and Home Manager modules may share the same capability name. Small
+application declarations may remain grouped when they need no substantial integration.
+Split independent purposes or shared integrations, not every configured package.
 
-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.
+Keep package definitions with their capability and reuse them across installations
+and development environments. Flake inputs belong in `flake.nix` and are locked in
+`flake.lock`; fixed external sources need a version/revision and hash. Workbench
+tools follow the system nixpkgs pin. The GitHub devenv CLI retains its upstream
+build dependencies. Product environment definitions and pins remain product-owned.
+Use store-qualified executables or `runtimeInputs` in packaged scripts; make runtime
+paths and failures explicit. Do not duplicate package lists, generated settings or
+binding references in documentation.
 
-## Existing experience and constraints
+These clarify the agreed model; they are not a one-package-per-file rule, a new
+testing policy, or a requirement for additional abstractions.
 
-These useful decisions and operational cautions are carried forward from earlier
-work. They are starting evidence, not fresh runtime verification.
+## Daily environment
 
-- 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.
+Niri owns navigation and frequent shortcuts; Walker owns application/resource search;
+Noctalia owns status and system controls. Workspaces remain flexible and optionally
+named by the user. Terminal titles provide orientation. No project-based workspace
+scheme, heuristic naming or custom Walker project discovery is wanted.
+
+Herdr remains an experiment, not a core dependency. Remove agent-deck, tmux and
+Zellij. Keep Ollama and grounded-docs for experimentation and preserve their data.
+Ollama's embedding model supports grounded-docs. Keep Handy for local dictation and
+Orion transcription. Handy preferences, recordings and models remain application-owned.
+Its push-to-talk release listener requires active-user keyboard access; press from
+idle, with Super and D on the same keyboard.
+
+Both notes entry points open the existing zk note picker with note creation.
+Notes stay in `~/sync/notes`, mostly meeting material; no new taxonomy. HTTP and
+database targets remain independently selected and visibly named. Dadbod working
+queries and connection state stay outside Git; see the editor's `database.lua`.
+
+Kanagawa remains the theme with Adwaita fallback icons. rbw unlocks on requested
+vault access, preserving its lock policy. Outlook PWA owns work email/calendar
+editing. Mailspring owns personal mail; Thunderbird remains a backup. Noctalia
+provides the combined read-only Radicale/Outlook agenda. The user accepts published
+ICS link access and supplies the URL privately through runtime settings. Personal
+calendar editing stays on the phone; keep khal/todoman.
+
+## Company environment
+
+`~/yookr` is the company root; product repositories are in `~/yookr/projects`.
+`~/yookr/workbench` is the access point for company services, databases and files.
+This repository owns its environment; requests, queries, analysis, findings, Python
+lock, content and private context stay writable there. The workbench capability
+owns setup and credential/mount instructions.
+
+Native devenv replaces direnv, initially with default reload behavior. Migration is
+limited to workbench and company-root integration. Product, personal, archived and
+learning projects are user-migrated; do not retain direnv as a transition.
+
+Use SecretSpec with existing test-cluster application Secrets and SOPS-backed live
+credentials. There is no live-cluster access. Company login is explicit. Sources
+must fail independently, tools remain available, and retries must clear stale values.
+Normal human editor startup can receive both targets; per-connection decryption and
+a global environment selector are not wanted. Stronger agent credential isolation
+is deferred; existing restrictions on company operations remain in force.
+
+OBS and SharePoint are continuously available as read-only mounts under the workbench
+on both workstations. User services own lifecycle, independent of shell entry.
+No persistent content cache or hourly mirror; memory buffers and metadata are accepted.
+Same-user processes, including agents, can read these mounts. Preserve old local data.
 
 ## 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.
+README owns navigation and maintenance; AGENTS owns essential durable collaboration
+constraints; this document owns rationale/conventions; current-work owns resumable
+state. Operational details live beside their owner. Use Git for chronology, replace
+superseded state, and remove temporary state when no longer useful.
 
-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.
+Keep instructions short and authoritative. Add a rule when it prevents a concrete
+mistake, resolves recurring ambiguity or points to its owner. Prefer formatter and
+validation feedback to repeated reminders. This applies the useful principle of
+progressive disclosure from [OpenAI's harness engineering article](https://openai.com/index/harness-engineering/)
+without introducing speculative skills, orchestration or evaluation infrastructure.
+
+`just validate` includes working-tree changes and new nonignored files without staging,
+formats, evaluates and builds. Concise results and saved logs minimize agent overhead.
+Targeted host builds support iteration; a full run also builds workbench tools.
+Builds do not prove activation or interactive behavior. Preserve the user's testing
+policy; this pass does not create a new automated testing policy.
+
+Keep native update and activation commands. `nix flake update` is normal; selective
+updates (often `llm-agents`) are appropriate while nixpkgs breakage awaits repair.
+Activation remains user-owned. No trivial `just` aliases for native commands.
+
+## Deliberately deferred
+
+No backups (user declined), Orion dashboard/monitoring (scrapped), new agent
+workflows/persistence/indexing/isolation, or broader editor redesign without friction.
+Zenith's Plymouth refresh and extra Noctalia keyboard controls are deferred.
+The existing single Syncthing `~/sync` layout is retained. TeamViewer is removed.