@plitzi/sdk-server 0.38.7 → 0.38.8

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @plitzi/sdk-server
 
+## 0.38.8
+
+### Patch Changes
+
+- Updated dependencies [1b45aae]
+  - @plitzi/sdk-shared@0.38.8
+  - @plitzi/plitzi-sdk@0.38.8
+
 ## 0.38.7
 
 ### Patch Changes

package/README.md

@@ -159,7 +159,7 @@ serve it — worth running over anything that arrives as a file.
 A space on Plitzi comes out whole, as a project wired to this server: `npx @plitzi/cli create my-site --from <space>`
 writes its pages as authoring code, its actions as `defineAction` code, its functions, the source of its plugins and
 runtime, and its files into `public/` — a draft, or any published snapshot (`--environment`, `--revision`) — and
-`plitzi pull` keeps it in step, and `plitzi push` puts what changed in it back on the space. See
+`plitzi space pull` keeps it in step, and `plitzi space push` puts what changed in it back on the space. See
 `docs/en/projects-from-spaces.md` in the workspace.
 
 ## Projects
@@ -221,7 +221,7 @@ What it wires from the project:
 - **Its files.** `public/` served as it is, `src/data/` read and never served (`dataDir`), the `kv` in `state/kv.json`
   (`createFileKv`), `PLITZI_SIGNING_SECRET` what `ctx.sign` signs with.
 - **Where it is.** `/health` answers with the space's permanent URL (or the cloud `name`), and `tmp/dev-server.json`
-  records the name, the port and the URL for `plitzi check`, `shot` and `visual`. A signal closes it (`closeOnSignals`).
+  records the name, the port and the URL for `plitzi page check`, `shot` and `visual`. A signal closes it (`closeOnSignals`).
 
 While developing — `NODE_ENV` other than `production` — `devMode` and `devReload` are on, and:
 
@@ -541,7 +541,7 @@ createServer({ dataDir: path.join(PROJECT_ROOT, 'src/data'), adapters: { ... } }
 ```
 
 The data is read through one lookup, `action.lookups.getData(spaceId, at)` — the space's own data as its files' text by
-path, as of the version being rendered or run: what a cloud deployment keeps for a space (`plitzi push`). Given none,
+path, as of the version being rendered or run: what a cloud deployment keeps for a space (`plitzi space push`). Given none,
 `createServer` derives it from `dataDir` (its `.json` files, read again once they change), so the folder and the
 platform are read the same way.
 
@@ -642,7 +642,7 @@ All fields are optional and combined with AND logic. Calling `invalidate()` with
 
 Plugins are React component bundles that extend the Plitzi schema renderer. They are defined globally at server config level, compiled or copied on first use, and cached on disk for one week. The `getSpaceDeployment` adapter controls which plugins each space gets access to via `pluginNames`.
 
-A compiled plugin is one module and its stylesheet, built as `plitzi pack plugin` builds it: React and the SDK kept out, and everything else inside — images and fonts as data URIs, and a file imported whole the way Vite imports it (`worker.js?raw` for its text, `engine.wasm?inline` for a data URI).
+A compiled plugin is one module and its stylesheet, built as `plitzi plugin pack` builds it: React and the SDK kept out, and everything else inside — images and fonts as data URIs, and a file imported whole the way Vite imports it (`worker.js?raw` for its text, `engine.wasm?inline` for a data URI).
 
 Whatever stylesheet the server writes for a plugin — compiled, copied or downloaded — goes into the `plitzi-sdk-plugin` cascade layer (`inPluginLayer` from `@plitzi/sdk-shared/style`), below the space's own: a space's classes and `customCss` win over what the plugin shipped, whatever the specificity. A `css` given as a web path (`/builder-assets/…`) is linked as it is.
 

package/dist/modules/actions/runtime/projectData.js

@@ -1,7 +1,7 @@
 import { readFile, readdir, stat } from "node:fs/promises";
 import path from "node:path";
 //#region src/modules/actions/runtime/projectData.ts
-/** What a project keeps in its data folder: JSON, the only files `plitzi push` sends as the space's data. */
+/** What a project keeps in its data folder: JSON, the only files `plitzi space push` sends as the space's data. */
 var DATA_EXTENSION = ".json";
 /**
 * A data folder as the lookup a deployment would otherwise write — what a self-hosted server derives from `dataDir`, so

package/dist/modules/project/plugins.d.ts

@@ -23,7 +23,7 @@ export declare const projectPlugins: (root: string) => Promise<ProjectPlugins>;
 /**
  * A plugin edited while developing is built again by the server, and the open pages swap it where it is drawn — the
  * rest of the page, its state included, stays as it was (`devReload`). Its server half (`functions/`) is loaded again
- * here, in place. A plugin ADDED — a new folder with an `index.ts`, what `plitzi add plugin` writes — is registered
+ * here, in place. A plugin ADDED — a new folder with an `index.ts`, what `plitzi plugin add` writes — is registered
  * here, and the pages load again to render it; one removed is turned off. A folder the server cannot build, or whose
  * server half has no entry, is said in the terminal as the layout check says it at boot — once, until it changes — and
  * the server goes on. Answers what stops watching.

package/dist/modules/project/plugins.js

@@ -39,7 +39,7 @@ var folderFunctions = async (root, folder) => {
 	const functions = path.join(root, PLUGINS_DIR, folder, PLUGIN_FUNCTIONS_DIR);
 	return existsSync(path.join(functions, "index.ts")) ? (await loadFunctions(functions)).at(0) : void 0;
 };
-/** A plugin of `vendor/plugins`, from the manifest `plitzi pack plugin` wrote beside its bundle when it was published. */
+/** A plugin of `vendor/plugins`, from the manifest `plitzi plugin pack` wrote beside its bundle when it was published. */
 var builtPlugin = (root, type) => {
 	const read = readVendorPlugin(root, type);
 	if ("problem" in read) throw new Error(read.problem.message);
@@ -88,7 +88,7 @@ var projectPlugins = async (root) => {
 /**
 * A plugin edited while developing is built again by the server, and the open pages swap it where it is drawn — the
 * rest of the page, its state included, stays as it was (`devReload`). Its server half (`functions/`) is loaded again
-* here, in place. A plugin ADDED — a new folder with an `index.ts`, what `plitzi add plugin` writes — is registered
+* here, in place. A plugin ADDED — a new folder with an `index.ts`, what `plitzi plugin add` writes — is registered
 * here, and the pages load again to render it; one removed is turned off. A folder the server cannot build, or whose
 * server half has no entry, is said in the terminal as the layout check says it at boot — once, until it changes — and
 * the server goes on. Answers what stops watching.

package/dist/modules/runtime/bundle.d.ts

@@ -19,7 +19,7 @@ export declare const inspectRuntime: (bytes: Uint8Array) => {
 };
 /**
  * A project's runtime module, as a server of its own runs it — `src/runtime/index.ts`, or what `build` compiled it to —
- * or nothing when the project has none: a project starts one by writing it (`plitzi add runtime`), with nothing to wire.
+ * or nothing when the project has none: a project starts one by writing it (`plitzi runtime add`), with nothing to wire.
  */
 export declare const loadRuntimeModule: (file: string) => Promise<SpaceRuntime | undefined>;
 /**

package/dist/modules/runtime/bundle.js

@@ -93,7 +93,7 @@ var runtimeOf = (loaded) => {
 };
 /**
 * A project's runtime module, as a server of its own runs it — `src/runtime/index.ts`, or what `build` compiled it to —
-* or nothing when the project has none: a project starts one by writing it (`plitzi add runtime`), with nothing to wire.
+* or nothing when the project has none: a project starts one by writing it (`plitzi runtime add`), with nothing to wire.
 */
 var loadRuntimeModule = async (file) => {
 	try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.38.7",
+  "version": "0.38.8",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -96,8 +96,8 @@
     "./dist/env.js"
   ],
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.38.7",
-    "@plitzi/sdk-shared": "0.38.7",
+    "@plitzi/plitzi-sdk": "0.38.8",
+    "@plitzi/sdk-shared": "0.38.8",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "jsonwebtoken": "^9.0.3",

package/skills/plitzi-authoring/SKILL.md

@@ -9,174 +9,59 @@ description: >-
 
 # Authoring Plitzi spaces
 
-A space is two JSON documents — a schema and a style — full of cross-referenced ids. **Never write them by hand.**
-`@plitzi/sdk-authoring` derives every id, class name, parent link, breakpoint map and flow chain from a small
-declaration, and refuses a declaration that would not render.
+A space is two JSON documents full of cross-referenced ids — **never write them by hand**. `@plitzi/sdk-authoring`
+derives them from a small declaration, and refuses one that would not render.
 
 ```ts
-import { authorSpace, container, heading, styles, text } from '@plitzi/sdk-authoring';
+import { heading, styles, text } from '@plitzi/sdk-authoring';
 
-const page = styles('page', { display: 'flex', 'flex-direction': 'column', padding: '96px 24px', gap: '16px' });
+const page = styles('page', { display: 'flex', 'flex-direction': 'column', gap: '16px' });
 
 export const space = {
   name: 'My space',
   permanentUrl: 'my-space',
   pages: [{ name: 'Home', slug: '', class: page, body: [heading('Hello', { subType: 'h1' }), text('A paragraph.')] }]
 };
-
-const { schema, style, warnings } = authorSpace(space);
 ```
 
-**Start with [the cheatsheet](CHEATSHEET.md)** — the factories, fields, steps and the problems met most, on one page —
-and open a reference below only when the task names its subject. What an element takes, a step's params, what a
-trigger hands its flow: `npx @plitzi/cli explain <name>` answers in a few lines (over MCP, `plitzi://explain/<name>`).
-The published `.d.ts` documents the rest — search it by name, never read it whole.
-
-This skill writes a space that lives in code. One that lives on Plitzi — edited in the builder, published from there —
-is edited through the Plitzi MCP server instead, never both on one space; `plitzi create --from <space>` turns the
-second into the first. If the MCP asks for a sign-in nobody can give, a project in code needs no account.
+A space on Plitzi — edited in the builder — is edited through the Plitzi MCP server instead, never both on one space.
 
 ## How to work
 
-1. **Read before you write.** Open `src/space/index.ts` (and whatever it imports) and find the layout, the classes and the
-   helpers already there. Extend them; do not add a second way of doing something the space already does.
-2. **Change the declaration, then author it.** `npm run author` (or a restart) runs `authorSpace` — not `doctor`, which
-   is the project's. It checks every field, value, template, name, param and page link, and a refusal says what to
-   write instead: do exactly that. Never work around a check, cast past it, or move the logic into a plugin to escape
-   it. The linter's problems come as ONE list — fix every line before running again. How it checks, and what it
-   cannot see: [validation](reference/validation.md).
-3. **Read every warning, then every suggestion.** A warning names something written that will not do what it says —
-   zero warnings is the bar. A suggestion (`[suggest]`) names a shorter way to the same page — a layout, a component,
-   a `list`, a button's own `content` — or what nothing uses. Take them, the ones that save the most first
-   ([efficiency](reference/efficiency.md)). Then `npm run lint:space`: how the source is written — long files, rows of
-   data inline, colours that are not tokens — at file:line. Leave both clean.
-4. **Look at it.** `npm run check -- /about --width 1440,390` says in text whether the page is whole — every element on
-   screen, nothing overflowing, a clean console; `npm run shot -- /about --width 390 --scheme dark` is the picture
-   (`--frames 4` shows what moves); `npm run visual` runs the checks. Look at desktop, tablet and mobile, light and dark, and the page while its data is still loading.
-5. **Go through the [review checklist](reference/review-checklist.md) before saying it is done.** It is the feedback a
-   reviewer gives on every change, written down so you do not need to hear it.
+1. **Find, then write.** `npx plitzi element where <id|class|words>` answers the file, the line and the call: edit there, and
+   extend what the space already has. People move files — never keep a note of where something is.
+2. **Author.** `npm run author`. A refusal says what to write instead: do exactly that. Every problem comes at once —
+   fix them all before running again. Zero warnings; take the suggestions, the biggest first.
+3. **Look.** `npm run check -- /path --width 1440,390` says in text whether the page is whole; `npm run shot` only
+   when the text is not enough.
+4. **Before saying done:** `npm run lint:space` clean, and the [review checklist](reference/review-checklist.md).
 
-## The rules that matter most
+What a name means — an element, a step, a trigger, a code, any export (`pageFamily`, `SpaceSpec`): `npx plitzi explain
+<name>`, in a few lines. Never read the `.d.ts`.
 
-1. **Name what is referred to.** Give an `id` to every element a binding, a flow or a test addresses. Ids are ONE
-   namespace for the whole space — layouts and every page share it — so a helper that runs more than once builds inside
-   `scope('promos', ref => …)`: every id in it is prefixed (`promos-panel`), and `ref('slides')` names one in full. An `id` is the element's name in the
-   space (`data-plitzi-el` in the page); the DOM id a URL's `#fragment` lands on is its `anchor`.
-2. **Share with classes, layouts and components, never with copies.** A look used twice is a `styles()` class.
-   Chrome shown on several pages — a header, a sidebar, a footer — is a **layout** the pages name, written once. A block
-   placed many times with different content — a product card, a testimonial — is a **component** placed with
-   `component(id, { props })`. A menu, a card grid, a list of steps is DATA, never a block pasted per item: a short
-   menu mapped in code is fine; rows — cards, dishes, tiles — are one `list` (`items: [ … ]`) whose row is written
-   once. A link or a button says its words as
-   its own `content`, not through a `text` inside it. Pages of one shape are one `pageFamily` over data. See
-   [layouts](reference/layouts.md), [components](reference/components.md), [structure](reference/structure.md) and
-   [efficiency](reference/efficiency.md).
-3. **One element, one base selector.** An element takes a shared `class` OR its own `css`, never both — authoring
-   refuses the pair. "This class plus one thing" is the class with rules on top, last in the list:
-   `class: [cover, { opacity: '0.25' }]` (needs the element's `id`; it becomes the class `<id>--own`). A look that
-   never changes is its own class.
-4. **Visible by default; decide which way the logic flips.** An element is on screen unless something hides it. When
-   the logic REVEALS it (hidden → shown: an empty state, a "get started" card, an admin-only panel), it starts hidden —
-   `visible: 'source'`, or `visible: false` plus a binding for a computed condition — so it never flashes while data
-   loads (`condition-starts-visible` warns). When a flag HIDES it (shown → hidden: a sidebar label until the sidebar
-   is folded), it keeps the default and an absent flag must leave it shown. See
-   [data and visibility](reference/data-and-visibility.md). What a PERSON switches on — a feature in beta, a rollout —
-   is a feature flag, not a visibility: gated off, it is not rendered at all. See [feature flags](reference/feature-flags.md).
-5. **Know where a template is evaluated.** A binding's template (`bindTemplate`) and a step's params evaluate full
-   Twig. An ATTRIBUTE resolves a name with filters (`{{ list_games.item.slug }}`, `{{ post.slug|url_encode }}`) against
-   the sources around the element; a condition there is used as written. Inside any template a source is spelled in
-   full — `apiContainer_stats`, `list_rows` — and a query param is `navigation.queryParams.x`. A template that feeds a
-   list its `items` hands over its value (`returns: 'value'`). `authorSpace` refuses a template it cannot read and a
-   name nothing answers to. See [templates](reference/templates.md).
-6. **Tokens, not colours.** Every colour is a variable of the space with a `light` and a `dark` value; both themes are
-   checked from the first commit.
-7. **Times in UTC, and say so.** Format with an explicit zone (`|date('j M · H:i', 'UTC')`) and print "UTC" beside it:
-   a page rendered on a server and hydrated in a browser in another zone must agree on the hour.
-8. **Breakpoints are ranges.** `tablet` (48–64rem) and `mobile` (up to 48rem) each inherit only from `desktop`; a rule
-   meant for both is written under `compact`.
-9. **Never invent data.** Numbers, names and states on screen come from a source. A panel with nothing true to say is
-   an empty state, not a placeholder figure. With no backend, the data is JSON read by an `apiContainer`: a server
-   project's `src/data/*.json`, read on the server and never served; with no server, `public/data/*.json`, which is
-   public — see [data and visibility](reference/data-and-visibility.md).
-10. **Never hand-write** `flat`, derived ids, `styleSelectors`, `beforeNode`/`afterNode`/`flowId`, or a
-    `styleVariant` binding's key — use the factories, `variantFrom` and `activeOn`.
-11. **A switch is named for how it leaves its default.** `toggleState` turns a key nobody has set yet ON, so a key
-    named for the default (`showPlates`, on by default) takes a first click to do nothing: name it `platesOff`, and read
-    every switch through `computed` (`plates: '{{ state.platesOff ? false : true }}'`) so its default shows before
-    anybody touches it.
-12. **Hand plugins over as their declarations**: `authorSpace(space, { plugins: [declaration] })` holds a plugin —
-    its own type, or a `custom({ renderType })` host — to the events, actions and attributes it declares. See
-    [plugins](reference/plugins.md).
-13. **Usable without sight.** Screen readers and browser agents (Claude in Chrome) find a page's controls in its
-    accessibility tree: every button and link has words (an icon-only button a `title`), every field a `label`
-    (`hideLabel: true` hides it and keeps the name), every image an `alt` or `decorative: true`. Clicks go on a
-    `button` — it holds children, so a whole card can be one — or a `link`, never on a container. See
-    [accessibility](reference/accessibility.md).
-14. **Motion that stays smooth.** Animate `opacity` and `transform` only; no animated blur, shadow or size. See
-    [motion](reference/colours-and-motion.md).
+## Five rules authoring cannot check for you
 
-## Recipes
+1. **Name what is referred to.** An `id` for every element a binding, a flow or a test addresses; ids are one namespace,
+   so a helper that runs twice builds inside `scope('promos', ref => …)`.
+2. **Share, never copy.** A look used twice is a class; chrome on several pages a layout; a block placed again with
+   other content a component; rows of data one `list`.
+3. **What is revealed starts hidden** (`visible: 'source'`), so it never flashes while its data loads.
+4. **Know where a template runs.** A binding and a step's params are full Twig; an attribute resolves a name with
+   filters. A source is spelled in full: `apiContainer_stats`.
+5. **Tokens, not colours** — a variable with a `light` and a `dark` value.
 
-Each is a whole file that authors with no warning — CI holds it to that. Copy the one that fits, then change the names.
+The rest, and why: [rules](reference/rules.md).
 
-| To… | Open |
-| --- | --- |
-| Show data with no backend: a JSON file, a card per row, a count, an empty state, a computed value | [recipes/show-data.ts](recipes/show-data.ts) |
-| Data typed by a sample of it: completed and checked paths, typed rows | [recipes/typed-data.ts](recipes/typed-data.ts) |
-| Data read by the page server (`--mode server`) | [recipes/server-data.ts](recipes/server-data.ts) |
-| An accordion, one answer open at a time | [recipes/accordion.ts](recipes/accordion.ts) |
-| Filter and sort a list from a select | [recipes/filter-a-list.ts](recipes/filter-a-list.ts) |
-| A page per record (`/products/:slug`), and "not found" | [recipes/detail-page.ts](recipes/detail-page.ts) |
-| Link to a section of a page (`/#plans`) | [recipes/link-to-a-section.ts](recipes/link-to-a-section.ts) |
-| A carousel: slides with arrows, dots and autoplay; a marquee; a row that swipes | [recipes/carousel.ts](recipes/carousel.ts) |
-| Do something every few seconds — a ticker, a poll, a slideshow by hand | [recipes/every-few-seconds.ts](recipes/every-few-seconds.ts) |
-| A marquee that scrolls for ever and stops under the pointer | [recipes/marquee.ts](recipes/marquee.ts) |
-| A row that scrolls sideways, with arrows that hide at its ends | [recipes/scroll-a-row.ts](recipes/scroll-a-row.ts) |
-| A link built from a row: WhatsApp with the product's name, `mailto:` | [recipes/link-with-data.ts](recipes/link-with-data.ts) |
-| React to a click or a submit; a modal; a switch | [recipes/forms-and-modals.ts](recipes/forms-and-modals.ts) |
-| A feature behind a flag | [recipes/feature-flag.ts](recipes/feature-flag.ts) |
-| An element of your own (a plugin), checked | [recipes/plugin.ts](recipes/plugin.ts) |
-| Controls a screen reader and a browser agent can use | [recipes/usable-without-sight.ts](recipes/usable-without-sight.ts) |
-| Tokens, a shared class, "the class plus one thing", tablet and phone at once | [recipes/style-a-page.ts](recipes/style-a-page.ts) |
-| A design in Tailwind classes, kept as classes the builder edits | [recipes/from-tailwind.ts](recipes/from-tailwind.ts) |
-| A page from elsewhere in a frame (`embed`: a map, a player) and a drawing of your own (`svg`) | [recipes/embed-and-svg.ts](recipes/embed-and-svg.ts) |
+## What to read
 
-## References
+Start with [the cheatsheet](CHEATSHEET.md), then only what the task names:
 
-| Read | When |
+| The task | Read |
 | --- | --- |
-| [elements-and-styles.md](reference/elements-and-styles.md) | Any element or CSS: factories, fields, classes, states, variants, tokens, fonts, lists, links |
-| [colours-and-motion.md](reference/colours-and-motion.md) | Colours for both themes, tokens, keyframes, and motion that stays smooth (good practices) |
-| [tailwind.md](reference/tailwind.md) | A design written in Tailwind classes: `tw()`, its breakpoints and states, what it refuses |
-| [layouts.md](reference/layouts.md) | Anything shown on more than one page; menus; reducing duplication of elements and styles |
-| [efficiency.md](reference/efficiency.md) | The same page with fewer elements: the suggestions `authorSpace` makes, and the short way for each long one |
-| [components.md](reference/components.md) | One block placed many times — a card, a tier, a testimonial: props, slots, binding a row into one, why it is closed |
-| [data-and-visibility.md](reference/data-and-visibility.md) | Bindings, providers, offline data, loading/empty/error states, live data, caching, showing and hiding, kept state |
-| [kept-state.md](reference/kept-state.md) | State that outlives a reload: `keepState`, transient and painted keys |
-| [auth.md](reference/auth.md) | Signing people in: providers, `authLogin`, `auth.*`, visitor roles |
-| [feature-flags.md](reference/feature-flags.md) | Switching a part of the space on or off — a beta, a rollout, the old version kept until the new one ships |
-| [lists.md](reference/lists.md) | Rendering rows, filtering and sorting them, a detail page for one record, carousels |
-| [typed-sources.md](reference/typed-sources.md) | Data typed by a sample of it: `source()`, typed rows, `twig` for templates |
-| [validation.md](reference/validation.md) | How `authorSpace` checks, the loop that wastes no attempts, and what it cannot see |
-| [authoring-errors.md](reference/authoring-errors.md) | What `authorSpace` refuses or warns about, and what to write instead |
-| [templates.md](reference/templates.md) | Any `{{ … }}` or `{% … %}`: where it runs, naming sources, filters, tests, dates |
-| [flows.md](reference/flows.md) | Clicks, submits, page loads, every few seconds, server actions, modals, state |
-| [realtime.md](reference/realtime.md) | Pages that see each other: channels, presence, cursors, a shared board, who may hear a topic |
-| [plugins.md](reference/plugins.md) | A component of your own: props, binding them, writing state, channels, registering, behaving in the builder |
-| [drawing.md](reference/drawing.md) | A plugin that draws or animates: a canvas sized to the device, WebGL, a loop that stops when unseen |
-| [structure.md](reference/structure.md) | A space bigger than one screen: files, helpers, naming, keeping it short |
-| [testing.md](reference/testing.md) | Any test: `inspectPage`, handles, fixtures, catching a flash from the first frame, shortcuts, counting renders |
-| [performance.md](reference/performance.md) | A page with many elements, a busy flow, something that feels slow: what renders, what it costs, how to measure it |
-| [snippets-and-export.md](reference/snippets-and-export.md) | Publishing a snippet; turning an exported JSON — or a server action — into code |
-| [accessibility.md](reference/accessibility.md) | Icon buttons, fields, images, clickable cards, toggles, headings, landmarks, a canvas — anything a screen reader or a browser agent has to use |
-| [review-checklist.md](reference/review-checklist.md) | Before you say it is done |
-
-**What to read for a kind of task** — the cheatsheet, then only these:
-
-- A site — landing, catalogue, blog: elements-and-styles, layouts, components, lists.
-- An app with state and actions: data-and-visibility, templates, flows — realtime when pages see each other.
-- A component of your own: plugins.
-- A refusal or a warning: search authoring-errors.md for its code — never read it whole.
-- Tests: testing.
-
-Nothing else needs reading up front.
+| A site — landing, catalogue, blog | [elements-and-styles](reference/elements-and-styles.md), [layouts](reference/layouts.md), [components](reference/components.md), [lists](reference/lists.md) |
+| An app with state and actions | [data-and-visibility](reference/data-and-visibility.md), [templates](reference/templates.md), [flows](reference/flows.md) |
+| A component of your own | [plugins](reference/plugins.md) |
+| A whole working file to copy | [recipes](reference/recipes.md) |
+| A refusal or a warning | `npx plitzi explain <code>` |
+| Tests | [testing](reference/testing.md) |
+| Anything else | [the index](reference/index.md): every reference, and when |

package/skills/plitzi-authoring/recipes/plugin.ts

@@ -1,5 +1,5 @@
 /**
- * An element of your own (a plugin): authored from its declaration — the one `plitzi add plugin` writes — so a flow on
+ * An element of your own (a plugin): authored from its declaration — the one `plitzi plugin add` writes — so a flow on
  * its events, a step to its actions and its attributes are all checked. Hand the declaration to `authorSpace` too.
  */
 import {

package/skills/plitzi-authoring/reference/accessibility.md

@@ -111,5 +111,4 @@ can't click something that only appears on focus.
 - `authorSpace` warnings: zero, as always.
 - In a test, `page.getByRole('button', { name: 'Close' })` fails when the name is missing.
   `expect(locator).toMatchAriaSnapshot(…)` pins the whole outline.
-- Through MCP, `plitzi_screenshot` with `view: "accessibility"` returns the page's tree and lists everything that has
-  no name.
+- Through MCP, `plitzi_look` returns the page's tree (its default view) and lists everything that has no name.

package/skills/plitzi-authoring/reference/authoring-errors.md

@@ -112,6 +112,7 @@ The space is not written until these are fixed.
 | `part-missing` | a compound element — a carousel, a tab container, a dropdown — without a part it renders through | the part the message names, inside it (`carousel()` writes its own track) |
 | `prop-missing` | an instance without a prop its component requires | `component('card', { props: { name: … } })`, or bind it |
 | `prop-name` | a prop whose name a template cannot read as `props.x` | letters, digits and `_` |
+| `prop-type-unknown` | a prop declared with a type no editor offers and nothing checks a value against | one of text, textarea, select, boolean, number, scalar, json, elementIds — words are `text` |
 | `prop-unknown` | a prop the component does not declare, handed in or read | the prop it suggests, or declare it: `props: { name: { type: 'text' } }` |
 | `prop-value` | a prop handed in with a value its declaration does not take | a value of the declared type, or one of its options |
 | `props-outside-component` | `props.x` read outside a component | read the source it would have come from |

package/skills/plitzi-authoring/reference/drawing.md

@@ -17,7 +17,7 @@ It sizes the canvas to the device (at most 2× — `maxPixelRatio`), follows its
 can see it move: on a live page (in the builder it draws one still frame), for a visitor who did not ask for less
 motion, with the tab in front and the canvas on screen; `paused` holds it (bind it to a hover). A shader that does not
 compile — GLSL ES 1.0 wants `196.0`, not `196` — throws a `ShaderError` with the driver's log, printed as
-`[plugin <type> "<id>"] fragment shader failed: …` (`plitzi check` lists it under the console) and `error` says it;
+`[plugin <type> "<id>"] fragment shader failed: …` (`plitzi page check` lists it under the console) and `error` says it;
 show the still image meanwhile, as above. `useAnimationFrame(onFrame, { target })` is the same loop for motion that
 is not a canvas.
 

package/skills/plitzi-authoring/reference/flows.md

@@ -21,8 +21,8 @@ source — `when({ field: 'flags.newCheckout', operator: '=', value: true }, …
 same flags, decided on the server. Use the step builders — they fill in where a step runs and what it takes:
 
 - **Where it runs.** A global callback registers under its source MODULE (`state`, `auth`, `actions`), an element
-  callback under an element's id, a utility under nothing. Naming either half wrong is a control that does nothing,
-  with no error — which is why the builders exist.
+  callback under an element's id, a utility under nothing. Either half named wrong is a control that silently does
+  nothing.
 - **Which `setState`.** `setState({ key })` writes `runtime.state.<key>` and is read as `state.<key>`; never put
   `state.` in the key. `updateElement(…)` changes one element's own attribute or state.
 - **Flip in one step.** `toggleState({ key })` for app state, `toggleElement({ category: 'state', key: 'visibility' },
@@ -144,6 +144,8 @@ without a word.
 The toast carries no class of the space's, so this — not a `.Toastify__*` rule in `customCss` — is where it is
 dressed.
 
+Copy link: `copyToClipboard('{{ navigation.href }}')`, then the toast — it fails with no clipboard.
+
 ## Modals, dropdowns, tabs
 
 - A modal or dialog is declared `visible: false` and driven with `openModal('credits')` / `closeModal('credits')`

package/skills/plitzi-authoring/reference/index.md

@@ -0,0 +1,33 @@
+# Every reference, and when to read it
+
+Read one only when the task names its subject.
+
+| Read | When |
+| --- | --- |
+| [rules.md](rules.md) | Every rule of writing a space, with its why |
+| [recipes.md](recipes.md) | A whole working file for a common task, to copy and rename |
+| [elements-and-styles.md](elements-and-styles.md) | Any element or CSS: factories, fields, classes, states, variants, tokens, fonts, lists, links |
+| [colours-and-motion.md](colours-and-motion.md) | Colours for both themes, tokens, keyframes, and motion that stays smooth (good practices) |
+| [tailwind.md](tailwind.md) | A design written in Tailwind classes: `tw()`, its breakpoints and states, what it refuses |
+| [layouts.md](layouts.md) | Anything shown on more than one page; menus; reducing duplication of elements and styles |
+| [efficiency.md](efficiency.md) | The same page with fewer elements: the suggestions `authorSpace` makes, and the short way for each long one |
+| [components.md](components.md) | One block placed many times — a card, a tier, a testimonial: props, slots, binding a row into one, why it is closed |
+| [data-and-visibility.md](data-and-visibility.md) | Bindings, providers, offline data, loading/empty/error states, live data, caching, showing and hiding, kept state |
+| [kept-state.md](kept-state.md) | State that outlives a reload: `keepState`, transient and painted keys |
+| [auth.md](auth.md) | Signing people in: providers, `authLogin`, `auth.*`, visitor roles |
+| [feature-flags.md](feature-flags.md) | Switching a part of the space on or off — a beta, a rollout, the old version kept until the new one ships |
+| [lists.md](lists.md) | Rendering rows, filtering and sorting them, a detail page for one record, carousels |
+| [typed-sources.md](typed-sources.md) | Data typed by a sample of it: `source()`, typed rows, `twig` for templates |
+| [validation.md](validation.md) | How `authorSpace` checks, the loop that wastes no attempts, and what it cannot see |
+| [authoring-errors.md](authoring-errors.md) | What `authorSpace` refuses or warns about, and what to write instead |
+| [templates.md](templates.md) | Any `{{ … }}` or `{% … %}`: where it runs, naming sources, filters, tests, dates |
+| [flows.md](flows.md) | Clicks, submits, page loads, every few seconds, server actions, modals, state |
+| [realtime.md](realtime.md) | Pages that see each other: channels, presence, cursors, a shared board, who may hear a topic |
+| [plugins.md](plugins.md) | A component of your own: props, binding them, writing state, channels, registering, behaving in the builder |
+| [drawing.md](drawing.md) | A plugin that draws or animates: a canvas sized to the device, WebGL, a loop that stops when unseen |
+| [structure.md](structure.md) | A space bigger than one screen: files, helpers, naming, keeping it short |
+| [testing.md](testing.md) | Any test: `inspectPage`, handles, fixtures, catching a flash from the first frame, shortcuts, counting renders |
+| [performance.md](performance.md) | A page with many elements, a busy flow, something that feels slow: what renders, what it costs, how to measure it |
+| [snippets-and-export.md](snippets-and-export.md) | Publishing a snippet; turning an exported JSON — or a server action — into code |
+| [accessibility.md](accessibility.md) | Icon buttons, fields, images, clickable cards, toggles, headings, landmarks, a canvas — anything a screen reader or a browser agent has to use |
+| [review-checklist.md](review-checklist.md) | Before you say it is done |

package/skills/plitzi-authoring/reference/plugins.md

@@ -9,7 +9,7 @@ custom({ id: 'arcade', renderType: 'nebulaRun', shipColor: 'amber', bind: { best
 
 ## Creating one
 
-The CLI writes it, in the shape Plitzi's own elements are written in: `npx @plitzi/cli add plugin seat-picker` (a
+The CLI writes it, in the shape Plitzi's own elements are written in: `npx @plitzi/cli plugin add seat-picker` (a
 package of its own and packing it: the CLI skill).
 
 One folder, four files: `SeatPicker.tsx` (the component), `declaration.ts` (its `type`, the `triggers` it fires, the
@@ -88,7 +88,7 @@ the widths the space's styles use, instead of a width of the plugin's own.
 
 ## Its own server code
 
-`plitzi add plugin board --server` writes `functions/index.ts` in its folder (the CLI skill). Its routes answer
+`plitzi plugin add board --server` writes `functions/index.ts` in its folder (the CLI skill). Its routes answer
 under `/fn/plugins/board/`; the component names them, with nothing for the space to wire:
 
 ```tsx

package/skills/plitzi-authoring/reference/recipes.md

@@ -0,0 +1,25 @@
+# Recipes
+
+Each is a whole file that authors with no warning — CI holds it to that. Copy the one that fits, then change the names.
+
+| To… | Open |
+| --- | --- |
+| Show data with no backend: a JSON file, a card per row, a count, an empty state, a computed value | [recipes/show-data.ts](../recipes/show-data.ts) |
+| Data typed by a sample of it: completed and checked paths, typed rows | [recipes/typed-data.ts](../recipes/typed-data.ts) |
+| Data read by the page server (`--mode server`) | [recipes/server-data.ts](../recipes/server-data.ts) |
+| An accordion, one answer open at a time | [recipes/accordion.ts](../recipes/accordion.ts) |
+| Filter and sort a list from a select | [recipes/filter-a-list.ts](../recipes/filter-a-list.ts) |
+| A page per record (`/products/:slug`), and "not found" | [recipes/detail-page.ts](../recipes/detail-page.ts) |
+| Link to a section of a page (`/#plans`) | [recipes/link-to-a-section.ts](../recipes/link-to-a-section.ts) |
+| A carousel: slides with arrows, dots and autoplay; a marquee; a row that swipes | [recipes/carousel.ts](../recipes/carousel.ts) |
+| Do something every few seconds — a ticker, a poll, a slideshow by hand | [recipes/every-few-seconds.ts](../recipes/every-few-seconds.ts) |
+| A marquee that scrolls for ever and stops under the pointer | [recipes/marquee.ts](../recipes/marquee.ts) |
+| A row that scrolls sideways, with arrows that hide at its ends | [recipes/scroll-a-row.ts](../recipes/scroll-a-row.ts) |
+| A link built from a row: WhatsApp with the product's name, `mailto:` | [recipes/link-with-data.ts](../recipes/link-with-data.ts) |
+| React to a click or a submit; a modal; a switch | [recipes/forms-and-modals.ts](../recipes/forms-and-modals.ts) |
+| A feature behind a flag | [recipes/feature-flag.ts](../recipes/feature-flag.ts) |
+| An element of your own (a plugin), checked | [recipes/plugin.ts](../recipes/plugin.ts) |
+| Controls a screen reader and a browser agent can use | [recipes/usable-without-sight.ts](../recipes/usable-without-sight.ts) |
+| Tokens, a shared class, "the class plus one thing", tablet and phone at once | [recipes/style-a-page.ts](../recipes/style-a-page.ts) |
+| A design in Tailwind classes, kept as classes the builder edits | [recipes/from-tailwind.ts](../recipes/from-tailwind.ts) |
+| A page from elsewhere in a frame (`embed`: a map, a player) and a drawing of your own (`svg`) | [recipes/embed-and-svg.ts](../recipes/embed-and-svg.ts) |

package/skills/plitzi-authoring/reference/rules.md

@@ -0,0 +1,61 @@
+# The rules of writing a space
+
+Every rule, with its why. The skill's core keeps the five that go wrong most in a line each; the rest authoring
+refuses or warns of, with the fix.
+
+1. **Name what is referred to.** Give an `id` to every element a binding, a flow or a test addresses. Ids are ONE
+   namespace for the whole space — layouts and every page share it — so a helper that runs more than once builds inside
+   `scope('promos', ref => …)`: every id in it is prefixed (`promos-panel`), and `ref('slides')` names one in full. An `id` is the element's name in the
+   space (`data-plitzi-el` in the page); the DOM id a URL's `#fragment` lands on is its `anchor`.
+2. **Share with classes, layouts and components, never with copies.** A look used twice is a `styles()` class.
+   Chrome shown on several pages — a header, a sidebar, a footer — is a **layout** the pages name, written once. A block
+   placed many times with different content — a product card, a testimonial — is a **component** placed with
+   `component(id, { props })`. A menu, a card grid, a list of steps is DATA, never a block pasted per item: a short
+   menu mapped in code is fine; rows — cards, dishes, tiles — are one `list` (`items: [ … ]`) whose row is written
+   once. A link or a button says its words as
+   its own `content`, not through a `text` inside it. Pages of one shape are one `pageFamily` over data. See
+   [layouts](layouts.md), [components](components.md), [structure](structure.md) and
+   [efficiency](efficiency.md).
+3. **One element, one base selector.** An element takes a shared `class` OR its own `css`, never both — authoring
+   refuses the pair. "This class plus one thing" is the class with rules on top, last in the list:
+   `class: [cover, { opacity: '0.25' }]` (needs the element's `id`; it becomes the class `<id>--own`). A look that
+   never changes is its own class.
+4. **Visible by default; decide which way the logic flips.** An element is on screen unless something hides it. When
+   the logic REVEALS it (hidden → shown: an empty state, a "get started" card, an admin-only panel), it starts hidden —
+   `visible: 'source'`, or `visible: false` plus a binding for a computed condition — so it never flashes while data
+   loads (`condition-starts-visible` warns). When a flag HIDES it (shown → hidden: a sidebar label until the sidebar
+   is folded), it keeps the default and an absent flag must leave it shown. See
+   [data and visibility](data-and-visibility.md). What a PERSON switches on — a feature in beta, a rollout —
+   is a feature flag, not a visibility: gated off, it is not rendered at all. See [feature flags](feature-flags.md).
+5. **Know where a template is evaluated.** A binding's template (`bindTemplate`) and a step's params evaluate full
+   Twig. An ATTRIBUTE resolves a name with filters (`{{ list_games.item.slug }}`, `{{ post.slug|url_encode }}`) against
+   the sources around the element; a condition there is used as written. Inside any template a source is spelled in
+   full — `apiContainer_stats`, `list_rows` — and a query param is `navigation.queryParams.x`. A template that feeds a
+   list its `items` hands over its value (`returns: 'value'`). `authorSpace` refuses a template it cannot read and a
+   name nothing answers to. See [templates](templates.md).
+6. **Tokens, not colours.** Every colour is a variable of the space with a `light` and a `dark` value; both themes are
+   checked from the first commit.
+7. **Times in UTC, and say so.** Format with an explicit zone (`|date('j M · H:i', 'UTC')`) and print "UTC" beside it:
+   a page rendered on a server and hydrated in a browser in another zone must agree on the hour.
+8. **Breakpoints are ranges.** `tablet` (48–64rem) and `mobile` (up to 48rem) each inherit only from `desktop`; a rule
+   meant for both is written under `compact`.
+9. **Never invent data.** Numbers, names and states on screen come from a source. A panel with nothing true to say is
+   an empty state, not a placeholder figure. With no backend, the data is JSON read by an `apiContainer`: a server
+   project's `src/data/*.json`, read on the server and never served; with no server, `public/data/*.json`, which is
+   public — see [data and visibility](data-and-visibility.md).
+10. **Never hand-write** `flat`, derived ids, `styleSelectors`, `beforeNode`/`afterNode`/`flowId`, or a
+    `styleVariant` binding's key — use the factories, `variantFrom` and `activeOn`.
+11. **A switch is named for how it leaves its default.** `toggleState` turns a key nobody has set yet ON, so a key
+    named for the default (`showPlates`, on by default) takes a first click to do nothing: name it `platesOff`, and read
+    every switch through `computed` (`plates: '{{ state.platesOff ? false : true }}'`) so its default shows before
+    anybody touches it.
+12. **Hand plugins over as their declarations**: `authorSpace(space, { plugins: [declaration] })` holds a plugin —
+    its own type, or a `custom({ renderType })` host — to the events, actions and attributes it declares. See
+    [plugins](plugins.md).
+13. **Usable without sight.** Screen readers and browser agents (Claude in Chrome) find a page's controls in its
+    accessibility tree: every button and link has words (an icon-only button a `title`), every field a `label`
+    (`hideLabel: true` hides it and keeps the name), every image an `alt` or `decorative: true`. Clicks go on a
+    `button` — it holds children, so a whole card can be one — or a `link`, never on a container. See
+    [accessibility](accessibility.md).
+14. **Motion that stays smooth.** Animate `opacity` and `transform` only; no animated blur, shadow or size. See
+    [motion](colours-and-motion.md).

package/skills/plitzi-authoring/reference/snippets-and-export.md

@@ -31,8 +31,8 @@ Never rewrite an exported space by hand. `specFromSpace({ schema, style })` read
 A server action reads back the same way: `actionSpecFromEntry({ id, document })` gives the `defineAction` spec that writes
 it — only when that spec writes the very same document, otherwise `reason` says why and it stays JSON — and
 `actionToSource(spec)` writes the module. For the whole space as a project — pages, actions, functions, the source of
-its plugins and runtime, its files — use `plitzi create --from <space>` (then `plitzi pull` to bring the space's changes in, and
-`plitzi push` to put the project's back) rather than exporting the parts by hand.
+its plugins and runtime, its files — use `plitzi create --from <space>` (then `plitzi space pull` to bring the space's changes in, and
+`plitzi space push` to put the project's back) rather than exporting the parts by hand.
 
 For a document you did not author — an export, a JSON edited by hand — run the gate before serving it:
 `validateSpace({ schema, style })`.

package/skills/plitzi-authoring/reference/structure.md

@@ -117,7 +117,7 @@ the rest.
 
 ## Checked for you
 
-`npm run lint:space` (`plitzi lint`) reads the source for what this page asks — a file past 400 lines, pages in one
+`npm run lint:space` (`plitzi space lint`) reads the source for what this page asks — a file past 400 lines, pages in one
 file, rows of data inline, a colour that is not a token, CSS copied three times, a row singled out by its id inside a
 `map`, a minted id, a file nothing imports — at file:line, beside authoring's suggestions. Leave it clean; a departure
 on purpose says why where it is: `// plitzi-lint-disable-next-line <code> -- why` for lint's own codes. A suggestion of

package/skills/plitzi-authoring/reference/testing.md

@@ -71,7 +71,7 @@ the space with it (the e2e harness: `renderSpace(page, space, { debugMode: true
 
 ## Asking the page what it holds
 
-`plitzi check` lists every flow that failed while the page loaded; `--state` adds the state and every source by its
+`plitzi page check` lists every flow that failed while the page loaded; `--state` adds the state and every source by its
 full name, `--element <id>` one element — what it reads, its own state, whether it is on screen. They come from the
 page's dev tools (debug mode, any development server). In a test, `readDevTools(page, { state: true })` from
 `@plitzi/sdk-authoring` answers the same.

package/skills/plitzi-authoring/reference/validation.md

@@ -46,7 +46,7 @@ bar.
    ```
 
 2. **Fix, re-run, until it prints zero warnings.** What has one fix (`author` says how many) is written for you: `npx
-   plitzi fix` shows it as a diff of your source, `--write` writes it and keeps it only if the space authors with each
+   plitzi space fix` shows it as a diff of your source, `--write` writes it and keeps it only if the space authors with each
    fix gone and nothing new — a fix it cannot place, or that would add a problem, is said with the reason. A
    suggestion with one reading is written the same way (`content-attribute`: words and an icon held as children become
    the button's or link's own `content` and `icon`). Then typecheck the project.