atelier/PLUGIN.md

Atelier — extracted from a standalone service into a plugin

Status: extracted 2026-08-20, unattended overnight run. Read BLOCKERS.md alongside this file — it has the decisions made without being able to ask, in the order they were found. This file is what moved, what didn't, and why; that one is what was uncertain.

Atelier is image generation as a service: a provider-shaped API over OpenAI's image endpoints, storing what it makes so every image has a durable reference. It came from ~/officer-dev/dockers/officer-atelier, a standalone Bun/Hono/Postgres server predating the plugin system, still running in production as officer-atelier (PM2, port 3002, atelier.officer.dev) — see "What did not move" below before assuming it is safe to touch.

---

What moved, and what changed on the way

Nothing pointed the other direction. Unlike offscale and music, a grep of the whole platform for atelier found no reverse dependency — no widget, no relay, nothing importing from the standalone service. It came out whole with no seam to design around, which is the exception rather than the rule for this kind of extraction.

The backend — sidecar/

Providers (adapter-shaped: types.ts, openai.ts, an index.ts that dispatches — OpenAI is the only adapter today, and the point of the shape is that a second one is a new file, not a new screen), the generation queue (Postgres-backed, MAX_CONCURRENT_GENERATIONS workers), collections, and the database layer moved essentially unchanged. Three things did not:

1. Images are served from GET /files/:filename, authenticated, not an unauthenticated PUBLIC_URL route. The standalone service served /images/* off Bun's own route table with no session, because every image needed "a permanent URL" reachable by the mobile app and anything else on the tailnet. Inside Officer that is not an option — see "What you may NOT do" in the kickoff prompt. The platform's own ?token= escape hatch (already used by FileViewer/file-types.ts and the music plugin's MusicPlayerHost for exactly this — a browser cannot put an Authorization header on an <img src>) covers it: the JSON API returns /files/<name> (relative, no host, no token — the sidecar cannot know the platform's public origin any more and does not need to), and the frontend appends its own token when rendering (web/lib/api.ts's fileUrl).

2. The OpenAI-key bootstrap fallback reads the secret store before .env. keyForProvider still prefers a provider row's own encrypted key; the fallback that used to be process.env.OPENAI_API_KEY directly is now getSecret('atelier-<adapter>-key') first, .env second — getSecret, never getKey, because a foreign credential must not be silently substituted with a random one. Set it with bun run secret:set atelier-openai-key.

3. provider_settings did not come along. It is the one-row-per-adapter shape providers replaced (see the standalone repo's own providers/schema.ts comment and scripts/migrate-providers.ts), and grepping the server code found no caller anywhere except that migration script — which also did not move. Its table and its one row stay in the atelier database, untouched. If a machine's migration never ran, that is a real gap, but it is the standalone service's gap, not one this extraction introduced.

ping/echo (smoke-test routes, no caller) did not move either — the sidecar's /_health covers liveness, matching every other HTTP sidecar in this codebase.

The database — stays separate, does not fold into officer_db

Decision 3 said to check whether collections and provider_settings were empty before folding them into officer_db. Both had rows (2 and 1), so the atelier Postgres database stays separate — the sidecar keeps its own connection (sidecar/db/db.ts), reading OFFICERDEV_POSTGRES_URL from the platform .env. This is new territory for the plugin system: db/schema.ts at a plugin's root is the officer_db-prefixed-tables convention (pushPluginSchema, <appname>_ prefix), and this plugin has no such file — discoverPlugins() correctly reports schema: null for it, and the install flow's schema step is simply skipped. Nothing in src/servers/plugins/ needed to change for this, because "no db/schema.ts" is already a valid state the discovery contract handles — a plugin with an internal, self-managed database is indistinguishable from a plugin with no tables at all, as far as the platform is concerned. Worth knowing before assuming every plugin's data lives in officer_db.

Not set automatically. OFFICERDEV_POSTGRES_URL has no default — see BLOCKERS.md for why (mainly: pointing it at the live production atelier database while that database's own standalone service is still running risks two processes racing the same generation queue). The owner has to add it before installing.

Migrating into officer_db as atelier_*-prefixed tables is real follow-up work, not done here — five tables (generations, collections, collection_items, providers, and the dead provider_settings, which should be dropped rather than migrated), real data, needs a human watching it.

The frontend — three panels, plus a settings screen

web/panels.ts + web/layout.ts: Generate, Gallery (+ Lightbox), Collections — the ≈1,200 lines of real work the brief identified, ported with the shadcn components Officer already ships (@/components/ui/* — the standalone service's own src/apps/frontend/components/ui/* did not move, per decision 1). Providers did not become a fourth panel:

Providers is a platform Settings screen (Settings → Integrations → Atelier, src/apps/officer-web/.../IntegrationsSettings/AtelierProviders.tsx), per decision 2. Worth flagging loudly: IntegrationsSettings/index.tsx itself carries a comment, written five days earlier when email was extracted, that says the opposite — "a plugin contributes panels, not settings sections, so it now lives inside the email workspace itself." Decision 2 was explicit and pre-made, so it was followed anyway, and the contradiction is recorded in BLOCKERS.md rather than silently resolved either way. AtelierProviders.tsx calls /api/atelier/providers over plain HTTP via useClient() — it imports nothing from plugins/atelier/, so nothing here reaches back across the plugin boundary; it is exactly the same relationship any authenticated frontend has with any authenticated backend.

Panel coordination is URL + one channel, never props (a panel component only ever receives panelId):

• Gallery's lightbox is ?selected=<id>; Collections' detail is ?collection=<id> — two different names because both panels render on the same route at once and would otherwise collide.
• Generate bumps useAtelierRefresh (added to src/workspaces/officerdev/src/channels.ts, same stable-bump shape as useFilesRefresh) when a job finishes; Gallery subscribes to it. This replaces the standalone app's onFinished callback prop, which only worked because App.tsx lifted the gallery's state above both tabs — not an option once they are independent panels.

The default layout is a fixed horizontal three-way split (Generate 26% / Gallery 48% / Collections 26%) rather than the standalone app's hash-based tabs — the LayoutNode type has no tab-group concept, only group (split) and panel, so three panels means three panes. Users can resize or rearrange freely; this is only the starting arrangement.

sharp — promoted to a direct dependency

generations/inspect.ts needs it to measure width/height/alpha-channel/opacity of a written image — load-bearing, not incidental: it is how a background: transparent request that silently produced an opaque image gets caught, which the standalone repo's own comments call "the single most consequential failure for an asset destined to be an app icon." It was already resolved in bun.lock as an optional transitive dependency of next; adding it as a direct dependency pulled in no new package versions — verified by reading the lockfile diff before committing it.

---

What did not move, and must not be touched

The standalone officer-atelier service keeps running, unchanged. Its own ecosystem.config.cjs says plainly: "this is the instance the mobile app talks to, so it holds still." It serves https://atelier.officer.dev, holds real data (87 generations, 2 collections, 5 providers on the machine this was extracted from), and this extraction did not stop it, did not touch its nginx config, and did not touch the mobile app. Cutting the mobile app over to the plugin's route — or deciding whether to at all — is the owner's call, not something this run made unilaterally. Until that happens, having both installed means two independent Atelier deployments existing side by side, which is expected, not a bug.

---

Verification

• bunx tsgo: clean.
• bun test: baseline was 1041 pass / 0 fail across 90 files; after this extraction, 1069 pass / 0 fail across 92 files — the two new files are sidecar/serialize.test.ts and sidecar/generations/response.test.ts, both ported from the standalone repo (URLs updated for the new /files/ scheme). No regressions, no file count drop.
• discoverPlugins() finds the plugin, the manifest validates, schema: null as expected (separate database).
• The platform-side proxy router (api/router.ts) mounts and correctly answers 503 atelier sidecar not available with no sidecar running — same behaviour as offscale's.
• The sidecar's internal Hono app was exercised directly (buildHonoApp(), real HTTP requests, no port bound) against the atelier_dev Postgres database: /providers, /providers/adapters, /collections, /images all answered 200 with real rows; /files/<missing> answered 404; an unknown route answered the OpenAI-shaped 404 envelope. Old provider rows correctly failed to decrypt (a fresh secret.key was generated for this checkout, as intended — a key that will not decrypt is broken, not absent, and keyForProvider reports configured: false rather than crashing).
• The real production SPA bundle builds successfully with the plugin included. Called generatePluginsModule and rebuildFrontend directly (the same functions refreshPluginMounts calls during a real install) against a synthetic "atelier is installed and enabled" state — no server running, no port bound. Bun.build, with the real Tailwind plugin, compiled Plugins.gen.tsx, all three panels, and the new AtelierProviders settings section in 2.2s with zero errors: 3 outputs, no warnings. This is the same build step an install performs and exercises everything bunx tsgo cannot — module resolution through Bun's own bundler, JSX compilation, Tailwind processing — without needing a running server. What it does not prove is that the result renders correctly in a browser; see below.
• Not done: a live PM2 install/enable/disable/uninstall/purge cycle through /marketplace, per the runbook's own verification table. This machine's live officer process serves the owner's real session and its own plugins/ directory is the main checkout, not this worktree — installing through it would write real rows into the shared officer Postgres database from code that only exists here. That crosses into "affects shared systems beyond the local environment," so it was not done unattended. The safer checks above cover the same ground read-only or against an isolated database.

---

Open, for whoever picks this up

1. Publish to gitea.officer.dev/plugins/atelier and register it in the marketplace. Not done — see BLOCKERS.md for why and the exact commands.
2. OFFICERDEV_POSTGRES_URL has to be set before install. No default, on purpose.
3. The atelier → officer_db migration, described above, once someone can watch it happen.
4. assets/icon.png and assets/splash.png are [placeholder] flat swatches. Done 2026-08-20: both come from the suite's own masters in the OfficerIcons repo — OffAtelierAppIcon (trimmed, since that master is 1312x1199 rather than square, then centred on a transparent 256 canvas) and OffAtelierSplashScreen at 1024. Same shapes and same convention as plugins/music.
5. A real PM2 install/enable/disable/uninstall/purge cycle, on a machine where doing so does not touch the owner's live session or shared database.
6. Deciding whether and when to cut the mobile app over from atelier.officer.dev to the plugin's route, and what happens to the standalone service afterward.

Reversed 2026-08-20: officer_db, not a separate database

The extraction kept Atelier's own atelier Postgres database, because BLOCKERS.md decision 3 said to when the tables already had rows. The owner reversed that afterwards, and the reasoning is worth keeping:

A plugin that behaves differently from every other plugin is a plugin nobody can reason about. The separate database meant a second connection string to set before install, a second thing to back up, a second thing to get wrong on a new machine, and failure modes no other plugin shares. None of that was bought by anything except avoiding a migration.

So: four atelier_-prefixed tables in officer_db — atelier_collections, atelier_collection_items, atelier_providers, atelier_generations — created empty by bun db:push, like every other plugin. Index and check constraint names carry the prefix too; those are global in Postgres and would otherwise be the one thing that collides.

ATELIER_POSTGRES_URL is gone. sidecar/db/db.ts reads OFFICERDEV_POSTGRES_URL ?? POSTGRES_URL, the house convention, which the platform already sets.

The standalone service's data is NOT here. It is still in the old atelier database, and the old service is still running against it, untouched. Migrating those rows — 2 collections, 73 items, 5 providers, 87 generations — is a deliberate, watched step, done after the plugin is installed and proven on alpha. Nothing about this plugin depends on it happening.