@plitzi/cli 0.38.2 → 0.38.4

package/CHANGELOG.md

@@ -1,5 +1,328 @@
 # @plitzi/cli
 
+## 0.38.4
+
+### Patch Changes
+
+- 6ae4161: ## `plitzi push`: a self-hosted project back on its space
+
+  `plitzi create --from` and `plitzi pull` took a space out as a project and kept it in step; nothing put the project's
+  own changes back but a command per part, and no command at all for its pages. `plitzi push` is the way back
+  (`docs/en/projects-from-spaces.md`):
+
+  - **What changed, or what is named.** `plitzi push` sends what changed since the project last had the space — at a
+    terminal, offered as a ticked list to choose from (`↑/↓`, space, Enter); `plitzi push space functions` sends only
+    those parts: `space`, `functions`, `runtime`, `plugins`.
+  - **In order:** each changed plugin packed and uploaded (`pack plugin` + `upload plugin`, `--cdn`/`--bucket`), the
+    functions, the runtime, then the space — `src/space.ts` authored, the actions `src/actions.ts` serves and the manifests
+    in `src/connectors/` — as the space's draft. Never a published environment.
+  - **Never over the builder's work unseen.** The export now carries which state the draft is in (`SpaceExport.draft`),
+    recorded in `.plitzi/space.json` by `create --from` and `pull`; a push names it, and a draft edited since is refused
+    until `--force`. A project that never had the space may take one nobody has worked on; one holding work takes
+    `--force`.
+  - **Then `pull` follows it.** `.plitzi/space.json` records what was sent — only that, so a builder's change to a part
+    not pushed is still the next pull's — and a project that started on its own works with `pull` from then on.
+  - `@plitzi/sdk-shared/source`: `SpaceImport` / `SpaceImportResult` (`SPACE_IMPORT_FORMAT`), the push's one shape for
+    both ends, beside `SpaceExport`, which gains `draft`.
+  - `functions push`, `runtime push` and `upload plugin` keep their behaviour; their cores are what `push` runs.
+
+  ## A project's folders: `tmp/` for what it writes, `.plitzi/` committed, `public/` said to be public
+  - **`tmp/` is what a project writes for itself.** `@plitzi/sdk-server` keeps the plugins it builds in `tmp/.sdk-plugins`
+    and resized pictures in `tmp/images` by default (were `.sdk-plugins` and `.plitzi/images`). A project the CLI writes
+    puts the port it took (`tmp/dev-server.json`), the space as last authored while developing (`tmp/space.json`) and
+    Playwright's output (`tmp/visual`) there too, and its `.gitignore` ignores `tmp` — one line for all of it.
+  - **`.plitzi/` is committed.** The scaffold ignored it whole, so a clone lost `space.json`, `functions.json` and
+    `scaffold.json` — what `pull`, `push`, `functions push` and `upgrade` stand on. Now it holds only what the CLI records.
+    `npx plitzi upgrade --write` brings an existing project's `.gitignore` up.
+  - **No `space/offline-data.json`.** `npm run author` checks the space and writes nothing; the server asks it for the
+    documents with `--out tmp/space.json` while developing. The space is `src/space.ts`, and nothing beside it says
+    otherwise.
+  - **`public/` is on the internet.** The generated `README.md` and `AGENTS.md`, the CLI and authoring skills, the MCP
+    guide, `@plitzi/sdk-server`'s README and the docs now say so where data goes: never a secret, a key or data only
+    some visitors may read — in `public/`, or in a space's documents, which reach every visitor too.
+
+  ## An agent leaves the project clean
+
+  `AGENTS.md` gains **Keep the project clean** — nothing unused left behind, scratch work in `tmp/`, one of everything,
+  files a reader can find, and `author`, `typecheck`, `lint`, `format` and `check` passing — and the authoring skill's
+  review checklist a **Nothing left behind** section.
+
+  ## The dev tools' X-ray is the outlines too
+
+  The QA tab had **Outlines** (every element's box, its type and id when pointed at) and **X-ray** (the same boxes,
+  fainter, with what is wired to each). They are one tool now: the X-ray draws every box with its type and id, and marks
+  the wiring picked — all of it, one kind, or **Boxes only**.
+
+  ## A new space that says where to go
+
+  The space a new account and `plitzi create` start from keeps its welcome, and gains the three ways to change it — the
+  builder, code (with the command to run) and an agent — before the guides, which are shorter. Header, navigation, main
+  and footer are landmarks; the grid behind the top fades out instead of ending at an edge; the footer's line spans the
+  content; the links say their words and icon themselves, with no suggestion left.
+
+  ## Server data reads the same everywhere
+  - **One shape for a provider with a `query`.** A `runtime: 'server'` provider that only reads a JSON file the server
+    serves answered the body itself, while the same provider in the browser publishes `{ status, data }` — so moving it
+    to the server broke every binding. `publicFileResolver` and the builder's mock now answer `{ status, data }` too:
+    `<source>.data.<field>` whichever runtime.
+  - **Server data is on unless a space turns it off.** The page render read a missing `rsc` as on and the connector
+    resolver as off, so a server provider in a space the builder or the MCP made (neither writes `rsc`) resolved to
+    nothing, silently. Both read it as on now; only `rsc: { enabled: false }` turns it off (and is warned with a server
+    element). `authorSpace` writes `enabled: true` for a space that has one.
+  - **Never inside a component.** The page server resolves a page's tree and its layouts only, so a server provider in a
+    component rendered nothing, silently. Refused now (`server-provider-in-component`), with the fix: the provider on
+    the page, the rows handed in as a prop.
+  - **Bindings held to the data.** `authorSpace` takes `data` — what a provider's `query` answers — and
+    `publicData(folder)` (`@plitzi/sdk-authoring/node`) reads it from `public/`. A binding onto a path the file does not
+    have is warned (`path-not-in-data`) with the keys it does have. Generated projects pass it.
+  - **`plitzi check` reads the data too.** A binding that reads a path its provider's answer lacks, a provider that
+    failed (once, not as every element it left empty) and the rows each list rendered (`dataIssues`). `--ssr` names what
+    the server's HTML lacks that the hydrated page has. The dev tools' badge and panel (`data-plitzi-devtools`) are hidden
+    while `check` and `shot` look.
+
+  ## Authoring, clearer where agents tripped
+  - **`controls` on a button** (`aria-controls`): named by the element's id; authoring gives that element the anchor and
+    refuses an id the space lacks (`controls-unknown`); a saved document naming no anchor is warned
+    (`controls-no-anchor`). The accordion recipe uses it.
+  - **`live` on a container** (`aria-live`, `polite` or `assertive`) for words that change while a visitor reads them.
+  - **`subType: 'p'`** for a paragraph made of parts; `span-holds-block` covers it.
+  - **`formControl` types `search`, `url` and `tel`.**
+  - **Images:** no `src` draws the SDK's own placeholder (the CDN one answered 404); `resize: false` keeps a picture as
+    written; an SVG is never resized — `/_plitzi/img` redirects to it (`307`) instead of refusing it.
+  - **Messages:** an id taken by another page or layout names it and the id to write; a hyphenated source in a template
+    (`list_study-plans`) is explained as valid; an unknown CSS property says to write it in `customCss`; an unknown
+    variant on `custom` says it is never a prop of the component it hosts.
+  - **`plitzi explain` knows the helpers** — `bindTemplate`, `visibleWhen`, `variantFrom`, `activeOn`, `activeWhen`,
+    `when`, `named`, `scope`, `source`, `twig` — and `motion`, from the presets the SDK plays (`MOTION_ENTERS`,
+    `MOTION_TRIGGERS`, `MOTION_LOOPS`, now exported). `--list helpers` lists them.
+  - **`plitzi shot`** writes to `tmp/shots/` by default, and a full page shows the arrivals tied to the scroll as they
+    end. `inspectPage` no longer reports an image a hidden ancestor hides.
+  - **Style inspector:** `container-type` in Size.
+  - **New recipes:** `server-data.ts`, `accordion.ts`.
+
+  ## Matching a page to another, measured
+  - **A whole page is the whole page.** The SDK scrolls a pane of its own, so `shot`'s full-page picture was one
+    screen; the pane is unrolled now (`unrollPage`) — the viewport untouched, so a `100vh` hero stays one screen.
+  - **`plitzi shot --compare` says why, not only how much.** Every lazy picture on both pages is loaded before they are
+    taken (`loadImages`), so a section no longer swings between 23 % and 40 % on how many covers had arrived. Each section
+    is compared where it is on the other page (`alignPictures` over row profiles): a page 400 px longer is said once, with
+    the section the drift starts at, instead of a footer with the same styles reading 100 %. And the texts both pages
+    have are paired (`pageTexts`, `compareTexts`), each with what it does differently there —
+    `h1 "Learn CSS" — font-size 68px → 60px · y +19px` — position less the drift of its section. `comparePictures` takes
+    its options as an object now (`{ regions, tolerance, align }`).
+  - **`--scheme` is the space's theme.** A space whose default is dark painted dark under `--scheme light`, and the file
+    said light. `check` and `shot` now set the `theme` cookie a visitor's toggle writes; left out, the space's default is
+    pictured and the file is named by the theme actually painted.
+
+  ## `motion: { on: 'view' }` arrives once
+
+  `view` was tied to the scroll both ways: cards faded out again as the reader scrolled back up. Now it plays once, the
+  first time the element comes into view, with its `duration`, and stays — `revealOnView` (`@plitzi/sdk-shared/schema/
+motionReveal`), one observer under the SDK's root, marks it `data-motion-seen`. The scroll-driven arrival is
+  `on: 'scroll'`. A page read without scripts shows them as they end (`@media (scripting: none)`); the builder's previews
+  and the MCP's local screenshots hold motion at its end. The builder's Motion tab has the three.
+
+  The builder's preview plays motion as the published page does. It held everything at its end, and nothing marked
+  the canvas `data-hydrated`, so neither the loops nor a space's own `[data-hydrated]` animations ever started there.
+  Now an arrival plays as it comes into view, and the loops and keyframes run; **▶** on the canvas being edited runs the
+  space's own `[data-hydrated]` loops too. The motion guide adds the rule this needs from a space: `[data-hydrated]` is for
+  loops; an entrance of its own that plays once (`transform`/`opacity` only) plays from the first paint with
+  `backwards`, as the presets do — gated on hydration it jumps when the page goes live, and a canvas that never goes
+  live holds it on its first frame.
+
+  ## Thirteen ways in, nine loops
+
+  `motion` grows from six arrivals and four loops to thirteen and nine, all still `opacity` and the transforms:
+
+  - **Bold arrivals:** `slide-up` (from well below), `zoom-in` (from 60%), `zoom-out` (settling from 125%), `tilt`
+    (rising as it turns straight), `spin-in` (half a turn as it grows).
+  - **Springy arrivals:** `pop` overshoots and settles; `bounce-in` falls into place and bounces.
+  - **Loops:** `bounce`, `wobble`, `orbit` (a slow circle round where it is), `heartbeat`, `drift`.
+
+  An arrival is now a list of frames (`MOTION_ENTER_FRAMES` in `@plitzi/sdk-shared/schema/motion`; `MOTION_ENTER_FROM`
+  is its first), and so is a loop (`MOTION_LOOP_FRAMES[name].frames`, replacing `transform`/`at`). Arrivals move the
+  individual `translate`, `scale` and `rotate`, so they still compose with an element's own `transform` and with a loop.
+  The builder's Motion tab previews every frame; authoring, the MCP, `explain motion` and GraphQL read the same lists.
+
+  An arrival from the side no longer scrolls the page sideways. `slide-left` starts 32px to the right of where it lands,
+  past a phone's 16px gutter, and until it had played the page could be dragged sideways. The SDK's root clips that way
+  now (`overflow-x: clip`, which keeps the window the scroller: sticky bars and scroll timelines are untouched), and the
+  builder's preview does the same. Content wider than the page is cut rather than scrolling the page — give it a box of
+  its own with `overflow-x: auto`.
+
+  **3D and the transform parts are style properties.** `transform-style`, `perspective-origin`, `backface-visibility`,
+  `translate`, `rotate` and `scale` join the vocabulary (they were refused as `css-property-unknown` and had to go in
+  `customCss`); `scale: 0.94` is a factor, not pixels.
+
+  **The builder's placeholder for an empty element is 24px** (was 50px), one size for every element that has one. It
+  is a minimum, so it also grew empty shapes with a size of their own — a dot, a planet — while editing; 24px is still
+  a box to see, pick and drop into.
+
+  The desktop app's window was blank: authoring, run in the renderer to build the rail, asked Vite's `process` shim for
+  a working directory it does not have. It reads one only where there is one now — and only when a class conflict is
+  reported, rather than for every element of every space it writes.
+
+  ## Authoring advice that knows where and when
+  - **`class-conflict` says where both declarations are:** `styles('md-menu-button') at src/components/dropdown.ts:12,
+used by button at …, and styles('md-menu-button') at src/site/layout.ts:8, used by …` — `styles()` records its line as
+    an element factory does.
+  - **`repeated-shape` leaves controls alone.** Siblings that read different sources or write different state keys — a
+    menu for the language, one for the level — are not offered as a list.
+  - **`quiet: ['repeated-shape']`** on an element says a suggestion was left on purpose, and it is not offered again.
+    Only suggestions' codes (`quiet-unknown`). It is saved on the element (`definition.quiet`), so the builder's problems
+    panel, the MCP's `upsertElement`/`patchElement` and a project pulled back with `plitzi pull` all leave it alone.
+
+  ## What the docs say is what the code does
+
+  A pass across authoring's own messages, the skills, the MCP guide, `docs/en`, the CLI's README and the website, so an
+  agent reading two of them is never told two things:
+
+  - **A binding's `source` is the bound value, and only that.** With no value yet it fell back to the attribute's
+    current one — `sourceTo` — so `{{ source|default('…') }}` never took its default and `{{ source ? … }}` read an
+    element's placeholder ("Text") as an answer. It is `undefined` until the source has a value now; `sourceTo` is still
+    the value before.
+  - **`explain` writes a step the way its builder is called:** `delay(ms)`, `openModal('modal-id', data?)`,
+    `scrollBy('row-id', { x: '80%' })` — not `delay(…)` above the document's param names, which read as `delay({ time })`.
+  - **A page field nobody takes is told what it was probably for** — `seo` → `seoTitle` and `seoDescription` — instead of a
+    hint about keeping state appended to every one.
+  - Docs set straight: an element's id is `data-plitzi-el` in the page (`data-id` is the builder's, with debugging on);
+    a visibility condition writes nothing while its source has no value and is a yes or a no once it has one; `mobile`
+    is up to and including 48rem; `loadStrategy` defaults by type (`lazy` for a modal); the accessibility codes listed
+    in full everywhere (`embed-without-title`, `dropdown-without-control`, `controls-no-anchor`); the generated
+    `AGENTS.md` says a repeated block is a component and rows of data a list, as the skill does; `plitzi runtime` is
+    documented in the CLI's README, its skill and the website, which no longer says state across requests needs a
+    server of your own.
+
+- Updated dependencies [6ae4161]
+  - @plitzi/sdk-authoring@0.38.4
+
+## 0.38.3
+
+### Patch Changes
+
+- e047e1d: ## `plitzi upgrade`: a project brought up to its CLI
+
+  A project written by an older CLI had no way up but `plitzi create` in a scratch folder and a file-by-file comparison:
+  `skills update` brought the skills and nothing else, so the `check` and `shot` scripts they teach did not exist.
+  `plitzi upgrade` (also `update`) shows what this CLI writes today for what is the CLI's in the project, and `--write`
+  makes it. One part or several: `plitzi upgrade skills`, `plitzi upgrade files packages`.
+
+  - **`files`:** the CLI's machinery — `author.ts`, `main.ts`, the Playwright, TypeScript and lint configs, AGENTS.md. One
+    nobody changed since the CLI wrote it is replaced, a missing one added; one the project made its own is shown as a
+    diff and left, until `--take <file>` (or `all`). `plitzi create` now records what it wrote, by digest, in
+    `.plitzi/scaffold.json`; a project made before that sees every file that differs as its own.
+  - **`packages`:** `package.json` merged, never replaced — the scripts and dependencies it lacks added, `@plitzi/*`
+    raised to this version, then the install (`--no-install` to leave it). A script of the project's own stays.
+  - **`skills`:** `.claude/skills/plitzi-*` from the packages installed, each replaced whole, and the ones a newer CLI
+    writes added. `plitzi skills update` is `plitzi upgrade skills --write`.
+  - **`renames`:** a name a version renamed with no alias, at its file and line — `canTemplate` → `canSnippet`,
+    `authorTemplate` → `authorSnippet` and its kin (renamed only where imported from `@plitzi/sdk-authoring`) — renamed
+    with `--write`.
+
+  `npm run author` says when the skills or the CLI's files are older than the SDK installed, and `plitzi --version`
+  prints the CLI's.
+
+  ## Page checks that can be the definition of done
+
+  `inspectPage`, `plitzi check` and the scaffold's visual test failed pages that were whole, so an agent learnt to ignore
+  them:
+
+  - **A breakpoint hiding an element on purpose** — the desktop navigation on a phone, a bottom bar only a phone shows —
+    is no longer "not visible": an element whose `display` or `visibility` a breakpoint rule sets is checked at the width
+    it shows at.
+  - **A lazy image out of sight** waits whichever side it is out of: below the fold, as before, or beside the screen in a
+    carousel's track — cut off by any ancestor that clips, as the browser decides when to fetch it.
+  - **A plugin that draws nothing** says so: `drawsNothing: true` in its declaration (a clock that fires a flow), and its
+    handle is `boxless`, so no check waits for it on screen.
+
+  `plitzi check --json` and `PageReport` carry `issues` beside `problems`: each with its `code` (`element-hidden`,
+  `image-not-loaded`, `sideways-scroll`…), the `elementId` it is about and, in `check`, the `width`.
+
+  ## Authoring
+  - **A link's `content` names it.** `control-without-name` read only a link's `label`, so applying the
+    `content-attribute` suggestion as written turned every link into a warning.
+  - **`plitzi fix` writes `content-attribute`** where it has one reading: a button's or link's children that are only
+    `text(…)` and `fontAwesome({ icon })` become its own `content` and `icon` — the words kept as written, an import left
+    unused taken out. A child with an id, options or a class of the space's own stays, and is said. `npm run author`'s
+    `[fix]` line counts these too.
+  - **The recipes, the skill's examples and the catalog template** hold to the suggestions as well as the warnings, and
+    their tests say so: six recipes and the template wrote a link's or a button's words as a child.
+
+  ## Declared motion — in code, in the builder and over MCP
+
+  An element says how it arrives and whether it keeps moving with `motion`, and the SDK's stylesheet plays it — no
+  keyframes to write: `{ enter: 'fade-up', on: 'view' }` arrives as it scrolls into view, `{ enter: 'scale', stagger:
+60 }` brings its children one by one (a grid, a list's rows), `{ loop: 'float' }` keeps it moving. Enters: `fade`,
+  `fade-up`, `fade-down`, `slide-left`, `slide-right`, `scale`; loops: `float`, `pulse`, `spin`, `sway`; `duration`,
+  `delay`, `stagger` in ms. Opacity and the transforms only — an arrival on `translate`/`scale`, so it composes with an
+  element's own `transform` — a loop held until the page is live (`data-hydrated`), and none of it for a visitor who asked
+  for less motion. `view` follows the scroll where the browser has scroll timelines and plays on load where not.
+
+  - **Authoring:** `motion` on any factory; refused where it cannot play (`motion-invalid`, `motion-no-tag`), and carried
+    by `specFromSpace` and `compareSpaces`.
+  - **Builder:** a **Motion** tab in an element's tools: the presets as chips, a stage that plays the one pointed at (a
+    loop shown stronger than the page plays it, and saying so), when and how long, children one by one, and the choices
+    read back as a sentence — laid out side by side once the sidebar is wide enough. The canvas holds motion still while
+    editing; **▶** in the header (or **Play on the canvas** in the tab) plays it from the start, restarting what already
+    played, and an arrival tied to the scroll plays by the clock there, where it is usually in view already.
+  - **MCP:** `motion` on `upsertElement` and `patchElement`, checked the same way; the guide names the presets.
+  - **Schema:** `definition.motion` (`ElementMotion`, `@plitzi/sdk-shared/schema/motion` — the presets, `motionProblems`,
+    `motionAttributes`, `isMotionAnimation`, and each preset's frames, which the stylesheet is tested against), in both
+    init queries. **The platform's GraphQL schema has to declare `SpaceElementMotion`
+    before this version's builder or SDK queries it.**
+
+  ## Dev tools QA: x-ray and motion
+
+  The **QA** tab gains an **X-ray**: every element the document wires something to — bound to data, shown on a condition,
+  running a flow, moving, behind a flag — outlined in its colour and named on the page, read from the space's document by
+  the element's name; its legend counts each kind on the page and picks one to show alone. Beside **Pause**, **Slow**
+  plays every animation at a quarter of its speed and **Replay** plays the declared motion again from the start, without
+  reloading the page.
+
+  ## Plugins that draw
+
+  `useCanvas2d`, `useWebGL`, `useWebGL2` and `useAnimationFrame` (`@plitzi/plitzi-sdk`): a canvas sized to the device (at
+  most 2×), followed as it resizes, animating only while somebody can see it move — a live page, no reduced motion, the
+  tab in front, the canvas on screen — and one still frame otherwise (the builder included). `createShaderProgram`
+  compiles and links, and a shader that fails throws a `ShaderError` with the driver's log, printed as
+  `[plugin <type> "<id>"] fragment shader failed: …` instead of an empty canvas; `error` and `ready` say where it is.
+  `useReducedMotion` for the rest.
+
+  ## A space re-authored without a restart
+
+  A project's `npm run start:dev` restarts for its server code and its plugins only: a save to the space is re-authored
+  in a process of its own and every open page loads again (`server.reloadPages()` over an SSE endpoint, on with
+  `createServer({ devReload: true })` — never by `devMode` alone, since every open page holds a connection for it); an
+  edit authoring refuses is printed and the page keeps the last space that authored. A shutdown also ends WebSockets at
+  once (`1001`, going away) rather than waiting out the grace — the ten seconds a restart used to wait on an open page.
+
+  ## Checks and authoring, from the stripe.com experiment
+  - **A component's instance** is found by its own name: its root carries `data-plitzi-instance`, and the instance's
+    handle selects it — `inspectPage` no longer reports every named instance as missing.
+  - **Hidden at this width on purpose** — the burger on a desktop, the desktop menu on a phone — is listed apart
+    (`hiddenAtWidth`, and a dim line under `plitzi check`'s ✓) rather than as a problem.
+  - **An element whose every child is conditional** — four flyouts in one list, each opening on the state that names
+    it — is conditional too: at rest it shows nothing, and that is it working.
+  - **A carousel that scrolls by itself** (`overflow-x: auto`) is not the page scrolling sideways; the page's own pane
+    still is.
+  - **Templates:** `{{ state.faq ?? -1 }}` — a sign on the right of `??` — reads.
+  - **A plugin attribute named as an element field** (`variant`, `class`, `id`…) is warned about
+    (`plugin-attribute-reserved`): a factory never hands it to the plugin. A `variant` no class or type style declares is
+    `unknown-variant`.
+  - **Lists:** a list with `items` renders as the `<ul>` (or `<ol>`) its `subType` says — it was a `<div>` — with no
+    markers and the same spacing, so a page looks as it did; the builder offers the list type for it too. Its rows are
+    `<li>`s: `list-row-not-li` warns of one that is not — a plain container is made one by `fixSpace`, a link or a button
+    is wrapped — and the recipes, the catalog template and the docs write rows as `listItem`.
+  - **CSS:** `mask-size`, `mask-position`, `mask-repeat`, `mask-composite`, `-webkit-mask-image`,
+    `-webkit-background-clip`, `box-decoration-break` and `-webkit-box-decoration-break`.
+  - **`plitzi shot`:** `--clip <element>`, `--scroll-to <element>` and `--viewport`; `--frames` takes the same framing.
+  - **SVG from files:** `svgFile` and `svgFiles` (`@plitzi/sdk-authoring/node`) read a logo or a folder of them,
+    compacted (`compactSvg`, also on the main entry), instead of strings in the space's source.
+  - The plugin scaffolds say that an inline `style` on `RootElement` outranks the element's classes.
+
+- Updated dependencies [e047e1d]
+  - @plitzi/sdk-authoring@0.38.3
+
 ## 0.38.2
 
 ### Patch Changes

package/README.md

@@ -59,8 +59,8 @@ code (JSON, with the reason said, where one would not read back exactly), its fu
 runtime, and its files downloaded into `public/` with every CDN address rewritten — served by the project with nothing
 of Plitzi's. `.env` gets a signing key made for it and the names of the variables and credentials the space had, never
 their values. It signs in as you and needs a space you may change; the end of `create` says what came across
-differently. What the project was given is recorded in `.plitzi/space.json` — commit it — for [`pull`](#pull). See
-`docs/en/projects-from-spaces.md`.
+differently. What the project was given is recorded in `.plitzi/space.json` — commit it — for [`pull`](#pull) and
+[`push`](#push). See `docs/en/projects-from-spaces.md`.
 
 ## The package manager
 
@@ -126,6 +126,14 @@ when an install fails the CLI says which setting names it.
   save the most first. Not problems: the space authors either way. `npm run author -- --json` carries them in
   `suggestions`.
 
+## The folders that are not the source
+
+| 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 |
+| `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 |
+| `.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 |
+
 ## `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`
@@ -140,17 +148,28 @@ per part under `src/site/`. Both go with `--source local`.
 ```bash
 plitzi check / --width 1440,390            # is the page whole? in text, per width; --json for a tool
 plitzi check /products --state --element catalog-count   # and what it holds: state, sources, one element
+plitzi check / --ssr                       # and what the server's HTML lacks that the hydrated page has
 plitzi shot /about --width 390 --scheme dark
 plitzi shot / --frames 4 --every 500       # what moves: a marquee, an autoplay
-plitzi shot / --compare https://example.com --width 1440   # side by side, and how much differs by section
+plitzi shot / --compare https://example.com --width 1440   # beside another site: what differs, and how
 ```
 
 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
-images, sideways scroll, text in the colour behind it, console errors and refused requests — a page's state in a few
-hundred tokens, where a screenshot costs thousands. `shot --compare` writes the two pictures side by side and the
-differences in red, and says the share that differs in each landmark of the page; `--frames` compares pictures taken
-one after another and names what moved. A project `create` writes has them as `npm run check` and `npm run shot`.
+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.
+
+`--scheme` is the space's own theme, set as a visitor's toggle sets it (the `theme` cookie); left out, the space's
+default, and `shot` names the file by the theme it was painted in. The dev tools' badge is hidden from both. A
+full-page `shot` is the whole page — the pane the SDK scrolls in unrolled, every lazy picture loaded, every arrival
+waiting for the scroll shown as it ends — in `tmp/shots/` unless `--out` says where.
+
+`shot --compare` writes the two pictures side by side and the differences in red. It compares each section where it
+is on the other page, so a page 400 px longer is said once, with the section the drift starts at; then it pairs the
+texts both pages have and says what each does differently there — `h1 "Learn CSS" — font-size 68px → 60px · y +19px`.
+`--frames` compares pictures taken one after another and names what moved. A project `create` writes has them as
+`npm run check` and `npm run shot`.
 
 ## `fix`
 
@@ -200,18 +219,29 @@ plitzi explain navigate         # a step: its params and the function that write
 plitzi explain onScroll         # a trigger: what it hands its flow, and what fires it
 plitzi explain class-and-css    # a problem's code: what was wrong, what to write instead
 plitzi explain content-attribute # a suggestion's code: what is written the long way, and the short one
-plitzi explain --list steps     # every one of a kind: elements, steps, triggers, codes, transformers
+plitzi explain bindTemplate     # a helper: how it is written, what it is for, an example
+plitzi explain motion           # the arrivals, triggers and loops the SDK plays
+plitzi explain --list steps     # every one of a kind: elements, steps, triggers, codes, transformers, helpers
 ```
 
 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}`.
 
-## `skills update`
+## `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
+```
 
-The skills `create` copies into `.claude/skills/` say the version of the package they came from (`version:` in
-`SKILL.md`), and `npm run author` says when the authoring skill is older than the `@plitzi/sdk-authoring` installed.
-`plitzi skills update` replaces each Plitzi skill there with the one of the installed package — whole, so a reference it
-no longer has goes with it — and leaves any other skill alone.
+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
+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`
 
@@ -237,6 +267,30 @@ write **nothing** and name them. Both sides are compared as the project's Pretti
 `package.json` only gains the packages the space's code now asks for. It follows the version the project was made from —
 the draft, an environment's latest, or a pinned revision.
 
+## `push`
+
+```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 --force                      # replace the draft even though it was edited in the builder since
+```
+
+The way back of `pull`: the project put on the space it works with, as its **draft**. With nobody at the terminal it
+sends what changed since the project last had the space. Each part goes up as its own command sends it, in the order
+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/`.
+
+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
+space nobody has worked on yet; one that holds work asks for `--force` too. Always the space the CLI is connected to,
+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.
+
 ## `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