# Developer experience

Personal workstation and dev-box workflows live here. Start with the
[developer guide](../docs/development.md) and [dev-box setup](common/GUIDE.md).

| Directory | Ownership |
| --- | --- |
| `common` | Workstation defaults, takeover controller, shared local AAI, tools images, Tilt, Minikube commands and the Pharos DX desktop |
| `metallo` | Identity and Site API qualifications, Icarus Runtime laboratory |
| `themelio` | Development configuration for the retained Themelio stack |
| `beto` | Beto development entry points and future service-specific tooling |
| `arm64-singledrive` | Opt-in existing-K3s, internal-drive storage and separate ARM64 build-runner configuration |

The root Makefile and `pnpm dev:*` are convenient entry points. Each checkout reads
its ignored root `.env`; private state remains under `.local` so sessions survive
the directory reorganisation. `make help` lists the daily workflow and `make
dx-help` lists shared tools and specialist qualifications.

Whole-stack commands now use service-neutral names. Update saved scripts using
these retired aliases; the old names no longer dispatch commands:

| Previous command | Current command |
| --- | --- |
| `make metallo-keycloak` or `make metallo-reconcile` | `make reconcile` |
| `make metallo-deploy` | `make deploy` |
| `make metallo-keycloak-forward` | `make devbox-forward` on the workstation |
| `make metallo-urls` | `make urls` for the current stack; `make legacy-controller-urls` for the older namespace |
| `make metallo-storage-test` | `make devbox-storage-test` |
| `make metallo-tools` / `make metallo-verify` | `make dx-tools` / `make dx-verify` |
| Older namespace loop's `make metallo-setup`, `metallo-plan`, `metallo-tilt`, etc. | Explicit `make legacy-controller-*` maintenance commands |

The [legacy controller guide](common/CONTROLLER-LOOP.md) covers that separate
namespace. Current dev-box setup uses `make devbox-setup`. Metallo's identity,
Site API and Icarus commands keep their `metallo-` prefix; list them with
`make metallo-help`.

`devops` owns reusable deployment infrastructure and assets for official testing,
staging and production. Canonical manifests remain in `gitops`. DX can consume
these interfaces; application and deployment code cannot import DX implementation.
The architecture check enforces this direction. Repository verification and
integration test runners remain in `scripts` and `.github`.

Both deployment and DX commands use the pinned Python environment in `devops`.
This avoids separate dependency versions for the same Ansible and Kubernetes
libraries. `scripts/environment.py` supplies the private credential helpers
shared by integration checks and the Minikube launcher.

The Minikube launcher is `common/scripts/local_cluster.py`. Use `pnpm dev:up`,
`pnpm dev:status`, `pnpm dev:forward` and `pnpm dev:down` from the repository root.
The dedicated profile retains its data when stopped.

The [Pharos DX desktop](common/desktop/README.md) adds a tray panel and Workspace
dashboard. Use `make dx` to develop it and `make doctor` for the same diagnostics.