The install layout a machine should have, seasoned owner or not:
~/officerdev/
platform/ the app
data/ DATA_PATH
dockers/ services the app store provisioned
capabilities/ the file-based item store
One root, everything under it. OFFICER_ROOT derives from DATA_PATH rather than being a second variable
that has to agree with the first.
Deliberately not `~/dockers`, where a seasoned user already keeps their own estate — 47 services on this
machine. That separation buys two things. Containers the app store created are distinguishable from the
user's own structurally, rather than by a naming convention we would have to enforce and they could
break. And we never reason about someone else's compose files: the store does not scan, adopt or modify
anything outside its own directory.
That also simplifies "I already have one of these" — it is answered by the user giving a URL, never by
us finding a directory and guessing whose it is. An earlier draft had the installer adopting existing
directories, which meant reading, and potentially writing over, services Officer did not create.
This development machine predates the convention and derives an ugly-but-correct path, since the project
sits inside ~/dockers/officer.dev. Still isolated, still one root. New installs get the clean shape.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
First slice, on a worktree branch so none of it touches the tree the live server runs from.
`sidecar_installs` — server-level, no userId, because a sidecar is one process serving the machine.
That is the line that keeps the model coherent for several users: installed is server-level and
owner-only, configured is per user in service_connections. A member can use Gitea without being able to
install it or point it somewhere else.
`installed` and `enabled` are separate because they answer different questions, which is what gives the
reversible middle ground: disable stops the process and keeps container, config, schema and data.
`completedSteps` makes install resumable rather than merely retryable — the failure mode being designed
against is a half-installed service that neither works nor uninstalls.
The catalogue is data, not code: no functions, no compile-time coupling, because the same shape has to
arrive as JSON from marketplace.officer.dev later. Its test pins it to the real estate — it offers
exactly the processes the light profile excludes, names processes that exist, and claims capabilities
that exist. That last check earned itself immediately: it caught `vault` (no capability at all — it is
EXEMPT because Bitwarden clients carry a Vaultwarden bearer, not a platform JWT) and `notify` (which
does have one, where I had written null).
Docker templates follow the convention already in use across 47 services in ~/dockers: a directory per
service, compose inside, relative bind mounts so data sits beside it, USER_UID/USER_GID as the owner.
An existing directory is evidence of an existing install and must be adopted, never overwritten.
Records what Phase 0 must not foreclose: a remote marketplace, sidecars moving to their own
repositories, and third-party plugins — including the note that catalogue.test.ts pins Phase 0's
invariant rather than the design's, since that relationship inverts once sidecars leave this repo.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Agreed in conversation, nothing implemented. Light stops being a variant and becomes the baseline —
chat, terminal, file browser — and the other fourteen sidecars arrive by the user asking for them from
an app store, eventually including sidecars the user did not write.
Mostly not a rewrite, for three reasons already true: every API route stays mounted regardless of which
sidecars run, officer already spawns nothing, and service_connections already solves the multi-user
case. What is new is provisioning, per-sidecar schema, and persisted install state.
Docker: officer is the installer, never the owner. Real compose files in the user's own directory,
started as him, found again by label. `docker compose down` works, and the containers outlive Officer.
Per-sidecar schema is right here specifically because third-party plugins are a real goal, and the
dependency graph makes it tractable: measured across 19 schema files, every sidecar depends on auth.ts
and nothing else, with no sidecar-to-sidecar edges anywhere. So the plugin contract is "you may
reference users.id" — which also makes full uninstall well-defined, since nothing else points at a
plugin's tables.
service_connections stays core and shared rather than per-service, because it already does the part
nobody would get right alone: a NULL url means "inherit the instance", so the owner's row is the
instance and members hold only their own credential, making "members never see the instance URL" a
property of the schema instead of a filter someone has to remember.
Records six open questions rather than settling them, including plugin migrations, ID namespacing for a
marketplace, and where plugin-specific config lives.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
pastilhasandClaude Opus 5