lux/docs/constellation.md

Constellation

An evolving personal computing environment. This is the current design, starting fresh with iteration two; decisions can change through discussion and use. See working state for how we collaborate and where to resume.

Philosophy

Build a quiet, keyboard-driven, text-oriented environment from understandable tools that compose naturally. Keep information accessible through standard formats and interfaces, so humans and agents can work with the same underlying resources. Organize files and workflows consistently, making it intuitive where to look, where things belong and how to proceed. Let structure guide everyday work while leaving room for exploration and exceptions. Use graphical applications where they serve the task well.

Make the usual path obvious and exceptions understandable. Consistency should reduce remembering and decision-making without requiring identical bindings or fixed procedures everywhere. A terminal interface alone does not establish fit.

Nix configures installed tools and system integration. Working directories, checkouts, workspace .envrc files and context documents are ordinary user-owned files, maintained directly rather than generated by Home Manager. A workbench may use a flake to declare its tools without Nix owning the surrounding workspace.

What that means so far

• Neovim, Niri, Walker and the terminal feel right: direct, keyboard-driven interaction with useful connections to the rest of the environment.
• Outlook is acceptable as an application, but its interaction and integration do not fit as naturally. Accessible mail for tools and agents matters separately from choosing a mail reader. Preserve meaning and source context, not just text.
• Herdr provides useful structure: spaces, running agents and visible attention states. Its keybindings and mouse-oriented interaction fit poorly. Agent-deck gave a poor first impression through startup issues; no replacement is selected. Explore whether Niri/Kitty or a terminal multiplexer can provide a more composable workflow while retaining that understandable overview.
• Current friction is a lack of consistent project and agent working practices, including Niri workspace use. Tool choice and agent collaboration need to be considered together. Alignment, maintainability and human attention matter alongside speed/cost; compare workflows through concrete tasks before adopting a fixed delegation pattern.
• Repositories should contain code and documentation needed by that code, not become containers for general notes and company material destined for Git remotes.
• Company work includes repositories, reference material, notes, credentials and investigation tools. Its organization must accommodate those different roles.
• Actual work is mostly project-based; notes are primarily meeting notes so far. Do not impose a topic/investigation workflow or a fixed future note taxonomy.
• Yookr workbench is an investigation environment, not a product repository. Its placement and versioning can be considered separately.
• Accepted direction: workbench supplies the environment at the company-workspace root. Its reusable requests live in workbench/http/ and queries in workbench/databases/, grouped by service/database; the company root need not itself be a Git repository.
• Expose native capabilities and useful context rather than a menu of predetermined investigations. The custom inventory and mail helpers are archived; native Garden/kubectl/K9s own the documented Kubernetes workflow. Mail retrieval and broader system access remain exploratory.
• Accepted interaction direction: find HTTP requests by service; start database exploration from a named connection. Keep targets visible and use the existing execution vocabulary. Working queries should survive restart without automatically becoming reusable tracked material. Company-wide Neovim search is deferred: no concrete use case currently justifies adding it.
• Human credential delivery uses environment variables with both test and live credentials available. Keep ordinary editor startup; no per-connection launcher or on-demand decryption workflow. Agent authority is a separate concern.
• Separate read-only company credentials for agents are the eventual direction. Access isolation is explicitly deferred: new credentials cannot be made now. Existing agent access boundaries remain in force; this does not block unrelated design and organization work.

The company root is ~/yookr, with repositories in ~/yookr/projects and the cross-project workbench in ~/yookr/workbench. Personal/non-company repositories live under ~/projects/{own,ext,forks}. Projects currently mostly live in their repositories; no extra project containers are needed. Meeting notes remain in ~/sync/notes. Remaining layout and credential locations are still being explored.

Sources

~/sync/notes/setup-todo.md is the idea inbox, not a committed backlog. Existing implementation is the starting system, not a fixed future architecture. Documents under .archive/ are historical evidence; consult only the relevant parts when needed. Their plans, priorities and old approvals do not define this iteration. Preserve existing work while reconsidering its design.