docs: archive workflow plans and introduce constellation

Preserve the accumulated phase-two record and introduce the constellation design and working agreement. Archived approvals and plans are historical, not current authority.
2026-09-09 17:31:03 +02:00
1 parent 85e4cbdc67
commit 4e3a3ac899
@@ -1,5 +1,7 @@
 # Yookr credential consolidation
 Archived: historical credential inventory and migration evidence.
 This inventory contains names and provenance only. It intentionally contains no
 credential values or value hashes.
@@ -1,5 +1,7 @@
 # Workflow system execution
 Archived: historical implementation evidence, not the current iteration plan.
 Source: [`../workflow-discovery.md`](../workflow-discovery.md)
 Phase one is complete; explicitly deferred pilots remain. This file is the
@@ -0,0 +1,65 @@
 # SharePoint reference mirror
 Archived: guidance for the existing implementation, not a new design decision.
 The Zenith user timer mirrors one selected company SharePoint document library
 into `~/.local/share/yookr-reference/sharepoint` hourly. SharePoint is
 authoritative: remote updates overwrite local files and remote deletions remove
 local files. Never author files there; edit them in SharePoint's web UI. The job
 stops before more than 100 local deletions and reports the failure in the user
 journal. A failed run may leave earlier updates in place and is not evidence of a
 complete current snapshot; rclone does not delete destination files when the run
 has errors.
 The timer remains inert until both `~/.config/rclone/rclone.conf` and
 `~/.config/rclone/sharepoint-reference.env` exist and the latter names a source.
 Before adding the SharePoint remote or source file, the user must explicitly
 start the interactive company sign-in and consent step. Use only delegated,
 cloud-read-only scopes:
 `Files.Read Files.Read.All Sites.Read.All offline_access`. Do not accept rclone's
 broader default scopes or create an application registration. Tenant policy may
 require administrator consent or an approved single-tenant application; involve
 the administrator only if the consent response requires it.
 After approval, run `rclone config`, choose Microsoft OneDrive, set the advanced
 `access_scopes` value above, and select one company SharePoint document library
 (not a personal account). Before enabling the job, inspect and accept its exact
 scope, footprint, and first change set:
 ```console
 rclone config redacted company-sharepoint
 rclone lsd company-sharepoint:
 rclone size company-sharepoint:
 rclone sync company-sharepoint: ~/.local/share/yookr-reference/sharepoint --dry-run --max-delete 100
 ```
 The remote-scoped redacted output confirms the configured requested scopes, not
 what the tenant actually granted. Confirm the consent response also contains only
 the requested read scopes; stop if it denies them or offers broader authority.
 Only after that preview is accepted, create the gate with mode `0600`:
 ```text
 RCLONE_SHAREPOINT_SOURCE=company-sharepoint:
 ```
 Save it as `~/.config/rclone/sharepoint-reference.env`. Home Manager activation
 then enables the hourly timer. This is the first bounded library, not a permanent
 allowlist or a claim that all accessible SharePoint content is mirrored. Add
 another library only after its own size/preview check, using another native unit
 and dedicated destination rather than widening this source silently. Refresh and
 inspect the current unit with:
 ```console
 systemctl --user start sharepoint-reference-sync.service
 systemctl --user status sharepoint-reference-sync.service
 journalctl --user -u sharepoint-reference-sync.service
 ```
 For an accepted deletion set larger than 100 files, rerun the dry-run and then a
 manual `rclone sync` without `--max-delete`; the scheduled guard stays in place.
 The mutable OAuth token remains in rclone's config outside the Nix store. The
 local directory is user-writable and its read-only consumer policy is not an OS
 permission or credential-isolation boundary. New mirror files are private to the
 user by default (`UMask=0077`), but same-user processes can still read and change
 them.
@@ -0,0 +1,210 @@
 # 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.
 - 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.
 ## Current exploration — organization
 Accepted: repositories are primarily code; general notes belong outside them.
 Company work is broader than repositories. Workbench has a different purpose from
 product projects. Structure should be intuitive without constraining future work.
 Observed through shallow listings: project groups (now relocated below), `~/work`,
 `~/sync/notes`, mixed material in `~/sync`, and loose work artifacts in home.
 Names alone do not establish ownership, contents or redundancy.
 Accepted: the workbench supplies an environment at the company root. Reusable HTTP
 and SQL files need a home. Native tools should remain freely composable; the current
 custom inventory and mail commands are not the desired direction. Notes, credential
 placement and synchronization remain open; no relocation is approved.
 Workbench `.envrc` still loads tools and exports test/live database, API,
 object-store and RabbitMQ credentials together. Neovim's global database plugin
 names four company connections. No services or secrets were read.
 Direction: a tool/context environment at company root, maintained `workbench/`
 tooling with `http/` and `databases/` material, and separate local investigation files.
 Human credentials are supplied through environment variables for both test/live;
 agent access requires separate treatment.
 Organize reusable requests by service and queries by database, with visible target
 selection. Keep setup
 shortcuts only where they add value; let kubectl and other clients own operations.
 Mail needs a searchable representation that preserves message meaning; rg over raw
 mailbox storage is not automatically an adequate substitute for the current helper.
 API/database proposal: reusable HTTP files grouped by service, shared authentication
 requests, and explicit visible HTTP target selection. Start database exploration
 from a named connection (database + environment), creating or reopening an attached
 query; retain direct-file opening with explicit connection assignment. Keep reusable
 query text separate from target credentials. Working queries should survive restart
 without automatically becoming tracked workbench material.
 Native evidence: [Kulala imports](https://github.com/mistweaverco/kulala.nvim/blob/main/doc/kulala.import-and-run-http.txt)
 support sharing named authentication requests across files.
 [Dadbod UI](https://github.com/kristijanhusak/vim-dadbod-ui/blob/master/doc/dadbod-ui.txt)
 supports connection-associated saved queries, persistent temporary-query locations
 and explicit assignment of independently opened buffers. Callable connection URLs
 resolve while populating the list, not on selection (confirmed in pinned source);
 they do not support the proposed per-selection credential delivery.
 Its save location also holds connection state, so do not put the entire directory
 under Git. Context7 covered Kulala; Dadbod required upstream help as fallback.
 The persistent-query option was also confirmed in pinned Dadbod source. HTTP
 import/run syntax was checked in current Kulala documentation; not exercised
 against company services.
 Chosen root: `~/yookr`. Company-wide Neovim search is explicitly deferred for lack
 of a concrete use case. Existing project search remains unchanged.
 Created `~/yookr` directly with ordinary `.envrc` and `AGENTS.md` files. Moved the
 actual workbench checkout from `~/dev/work/yookr-workbench` to `~/yookr/workbench`;
 the temporary link was removed. Prefer direct moves over compatibility links.
 Removed the earlier Home Manager
 workspace declarations: Nix owns tools/integration, not working directories or
 their authored files. Notes and credentials remain in place;
 workbench uncommitted work moved with the checkout. Walker's Yookr entry and Git's new work-path identity rule remain
 activated by the user.
 Repository environments remain independent. Future relocation/composition must
 account for their own `.envrc` files (direnv provides `source_up`) without imposing
 a personal directory layout on portable repositories. The workbench's own `.envrc`
 still exports aggregate credentials; root entry uses its flake only.
 Verification: checked ordinary file types and whitespace
 after the ownership correction. The earlier Nix configuration evaluation passed;
 it was not repeated for removing the workspace declarations. No builds, tests,
 credential reads or activation performed. The workspace files exist now; the user
 can authorize its environment with `direnv allow ~/yookr`. System activation for
 Walker/Git also includes pre-existing editor/AI/SharePoint changes in this checkout.
 Credential decision: user wants environment-variable delivery of BOTH test and
 live credentials, with ordinary Neovim startup. Removed the rejected `mysql-test`
 launcher; existing workbench `.envrc` already supplies both and remains unchanged.
 Do not resume per-selection decryption or add per-connection launchers. The root
 environment is still tools-only; agent isolation remains separate from the chosen
 human workflow. No secrets were decrypted or databases contacted.
 API/database organization implemented: `http/` contains service-specific files,
 shared `auth.http` and the unchanged endpoint catalogue. Protected requests use
 native `import`/`run` to authenticate before execution in the selected environment.
 `databases/mysql/` separates server discovery and the two existing schemas;
 `databases/mongodb/server.js` preserves MongoDB discovery. Existing request and
 query contents were retained, with no additional system access or credentials.
 Private HTTP environment files are ignored at any depth. No compatibility files.
 Neovim uses `db_ui_tmp_query_location` under its data directory at
 `db_ui/working`; write working queries there without promoting them into Git.
 Dadbod's saved-query storage and connection selection remain unchanged. This
 one-line editor change has been activated by the user. Whitespace and Lua syntax
 were checked; no tests, company-service requests or decryption performed.
 Target context prepared in the existing Lualine statusline: pinned Kulala 6.29.0
 supplies a native `kulala` component for `.http` buffers (environment selection);
 Dadbod's `db_ui#statusline` supplies connection/schema/table in attached query
 buffers and timing in result buffers. No copied target state or credential URLs.
 These additions await the next user activation; they are indicators, not access
 controls. Lua syntax and whitespace checked; no company-service calls or tests.
 Access isolation explicitly deferred by the user. Separate read-only credentials
 for agents are the eventual direction, but cannot be created now. Root remains
 tools-only; the workbench child supplies both human credential environments.
 Existing agent restrictions remain. Do not revisit isolation as a prerequisite
 for unrelated work or silently broaden access.
 Current focus: the bigger picture, not further API/database polish. Revisited the
 idea inbox. Proposed areas for exploration, not a committed implementation plan:
 places and ownership; navigation and interaction; human/agent collaboration;
 system operation and maintenance. Start with places because they establish the
 context that launchers, editors and agents enter.
 User clarification: work is mostly project-based, not organized into topics or
 investigations; relevant project material mostly stays in the repository. Notes
 are mostly meeting notes so far. Do not add investigation folders or outer project
 containers without a concrete need.
 Approved relocation completed: `~/dev/work` moved directly to `~/yookr/projects`,
 including `.archive` and `.worktrees`; remaining `~/dev` renamed `~/projects`,
 retaining `own`, `ext`, `forks`. No compatibility links. Repaired the three linked
 worktrees in yookr-dashboard and yookr-dashboard-new with native Git repair;
 all three resolve at their new paths. Updated company README/AGENTS references.
 Walker roots, XDG projects path and Git identity rules updated in Nix. The new
 XDG projects path is now active. Existing shells and path-dependent development environments
 may need reopening/recreation; no caches or project files were rewritten.
 User requested removal of Bruno collections and their Syncthing configuration.
 Stopped the local Syncthing service before moving `~/dev/bruno` to Trash
 (recoverable); removed its folder entry from shared Nix configuration. Other
 devices' files were not touched. Syncthing was stopped for the move and has since
 resumed (observed active on the following turn).
 Only zenith's filesystem was migrated; other hosts need their own relocation
 before adopting the shared project-path change. Nix files formatted; worktree
 paths and whitespace checked. No tests or remote repository changes.
 Notes entry: existing Neovim `Space n f` finds notes, `Space n n` creates one,
 and `Space n t` finds tags. Niri `Mod+N` opens a daily note. Added a standard
 Notes desktop entry, discoverable through Walker, opening `~/sync/notes` in
 terminal Neovim. This neutral entry uses existing file/text search (`Space s f`,
 `Space s g`) and note commands, without creating a daily note. Pending activation.
 No new search provider, shortcuts, templates or note directories. Notes placement
 and existing daily-note behavior unchanged; agent isolation remains deferred.
 Current exploration: agent-session navigation. Agent-deck 1.15.0 is already
 installed alongside Herdr and tmux; do not plan installation from stale notes.
 Its installed help provides session search, attach and Ctrl+Q detach, plus native
 project-path sessions and optional groups. No sessions were started, inspected,
 stopped or migrated. Asked the user whether they have tried it and what feels good
 or awkward before changing bindings or selecting it as Herdr's replacement.
 Proposed division of responsibility: Walker enters a place/application, Niri
 navigates visible windows, the session manager finds and resumes agent work.
 Avoid mirroring the whole session list into another launcher or forcing a group
 hierarchy before actual use. Agent isolation remains deferred.
 Command cleanup complete: archived the workbench justfile, custom mail reader,
 discovery pilot and old README in its `.archive/`. Removed the obsolete command
 catalogue check and bubblewrap/Python/just shell dependencies. The shorter README
 documents native Garden target/session setup followed by ordinary kubectl or K9s,
 fixes product-repository links after relocation, and marks mail search unresolved.
 No credentials, mail or remote systems were accessed. Files are recoverable in the
 archive; no replacement wrapper or index was introduced.
 Workbench `nix flake check --no-build --quiet` and whitespace checking passed.
 Iteration setup: all five previous docs moved under `docs/.archive/`, retaining
 their relative layout. Prior editor, AI and SharePoint implementation changes
 remain; consult their owners when those areas become active.
@@ -0,0 +1,75 @@
 # 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](constellation-work.md) 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's persistent-agent concept fits; its shortcuts do not. Agent-deck is
  already installed alongside Herdr; whether it fits through actual use remains
  open. No replacement has been selected.
 - 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 maintained tooling and reusable HTTP/SQL files still need a clear home;
  the company root need not itself be a Git repository.
 - Expose native capabilities and useful context rather than a menu of predetermined
  investigations. The user rejects the current `k8s-inventory` and custom `mail`
  direction. API/database organization 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/](.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.