scripts/ was holding two unrelated kinds of thing: install-this-machine, and run-this-occasionally. The
eight installers now live in scripts/setup/; what stays at the top level is the build steps (gen-index,
prebuild, build/) and the two maintenance scripts (reindex-music, rebuild-soulseek-tree).
The move is not just a rename. Three of these derive the repo root from their own location:
setup.sh:51 PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
setup_mac_light.sh:51 same
cleanup-desktop.sh:134 ENV_FILE="$(dirname "$0")/../.env"
Left alone, all three would now resolve to scripts/ — and nothing downstream complains. PROJECT_DIR is
where .env is written, where `bun install`, `gen:index` and `db:push` run, and what pm2 is pointed at, so
a fresh install would have quietly provisioned scripts/ and reported success. cleanup-desktop.sh fails
the other way: it would find no .env, print "No .env — skipping", and leave the real VNC_PASSWORD in the
real file. All three are now `../..` with a comment saying why the level matters.
provision-user-dirs.ts imports data-path.ts relatively; that one tsgo caught.
Also disambiguated `setup.sh` where it had become two files. app-store/templates/<name>/setup.sh is a
per-sidecar installer with its own contract, and preflight.ts + docs/sidecar-app-store.md discussed both
in the same paragraph. The host one is now spelled with its full path at those sites.
Verified: bash -n on all six shell scripts, tsgo clean, os-user tests pass, both derivations resolve to
the repo root, starship.toml still resolves from os-user-shell.ts, and provision-user-dirs.ts runs under
DRY_RUN.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
It was in both light profiles on the reasoning that it fronts a REMOTE instance and so
needs nothing installed locally. That is true and it was beside the point: a baseline
process appears in the dock and in the Permissions screen whether or not anyone ever
gave it a URL, so a fresh server offered to grant members access to a Gitea that did
not exist. "Is Gitea here" had two answers that could disagree.
Now it is `existing` mode with a URL and a token, like any other remote service, and
the one place that says whether it is here is the install row. No compose template and
no `provisioned` mode: Gitea is always something the owner already runs, and offering to
spin one up would mean owning its migration, backup and upgrade story.
members: 'none' — not because Gitea is single-tenant, it is the most per-user service
in the catalogue, but because there is nothing for the INSTALLER to do. The owner's
connection carries the instance; each member adds their own access token from /gitea and
acts only as themselves upstream. A provisioner would need an admin token and would mint
credentials on their behalf, which is more authority than this needs.
The catalogue test already pinned "the store offers exactly what light leaves out", so
removing it from the profile is what forced the entry to exist. Both light profiles
changed together — the mac one carried the same comment and the same gap.
Permissions on a fresh install is now Files and Plans. Plans stays because it reads the
platform's own shipped markdown from <repo>/plans, not anyone's disk, so it needs
nothing installed and exposes nothing.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`ecosystem.light.config.cjs` did not mention officer-gitea, so `defineProfile` threw while the file was
being loaded and pm2 could start NOTHING from it — not the app, not the agent, not the terminal. The
profile has been dead on arrival since gitea was added to ecosystem.config.cjs and to the mac profile
but not to this one.
That is the drift check doing its job rather than a flaw in it: the alternative is a light install that
silently starts less than it claims. The cost is that adding a sidecar breaks every profile until each
one classifies it, which is the trade the file already documents.
Included rather than excluded, matching the mac profile's reasoning: this sidecar fronts a REMOTE Gitea
whose URL and token live in `service_connections`, so it installs nothing locally. That is the line
between it and the excluded sidecars, which supervise a local daemon or container.
Both light profiles now load and contain the same six processes.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
officer-jellyfin owns the whole Jellyfin contract: the instance URL, the access
token, the Jellyfin user it belongs to and the DeviceId its sessions are keyed
by. The platform side is a 17-line proxy holding no credentials.
Servers are a registry, not a single row — this machine runs four instances and
the owner switches between them. The password is never stored: it is traded once
for an access token through AuthenticateByName, and only that token is persisted,
encrypted.
Two doors. /_officer/* is a hand-written JSON façade for the things the browser
should not have to know — the user id in the path, the Fields lists that decide
whether a grid has posters, the PlaybackInfo negotiation. /_jf/* is a GET-only,
allow-listed byte pass-through for images, video, HLS and subtitles; it keeps
Jellyfin's own paths because a master playlist references its segments
relatively, so any renaming would mean rewriting m3u8 bodies.
TranscodingUrl arrives with api_key=<access token> in its query string and would
otherwise be handed straight to a video element. It is stripped before anything
is returned; the pass-through re-adds the credential as a header.
Video only — Officer's own player owns audio, so music collections are filtered
out of the library list.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Renamed for parity now that Linux has a light profile too:
scripts/setup_mac.sh -> scripts/setup_mac_light.sh
ecosystem.mac.config.cjs -> ecosystem.mac.light.config.cjs
The macOS process list was still a hand-copied subset, which is the shape that
broke it: written 2026-07-28, within days it was running the Anthropic proxy
under the name officer-claude with nothing spawning `claude`, and pointing at a
pty entry point that had moved. Both silent. It now declares names and reasons
and reads script/args from ecosystem.config.cjs, so a launch change on the host
reaches it for free.
The include/exclude checks moved into ecosystem.profile.cjs rather than being
copied into the second profile — duplicating the guard rails would have repeated
the mistake they exist to catch. Both profiles were re-tested against a mutated
host ecosystem: renaming an included app and adding an unclassified sidecar each
throw in both, and an unmodified host loads five apps in both.
Kept as two files rather than collapsed into one, even though they currently
produce identical output. The exclusions do not mean the same thing: on macOS
officer-vnc CANNOT run, there being no Xorg; on a Linux light install it could
run fine and you have chosen not to. Merging them would lose that, and they
diverge the moment one profile gains something the other cannot have.
setup_mac_light.sh's verification loop now reads app names with node instead of
grepping for `name:` — the derived profile has no literal keys, so the grep
would have silently listed no services at all, which reads the same as a healthy
install with nothing configured.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
OFFICER_PROFILE=light installs the same thing the macOS build does, on Linux:
the file browser, the terminal, and Claude/opencode chat. It skips the archive
extras, the sudoers entry and auto-suspend disabling, Go, Rust, PulseAudio,
cliamp, Neovim, the shell tooling and yt-dlp, brings up Postgres alone of the
five Docker services, and starts ecosystem.light.config.cjs. Unset or `full`
behaves exactly as before.
The profile changes which processes start, not which code ships — every API
route stays mounted, so features whose sidecars are absent report themselves
unavailable rather than disappearing.
ecosystem.light.config.cjs DERIVES its apps from ecosystem.config.cjs rather
than copying them, because the hand-copied Mac list was broken within days of
being written by a sidecar split in two and a pty entry point that moved, and
both failures were silent. Here a script/args change on the host propagates for
free, and two consistency checks turn the silent cases loud:
- a name the profile needs that the host no longer defines throws at load
- an app added to the host that is in neither the include list nor the annotated
exclusion list throws, so a new sidecar cannot default to "not in the profile"
without someone deciding
Both were tested against a mutated copy of the host ecosystem: renaming
officer-agent and adding an unclassified sidecar each throw, and the unmodified
file loads five apps.
The verification block now reads app names with node instead of grepping for
`name:` — the derived file has no literal keys to match, so a grep would have
silently verified nothing — and skips the checks for tools the profile did not
install, so a clean light run does not report Go and cliamp as missing.
Full-profile behaviour is unchanged by construction: every guard wraps the
original code in an else branch. The preamble was tested across unset, full,
light and an invalid value.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
pastilhasandClaude Opus 5