lux/docs/constellation-work.md

# Constellation: working state

Read [the design](constellation.md) and this file to resume. Keep this file short:
replace superseded state rather than appending a chronological log.

## Working agreement

- Explore the philosophy through concrete use, discuss meaningful choices, then
  implement a small coherent change. Curiosity and alternative designs are welcome;
  an idea need not prove a defect before we explore it.
- Write succinctly without losing important details. Distinguish accepted choices,
  proposals and observations. Ask when intent would change the design; resolve
  routine implementation details autonomously. Infer opportunities from the user's
  philosophy and actual use; contribute design ideas beyond literal backlog items.
  Continue to the next natural step when the user could only usefully say "continue";
  pause for material choices or missing authority, not routine progress.
- Minimize input stops: plan a coherent batch of autonomous work and gather the
  material inputs needed for the next batch together. Avoid serial question/action
  loops. When pausing, state exactly what input is needed and what it will decide;
  otherwise continue with the next logical step rather than ending with an offer.
- The main agent owns alignment, design and integration and may do small work.
  Use subagents for bounded independent investigations or implementation with clear
  ownership. Begin with at most two workers; avoid overlapping writes, duplicate
  investigations and mandatory delegation of trivial tasks.
- Give workers the question, relevant paths, constraints and expected result.
  Prefer a compact brief and fresh context when sufficient; retain relevant prior
  context for follow-ups. Return conclusions, uncertainty and evidence pointers,
  not raw logs. Astra/Sol orchestration is a candidate to learn from, not a fixed rule.
- Read only what can affect the current decision. Use quiet commands and bounded
  output; keep large logs in `/tmp` and inspect relevant failures. Do not repeatedly
  check settled facts. Consult current documentation for consequential or unfamiliar
  interfaces when needed for the task.
- No tests unless explicitly requested. Keep other verification proportional;
  report only what was actually checked. Avoid turning small changes into campaigns.
- Keep durable decisions in the design and current questions/next steps here.
  Add an area-specific document only when an active topic outgrows this arrangement.
  No separate backlog, scratchpad, audit ledger or agent-role files for now.

## Boundaries

Repository remotes are read-only. Only the user activates system generations.
Agents must not have write access to live company systems; test writes require
task-specific authority and care. Do not read secret values for layout discovery.
Current exploration does not authorize relocating credentials, synchronizing
company content or deleting existing material. Existing local changes are preserved.

## Git baseline — 2026-09-09

The accumulated NixOS changes are recorded in focused local commits on
`chore/workflow-system`: AI tooling/inputs, editor ergonomics, query persistence
and target context, workspace navigation, Notes, SharePoint, Zellij and TeamViewer.
The original long handoff and archived plans are preserved in commit `4e3a3ac`;
use Git history for chronology. `nvim.log` is retained locally and ignored.
Workbench changes are committed on its local `main`: `eb8da6a` organizes HTTP/SQL
material and `063157c` archives helpers and documents native tools. The ordinary
company-root files are outside either repository and remain user-owned.
This cleanup preserves implementation behavior; a commit does not establish runtime
acceptance. Keep subsequent implementation and its documentation in the same
coherent commit before starting unrelated work.

## Implemented state

- **Places:** `~/yookr` has ordinary `.envrc` and `AGENTS.md` files; its environment
  loads workbench tools only. Workbench is at `~/yookr/workbench`, company projects
  at `~/yookr/projects`, and personal groups at `~/projects/{own,ext,forks}`.
  Direct moves retained archives/worktrees; all three linked dashboard worktrees
  were repaired. Nix owns tools/integration, not these workspace files.
- **Navigation:** Walker enters Yookr or a repository; Git identity follows the
  company root; XDG projects points to `~/projects`. Notes has a desktop entry
  opening `~/sync/notes` without creating a daily note. Existing note commands,
  project search and Niri daily-note behavior remain.
- **Synchronization:** Bruno collections were previously moved to Trash on Zenith
  and their shared Syncthing entry removed. Other devices' files were untouched.
  Syncthing was subsequently observed running. Notes and credentials remain in place.
- **API/database work:** workbench `http/` groups requests by service with shared
  authentication; `databases/` groups reusable queries by database. Private HTTP
  environment files are ignored at any depth. Dadbod working queries persist under
  `stdpath('data')/db_ui/working`; write them there without promoting them into Git.
  Saved-query storage also contains connection state and must stay outside Git.
  Lualine uses native Kulala environment and Dadbod connection/timing components.
  These indicators are not access controls.
- **Editor ergonomics:** word-boundary wrapping, count-aware displayed-line `j/k`
  in ordinary normal/visual buffers, and default Escape behavior to leave insert
  mode. The Neovim smoke tests were removed; earlier smoke-check evidence is in
  the archived plan.
- **Agents:** Herdr is selected; agent-deck and tmux remain installed alongside it.
  Codex has agent-deck notifications and hooks enabled. Shared Context7/NixOS skills
  live under `.agents/skills`.
  Zellij is also declared on workstations. Further project workflow work is deferred.
- **SharePoint:** Zenith mounts `company-sharepoint:` at
  `~/.local/share/yookr-reference/sharepoint/Algemeen` and
  `company-sharepoint-projecten:` at `Projecten` using the user services
  `sharepoint-reference-algemeen` and `sharepoint-reference-projecten`.
  These read-only reference mounts stream files on demand with no VFS disk cache
  and a 16 MiB memory buffer per open file. Internet access is required; directory
  listings are cached in memory for five minutes. Credentials stay in
  `~/.config/rclone/rclone.conf`. The previous hourly mirror is removed.
  When migrating another existing mirror, stop its sync timer and service,
  verify local files against their remotes with `rclone check --one-way`, and move
  the mirror aside before starting the mounts. Remove verified local copies only
  after checking that the mounts work; preserve unmatched files separately.
- **Remote support:** Zenith enables TeamViewer. Temporary Xorg/Xfce settings are
  comments only. The purpose beyond remote support and runtime acceptance were
  not recorded; preserve the change without calling it a settled design.
- **Inputs:** accumulated lock updates are retained, including an older Elephant
  revision (`376ee71c` replacing `23f37238`). No rollback rationale was recorded.

## Activation and verification

Earlier handoffs report user activation of the relocated XDG/Git/Walker paths and
Dadbod working-query persistence. Notes and the newer target statusline were last
recorded as pending activation. Only Zenith's filesystem was relocated; other hosts
need their own migration before adopting the shared paths. Reopen shells or
recreate path-dependent development environments as needed; no compatibility links
or cache rewrites were introduced.

For this cleanup, `nix flake check --no-build --quiet` and diff whitespace checking
passed in both NixOS and workbench. NixOS emitted the expected dirty-tree and unknown
`modules` warnings; workbench emitted only the dirty-tree warning.
No builds, tests, activation, credential reads or company-service calls were
performed. Active-generation differences were not checked; earlier activation
reports are not a fresh comparison with this baseline.

## Open choices and next discussion

Current focus: look and feel/theming, informed by `~/sync/notes/setup-todo.md`.
The user accepted complete Nix theme modules with arbitrary plugin/configuration
behavior, rather than Stylix or a palette-only abstraction. The single import in
`modules/capabilities/theme.nix` selects `./_themes/kanagawa.nix`. `_themes` is
excluded from automatic module discovery, so unselected themes are not loaded.
Kanagawa owns GTK/icons/cursor, Qt integration, Kitty, Niri colors, Noctalia
palette/font/wallpaper, Herdr colors, the native Neovim plugin and its setup, and
Limine/SDDM/Plymouth appearance. Only Kanagawa is implemented so far; switching
means selecting another module and rebuilding, not a live theme picker.
Walker shares a compact layout with theme-provided colors: reduced padding,
24px icons, clearer secondary text, and a smaller minimum window height.
Limine's terminal background is fully transparent with no edge gradient so it
does not obscure the wallpaper. Runtime appearance needs user verification.
SDDM's purple-leaves theme and Plymouth's spinner are retained within Kanagawa;
their visual redesign and the low-frame-rate boot animation remain open.
Verification: flake evaluation and both workstation builds passed. A headless
check of the built Neovim confirmed Kanagawa Wave, inactive-window dimming and
the custom gutter setting. Rendered Herdr TOML, Walker XML and Limine settings
also passed targeted checks. No system activation or live desktop changes performed.

Dictation: plain local transcription is selected; rambling cleanup is deferred.
Handy preferences are application-owned again: the Nix settings generator and
startup reset are removed. The existing settings file is left untouched.
Nix installs Handy/wtype and runs Handy as a graphical-session user service.
Super+D launches a short-lived Python/evdev listener: hold to record, release D
or Super to finish. Both keys must be on the same keyboard. Niri owns the shortcut
and disables repeat; no persistent keyboard logger or exclusive input grab runs.
A udev uaccess rule grants the active local user access to keyboard event devices.
Super+Shift+D toggles; Super+Ctrl+D cancels. Both stop any active hold listener
before issuing their Handy command, preventing a later release from restarting
recording. Begin push-to-talk from idle: Handy exposes toggles, not idempotent
start/stop commands. Niri 26.04 itself has no key-release bindings.
Noctalia suppresses microphone activity popups/indicators; camera and screen-sharing
indications remain. Automatic paste and live capture need interactive checks.

Hang investigation, parked at the user's request: a debugger capture confirmed
Handy's recorder waits for another audio chunk before processing its stop command.
When capture stalls, stopping can therefore hang indefinitely; the transcription
worker was idle. Bluetooth transport failures accompanied the hangs, and the user
reported dictation working after disconnecting the Sony WH-1000XM6. The user wants
its microphone when connected. Keeping the headset in a microphone-enabled HFP
profile was proposed to avoid repeated profile transitions, but was not applied
or verified; the reconnect attempt timed out. No source or Bluetooth configuration
was changed. CPU and Vulkan batch inference both worked; changing inference backend
is not an established fix. Resume this investigation only if requested.
Synthetic listener checks cover release during startup, repeat, modifier-first
release, device disconnect and cancellation, without live input/audio access.
System activation and an interactive hold/release trial remain user-owned.
Formatting, flake evaluation, both workstation builds, synthetic listener checks
and whitespace checking passed. No live input listener or microphone was started.

The focus is the broader environment, not further API/database polish. Candidate
areas remain places/ownership, navigation/interaction, human/agent collaboration,
and system operation/maintenance; these are discussion areas, not a work queue.

Herdr's configured keys are accepted: the user reports liking them in practice.
Niri workspace grouping stays informal while the user discovers what fits; Herdr
provides enough structure for now. No workspace rules or fixed layout are needed.
The user reopened Herdr configuration on 2026-09-10 for direct shortcuts and less
interaction friction, using supported configuration only. Layout presets and
launchers are explicitly unwanted; arrange panes manually. Agent evaluation is
explicitly deferred. Do not resume replacement-tool comparisons or ask for an
evaluation task/budget as a prerequisite for this work.

Read-only inspection found existing Niri overview, workspace movement and tabbed
columns; Kitty has no declared project/session organization. Installed versions:
Kitty 0.48.2, Niri 26.04, tmux 3.7c, Zellij 0.45.1 and Herdr 0.9.0.
Herdr's installed default config confirms remappable navigation and agent jumps.
Current [Herdr keyboard docs](https://herdr.dev/docs/keyboard/) describe direct
chords; [Kitty sessions](https://sw.kovidgoyal.net/kitty/sessions/) supply native
session creation/switching. Session layouts and window overviews do not themselves
provide authoritative agent attention states. tmux detach keeps processes alive;
Zellij resurrection recreates layouts/commands, not process memory. None of these
capabilities was exercised interactively; no sessions were inspected or changed.

Deferred agent workflow proposal (not accepted or a Niri workspace requirement):
one lead conversation owns each coherent change. Use bounded subagents when work
is independent, with explicit ownership and evidence returned to the lead. Separate
worktrees for independent writing efforts, one integration owner. Keep enduring
repository rules in AGENTS.md, current goals/acceptance in task prompts, and durable
decisions/current state in existing project docs. No fixed agent team is selected.

Herdr configuration is now declared in `modules/capabilities/ai.nix`, including
the existing Kanagawa theme, workspace-sorted agent panel and disabled toasts.
Home Manager owns `~/.config/herdr/config.toml` after activation; maintain these
preferences in Nix. Its configured `.bak` mechanism preserves the previous regular
file. Direct Ctrl+Alt bindings supplement the existing Ctrl+B prefix shortcuts:

| Ctrl+Alt + | Action |
| --- | --- |
| H / J / K / L | Focus pane left / down / up / right |
| U / I | Next / previous workspace |
| O / G | Workspace picker / goto picker |
| P / N | Previous / next agent |
| [ / ] | Previous / next tab |
| Enter | New tab |
| V / Minus | Split right / down |
| F | Zoom pane |
| Q | Detach, leaving the session running |
| Shift+H / J / K / L | Swap panes left / down / up / right (Shift on each) |
| Shift+arrows | Resize pane directly |
| R | Resize mode |
| Tab / Shift+Tab | Next / previous pane |
| Backspace | Return to last pane, including across tabs/spaces |
| X / Shift+X | Close pane / tab |
| Shift+P / Shift+A | Rename pane / tab |
| Shift+[ / Shift+] | Move tab earlier / later |
| Shift+Enter | New space |
| Shift+W / Shift+D | Rename / close space |
| W / Shift+B | Open / create worktree |
| Y / E | Copy mode / open scrollback in Neovim |
| Shift+G | Lazygit popup |
| B | Toggle sidebar |
| / | Keybinding help |
| S / Shift+R | Settings / reload configuration |

Inside workspace navigation, U/I moves down/up and H/J/K/L retains pane navigation.
Niri and Kitty bindings are unchanged. Direct number bindings are removed because
the user finds them unergonomic; built-in prefix shortcuts remain available.

Use one space per project or worktree, tabs for different activities, and panes
for tools needed together. Start Neovim in a shell, split right with Ctrl+Alt+V
for an agent shell, and optionally split that pane down with Ctrl+Alt+Minus for
tests or a server. Choose and launch the agent manually. No preset is installed.
Ctrl+Alt+Shift+G opens lazygit at 90% width/height in the focused pane's working
directory. Quit lazygit to return; the popup owns input until its command exits.

Tabs now open immediately with generated names; rename them only when useful.
New spaces already skip naming, and new panes inherit the current directory by
default. Workspace-close confirmation remains enabled to protect running work.
Direct resizing, previous/next agent navigation, last-pane switching, copy mode,
and Neovim scrollback access avoid extra navigation or mode-entry steps.
No documented native setting or CLI action opens Goto directly in search mode;
that limitation remains under the configuration-only constraint. No input macros,
plugins, or package patches are added.

After activating Nix, reload Herdr with Ctrl+B then Shift+R; subsequent reloads
can use Ctrl+Alt+Shift+R. The expanded shortcuts require interactive verification
through Kitty, including popup working directory, pane swapping/resizing, and
scrollback opening. The earlier bindings were reported working by the user.
Verification (2026-09-10): formatting, flake evaluation, Polaris and Zenith no-link
system builds, and whitespace checks passed. Both hosts generate identical Herdr
TOML, accepted by installed Herdr 0.9.0's `config check`. No activation or live
Herdr session changes were performed.
The earlier activation installed the Herdr config and preserved `config.toml.bak`,
but Home Manager later timed out (below).

Activation fix (2026-09-09): Home Manager's service switch stopped and restarted
the running SharePoint oneshot, then waited until Home Manager's five-minute start
timeout. Service-state inspection identified SharePoint as the sole pending user
job; its oneshot start timeout is unlimited. This was not a Herdr file collision.
Set `Unit.X-SwitchMethod = "keep-old"` in `sharepoint-reference.nix` so activation
leaves an in-flight sync running; subsequent timer runs use the updated unit.
Verified against pinned Home Manager/sd-switch source. Formatting, flake evaluation,
Zenith build and whitespace checks passed; the focused sd-switch dry run reported
`Keep active sharepoint-reference-sync.service`, with no restart planned. No live
units were changed and no company content or credentials were read. The user must
retry activation to verify the full switch; sync health/content completeness were
not investigated.

Mail search remains unresolved. The workbench's custom mail reader, inventory
pilot, justfile and old README are archived; native Garden/kubectl/K9s now own the
documented operations. No replacement mail helper or semantic index is selected;
raw mailbox grep is not assumed sufficient. No new ingestion is authorized.

Human credential delivery remains both test/live via environment variables with
ordinary editor startup. Workbench `.envrc` supplies aggregate credentials; agents
must not source it. Separate read-only agent credentials and access isolation are
explicitly deferred, not prerequisites for unrelated work. Do not resume the
rejected per-connection launchers or per-selection decryption proposal.

Notes placement and further company material organization remain open. Work is
mostly project-based and notes mostly meetings; do not impose investigation
folders, outer project containers or company-wide editor search without a need.