updates

modules/capabilities/workbench/README.md

@@ -0,0 +1,115 @@
+# Company environment
+
+This capability owns the company-root tools, human workbench environment and
+persistent read-only company mounts. Garden packaging and company certificates
+remain in `../yookr-dev/`. Requests, queries, analysis, `uv.lock`, content and
+runtime state stay in `~/yookr/workbench`.
+
+Home Manager installs `devenv.nix` and `devenv.yaml` in `~/yookr/workbench`
+(human credentials), selecting the system's exact nixpkgs store path. The work
+profile also installs the tools for use at the company root without activation. The devenv CLI
+uses its own upstream dependency closure; this avoids rebuilding its dependencies
+against an unsupported pin. Its version is locked by the repository flake.
+
+## Activation and trust
+
+After reviewing and activating the configuration on each workstation:
+
+1. Remove the obsolete `~/yookr/.envrc` and `~/yookr/workbench/.envrc`. Direnv is
+   no longer installed or hooked. Product/personal `.envrc` files remain yours to
+   migrate; this pass does not convert them.
+2. Run `devenv allow` in `~/yookr/workbench` only. Open a new terminal
+   for the native Zsh hook. Reload/file watching uses upstream defaults.
+3. `devenv.lock` and `.devenv/` are local generated state, not new configuration
+   owners. Do not commit them into the Nix repository. Retain product locks.
+4. The human workbench attempts company, live and test resolution independently.
+   `workbench-reload` retries; `workbench-reload --tools-only` clears the variables
+   owned by this loader. Existing processes/editors keep their original environment.
+
+For a clean, credential-free check use the flake's tools-only `#workbench` shell
+from a clean parent environment. For native devenv without credential loading,
+set `WORKBENCH_TOOLS_ONLY=1` before `devenv shell`. Neither method removes arbitrary
+credentials already inherited from its parent; they are not isolation mechanisms.
+
+The company root intentionally has no generated devenv environment pending review:
+upstream's hook does nothing while another devenv shell is active, so an ancestor
+shell would prevent automatic workbench entry and interfere with project environments.
+The recommendation is installed tools at the company root, native activation at the
+workbench, and product-owned environments below `projects/`.
+
+## Credential provisioning (user-run only)
+
+The encrypted company document belongs at `modules/secrets/company.yaml` in this
+repository. It is deliberately absent until you migrate it. Reuse the existing
+machine age identities; never copy private keys into Git. On each workstation,
+obtain its public recipient with `age-keygen -y /var/lib/sops/keys.txt`.
+
+On the machine holding the old credentials, run from this repository:
+
+```console
+SOPS_AGE_KEY_FILE="$HOME/.config/sops/age/keys.txt" python3 modules/capabilities/workbench/migrate-credentials.py \
+  "$HOME/.config/yookr/credentials.yaml" modules/secrets/company.yaml \
+  --age 'POLARIS_PUBLIC_AGE_RECIPIENT,ZENITH_PUBLIC_AGE_RECIPIENT'
+```
+
+The helper decrypts only in memory, preserves the old file, and refuses to overwrite
+an existing destination. The new document contains root-level company login and
+live database URLs for SecretSpec, plus the existing `leafcloud` map for mounts.
+MySQL certificate verification behavior is preserved. Test credentials are not
+copied into the new document. Review the encrypted result before a local commit;
+pushing remains a separate decision. Other machines receive ciphertext through the
+existing repository. Edit it with `sops edit modules/secrets/company.yaml` using the
+machine's normal `SOPS_AGE_KEY_FILE=/var/lib/sops/keys.txt`.
+
+### Test cluster: mapping and login still pending
+
+No cluster query is needed to build this repository. Before enabling test loading,
+settle the explicit test context and existing application Secret/namespace/key
+mappings. The loader expects a `~/.config/workbench/test-secrets.toml` manifest with
+profile `test`, using only explicit `k8s+secret://SECRET@NAMESPACE` providers and
+`ref.item` for existing keys. Required exports are:
+
+- `YOOKR_MYSQL_TEST_DATABASE_URL`, `YOOKR_MONGODB_TEST_DATABASE_URL`
+- `RABBITMQADMIN_USERNAME`, `RABBITMQADMIN_PASSWORD`
+
+If applications store URL components separately, the manifest/composition must be
+adapted after confirming their keys; do not invent field names or change URL escaping.
+This manifest is a provisioning boundary pending review, not a second global secret store.
+
+Test loading also requires an explicitly prepared, noninteractive kubeconfig at
+`$XDG_RUNTIME_DIR/workbench/test-kubeconfig`. No generic login helper is provided:
+the actual context and exec plugin must be inspected first, then its native or
+provider-specific cached login flow selected. Do not reimplement Kubernetes' exec
+credential protocol for an unknown plugin. Until both runtime files exist, test
+reports unavailable. Shell entry never invokes authentication or opens a login popup.
+
+SecretSpec exports are captured in memory with stdin closed and a timeout. Errors
+report only the unavailable source, not provider output or secret values. Sources
+load independently; unavailable sources clear their old variables. Test never falls
+back to SOPS, and live never depends on Kubernetes. Native devenv's all-at-once secret
+resolution is intentionally not used: it would couple their failure behavior.
+
+## Mounts
+
+`company-obs.service` and `company-sharepoint.service` are user services on both
+workstations. Mounts live at `~/yookr/workbench/{obs,sharepoint}`. They are read-only,
+use `--vfs-cache-mode off`, and retry failures every minute. No background content
+mirror remains. The existing local SharePoint mirror is preserved, not deleted.
+Small memory buffers and filesystem metadata are still used.
+
+OBS uses the company's encrypted `leafcloud` map and machine age key. SharePoint
+uses the existing native rclone remotes `company-sharepoint` and
+`company-sharepoint-projecten` in `~/.config/rclone/rclone.conf`; configure/login to
+these on each workstation with rclone. Tokens remain application-owned outside Git.
+Before first activation, unmount any old workbench-entry OBS mount. Do not empty or
+replace nonempty mount directories: move any authored content deliberately first.
+
+```console
+systemctl --user restart company-obs company-sharepoint
+systemctl --user status company-obs company-sharepoint
+```
+
+Do not invoke the old workspace `just mount-obs` helper once systemd owns the mount.
+The old helper/recipes can be removed after the new mounts are accepted in use.
+Shell exit does not unmount company files. All processes running as your user can
+read the mounts; these services do not isolate agents.