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.
This commit is contained in:
kiri committed
1 parent
85e4cbdc67
commit
4e3a3ac899
7 files changed
+1510
No files matched your search
@@ -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.
|
||||
File diff suppressed because it is too large.
Load diff
@@ -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.
|
||||
@@ -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,220 @@
|
||||
# Workflow system blueprint
|
||||
|
||||
Status: phase one implemented and active; explicitly deferred pilots remain.
|
||||
The operational handoff lives in
|
||||
[`plans/workflow-system.md`](plans/workflow-system.md).
|
||||
|
||||
This document is the durable design for the workstation and surrounding Yookr
|
||||
workflow. Implementation history belongs in Git.
|
||||
|
||||
## Governing intent
|
||||
|
||||
Build a quiet, keyboard-first control plane over development, investigation,
|
||||
operations, agents, and personal knowledge. Keep the system small and give each
|
||||
intention one canonical owner.
|
||||
|
||||
- Standardize vocabulary and entry points without forcing unlike workloads onto
|
||||
one implementation.
|
||||
- Put frequent actions on direct keys and less frequent actions on their owning
|
||||
discovery surface.
|
||||
- Keep stable packages, services, integration, and durable preferences in Nix.
|
||||
Keep credentials, sessions, databases, caches, and other mutable state with
|
||||
their owning application.
|
||||
- Prefer native file formats and supported application layers. Add wrappers only
|
||||
for demonstrated gaps.
|
||||
- Repositories own reproducible development context, executable project
|
||||
documentation, and code-specific artifacts.
|
||||
- Select `local`, `test`, or `live` per operation; do not depend on an ambient
|
||||
production context.
|
||||
- Make production and destructive actions more deliberate than navigation and
|
||||
read-only inspection.
|
||||
- Promote automation only after the manual workflow repeats and can be verified.
|
||||
- Optimize conceptual complexity and review burden, not package count or line
|
||||
count in isolation.
|
||||
|
||||
The main coordinates are scope (`work`, `own`, `ext`, or `forks`), Yookr domain,
|
||||
environment (`local`, `test`, or `live`), and intention (develop, inspect, query,
|
||||
review, operate, or deploy).
|
||||
|
||||
## Ownership model
|
||||
|
||||
<!-- markdownlint-disable MD013 -->
|
||||
|
||||
| Intention | Canonical owner |
|
||||
| --- | --- |
|
||||
| Find applications, projects, or windows | Walker/Elephant and direct Niri bindings |
|
||||
| Search personal passwords | Walker with `rbw`; company Bitwarden stays in its browser extension |
|
||||
| Navigate browser state | Vivaldi Quick Commands |
|
||||
| Arrange windows and displays | Niri dynamic workspaces |
|
||||
| Work in a terminal | Kitty |
|
||||
| Edit related files and views | Neovim |
|
||||
| Enter a repository environment | `direnv` with `nix-direnv` |
|
||||
| Discover project actions | `just --list` |
|
||||
| Run edited first-party code | Native processes, optionally Process Compose |
|
||||
| Run a container-only project stack | Rootless Podman Compose |
|
||||
| Run a persistent containerized user service | Rootless Podman Quadlet |
|
||||
| Run a durable host service | NixOS modules and systemd |
|
||||
| Exercise APIs | Kulala and `xh`, with tracked `.http` files |
|
||||
| Query databases | Dadbod and native driver CLIs |
|
||||
| Investigate across Yookr systems | `yookr-workbench` |
|
||||
| Connect the Yookr VPN | NetworkManager/OpenVPN through Noctalia |
|
||||
| Inspect test Kubernetes | `just k8s test` using Gardenctl and read-only K9s |
|
||||
| Inspect RabbitMQ | Official management UI; `rabbitmqadmin` for exact terminal operations |
|
||||
| Browse S3-compatible storage | Native `rclone` commands |
|
||||
| Capture and find notes | `zk` through Neovim in one synchronized Markdown notebook |
|
||||
| Present work and personal PIM | Evolution pilot beside Thunderbird and Outlook |
|
||||
| Present personal PIM on Android | DAVx5, aCalendar+, Google Contacts, and Tasks.org |
|
||||
| Give agents durable project context | `AGENTS.md` and project commands |
|
||||
| Run top-level agents | Herdr on demand |
|
||||
| Maintain conversation state and subagents | Each native agent, primarily Codex |
|
||||
| Review local changes | LazyGit in the task checkout |
|
||||
| Review pull requests | `gh`, then a review worktree when local checks are useful |
|
||||
|
||||
<!-- markdownlint-enable MD013 -->
|
||||
|
||||
## Repository contract
|
||||
|
||||
Active work repositories live under `~/dev/work`; inactive repositories live
|
||||
under `~/dev/work/.archive`, and worktrees under `~/dev/work/.worktrees`.
|
||||
Repositories and worktrees never live under `~/sync`.
|
||||
|
||||
Participating repositories use the following small contract:
|
||||
|
||||
- A tracked `.envrc` enters the default flake development shell without starting
|
||||
services, fetching data, or mutating the checkout.
|
||||
- `flake.nix` owns reproducible dependencies, checks, packages, and formatting.
|
||||
- `just --list` indexes non-obvious tasks and delegates to native commands.
|
||||
- `AGENTS.md` contains concise project facts, invariants, architecture pointers,
|
||||
and checks without duplicating global guidance.
|
||||
- Service-owned `.http` and schema-owned `.sql` files stay beside their owner;
|
||||
generated views, caches, and scratch output do not become durable sources.
|
||||
- Secrets enter at runtime from an approved source or a user-only file outside
|
||||
checkouts, initially `~/.config/yookr/<repository>.env`.
|
||||
- A new worktree behaves like a fresh clone and requires its own explicit
|
||||
`direnv allow`.
|
||||
- Branch-derived ports, databases, and container names are added only after a
|
||||
real collision.
|
||||
|
||||
Use Process Compose only when multiple foreground processes benefit from one
|
||||
visible lifecycle. Use Podman Compose for wholly containerized project stacks,
|
||||
Quadlet for persistent user containers, and NixOS modules for durable host
|
||||
services. Do not nest lifecycle tools for another status screen.
|
||||
|
||||
`yookr-workbench` owns cross-system API requests, operational queries, the
|
||||
Garden/Kubernetes entry point, and Marimo investigations. It does not collect
|
||||
service OpenAPI specifications, schema migrations, deployable model code, or
|
||||
copied application state.
|
||||
|
||||
## Interaction and knowledge boundaries
|
||||
|
||||
- Walker scans the four repository roots, excludes `.archive` and `.worktrees`,
|
||||
and invokes one Nix-owned `open-project` command. The command opens Kitty at
|
||||
the repository root, starts Neovim, and leaves a shell after Neovim exits.
|
||||
- Vivaldi remains the bookmark and web-app authority. Home Manager declares
|
||||
stable launchers for Actual, WhatsApp, and Outlook without duplicating browser
|
||||
state and reclaims their paths when a changed Home Manager generation is
|
||||
deployed. Manual shortcut regeneration may replace one meanwhile and is an
|
||||
accepted unused edge case. Its
|
||||
`Operations` folder owns visibly labeled test/live RabbitMQ bookmarks; terminal
|
||||
inspection uses the Nix-provided `rabbitmqadmin-ng` on demand.
|
||||
- Niri keeps dynamic general-purpose workspaces and a compact navigation and
|
||||
movement vocabulary. The two-output active-workspace exchange remains a
|
||||
bounded pilot.
|
||||
- Codex is primary; Claude Code and Pi are fallbacks. Herdr owns persistence and
|
||||
attention for top-level sessions, while each agent owns its internal state.
|
||||
- Use one primary writer per checkout. Subagents may perform bounded independent
|
||||
read-heavy work, but overlapping changes are sequenced.
|
||||
- Substantial multi-session work may keep one living
|
||||
`docs/plans/<task-slug>.md`; lasting knowledge moves to normal documentation
|
||||
and transient execution history is removed when finished.
|
||||
- `~/sync/notes` is the Markdown/zk authority. Daily intake uses
|
||||
`daily/YYYY-MM-DD.md`; planned meetings and raw transcripts use `meetings/`
|
||||
and `transcripts/` respectively.
|
||||
- Microsoft 365 remains authoritative for work/university PIM and Radicale for
|
||||
personal CalDAV, VTODO, and CardDAV. Clients present those authorities without
|
||||
bridging or copying them.
|
||||
- Fossify records on Android and Syncthing delivers completed recordings to
|
||||
Orion. Orion owns event-driven CPU transcription, diarization fallback,
|
||||
archival, and Markdown publication.
|
||||
|
||||
## Safety boundaries
|
||||
|
||||
GitHub and all other remotes are read-only. Local commits, clones, fetches, and
|
||||
worktrees are allowed; remote mutation requires a separate change to policy.
|
||||
Yookr production source is also read-only during these pilots. Development
|
||||
tooling may be changed, and `yookr-workbench` is the explicit source-code
|
||||
exception.
|
||||
|
||||
Credentials and `.env` files normally stay outside Git, the Nix store, and broad
|
||||
synchronization. Machine-local Yookr credentials use the approved user-key SOPS
|
||||
authority at `~/.config/yookr/credentials.yaml`; callers expose only the fields
|
||||
they need. Original plaintext sources remain until their consumers are verified
|
||||
and removal is explicitly approved. The accepted `yookr-vpn.ovpn` is a narrow
|
||||
exception for Zenith and Polaris: keep it user-restricted and import it into
|
||||
NetworkManager without printing or committing its contents.
|
||||
|
||||
`yookr-data-science/conf/local/credentials.yml` is a separate application-owned
|
||||
exception: Kedro resolves its named credential dataset through the conventional
|
||||
ignored `conf/local` hierarchy. Keep the file untracked and mode 0600; do not
|
||||
generalize the exception to other repositories.
|
||||
|
||||
Only the user activates a NixOS or Home Manager generation. Agents may evaluate
|
||||
and build configurations, then provide an activation command.
|
||||
|
||||
## Phase-one closure
|
||||
|
||||
- The workbench environment, all four SOPS-derived Dadbod connections, read-only
|
||||
example-query runs, and Kulala response chaining passed. The cross-system
|
||||
investigation and Marimo report pilots move into phase two.
|
||||
- Add another ephemeral read-only rclone remote only when credentials for a new
|
||||
Leafcloud project become available. Irristaud listing has passed; do not upload.
|
||||
- Use the reviewed local Yookr OpenAPI contract while the accepted malformed
|
||||
generated test document remains deployed.
|
||||
- Herdr's bounded issue 197 pilot is complete. Documented named-session
|
||||
detach/reattach persistence is accepted without a redundant live trial, and
|
||||
notifications are intentionally disabled. Codex/Claude fallback, attention
|
||||
states, local branches, parallel non-overlapping plans, and the dirty-removal
|
||||
guard passed; the plans show that implementation belongs outside the dashboard
|
||||
repository.
|
||||
- Keep Bruno and DBeaver; retiring old applications is outside phase one.
|
||||
|
||||
## Deferred pilots
|
||||
|
||||
Revisit these alongside related phase-two ideas rather than as isolated cleanup.
|
||||
|
||||
- Capture Zenith's external display identity during a docked session and test the
|
||||
two-output `Super+A` exchange, including name and focus restoration on failure.
|
||||
- Resume Evolution and Android PIM only when the user chooses to run those daily
|
||||
use pilots.
|
||||
- Replicate the proven workstation workflow on Polaris only when the user resumes
|
||||
its machine-local VPN and credential procedure.
|
||||
|
||||
## Deferred work
|
||||
|
||||
- Define the team release process and OpenAPI publication policy before encoding
|
||||
deployment automation.
|
||||
- Adopt a company-wide infrastructure secret source only after Yookr selects one.
|
||||
- Publish `yookr-workbench` only when sharing becomes useful.
|
||||
- Pilot SharePoint browse/download through `rclone` after Microsoft consent.
|
||||
- Revisit Worktrunk, `codex agents`, Walker-to-agent launching, formal agent
|
||||
evaluation, remote builders, CI runners, and agent offload only after a concrete
|
||||
gap appears.
|
||||
- Add report servers, notebook hubs, groupware, terminal PIM, meeting summaries,
|
||||
concurrency isolation, OCR, dictation, clipboard remapping, or additional
|
||||
convenience surfaces only after repeated use establishes an owner.
|
||||
|
||||
## Reference baseline
|
||||
|
||||
Recheck fast-moving interfaces against their pinned versions before changing
|
||||
them.
|
||||
|
||||
<!-- markdownlint-disable MD013 -->
|
||||
|
||||
- Projects: [Nix flake templates](https://nix.dev/manual/nix/latest/command-ref/new-cli/nix3-flake-init), [nix-direnv](https://github.com/nix-community/nix-direnv), [just manual](https://just.systems/man/en/), [Podman Compose](https://docs.podman.io/en/latest/markdown/podman-compose.1.html), [Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html), [Marimo](https://docs.marimo.io/).
|
||||
- APIs/data: [Kulala](https://kulala.app/), [Dadbod](https://github.com/tpope/vim-dadbod), [RabbitMQ management](https://www.rabbitmq.com/docs/management), [rclone S3](https://rclone.org/s3/), [rclone OneDrive/SharePoint](https://rclone.org/onedrive/).
|
||||
- Desktop: [Walker](https://walkerlauncher.com/docs/providers), [Elephant menus](https://github.com/abenz1267/elephant/tree/master/internal/providers/menus), [Vivaldi web apps](https://help.vivaldi.com/desktop/miscellaneous/progressive-web-apps/), [Niri IPC](https://niri-wm.github.io/niri/IPC.html).
|
||||
- Agents: [Codex configuration](https://learn.chatgpt.com/docs/config-file/config-basic), [Codex long-running work](https://learn.chatgpt.com/docs/long-running-work), [Herdr](https://herdr.dev/docs/configuration/), [Git worktrees](https://git-scm.com/docs/git-worktree).
|
||||
- PIM/knowledge: [Evolution account types](https://help.gnome.org/evolution/intro-account-types.html), [Radicale](https://radicale.org/v3.html), [DAVx5](https://manual.davx5.com/introduction.html), [Tasks.org](https://tasks.org/docs/), [`zk` daily journal](https://github.com/zk-org/zk/blob/main/docs/tips/daily-journal.md).
|
||||
- Infrastructure: [Gardenctl](https://gardener.cloud/docs/gardenctl-v2/), [NetworkManager](https://networkmanager.pages.freedesktop.org/NetworkManager/NetworkManager/nmcli.html), [Syncthing](https://docs.syncthing.net/users/syncing).
|
||||
|
||||
<!-- markdownlint-enable MD013 -->
|
||||
Reference in new issue
Block a user