lux/docs/design.md

# 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 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. Walker uses upstream Elephant
without a local vault patch; it may query rbw during startup. 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` is available on explicit request. It includes working-tree changes
and new nonignored files without staging, formats, evaluates and builds. Targeted
host builds are supported; a full run also builds workbench tools. Builds do not
prove activation or interactive behavior. Do not write or run tests or perform
extensive validation unless explicitly requested.

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.