updates

docs/current-work.md

@@ -1,78 +1,135 @@
 # Current work
 
-## Scope and accepted decisions
+## Phase and working method
 
-Foundation pass started 2026-09-19. Improve existing capabilities through discussion
-and coherent implementation batches; completion requires the user's agreement.
+Implementation is authorized and underway. Do not restart the broad design pass or
+reconfirm accepted choices. `docs/design.md` owns the model, decisions and coding
+conventions; README owns navigation/maintenance; operational details live with owners.
 
-Accepted: retain host/profile/capability/facts composition and explicit ownership;
-Polaris and Zenith have identical intended use; use the four-file harness. Validation
-uses a Git-ignore-aware snapshot without index changes, prioritizing low token cost.
-The work profile is explicitly provisional. Consolidate the workbench environment
-only, using the shared NixOS nixpkgs pin; authored material and the Python lock stay
-in the writable workbench. See [design](design.md) for durable boundaries.
+Complete independent agreed work and obvious fixes autonomously. Leave consequential
+unknowns pending and collect recommendations/alternatives into one substantial review
+batch. Ask earlier only to prevent broad rework/blockage. The old 2–4-question quota
+is superseded. Keep effort focused; no speculative systems or peripheral research.
+Do not activate, push, decrypt for discovery or access company systems with write
+authority. No subagents unless explicitly authorized by current instructions.
 
-## Completed and evidence
+Keep this record current by replacing superseded state. Pass-specific procedures
+stay here, not in AGENTS. The user must agree before the overall pass is complete.
+The unedited `~/sync/notes/setup-todo.md` remains an idea inbox, not authorization.
 
-- Replaced Constellation with the four-file harness after preserving useful knowledge;
-  older archives remain historical sources. Survey began from clean `3c022ad` on Polaris.
-- Implemented `just validate` with optional host arguments. Full runs format, evaluate,
-  build all hosts, and now build the workbench shell. Logs are brief; details remain
-  in `/tmp`. The index is untouched by validation. Both prerequisites were already
-  declared on workstations.
-- Added provisional `modules/profiles/work.nix`, imported by both workstations.
-  It selects existing VPN/development integration, Garden tools, and work Git settings.
-  Generic development/editor tools remain shared; SharePoint remains Zenith-only.
-- Garden definitions now have one owner in `yookr-dev/_packages.nix`, used by both
-  installed tools and `devShells.x86_64-linux.workbench`. Preserved the workbench's
-  tools and Python variables; its nixpkgs pin now follows the system as agreed.
-- Updated `~/yookr/.envrc` and `~/yookr/workbench/.envrc` to select the shared
-  environment; updated workbench README/instructions and removed its redundant
-  flake/lock. Its credential/mount body is unchanged. Requests, queries, analysis,
-  Python lock, existing changes, and generated data remain in place. Pre-change
-  migration files: `/tmp/workbench-environment-before-6k4dwzuo`.
-- Full validation passed formatting, evaluation, Orion/Polaris/Zenith builds, and
-  workbench shell build on 2026-09-19. Logs: `/tmp/nixos-validate-4ojjb2q7`.
-  The existing unknown `modules` output warning remains. Whitespace review passed
-  in both repositories; loader changes were compared against pre-change copies.
-  No tests, activation, credential loading, mounts, or remote changes.
+## Implemented, reviewed and validated; awaiting user checkpoint
 
-## Next step and user-owned actions
+- Flat capability owners; service category flattened. AI, theme, Handy and
+  transcription support colocated. Imported Nix helpers moved under `_support/`.
+  File management owns Nautilus/GVfs/udisks; keyring remains separate.
+- Removed Walker project discovery, agent-deck/notify, tmux, Zellij, TeamViewer and
+  direnv. Removed the uninstalled nixos-maintainer skill source. Retained Herdr,
+  Ollama/grounded-docs and their data, mail/calendar tools, dictation/transcription.
+- Shared notes launcher uses Kitty's explicit directory and native zk note picker;
+  the picker already supports Ctrl+E creation. Oil's mini.icons provider loads
+  before initial directory buffers. Manual workspace naming/clearing and visible
+  Noctalia labels; shell titles include directory/command. Garden shell initialization
+  now belongs to company integration instead of every host's generic shell.
+- Kanagawa declares Adwaita/hicolor icon fallback; modest Limine branding/layout.
+  A pinned Elephant patch defers its startup `rbw list` to the explicit vault query.
+- GitHub devenv 2.3.2 installed with native Zsh hook and upstream reload defaults.
+  CLI dependencies keep upstream pins/cache; workbench tools use this repository's
+  exact nixpkgs pin. Company tools are also installed through the work profile. Product and
+  personal environments are untouched. No external loader was sourced or changed.
+- Workbench runtime SecretSpec export helper resolves company/live/test independently,
+  clears stale owned variables, reports value-free status, and supports tools-only
+  entry/retry. Source mappings/provisioning remain pending below.
+- User-run encrypted company migration helper prepared, never run. Company document
+  absent until user provisioning. Test mapping and login remain deliberately
+  unimplemented until the concrete context and plugin are known; the loader accepts
+  only an explicit noninteractive runtime snapshot. No company credential values
+  have been read.
+- Both workstations select persistent read-only OBS/SharePoint user mounts, no content
+  cache; replaced Zenith-only hourly mirror. Existing data is preserved. Credentials,
+  old OBS mount handover and runtime acceptance remain user-owned.
+- Tailscale enabled on all hosts; ordinary SSH keys retained. Zenith SSH is tailnet-only,
+  Polaris LAN SSH unchanged, Orion public SSH unchanged pending verification.
+- Documentation consolidated; coding conventions in design, short AGENTS retained.
+  Validation prepares upstream devenv's import-from-derivation dependencies before
+  read-only flake checking, accepts the repository's declared official cache, and
+  reports interruption concisely. Full builds still include the tools-only shell.
 
-User reviews and re-allows the two changed `.envrc` files with direnv, and activates
-NixOS when ready. Do not run those loaders as an agent. The workbench retains
-unrelated uncommitted analysis, documentation, and mount-helper work; do not commit
-that work as part of this pass. Replicate the two loader changes and removal of the
-old environment definition on Zenith; only Polaris's workspace was changed here.
+## Decisions/provisioning still needed
 
-Evaluate the provisional work boundary in practice, then discuss secret delivery.
-Current constraints: human workbench entry exposes both test/live credentials and
-starts read-only object-storage mounts; the tools-only environment does neither
-but does not erase inherited credentials. SOPS is already used, with different
-key locations for system and company material. No credential values were read.
-Clarify encrypted-file/key distribution across machines before proposing changes.
-Devenv and secretspec remain candidates, not dependencies. No new live authority
-or per-connection launchers are authorized.
+1. **Company-root activation.** Native devenv suppresses its hook inside an active
+   devenv shell, including nested projects. No root environment is generated now;
+   recommend globally installed company tools at root and autoactivation only in
+   workbench. This avoids custom activation machinery; confirm at the user checkpoint.
+2. **Test SecretSpec mapping.** Need the explicit test context and existing application
+   Secret/namespace/key coordinates (metadata only, no values). Confirm whether
+   database Secrets hold complete URLs or separate components. Do not invent keys,
+   silently use the current context or fall back to live/SOPS test credentials.
+   Test loading reports unavailable until its runtime manifest and login snapshot exist.
+3. **Explicit-login mechanism.** Final review removed the generic ExecCredential
+   interpreter: it duplicated a security-sensitive Kubernetes client protocol before
+   the actual company plugin was known. Inspect the selected context's exec stanza,
+   then choose its native/provider-specific cached login flow and prepare a mode-0600
+   runtime snapshot. Shell entry must not launch authentication.
+4. **Live MariaDB certificate verification.** The migration helper preserves the
+   old `ssl-verify-server-cert=0` behavior. Before running it, either explicitly accept
+   that legacy risk or identify the correct CA/hostname settings and enable verification.
+5. **Manual provisioning/acceptance.** Company SOPS recipients/migration, rclone
+   OAuth on both hosts, old OBS mount handover, devenv trust/responsiveness, Noctalia
+   Radicale password and private Outlook ICS URL, tailnet enrollment/private SSH.
+   See workbench README and root README. Do not close public Orion SSH yet.
+6. **Guidelines review.** Design now spells out owner naming, module selection,
+   helper placement, package reuse/pinning, runtime boundaries and validation. No new
+   test policy, automation framework or pass-specific repo-wide rules were added.
 
-## Questions to carry into relevant areas
+## Validation state
 
-- Desktop integration: terminal/launcher interfaces have inconsistent consumers;
-  Mailspring coexists with Thunderbird account declarations; Herdr coexists with
-  agent-deck notifications and multiple session tools. Determine purpose before
-  removing anything. The disabled nixos-maintainer skill's source remains.
-- Cross-host behavior: earlier workspace migration was reported only on Zenith.
-  Verify Polaris paths before assuming equivalent filesystem state. TeamViewer and
-  SharePoint currently exist only on Zenith despite identical intended use.
-- Runtime evidence: earlier theme/greeter, expanded Herdr shortcuts, Handy
-  hold/release/paste, and SharePoint activation checks were incomplete. Old build
-  results do not establish current behavior. Ask in the relevant area.
-- Handy hang investigation remains parked unless requested: a prior debugger
-  capture found the recorder waiting for an audio chunk before handling stop;
-  Bluetooth failures coincided, and disconnecting Sony WH-1000XM6 helped. The user
-  wants that microphone. Persistent HFP was proposed but never applied or verified;
-  inference-backend changes were not an established fix.
-- Agent evaluation, new mail ingestion, and company credential isolation were
-  deferred. Secret-management discussion reopens design, not live access.
+Final full validation passed before the final review deletions:
+`/tmp/nixos-validate-t7zv1zux` (session 88912,
+completed exit 0). Formatting, devenv preparation, flake check, all three host
+builds (Orion, Polaris, Zenith), and the tools-only workbench build passed.
+This includes the final notes startup ordering, serialized vault-query patch,
+FUSE wrapper paths, native Zsh retry function and SecretSpec package collision fix.
+No systems were activated.
 
-The inbox is not a backlog. Detailed old handoffs remain in Git before this batch;
-consult them only when their evidence affects a current choice.
+Native devenv tools-only startup also passed in an isolated temporary home:
+`/tmp/foundation-native/startup.log`. Company/live/test loading was disabled;
+SecretSpec 0.20.0 and Python 3.14.7 were available. No company credentials loaded.
+
+Clean-home manual editor checks passed: direct directory startup renders a Lua-file
+icon in Oil; opening the note picker after VimEnter reaches TelescopePrompt.
+Evidence: `/tmp/foundation-editor-check/{startup,notes}.log`. No real notebook or
+credentials loaded. Built Kanagawa index declares `Inherits=Adwaita,hicolor`.
+Python source syntax and local documentation links checked; no automated tests added.
+
+The final review only removed the unaccepted Kubernetes login wrapper and the
+machine-wide devenv cache setting; the flake-scoped cache remains. Full builds were
+not repeated for those deletions.
+
+Builds do not establish interactive acceptance. The user checkpoint remains; do not
+repeat full builds for documentation-only handoff edits.
+
+## Review checkpoint
+
+The final diff was reviewed for correctness, integration and Ponytail complexity.
+Desktop/capability moves and repository wiring had no material findings. The review
+removed the speculative Kubernetes login interpreter and kept the devenv cache at
+flake scope instead of granting it machine-wide trust. The remaining Python has a
+concrete role: in-memory concurrent secret loading with completeness checks, one-time
+encrypted credential reshaping, dynamic OBS rclone configuration, or pre-existing
+dictation/transcription behavior.
+
+The user checkpoint is still required before this pass is complete. No implementation
+commit was made in this turn.
+
+Initial local commit `f164d8b` predates this implementation. Four documentation files
+were already modified during the design pass; those changes belong to this effort.
+No remote changes or activation have occurred. External workbench analysis/content
+changes are unrelated and must not be committed here. Previous external loader
+copies remain at `/tmp/workbench-environment-before-6k4dwzuo`; only root/workbench environment documentation and ignore entries were updated.
+Backups: `/tmp/foundation-workbench-docs-bvrs1hu9`. Old external loaders remain
+until user activation, so the currently running system is not broken. Constellation documents were already
+superseded and removed in the prior foundation commit.
+
+Deliberate deferrals remain in design: backups declined, dashboard scrapped,
+Zenith Plymouth and extra Noctalia keyboard controls deferred, stronger credential
+isolation/new agent workflows/indexing and unrelated editor redesign out of scope.

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.