8.0 KiB
Repository design
Working decisions, open to evidence from implementation and use.
Model and ownership
Build a quiet, keyboard-driven, text-oriented environment from understandable tools 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.
- Profile: a deliberate combination of capabilities.
- 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.
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.
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.
Coding and composition conventions
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.
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.
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.
These clarify the agreed model; they are not a one-package-per-file rule, a new testing policy, or a requirement for additional abstractions.
Daily environment
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 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.
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 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.