PLUGIN.md and README.md

PLUGIN.md is the record: what moved, what changed on the way (authenticated image serving, the
secret-store OpenAI key fallback, provider_settings left behind), what stays running untouched (the
standalone service the mobile app still talks to), why there is no db/ directory, and what verification
did and deliberately did not cover.

README.md is the marketplace shop window — what it does, what it needs (its own Postgres database,
an OpenAI key), and an honest limitations section: two Ateliers can exist side by side right now, and
there is no per-user data model yet.

README.md

@@ -0,0 +1,73 @@
+# Atelier
+
+Image generation for an Officer server: a provider-shaped API over OpenAI's image endpoints, storing
+what it makes so every image has a durable reference — a gallery you can browse, collections you can
+organise, and a job an agent can poll rather than block on.
+
+Atelier was a standalone service before this plugin existed
+(`~/officer-dev/dockers/officer-atelier`, still running as `officer-atelier`, still what the mobile app
+talks to). This plugin is a fresh extraction into Officer, not a replacement for it yet — see
+`PLUGIN.md` before assuming the two are interchangeable.
+
+## What you get
+
+- **Generate** — a prompt, a model, size/quality/background, and a job you watch settle. `n` images
+  become `n` independently-tracked rows, so one failure out of four does not discard the three that
+  worked.
+- **Gallery** — everything generated, newest first, with a lightbox: pan, zoom about the cursor,
+  checkerboard/dark/light backdrops for telling a transparent background from an opaque one that only
+  looks it.
+- **Collections** — named sets of images. A generation request can name one by name and it is created on
+  first use; the gallery and the lightbox can file an image into one after the fact.
+- **A provider-shaped backend.** "OpenAI" is code, written once; a *provider* is a row — which model,
+  whose key, on or off — and several can share one adapter. Today OpenAI is the only adapter; the point
+  of the shape is that a second one is a new file, not a redesign.
+- **An OpenAI-compatible job API**, for agents. `POST /api/atelier/images/generations` accepts OpenAI's
+  request body verbatim and answers `202` with a job id rather than blocking for the length of the
+  generation — the caller polls `GET /api/atelier/images/generations/:id`, optionally with `?wait=` to
+  long-poll instead of retrying in a loop.
+
+## Requirements
+
+- An Officer server, version 1.0.0 or later.
+- A **separate Postgres database**, and its own environment variable: `ATELIER_POSTGRES_URL`. Atelier's
+  tables (`generations`, `collections`, `collection_items`, `providers`) do not live in `officer_db` —
+  see `PLUGIN.md` for why, and set this before installing. There is no default.
+- An OpenAI API key, set with `bun run secret:set atelier-openai-key`, or configured per-provider in
+  Settings → Integrations → Atelier, or (for an install that predates the secret store) as
+  `OPENAI_API_KEY` in `.env`.
+
+## Install
+
+From the Officer marketplace: find Atelier, install. That mounts `/api/atelier` and `/atelier`, starts
+the `officer-atelier` sidecar under PM2, and connects it to whatever `ATELIER_POSTGRES_URL` points at —
+which has to already have the schema (the standalone repo's own `bun db:push` creates it; this plugin
+does not run migrations against a database it does not own the schema of).
+
+Uninstalling stops the sidecar and unmounts the route. **It never touches your database** — Atelier's
+tables and rows are not this plugin's to drop, since it does not own the schema push for them either.
+
+## Permissions
+
+One permission, `atelier`, grantable per role at read or write.
+
+- **Read** lets an account use Generate, browse the Gallery and Collections, and see which providers are
+  configured (never a key, in any form — not even masked).
+- **Write** additionally lets an account add, edit or delete providers, including their API keys. A
+  provider's key authorises real spend on someone's OpenAI account, so treat write here the way you
+  would treat write on any billing-adjacent surface.
+
+Providers is not a panel — it is a platform Settings screen (Settings → Integrations → Atelier), because
+it is owner-level configuration rather than a working view. See `PLUGIN.md` for why.
+
+## Limitations, honestly
+
+- **Two Ateliers can exist at once.** This plugin and the standalone service are independent — installing
+  this one does not migrate the standalone one's data, stop it, or repoint the mobile app. See
+  `PLUGIN.md`.
+- **No per-user data.** Every account with `read` sees the same gallery and the same collections — there
+  is no ownership model yet, the same simple shape offscale shipped with first.
+- **The database is separate from `officer_db`**, which means Atelier's tables are not covered by
+  `bun db:push`, are not part of the platform's usual backup story unless you back up the second
+  database too, and need their own connection string. Migrating them in is real, tracked follow-up work
+  — see `PLUGIN.md`.