@plitzi/cli 0.38.4 → 0.38.6

package/README.md

@@ -20,6 +20,12 @@ npx @plitzi/cli upload plugin                  # that zip, on the space you work
 - **The same flag means the same thing everywhere:** `-o, --out` where it writes, `-f, --force` to write over what is
   there, `-e, --environment` for which version of the space, `--width` for the widths a page is looked at (one, or
   several separated by commas), `--api` for the platform, `--json` for a tool or an agent.
+- **`--dry-run` says what it would do, and does none of it** — on every command that writes or sends: `create`,
+  `add plugin`, `add runtime`, `pull`, `push`, `pack plugin`, `source`, `import`, `upload plugin`, `functions pull`/
+  `push`, `runtime push`/`start`/`stop`/`size`/`vars`, `skills update`, `doctor --fix`. Each file it would write (`+` new, `~` replaced, `-`
+  removed), what it would install or run, what it would send and where. It still reads what it needs to say so — the
+  project, the files it would send, the space it would pull, signing in for that. `upgrade` and `fix` only show until
+  `--write`.
 
 ## `create`
 
@@ -97,13 +103,14 @@ when an install fails the CLI says which setting names it.
 
 ## What lands in the project
 
-- **The space, as yours.** A local project gets `src/space.ts` — a _copy_ of the space Plitzi gives a new
-  account, declared as a tree, some CSS and a palette rather than exported as a document. It is the same
-  declaration the platform authors a new space from, so what you start with and what signing up gives you cannot
-  come apart — and unlike a document, you can read and change it.
+- **The space, as yours.** A local project gets `src/space/` — a _copy_ of the space Plitzi gives a new account,
+  declared as a tree, some CSS and a palette rather than exported as a document, a file per part: `index.ts` (the page
+  and the space), `tokens.ts`, `theme.ts`, `content.ts`. It is the same declaration the platform authors a new space
+  from, so what you start with and what signing up gives you cannot come apart — and unlike a document, you can read
+  and change it.
 - **A live loop.** In client mode a save is a hot module replacement: the space module is swapped and the tree
-  remounted, so the page updates without reloading. In server mode `--watch` restarts the process and the next
-  request renders the change.
+  remounted, so the page updates without reloading. In server mode `start:dev` re-authors a saved space and the open
+  page loads again, swaps a saved plugin where it is drawn, and restarts only for the server's own code.
 - **A plugin of the project's own.** `src/plugins/StatCard` is a React component the space renders through a
   `custom` element — the one thing about Plitzi a page of built-in elements cannot show. Every folder of
   `src/plugins` is registered by itself, under its name in camelCase, so `plitzi add plugin` is all a new one takes. Its props ARE the
@@ -130,18 +137,38 @@ when an install fails the CLI says which setting names it.
 
 | Folder | What it is | In git |
 | --- | --- | --- |
-| `public/` | Served to anyone who asks, as it is — data, pictures, a favicon. **It is on the internet**: never a secret, a key, a private document or data only some visitors may read | yes |
+| `public/` | Served to anyone who asks, as it is — pictures, a favicon, and in client mode the data the browser fetches (`public/data/`). **It is on the internet**: never a secret, a key, a private document or data only some visitors may read | yes |
+| `src/data/` | Server mode: the project's own data — JSON its server reads for a provider (`query: '/data/<file>'`, `runtime: 'server'`) and never serves (`dataDir`). What a provider reads is in the page it renders: data a page must not carry is a server action's to read | yes |
+| `src/functions/` | Server mode: the project's own server code — tasks and `/fn/` routes (`defineFunctions`), built at boot | yes |
+| `vendor/plugins/` | The plugins the project runs as they were built, with no source (a project made from a space gets them), each folder with its `plugin-manifest.json`. The server runs them, and `author`, `check`, `fix` and `push` know every element type each provides | yes |
 | `tmp/` | What the project writes for itself while it runs: the plugins the server builds (`tmp/.sdk-plugins`), resized pictures, the port it took (`tmp/dev-server.json`), the space as last authored, screenshots and test output. Rebuilt when missing | no |
+| `state/` | Server mode: what the server keeps for the space — its `kv` in `state/kv.json` (`createFileKv`): saved layouts, counters, cached answers. The deployment's state: kept across restarts, never rebuilt. `action.kv` in `src/config/serverOptions.ts` keeps it elsewhere (`createSqliteKv` for several processes, or a database) | no |
 | `.plitzi/` | What the CLI records about the project: the space it came from (`space.json`), the functions' working copy, the files `create` wrote — what `pull`, `push` and `upgrade` stand on | yes |
 
+**`plitzi/` is the CLI's; `src/` is yours — but `src/main.ts`.** `plitzi/` holds `author.ts`, the types plugins import
+(`assets.d.ts`, server mode) or the page's base styles (`preflight.css`, client mode), and a `README.md` saying what
+each folder of `src/` is. `src/main.ts`, the entry point, is the CLI's too, kept in `src/` where an entry point is
+looked for; `upgrade` keeps all of them current, and the build compiles `src/` into `dist/main.js`. A plugin is declared by its folder: the server, `author` and `check` find every
+`src/plugins/<Name>/declaration.ts` (`pluginDeclarations` from `@plitzi/sdk-authoring/node`). What the server does
+besides serving the space is the project's own, in files it reads: `src/config/serverOptions.ts` (handed to `createServer` —
+`images`, `action.limits`, `action.kv`, `rsc`) and, with `--source local`, `src/actions/index.ts` (the space's server
+actions, one `defineAction` each, a file each as they grow).
+What `main.ts` wires itself — where the space comes from, the plugins, `public/`, `src/data/`, `src/functions/`, the
+actions' lookups — is left out of `serverOptions`' type, and comes after it, so an option there can never unwire it.
+`src/functions/` holds the project's own server code; `start:dev` restarts on a change to any of them. A plugin is not
+server code to restart for: a save to one is built again and swapped in the open pages where it is drawn — the rest of
+the page, its state included, stays — its server half (`src/plugins/<Name>/functions/`) is loaded again in place, and a
+new plugin folder is registered without a restart.
+
 ## `create --template blank` and `--template catalog`
 
 A space written in the project starts as the welcome tour, with a plugin of the project's own. `--template blank`
 starts it as tokens for both themes, a layout whose `site-main` the pages render in, and one empty page — with
-`public/data/` and no example plugin — for a project that is about to be a specific site. `--template catalog` starts
-it as a complete small shop to read and change: a layout with a menu, a product card component, the products in
-`public/data/products.json` read as a typed source, a catalog filtered by category, and a page per product — a file
-per part under `src/site/`. Both go with `--source local`.
+a folder for its data and no example plugin — for a project that is about to be a specific site. `--template catalog`
+starts it as a complete small shop to read and change: a layout with a menu, a product card component, the products
+in `src/data/products.json` read on the server as a typed source (`public/data/products.json`, fetched by the browser,
+in client mode), a catalog filtered by category, and a page per product — a file per part under `src/space/`. Both go
+with `--source local`.
 
 ## `check` and `shot`
 
@@ -155,7 +182,9 @@ plitzi shot / --compare https://example.com --width 1440   # beside another site
 ```
 
 Both run on the project's own Playwright against its running server (`npm start`), and refuse a port that answers as
-another project. `check` reports every element the space owes the page that is missing or hidden (with why), broken
+another project. They wait for the page to settle — loaded, then half a second with nothing asked for — counting no
+stream that stays open, so a page with a realtime `channel` is checked like any other (`openPage` of
+`@plitzi/sdk-authoring`, which the generated `npm run visual` uses too). `check` reports every element the space owes the page that is missing or hidden (with why), broken
 images, sideways scroll, text in the colour behind it, console errors, refused requests and failed flows — and the
 page's data: a binding that reads a path its provider's answer lacks (with the keys it has), a provider that failed,
 the rows each list rendered. A page's state in a few hundred tokens, where a screenshot costs thousands.
@@ -184,6 +213,43 @@ by the line and column the element remembers — and only where the value is wri
 listed with where it is and why it was left. `--write` authors the space again in a fresh process and keeps the edits
 only if every fix is gone and no problem was added; a fix that would add one is put back and said.
 
+## `lint`
+
+```bash
+plitzi lint                    # the space's source, eslint's way: each practice to change at its file and line
+plitzi lint --json             # one object: { scope, notChecked, counts, findings }
+plitzi lint --max-warnings 0   # more warnings than that fail (exit 1); --strict: any warning does
+```
+
+How the space in `src/space/` is written — what only its source can say, and what grows hard to read and to change as
+a space reaches thousands of lines. Each finding has a stable `code`, a severity, the file, line and column, what to
+write instead, and `docs`: the reference of the project's skills that explains the practice. A project `create` writes
+has it as `npm run lint:space`.
+
+| Code | What it finds |
+|---|---|
+| `unused-file` | a file of `src/space/` nothing `src/space/index.ts` imports reaches |
+| `file-too-long` | a file of more than 400 non-blank lines: split it by what changes together |
+| `pages-in-one-file` | two pages or more (past 40 lines) written in `index.ts`, which only assembles the space; three or more (past 150 lines) in any other file — one file per page, or per page family, under `src/space/pages/` |
+| `inline-records` | ten or more records written inline that a page renders (`.map`ped, or a list's `items`): rows of data for `src/data/` (`public/data/` without a server), read by a provider into one `list` |
+| `repeated-css` | the same CSS — three declarations or more, in any order or spelling — written three times: one class |
+| `special-case-in-map` | a `map` that singles out a row by its `id`, `key`, `slug`, `name`, `title` or `label`: the difference belongs in the row's data |
+| `colour-not-token` | a hex, `rgb()`/`hsl()`/`oklch()`… or a named colour where a colour is all a property takes — outside the declared tokens (`variables`, `light`/`dark`), anchors, masks, markup and URLs |
+| `positional-id` | an id minted for an element nobody named — `container-45`, `heading-a7k2` |
+| `space-does-not-author` | error: the space does not author, so authoring's suggestions could not be read — `npm run author` says why |
+| `source-unreadable` | error: the source could not be read (no TypeScript installed, a rule that could not finish) |
+
+Beside them, every suggestion authoring makes about the space it authors to (`authorSpace(…).suggestions`) — whatever
+its code, the day authoring adds it — as a warning at the line that wrote its element; `plitzi explain <code>` says what
+each means. They are quieted on the element (`quiet: ['repeated-shape']`), where the builder and the MCP read it too.
+A practice the source departs from on purpose is said where it is, eslint's way:
+`// plitzi-lint-disable-next-line colour-not-token -- the partner's own red`, `-line` for its own line, and
+`// plitzi-lint-disable <codes>` for the whole file.
+
+It is not whether the space authors — what it refuses and warns of is `npm run author`'s — nor a page as it renders
+(`check`), nor the project around the space (`doctor`); every report says so (`notChecked`). Exit code 1 while anything
+is an error; with `--strict` a warning too, with `--max-warnings <n>` more than n of them.
+
 ## `import`
 
 ```bash
@@ -204,9 +270,11 @@ What lands in `--out`:
 - `assets.json`, `screens/<width>.png`, and `IMPORT.md`: what was not carried over (the text, states, scripts, fonts
   not on Google) and what to do next.
 
-It reads only a site that is yours: one served from this machine (a host that resolves to loopback), or one a verified
-domain of one of your spaces covers — the `_plitzi` TXT record a custom domain is verified by, under **Domains** in the
-dashboard, asked of the platform you are signed in to (`--api`). Anything else is refused before a page is opened.
+It reads only a site that is yours: one served from this machine (a host that resolves to loopback), with nothing asked
+of anybody; or, with `--account`, one a verified domain of one of your spaces covers — the `_plitzi` TXT record a custom
+domain is verified by, under **Domains** in the dashboard, asked of your Plitzi account (`--api`), signing in when you
+are not. Without `--account` it never reaches the platform: a site not served from this machine is refused, saying so.
+Anything else is refused before a page is opened.
 
 It refuses an `--out` that already has files unless `--force`, and then names the files an earlier import left that it
 did not write again.
@@ -227,27 +295,81 @@ plitzi explain --list steps     # every one of a kind: elements, steps, triggers
 What a name means when authoring, from the catalogues the checks themselves read — the answer to a question that would
 otherwise be a search through the SDK's types. `--json` answers in one object; over MCP it is `plitzi://explain/{name}`.
 
+## `doctor`
+
+```bash
+plitzi doctor                  # every area, each problem with where it is and what fixes it
+plitzi doctor --fix            # repairs what is simple and safe, then checks again
+plitzi doctor --fix --dry-run  # what --fix would repair, nothing done
+plitzi doctor --json           # one object: { ok, counts, areas, findings, repaired, recommendations }
+plitzi doctor --strict         # warnings fail too — for a CI that keeps the project up to its CLI
+```
+
+Whether the project is whole as the CLI sets it up, read from what it is now rather than from what the CLI once wrote:
+a developer may change any file, and the checks are what each part must be for the project to install, start, build and
+push. It is the CLI's check of the project, not of the space: what the space authors to and warns of is `npm run
+author`'s, how it is written `lint`'s, and how a page renders `check`'s. Exit code 1 while anything is an error (with `--strict`, a warning).
+
+Each finding has an area, a stable `code`, the file and its `fix`; the report ends with **what to run next** — the few
+commands (`plitzi upgrade --write`, an install, `doctor --fix`) that clear most of the list, by how many each fixes.
+
+**`--fix`** makes only what is simple and safe, then examines the project again: a layout an older CLI left, moved (every
+import, `new URL(…, import.meta.url)` and script naming a moved file follows, and what the CLI recorded of its files
+follows them); an older CLI's dead files and caches deleted; `.gitignore` lines added or taken out; `"type": "module"`
+and `engines`; a folder `start:dev` watches; a `PLITZI_SIGNING_SECRET` where there is none (or one too short). What
+replaces a file of the project's, installs, or touches git is recommended, never done — `upgrade --write` and the install
+are a step of their own.
+
+**A project an older CLI made** is the usual patient, and its own installed CLI may predate `doctor`: run the latest one
+from it — `npx @plitzi/cli@latest doctor --fix`, then what it recommends. While its layout is an older one (the space in
+`src/space.ts`, `author` in `src/`, `functions/` at the root), nothing else is checked — read against it, every other
+area would only say what the move fixes — and `upgrade` writes no file until it is moved.
+
+| Area | What is held |
+|---|---|
+| `layout` | where an older CLI kept what this one reads elsewhere (`src/space.ts`, `src/site/`, `src/actions.ts`, `src/author.ts`, `functions/`) and what it left behind (`src/plugins/declarations.ts`, `.sdk-plugins/`, `.plitzi/dev-server.json`) |
+| `packages` | `"type": "module"`, the Node version; every package the project and its scripts need, declared and installed at a version its range allows; the SDK's packages at one version, no older than the CLI; one copy of the SDK and of React (none installed inside another); the scripts — gone, behind the CLI, or the project's own — the file each Node script starts and every folder `start:dev` watches; one lockfile |
+| `machinery` | the CLI's files (`MACHINERY`), as `upgrade` sees them: gone, behind, or the project's own (said, never failed); the scaffold record |
+| `config` | `tsconfig.json` reads `src/` and `plitzi/` and sets what Node's type stripping needs; `tsconfig.build.json` writes the file `start:prod` runs; `.gitignore` keeps `.env` out (and `node_modules`, `tmp`, `dist`, `state`) and `.plitzi/` in; `.env` not in git; the signing secret, as long as the project's own server wants it; a cloud project's key |
+| `sources` | what Node runs as written — `src/main.ts`, `src/config/`, `src/actions/`, `src/space/`, `src/runtime/`, `plitzi/author.ts`, the plugins' declarations, and all they import: every relative import a file that is there, with its extension; JSON imported `with { type: 'json' }`; no JSX; every package declared (a devDependency, in what production runs, is said); what the server loads by name exported (`space`, `actions`, the runtime's default) |
+| `plugins` | each folder of `src/plugins/`: an `index.ts` that builds and exports its component, its packages declared; a `declaration.ts` whose `type` is the folder's (`StatCard` → `statCard`); one folder a type; none shadowed by a built copy in `vendor/plugins/` |
+| `data` | every file of `src/data/` and `public/data/` JSON — what the server answers with and `push` sends |
+| `functions` | `src/functions/` built by the project's own `@plitzi/sdk-server` (`buildFunctions`), as every runner builds them |
+| `records` | `.plitzi/space.json`, `scaffold.json` and `functions.json` readable, and of the same space |
+| `skills` | `.claude/skills/plitzi-*` as the packages installed write them |
+
+It loads the plugins' declarations and the project's own `@plitzi/sdk-server` to ask them — as the server does — and
+never starts the server or the runtime. A check that cannot finish is said as an error
+of its area, never a crash.
+
 ## `upgrade`
 
 ```bash
 plitzi upgrade                       # what this CLI would change in the project — shown, nothing written
 plitzi upgrade skills --write        # only the skills, each replaced whole from the packages installed
-plitzi upgrade --write --take src/author.ts
+plitzi upgrade --write --take plitzi/author.ts
 ```
 
 A project brought up to the CLI it has now, part by part: `files` (the machinery — `author.ts`, `main.ts`, the
 Playwright and lint configs, `AGENTS.md`), `packages` (`package.json` merged, `@plitzi/*` raised to this version, then
 the install), `skills` (`.claude/skills/plitzi-*`, whole, so a reference a skill no longer has goes with it) and
 `renames` (a name a version renamed, at its file and line). A file nobody changed since the CLI wrote it is replaced;
-one the project made its own is a diff, left unless `--take` names it (`all` for every one). `update` is the same
+one the project made its own is a diff, left unless `--take` names it (`all` for every one). The generated
+`.prettierignore` names them, so the project's `format` never turns one into a file `upgrade` believes was changed. A file of the project's own
+that the machinery reads (`src/config/serverOptions.ts`, `src/actions/index.ts`) is written when the project has none and the
+`main.ts` reading it is the CLI's, and never replaced. A script is the same: one the CLI wrote and nobody changed takes
+today's command, one the project changed is left and said (`.plitzi/scaffold.json` records both, and the package
+manager the files were written for — what a project not installed yet has no lockfile to say). In a project made from
+a space, a file the space gave over one of the CLI's would be the space's, and `upgrade` would leave it to `plitzi pull` —
+none does: `src/main.ts` runs whatever the space brought, from where it lands. `update` is the same
 command, and `plitzi skills update` is `upgrade skills --write`. `npm run author` says when the authoring skill is
 older than the `@plitzi/sdk-authoring` installed.
 
 ## `data describe`
 
 ```bash
-plitzi data describe public/data/products.json          # its shape, and one row of its longest list
-plitzi data describe public/data/products.json --json   # { shape, example }
+plitzi data describe src/data/products.json          # its shape, and one row of its longest list
+plitzi data describe src/data/products.json --json   # { shape, example }
 ```
 
 The fields of a JSON file, their types and which rows have them — `price?: number  (in 812 of 879)` — so a page can
@@ -271,7 +393,7 @@ the draft, an environment's latest, or a pinned revision.
 
 ```bash
 plitzi push                                    # at a terminal: tick what goes up — what changed is ticked already
-plitzi push space functions                    # only these: space, functions, runtime, plugins
+plitzi push space functions                    # only these: space, functions, data, runtime, plugins, files
 plitzi push space --force                      # replace the draft even though it was edited in the builder since
 ```
 
@@ -281,9 +403,13 @@ that names come before what names them:
 
 1. `plugins` — every plugin whose source changed, packed and uploaded to the space's CDN (`--cdn`/`--bucket` when it
    has several public buckets);
-2. `functions` — `functions/`, as `functions push`;
-3. `runtime` — the runtime module, as `runtime push`;
-4. `space` — `src/space.ts` authored, with the actions `src/actions.ts` serves and the connectors in `src/connectors/`.
+2. `files` — each changed file of `public/assets/`, put at the same path under the space's `assets/` on its CDN
+   (images, sounds, videos and JSON; any other type is named and stays here);
+3. `functions` — `src/functions/`, as `functions push`;
+4. `data` — `src/data/` whole, as the space's own data: kept privately, read by its server providers, frozen with each
+   publish — refused when the space's copy changed since the project last had it, unless `--force`;
+5. `runtime` — the runtime module, as `runtime push`;
+6. `space` — `src/space/` authored, with the actions `src/actions/index.ts` serves and the connectors in `src/connectors/`.
 
 The draft is never replaced unseen: when it was edited in the builder since the project's last pull or push, the push
 is refused — pull first, or `--force`. A project that never had the space (one not made with `create --from`) may take a
@@ -291,6 +417,12 @@ space nobody has worked on yet; one that holds work asks for `--force` too. Alwa
 which must be the one the project came from, and never a published environment: publish in the builder. Afterwards
 `.plitzi/space.json` records what was sent, so `pull` keeps working — on a project that started on its own too.
 
+The space goes back with its files where Plitzi serves them: a path to a file of `public/assets/` (`/assets/a.png`) —
+one `create --from` or `pull` wrote, or one the `files` part put on the CDN — is sent as that file's CDN address. Only
+`public/assets/` goes to the CDN: the rest of `public/` is the project's own server's. What would not reach Plitzi is
+said before anything is sent, with what to do: a provider reading a file `src/data/` does not hold, a file of
+`public/assets/` the space names that is not on its CDN yet, and one of `public/` outside `assets/`.
+
 ## `add plugin`
 
 Adds elements of your own to the project you are in — one, several at once (`add plugin seat-picker legend`), or one at
@@ -300,10 +432,8 @@ adds), its `Settings.tsx` panel for the builder, and the `index.ts` that puts th
 what the builder shows, and what it is for, and checks every folder is free before writing any.
 
 - **In a project `plitzi create` wrote**, it goes in `src/plugins`, where the project already looks: nothing to
-  register, and `start:dev` restarts onto it. Host it with `custom({ renderType: 'seatPicker' })` in `src/space.ts`
+  register, and a running `start:dev` picks it up without a restart. Host it with `custom({ renderType: 'seatPicker' })` in `src/space/`
   — or, when the space lives in Plitzi, with a Custom element in the builder.
-- **In a project written before plugins were found by folder**, it goes in `src/plugins` too, and prints the line to
-  add to the `plugins` list in `src/main.ts`.
 - **In a plugin package**, it goes in `src/`, and is added to `src/elements.ts` and `src/declarations.ts`, from which
   the package publishes it.
 - **In any other project**, it asks which folder holds the project's components (`--dir` answers it) and prints how
@@ -318,11 +448,21 @@ plitzi add plugin ticker --prop interval:number=5000 --prop paused:boolean --tri
 ```
 
 `--prop name:type=default` (string, number or boolean) is an attribute: in the props, the declaration's defaults and
-`bindingsAllowed`, and a control in `Settings.tsx`. `--trigger onTick:count,at` is an event and what a flow started by
-it reads, fired with the `useTickerEvents()` hook it gets. `--callback reset` is an action a flow can call. `--headless`
-is an element with nothing to see: hidden on a page, a badge in the builder. The files are written as the project's
+`bindingsAllowed`, and a control in `Settings.tsx`; `--prop rows:list` and `--prop meta:json` are data a binding fills
+(`unknown[]`, `Record<string, unknown>`, empty until it does). `--trigger onTick:count,at` is an event and what a flow
+started by it reads, fired with the `useTickerEvents()` hook it gets — never on the builder's canvas. `--callback reset`
+is an action a flow can call. `--headless` is an element with nothing to see: hidden on a page, a badge in the builder,
+and `drawsNothing` in its declaration, so a page check does not look for it. The files are written as the project's
 Prettier writes them.
 
+`--server` gives the element a server half: `functions/index.ts` in its folder, written like a space's functions — its
+routes answer under `/fn/plugins/<type>/` (`usePluginRoute(type)` in the component names them), its tasks are steps
+`<type>.<action>`, and it runs with a plugin's own corner of `kv`, none of the space's credentials or channels. In a
+server-mode project or a plugin package (which gets `@plitzi/sdk-server` for the types); a project that renders in the
+browser alone has nothing to run it, and is refused. `pack plugin` carries it as `functions.source.json`, and the
+platform builds and keeps it privately when the plugin is uploaded — see
+[functions § a plugin's server half](../../docs/en/functions.md#10-a-plugins-server-half).
+
 ## `create --plugin`
 
 A plugin package: elements any space can load, with a Vite preview to write them in. It builds nothing itself —
@@ -352,9 +492,11 @@ plitzi pack plugin src/plugins/SeatPicker             # an element of a self-hos
 plitzi pack plugin src/plugins/SeatPicker src/plugins/Legend   # several in one plugin, the first its main
 ```
 
-It writes one ES module (esbuild; React and the SDK kept out — the page provides them; images and fonts inside, since
-a page imports the module from a blob URL), `plugin-manifest.json` written from the elements' declarations with each
-file's integrity hash, and the zip the builder takes: upload it under Resources, as a plugin. A package also gets its
+It writes one ES module (esbuild; React and the SDK kept out — the page provides them; images, fonts and any file
+imported whole — `worker.js?raw` for its text, `engine.wasm?inline` for a data URI — inside, since a page imports the
+module from a blob URL), `plugin-manifest.json` written from the elements' declarations with each file's integrity
+hash, and the zip the builder takes — its stylesheet in the `plitzi-sdk-plugin` cascade layer, below the space's
+styles, so a space's classes and `customCss` win over it: upload it under Resources, as a plugin. A package also gets its
 type declarations, written with its own TypeScript. Or serve the build at a versioned address with CORS open, and list
 it in a space's plugins as `{ type, resource }`.
 
@@ -371,7 +513,7 @@ in the code keeps it from being written — said, and never stopping the build.
 ## `pack source`
 
 ```bash
-plitzi pack source src/runtime.ts --kind runtime --name runtime -o runtime.source.json.gz
+plitzi pack source src/runtime/index.ts --kind runtime --name runtime -o runtime.source.json.gz
 ```
 
 What `upload plugin` and `runtime push` keep, written to a file to look at: the closure of the entries named, gzipped.
@@ -411,7 +553,7 @@ certificate authorities the system trusts, as the browser beside it does.
 ## `runtime`
 
 ```bash
-plitzi runtime push                                   # pack src/runtime.ts and keep it as the space's draft runtime
+plitzi runtime push                                   # pack src/runtime/index.ts and keep it as the space's draft runtime
 plitzi runtime status                                 # how each environment's runtime is, and its variables' names; --json
 printf %s "$URL" | plitzi runtime vars set REDIS_URL   # a value from stdin stays out of the shell history
 plitzi runtime vars unset REDIS_URL
@@ -425,8 +567,9 @@ connection kept open, memory that outlives a request, Node and its packages (`do
 
 **Its code lives in a project of yours** — a folder, usually a repository — and nowhere else: the builder shows how a
 runtime runs and sets its variables, but it does not hold its code and cannot change it. The project has
-`src/runtime.ts` (or `--entry`), whose default export is `defineRuntime(…)`, and `@plitzi/sdk-server` installed: a
-project from `plitzi create` in server mode has it; `examples/self-hosting/10-runtime` is the smallest one to start
+`src/runtime/index.ts` (or `--entry`), whose default export is `defineRuntime(…)`, and `@plitzi/sdk-server` installed:
+`plitzi add runtime` writes it in a project from `plitzi create` in server mode, whose `src/main.ts` runs it too —
+`/hello` answers on `npm start` — and whose `start:dev` restarts on it; `examples/self-hosting/10-runtime` is the smallest one to start
 from, and it runs as a server of its own too.
 
 `push` packs the module with the project's own `@plitzi/sdk-server` — the module and every package it imports, bar
@@ -446,21 +589,26 @@ running one would stop, and why a stopped one is.
 ## `functions`
 
 ```bash
-plitzi functions pull                                              # the space's functions into functions/
-plitzi functions push                                              # functions/ saved as the space's draft, built and checked
+plitzi functions pull                                              # the space's functions into src/functions/
+plitzi functions push                                              # src/functions/ saved as the space's draft, built and checked
 plitzi functions try seismic.feed --params '{"minMagnitude":"4"}'  # one task of the saved draft, in the sandbox
 plitzi functions dev seismic.feed --params '{}' --watch            # on this machine, as the platform runs it
 ```
 
-A space's own server code — tasks its actions run as steps, routes under `/fn/` — and `functions/` is a working copy
+A space's own server code — tasks its actions run as steps, routes under `/fn/` — and `src/functions/` is a working copy
 of it: `.plitzi/functions.json` keeps what was pulled, so `pull` refuses to overwrite what is not pushed (`--force`
 throws it away) and `push` refuses when the space moved on since. A problem comes back as
-`functions/<file>:<line> <message>`. `dev` runs with the project's own `@plitzi/sdk-server` (`isolated-vm` and
+`src/functions/<file>:<line> <message>`. `dev` runs with the project's own `@plitzi/sdk-server` (`isolated-vm` and
 `core-js` beside it); credentials come from `PLITZI_FUNCTIONS_CREDENTIALS`. See `docs/en/functions.md`.
 
 ## Credentials
 
-`create` never mints one. A cloud project's key comes from Credentials in the builder, is written to `.env`, and
-`.gitignore` is written in the same breath. Server and browser take **different** keys and the scaffold names
-them differently on purpose: a server gets the secret self-hosting key, a browser gets the public render key,
+`create` never mints a key to Plitzi. A cloud project's key comes from Credentials in the builder, is written to
+`.env`, and `.gitignore` is written in the same breath. Server and browser take **different** keys and the scaffold
+names them differently on purpose: a server gets the secret self-hosting key, a browser gets the public render key,
 whose protection is the origin it is presenting from.
+
+Every server project's `src/main.ts` reads `.env` itself (`process.loadEnvFile`), so `npm start` needs nothing else.
+`create` gives each one a signing key there, made for it: `PLITZI_SIGNING_SECRET`, what `ctx.sign` and `ctx.verify`
+sign with — at least 32 characters (`doctor --fix` writes one where it is missing). `PORT` is left commented out: 8080,
+or the next free port while developing.