108 lines
6.6 KiB
Markdown
108 lines
6.6 KiB
Markdown
# 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.
|