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.

docs/.archive/plans/credential-consolidation.md

@@ -0,0 +1,116 @@
+# 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.
+
+## Authority
+
+Use one SOPS-encrypted `~/.config/yookr/credentials.yaml`, backed by the existing
+mode-0600 user age identity. SOPS 3.13.3 and the identity are already present,
+and an exact encrypt/decrypt comparison passed on 2026-09-06. The user approved
+this authority and an active-credentials-first migration. The directory is mode
+0700 and the encrypted file is mode 0600; it remains outside Git and the Nix
+store.
+
+Keep the document hierarchical so operators can inspect and edit everything in
+one place while callers extract only their own scalar values or subtree. Do not
+load the complete document into every repository environment. Public endpoints,
+queue names, bucket names, and other non-secret configuration remain with their
+normal owners.
+
+Top-level groups:
+
+- `company_login`
+- `databases`
+- `leafcloud`
+- `rabbitmq`
+- `applications`
+- `archive`
+
+Active credentials and ten archived credential sources have been migrated.
+Archive membership does not imply inactivity, so their source namespaces are
+preserved. Delete redundant plaintext only with explicit approval after each
+original consumer is verified.
+
+## Active sources
+
+- `~/dev/work/yookr-dashboard/backend/.env`: MySQL, MongoDB, Leafcloud S3, and
+  logger credentials.
+- `~/dev/work/yookr-dashboard/front-end/.env`: `VITE_BASE_TOKEN` is referenced by
+  frontend source and is therefore client-visible, not a protectable secret.
+- `~/dev/work/yookr-data-science/.env`: WeatherAPI key.
+- `~/rabbitmq-creds-test`: test RabbitMQ username and password.
+- `~/irristaud-openstack-creds`: Irristaud project EC2 credentials.
+- `~/db-creds`: MySQL test/live and MongoDB test/live material.
+- `~/dev/work/yookr-api/http-client.private.env.json`: company email and
+  password used for API logins.
+- `~/.local/share/db_ui/connections.json`: existing `traceability` connection.
+
+All credential-bearing active files above are mode 0600 after the audit.
+They remain in place pending consumer-by-consumer removal approval. The dashboard
+backend's MySQL and MongoDB credentials do not match either named test/live pair,
+so they are preserved separately instead of being assigned an environment by
+assumption.
+
+## Archived credential sources
+
+- Service login: `inteerlijn`, `water-need`, `temperature-relay-dendron`, and
+  `prediction_mildew_rust`.
+- Rules service: RabbitMQ and database credentials in `rules-service-hex`.
+- Legacy management: database, logger, and local-login credentials.
+- Legacy data science and soil-moisture tools: company login credentials.
+- `salemans`: CMI credentials.
+
+These files are now mode 0600 and their selected credentials are preserved under
+`archive`. The user is still cleaning the filesystem, so stale status must be
+decided per source; stale credentials should be revoked instead of retained
+indefinitely.
+
+## Verified consumers
+
+- `yookr-workbench` decrypts once in memory and exports only its API login, four
+  database connections, Irristaud S3 credential, and test RabbitMQ credential.
+- Central test API login and the read-only RabbitMQ overview passed.
+- MariaDB test/live example queries and MongoDB test/live example scripts passed.
+  Both MariaDB sessions negotiated TLS 1.3. The routers expose auto-generated
+  certificates from unavailable private CAs without valid host identities, so
+  only these two URLs disable certificate verification. The MongoDB endpoints
+  publish SRV rather than direct address records and therefore use `mongodb+srv`
+  URLs.
+- The ephemeral `irristaud:` rclone remote found the sole `irristaud` container
+  and listed its six root entries. No object content was downloaded and no
+  rclone configuration was persisted.
+
+Dadbod's four display names are active, both MongoDB connections work, both
+MariaDB examples produce results through Dadbod UI, and the workbench environment
+supplies successful Kulala response chaining.
+
+## Excluded from migration
+
+- Tracked `.env.example` files and public URL-only frontend environments.
+- Tracked Apache Superset/Hive development defaults.
+- Empty placeholders, queue names, ports, bucket names, and service URLs.
+- NixOS SOPS secrets and personal Vaultwarden entries, which already have their
+  own authorities.
+
+## Observed services
+
+The scan identified Yookr measurement, authentication, management, aggregation,
+rules, prediction, dashboard, and data-science workflows plus MySQL, MongoDB,
+RabbitMQ, Leafcloud S3, logger, SMTP, Vonage, TTN, WeatherAPI, CMI, Superset, and
+Hive integrations. Presence in an archive does not establish that a service or
+credential is still active.
+
+## Immediate findings
+
+- The dashboard S3 credential and the Irristaud project credential are distinct;
+  the latter is now centralized and its read-only pilot passed.
+- The generated Yookr OpenAPI document remains malformed, but direct requests use
+  the reviewed local contract and work independently.
+- Management accepts an account-issued JWT only as the raw `Authorization` value,
+  contrary to its current OpenAPI Bearer declaration.
+- The Herdr issue 197 pilot produced local-only frontend and backend planning
+  commits without touching company GitHub. Both identify the separate account
+  service, not `yookr-dashboard`, as the implementation owner.

docs/.archive/plans/workflow-system.md

@@ -0,0 +1,190 @@
+# 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
+living handoff for operational constraints and future work; implementation
+history is available in Git.
+
+## Activation boundary
+
+Only the user may switch or activate configurations. Agents must not run
+`nixos-rebuild switch`, Home Manager activation, or an equivalent command that
+changes the active generation. Evaluation and builds are allowed; after a
+successful build, provide the exact activation command and wait for the user.
+
+This boundary includes changes described as user-level, harmless, temporary, or
+necessary for live verification. A direct Home Manager activation previously
+restarted Kitty and closed the user's terminal session.
+
+## Execution discipline
+
+- Advance all safe independent work before asking the user to act.
+- Batch declarative changes behind user-controlled activation.
+- Consolidate empirical, credential, hardware, and approval gates only after no
+  autonomous work remains.
+- Keep repositories and worktrees outside `~/sync`; synchronize authored
+  artifacts instead.
+- Keep GitHub and other repository remotes strictly read-only.
+- Treat Yookr production source as read-only. Dev-tooling changes are allowed;
+  `yookr-workbench` is the only repository whose own source may be changed for
+  these pilots.
+
+## Current checkpoint
+
+- State: phase one complete and active; explicitly deferred pilots remain.
+- Branch: `chore/workflow-system`.
+- Validation: `nix flake check --no-build --quiet`, all three no-link system
+  builds, generated Zenith and Polaris Niri validation, and all six companion
+  flake evaluations passed on 2026-09-06. The updated data-science shell exposes
+  Python 3.14.7 and its full project check passes. The expected dirty-tree and
+  unknown `modules` warnings were emitted.
+- Live state: Walker project and terminal actions, daily notes, stable web apps,
+  Evolution D-Bus activation, the Zenith VPN, invocation-scoped GitHub and
+  Context7 credentials, Pinta, and Orion transcription passed their completed
+  pilots. The corrected Actual, WhatsApp, and Outlook launchers all started
+  successfully. The labeled RabbitMQ test/live bookmarks are present, and the
+  invocation-scoped test overview and queue listing passed. Test API login,
+  Yookr administrator read, rules read, aggregation login, and management health
+  passed. Account login plus a raw-token management user read also passed.
+  The approved user-key SOPS authority now contains active credentials and ten
+  provenance-preserving archive namespaces. Its workbench exports passed a test
+  API login, RabbitMQ overview, MySQL test/live `SELECT 1`, MongoDB test/live
+  `ping`, and read-only Irristaud object-storage listing. Dadbod exposes all four
+  names and the MongoDB connections work. Both MariaDB connections now use the
+  native client with narrowly scoped certificate-verification exceptions; their
+  exact example queries passed over TLS 1.3 in both environments. Direct test
+  login and authenticated reads still return HTTP 200 for Yookr, rules, and
+  management. Kulala login and response chaining are confirmed in Neovim, and
+  both MariaDB examples produced results through Dadbod UI.
+- Herdr ran the issue 197 planning pilot in two predictable, non-overlapping
+  dashboard worktrees. Codex produced frontend commit `20f9d0f`; Claude produced
+  backend commit `bd965ea`. Short, long, done, fallback-agent, and genuinely
+  approval-blocked states behaved correctly, and dirty worktree removal was
+  refused. Nothing reached company GitHub. Both plans found that password reset
+  belongs to the separate account service rather than `yookr-dashboard`.
+  Documented named-session detach/reattach persistence is accepted without a
+  redundant live trial; notifications are intentionally disabled after their
+  live pilot.
+
+## Phase-one closure
+
+- The cross-system investigation and Marimo report pilots move into phase two.
+- Bruno and DBeaver remain available; retiring old applications is not part of
+  phase one.
+- Issue 197 planning is complete. Before implementation, route it to the actual
+  account repositories; leave the two local dashboard planning branches
+  available as evidence.
+
+Herdr's bounded pilot is complete. If later use exposes a problem, fall back
+independently to native agent sessions or native `git worktree add/list/remove`;
+do not add a wrapper or Worktrunk without a demonstrated gap.
+
+## Deferred pilots
+
+Revisit these alongside related phase-two ideas rather than as isolated cleanup.
+
+- During a docked Zenith session, capture the external display's stable identity
+  and test the two-output `Super+A` exchange. The current recorded session exposed
+  only `eDP-1`.
+- Resume Evolution only when the user chooses to configure the personal,
+  old-personal, university, work, and Radicale accounts. Keep Thunderbird and
+  Outlook until the daily-use gate passes.
+- On Android, complete the DAVx5/Radicale and Tasks.org pilots, including default
+  accounts, recurrence, reminders, and Microsoft To Do within documented limits.
+- Do not replicate the workstation workflow on Polaris until the user resumes
+  the procedure below.
+
+The Niri pilot is two-output-only. It passes when the active workspaces exchange
+physical outputs, both arrivals are active, original names are preserved, and
+focus returns to the original physical output. Any temporary names must be
+collision-free and restored on success or failure; missing output or workspace
+state must leave the session unchanged. Keep the helper only after repeated
+reliable swaps with an acceptable visible transition.
+
+## Deferred Polaris replication
+
+Do not access or test Polaris unless the user resumes this deferred replication.
+Zenith's result remains representative meanwhile.
+
+1. Activate this NixOS configuration so `networkmanager-openvpn` is installed.
+2. Restrict `~/sync/yookr-vpn.ovpn` to mode 0600.
+3. Import it with `nmcli connection import type openvpn file ~/sync/yookr-vpn.ovpn`.
+4. Rename the connection to `Yookr VPN`, disable autoconnect, and add
+   `data-ciphers=AES-256-CBC`.
+5. Connect with `nmcli connection up "Yookr VPN"`.
+6. Create mode-0600 `~/.config/yookr/github-read-only.token` without a trailing
+   newline, then verify a new shell can run
+   `gh project list --owner yookrdev`.
+7. Create mode-0600 `~/.config/context7/api-key` without a trailing newline,
+   restart Codex after activation, and run one Context7 lookup.
+
+Replication passes only when the VPN has the expected route and DNS behavior,
+reaches a test service, reconnects after disconnect and suspend, and survives a
+reboot without autoconnecting. The two credential files must remain mode 0600;
+the fresh-shell GitHub read and restarted-Codex Context7 lookup must both work.
+
+## Durable implementation decisions
+
+- Active work repositories live under `~/dev/work`, archives under `.archive`,
+  and worktrees under `.worktrees`. Repository trees never enter Syncthing.
+- Participating repositories expose non-mutating direnv shells, minimal flake
+  checks, native commands through `just`, concise `AGENTS.md`, and machine-local
+  credential inputs.
+- `yookr-data-science/conf/local/credentials.yml` is an approved narrow
+  application-owned exception to the external credential-file default: Kedro's
+  named credential dataset resolves it from the native ignored `conf/local`
+  hierarchy. Keep it untracked and mode 0600.
+- `yookr-data-science` follows ordinary `nixos-unstable`, like the other
+  companion repositories; it needs no `devenv-nixpkgs` compatibility input.
+- `yookr-workbench` starts with cross-system work only; isolation and additional
+  tools wait for observed needs. Its one API environment catalogue covers the
+  Yookr, rules, aggregation, and management APIs; Kulala owns requests and
+  Dadbod receives the four named database connections from the workbench's
+  SOPS-derived environment. The two MariaDB routers expose auto-generated
+  private-CA certificates without a valid host identity, so only those URLs
+  disable certificate verification while retaining TLS; restore verification
+  when infrastructure provides usable CA and host certificates.
+- The reviewed `yookr-api/openapi.yaml` remains the usable local contract. The
+  deployed generated document's dangling `ReadParameters` reference is accepted
+  for now and does not block direct API requests.
+- Walker's native Elephant menu scans repository roots and calls one Nix-owned
+  `open-project` command. Rare menu changes take effect at login.
+- Home Manager declares the three stable Vivaldi launcher paths with forced
+  ownership. Vivaldi's manual `Create shortcuts` action can replace one until a
+  changed Home Manager generation reclaims it; repeating a no-op activation need
+  not relink it. This accepted edge case does not justify filtering, immutable
+  files, or a watcher because that action is not part of normal use.
+- Kitty and Neovim are the sole declared terminal and editor. Retired duplicate
+  applications and global language runtimes stay absent unless a concrete owner
+  appears.
+- The fine-grained GitHub token and Context7 key stay in mode-0600 machine-local
+  files and are exposed only to their callers. Secrets do not enter Nix or broad
+  process environments.
+- The credential audit and approved central SOPS authority are in
+  [`credential-consolidation.md`](credential-consolidation.md). The authority is
+  active, while original plaintext sources remain pending consumer-specific
+  verification and explicit removal approval.
+- `sync/notes` is the single notebook owner. Daily notes, meetings, and raw
+  transcripts have separate paths, and agents do not create issues or ingest
+  transcripts automatically.
+- Orion is the sole transcription owner. It waits for file settlement, validates
+  media, archives originals, and publishes an unlabeled transcript when
+  diarization fails.
+- Evolution remains a deferred presentation-layer pilot. Microsoft 365 and
+  Radicale remain the data authorities; Thunderbird and Outlook remain available.
+- GitHub and every other repository remote stay read-only. Local files, commits,
+  fetches, clones, and worktrees remain available.
+- The provisional team chain is Project Overview project → work package → user
+  requirement → Software Development Backlog ticket → repository issue → one
+  pull request. Treat it as discovery context, not automation policy, until the
+  team settles the workflow; company GitHub remains read-only throughout.
+- Yookr production source stays read-only during workflow pilots. Changes to
+  development tooling are allowed, and `yookr-workbench` remains the explicit
+  source-code exception.
+
+## Next step
+
+Begin phase-two discovery from the user's new workflow ideas.