137 lines
8.0 KiB
Markdown
137 lines
8.0 KiB
Markdown
# 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](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.
|