@plitzi/cli 0.38.7 → 0.38.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/cli",
-  "version": "0.38.7",
+  "version": "0.38.9",
   "license": "AGPL-3.0",
   "description": "Command line for Plitzi: scaffold a project that renders a space, a plugin package, or an element of your own.",
   "files": [
@@ -21,14 +21,14 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@plitzi/sdk-authoring": "0.38.7",
+    "@plitzi/sdk-authoring": "0.38.9",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "esbuild": "^0.28.2",
     "fflate": "^0.8.3"
   },
   "devDependencies": {
-    "@plitzi/sdk-shared": "0.38.7",
+    "@plitzi/sdk-shared": "0.38.9",
     "@types/node": "^26.6.4",
     "eslint": "^9.39.5",
     "eslint-plugin-import": "^2.32.0",

package/skills/plitzi-cli/SKILL.md

@@ -4,211 +4,56 @@ description: >-
   Use the Plitzi command line (@plitzi/cli, `plitzi …` or `npx @plitzi/cli …`) instead of hand-writing what it
   generates: scaffold a project that renders a space, add plugins to it or build a plugin package, pack, upload and
   install one, edit a space's functions, take a space on Plitzi out as a self-hosted project and back (`create --from`,
-  `pull`, `push`), and check a project (`doctor`) or how its space's source is written (`lint`). Use whenever the task is
-  to start a Plitzi project, create or change a plugin, pack, upload or install one, pull/push/try a space's functions,
-  move a space to a server of its own and back, or work out which space the CLI is connected to.
+  `space pull`, `space push`), check a project (`doctor`) or how its space's source is written (`space lint`), and
+  write a report to Plitzi of what broke, misled or cost time (`feedback`). Use whenever the task is to start a Plitzi
+  project, create or change a plugin, pack, upload or install one, pull/push/try a space's functions, move a space to a
+  server of its own and back, work out which space the CLI is connected to — or when the person asks for a report,
+  feedback or a list of what went wrong with Plitzi.
 ---
 
 # The Plitzi CLI
 
-The CLI writes what an agent would otherwise get subtly wrong by hand: a project's server, bundler, lint and visual
-test wired together; a plugin's four files in the shape Plitzi's own elements use; a manifest with integrity hashes;
-a signed-in upload. **Reach for it before writing any of those yourself.**
+The CLI writes what an agent would otherwise get subtly wrong by hand: a project's server, bundler, lint and visual test
+wired together; a plugin's files in the shape Plitzi's own elements use; a signed-in upload. **Reach for it before
+writing any of those yourself.** `plitzi <command> --help` lists every flag.
 
 ```bash
-npx @plitzi/cli create my-site                 # a project that renders a space (--template blank | catalog)
-npx @plitzi/cli create my-board --from pizarra # a space on Plitzi, as a project that serves it alone
-npx @plitzi/cli pull                           # that project brought up to date with its space
-npx @plitzi/cli push                           # its changes back as the draft (or: push space functions)
-npx @plitzi/cli add plugin seat-picker legend  # elements of your own, in the project you are in
-npx @plitzi/cli create seat-picker --plugin    # a plugin package any space can load
-npx @plitzi/cli pack plugin                    # a plugin built, and zipped the way the builder takes it
-npx @plitzi/cli upload plugin                  # that zip, on the space you work in, and installed there
-npx @plitzi/cli whoami                         # who the CLI is signed in as, and the space it works in
-npx @plitzi/cli data describe src/data/x.json      # a JSON file's fields, types and one row
-npx @plitzi/cli upgrade                        # the project up to this CLI: files, package.json, skills, renames (--write)
-npx @plitzi/cli explain navigate               # what a name means: element, step, trigger, code, helper (bindTemplate, motion)
-npx @plitzi/cli functions pull                 # the space's functions (its own server code) into src/functions/
-npx @plitzi/cli functions push                 # src/functions/ back as the space's draft, built and checked
-npx @plitzi/cli functions try feed.read --params '{"limit":3}'   # one task of the saved draft, in the sandbox
-npx @plitzi/cli functions dev feed.read --watch                   # the same, from src/functions/, on this machine
+npx plitzi element where hero-cta                       # where the code writes an element: file:line and the call
+npx plitzi element edit hero-cta --set content="Hi"     # an attribute written there, checked
+npx plitzi element remove ent-trust                     # an element taken out, with what only it used
+npx plitzi element move ent-faq --before ent-pricing    # an element put elsewhere among its siblings
+npx plitzi verify                               # left passing? author, lints, types, format, pages
+npx plitzi page check -- /about --width 1440,390     # whether a page is whole, in text
+npx plitzi explain navigate                     # what a name means: element, step, code, any export
+npx plitzi doctor                               # whether the project is whole; --fix the simple parts
+npx plitzi upgrade                              # the project up to this CLI (--write)
+npx plitzi feedback                             # a report to Plitzi, for the person to send as a link
 ```
 
-`plitzi <command> --help` lists every flag; what follows is what the help does not say.
-
 ## Running it as an agent
 
-- **Which check.** The space as a document: `npm run author`. How its source is written: `npm run lint:space`. A
-  rendered page: `check`. The project around them (layout, packages, configs, imports, plugins, data): `doctor`,
-  before `push`; `--fix` repairs the simple ones (an older project: `npx @plitzi/cli@latest doctor --fix`).
-
-- **Reporting to Plitzi: `feedback`.** It writes the report's page and says how to fill and publish it; give the
-  person the link.
-
-- **After the SDK moves, `upgrade`.** It shows the CLI's files, scripts, versions, skills and renamed names as they
-  should be. `--write` replaces what nobody changed, merges `package.json` and installs; a file you changed comes as a
-  diff — `--take <file>` once read.
-
-- **`create` never decides for the person.** Three choices shape a project — package manager, `--mode`
-  (`server`: SSR + RSC on a Node tier, `client`: browser only) and `--source` (`local`: the space lives in the project,
-  `cloud`: it lives in Plitzi). With nobody at the terminal it writes NOTHING and prints each missing choice as a
-  question: ask the user, then run again with their answers as flags. `--yes` only takes the defaults for a person at
-  a terminal; never guess the answers.
-- **Signing in happens in the browser.** `login`, `space` and a first `upload` open one; the person completes it (MFA
-  and social sign-in included — the CLI never sees a password). Tell them a tab is waiting, and wait.
-- **One space at a time.** Everything goes to the space `whoami` names; `plitzi space` switches it. No command takes a
-  space as a flag, so check `whoami --json` (`{ api, user, space }`) before an upload.
-- **Read stdout, exit code and stderr apart.** The answer is on stdout (`--json`: one object, one line); errors and
-  sign-in prompts are on stderr; exit 1 means it did not do what was asked, or a check found something. A bad flag
-  value is refused with what it takes: read it, do not drop the flag.
-
-## The Plitzi MCP or this CLI
-
-Where the space lives decides which one an agent uses — the two never take turns on one space.
-
-| The space | Use |
-| --- | --- |
-| In a project, written in code (`src/space/`, `--source local`) | this CLI and `@plitzi/sdk-authoring`. No account and no MCP |
-| On Plitzi — edited in the builder, with collaborators, published from there | the Plitzi MCP server: it reads and edits the live space, previews a page and checks every edit with the same linter |
-| On Plitzi, and wanted in code from now on | `create --from <space>`, then `pull` and `push` keep both in step |
-
-The MCP needs a signed-in account; when nobody can give one, do not wait on it: a `--source local` project needs
-neither.
-
-## Projects (`create`)
-
-| | `--source local` | `--source cloud` |
-| --- | --- | --- |
-| `--mode server` | A page server of your own, rendering the space in `src/space/`. No account | Your page server, rendering the live space from Plitzi (secret self-hosting key in `.env`) |
-| `--mode client` | Vite + the SDK in the browser, no server, no account | The SDK fetches the space with the public render key |
-
-What a project gives you, so you use it rather than rebuild it:
-
-| Script | What it is for |
-| --- | --- |
-| `start` | serve it — in client mode Vite, which hot-replaces on save. The server prints only what goes wrong; `-- --verbose` adds every request |
-| `start:dev` | server mode: restarted on a save to its code; a plugin is swapped in the open page. Options in `src/config/serverOptions.ts`, actions in `src/actions/`; `plitzi/` is the CLI's, never edit it |
-| `author` | author `src/space/`: every problem at once (file:line, what to change), then the suggestions (`[suggest]`: a shorter way to the same page, the most elements saved first); `-- --json` for a tool |
-| `lint:space` | how `src/space/` is written, at file:line, and authoring's suggestions; `-- --max-warnings 0`. On purpose: `// plitzi-lint-disable-next-line <code> -- why` (a suggestion: `quiet` on its element) |
-| `npx plitzi fix` | what `author` reports that has one fix, as a diff of your source; `--write` writes it, formatted, and keeps it only if the space then authors with it gone and nothing new |
-| `check -- /path --width 1440,390` | whether a page is whole, in text: elements on screen, overflow, console, refused requests, failed flows, a binding its data lacks; `--state`, `--element <id>`: what it holds; `--ssr`: SSR misses; `--as <user>`; `--json` |
-| `npx plitzi import <url>` | a page the user owns, as a start: `tokens.ts`, `outline.ts` (blocks and layout per breakpoint), lists as `data/*.json`, screenshots, `IMPORT.md`. Never the words. **Only when the user asks.** A site not on this machine needs `--account` (their Plitzi account, its domain verified on a space): ask first |
-| `shot -- /path --width 390 --scheme dark` | a picture of one page — `--clip <element>` one element, `--scroll-to <element>` / `--viewport` the screen there, `--frames 4` what moves, `--compare <url>` what differs from another site, by section and by text |
-| `visual` | a browser asserts every element the space names is visible |
-| `typecheck`, `lint`, `format` | before calling a change done |
-
-**Which port.** `start` takes 8080, or the next free one — printed, and written to `tmp/dev-server.json` for `check`,
-`shot` and `visual`. `PORT` chooses one (a taken one is then an error). `/health` answers with the space's name.
-
-Data with no backend, server mode: `src/data/*.json`, never served — a provider with `runtime: 'server'` and `query:
-'/data/x.json'` reads it on the server. Client mode: `public/data/`, fetched — public. Learn a file's fields with
-`data describe`, never by reading it.
-
-**`public/` is on the internet**: never a secret there. `tmp/`, `state/` (its `kv`) ignored; `.plitzi/` committed.
-`--dry-run` on a command that writes or sends says what it would do, and does none of it.
-
-A local space starts as a tour of the platform with a plugin of the project's own; **`--template blank`** as tokens, a
-layout and one empty page — for a project about to be a specific site; **`--template catalog`** as a small shop
-(layout, card component, data in `src/data`, a filtered list, a page per product), a file per part — the one to read
-when unsure how a whole site is put together.
-
-The space itself is written with `@plitzi/sdk-authoring` — see the `plitzi-authoring` skill, which `create` copies into
-`.claude/skills/` beside this one.
-
-## A space on Plitzi, as a project (`create --from`, `pull`)
-
-Taking a space out of Plitzi as a server project of its own, and keeping it in step: read
-[reference/from-space.md](reference/from-space.md) when the task names `--from` or `pull`.
-
-## Elements of your own (`add plugin`)
-
-A plugin is a React component the space renders — a map, a chart, a seat picker: whatever is not text in a box. **Never
-start one from a blank file**: `add plugin <name>` writes it in the shape the platform, the builder and the linter all
-read.
-
-```bash
-plitzi add plugin seat-picker                                  # one; asks what the builder calls it and what it is for
-plitzi add plugin seat-picker legend                           # several at once
-plitzi add plugin ticker --prop interval:number=5000 --prop paused:boolean --trigger onTick:count --callback reset --headless
-```
-
-**Say its shape and it is written in it**: `--prop name:type=default` (string, number, boolean; `list`/`json` for data
-a binding fills) per attribute — typed, bindable, with a control in its panel; `--trigger onTick:count` per event and
-what a flow reads, fired with its `use<Name>Events()` hook; `--callback reset` per action a flow calls; `--headless`
-for one with nothing to see. Without them it writes a counter showing the three ways an element talks to a space.
-
-Each is a folder (`src/plugins/SeatPicker/` in a project `create` wrote):
-
-| File | What it holds |
-| --- | --- |
-| `SeatPicker.tsx` | the component. Its props ARE the element's attributes; render through `RootElement` |
-| `declaration.ts` | its `type`, the `triggers` (events) it fires, the `callbacks` (actions) it answers, its default attributes — data only |
-| `Settings.tsx` | its panel in the builder |
-| `index.ts` | the three put together |
-
-- **Registered by itself**: every folder of `src/plugins` is, under its name in camelCase (`SeatPicker` → `seatPicker`).
-  Elsewhere the command prints the line that registers it (for `render()`, `<PlitziSdk>` or a page server).
-- **Host it** with `custom({ renderType: 'seatPicker', … })` in `src/space/` — or a Custom element in the builder.
-- **Checked like a built-in element**: its folder's `declaration.ts` is found by itself and handed to
-  `authorSpace(space, { plugins })`: flows on its events, steps to its actions and its attributes are
-  refused when wrong; `declaredTrigger(declaration, 'onPick')` and `declaredCallback(declaration, 'reset', { on: 'seats' })`
-  build them typed. A plugin written by hand is added to that list.
-- **A new event or action** is declared in `declaration.ts` and registered by the component FROM there — never only
-  in the component, or neither the builder nor the linter knows it exists.
-- A name that is a built-in type (`button`, `form`) is refused: a space could not tell the two apart.
-- **A server half** (`--server`): `functions/index.ts` in its folder — routes under `/fn/plugins/<type>/`
-  (`usePluginRoute`), steps `<type>.<action>`, its own `kv`, none of the space's credentials.
-
-## Plugin packages (`create --plugin`)
-
-Elements any space can load, published on their own, with a Vite preview to write them in:
-
-```bash
-plitzi create seat-picker --plugin
-plitzi create packages/seat-picker --plugin --name @acme/plitzi-plugin-seat-picker --elements legend,price-tag
-```
-
-Its scripts: `start` (the elements inside a space, hot-replaced), `visual`, `typecheck`, `lint`. Add more elements with
-`add plugin` from inside it — they are listed in `src/elements.ts` and `src/declarations.ts`, which the package
-publishes from. A package's element is authored as a TYPE of its own: `defineElement<SeatPickerAttributes>(declaration)`.
-
-## Building and shipping (`pack plugin`, `upload plugin`)
-
-```bash
-plitzi pack plugin                              # in a plugin package: every element
-plitzi pack plugin src/plugins/SeatPicker       # an element of a project; several folders → one plugin, the first its main
-plitzi upload plugin                            # the zip pack left, onto the space whoami names, installed there
-```
-
-`pack` writes one ES module (React and the SDK kept out — the page provides them), `plugin-manifest.json` from the
-declarations with integrity hashes, and the zip the builder takes under Resources. `upload` checks the manifest,
-sends the zip to one of the space's CDNs (`--cdn`) and installs it — a plugin already there moves to the new version with
-its settings kept. `--plugin-version` sets the version the manifest carries. The plugin's source — every file it
-imports, followed from its entry — is kept beside it on the space (`runtime push` does the same for a runtime), which
-is what `create --from` brings back; `plitzi pack source` writes what would be kept to a file, to look at.
-
-A self-hosted page server does not need `pack`: it compiles a plugin from its source (`action: 'compile'`).
-
-The same server decides its own say over the space's **feature flags**: `createServer({ flags: { newCheckout: true } })`
-(or a function of `{ spaceId, environment }` when it serves several). It overrides what the space declares — only for
-flags the space declares — and is overridden by the SDK's `flags` prop and a tester's dev tools. Declaring the flags
-themselves is the space's (`flags` in the spec; see the authoring skill's feature flags).
-
-## Server code (`functions`, `runtime`)
-
-A space's own server code, edited in `src/functions/` (`pull`, `push`, `try`, `dev`) or run as its runtime
-(`src/runtime/`, `add runtime`, `runtime push`): read [reference/functions.md](reference/functions.md) for either.
-
-
-## When something does not work
-
-| What you see | What it is |
-| --- | --- |
-| `create` printed questions and wrote nothing | nobody answered the three choices — ask the user, pass them as flags |
-| `start` says the port is in use | `PORT` is set to a taken port — unset it to take the next free one, or choose another |
-| A page that is not this project's, or `shot` refuses the port | another server answers there — `curl 127.0.0.1:<port>/health` names it; `tmp/dev-server.json` has this project's port |
-| "Custom Component … Not Found", or a flow on a plugin's event never runs | `doctor` names the folder whose type or declaration is off |
-| "not laid out as Plitzi reads it" | each misplaced part, with its fix; `doctor --fix` |
-| `upload` opens a browser | there is no session, or no space chosen — the person completes it there |
-| The upload went to the wrong space | `plitzi space` chooses another; check `whoami` first |
-| `pull` wrote nothing and named files | they changed here and on the space — set your changes aside and pull again, or `--force` |
+- **Which check.** All of it before you finish: `verify` — only what fails is printed. The space alone: `npm run
+  author`; a page: `page check`. The project around them: `doctor`, before `space push`. Pages for signed-in visitors
+  are checked as the account `.env` names (`PLITZI_CHECK_USER`, `PLITZI_CHECK_PASSWORD`); `verify` says when none is.
+- **`create` never decides for the person.** With nobody at the terminal it writes nothing and prints each choice as a
+  question: ask the user, then run again with their answers as flags. Never guess them.
+- **Signing in happens in the browser** (`login`, `space use`, a first `plugin upload`): tell the person a tab is waiting.
+- **One space at a time** — the one `whoami --json` names; `plitzi space use` switches it.
+- **A report to Plitzi** — the person asks for a report, feedback, the bugs found or what cost time: `npx plitzi
+  feedback` (`--previous <link>` continues an earlier one). It reads the versions and `doctor` itself and writes the
+  page; fill it and publish it as its brief says, rather than a report of your own making.
+- **Read stdout, exit code and stderr apart.** The answer is on stdout (`--json`: one line); exit 1 means it did not do
+  what was asked. A refusal says what to change: change it — the same refusal twice says to stop and ask.
+
+**The MCP or this CLI.** A space written in code (`src/space/`) is this CLI's, with no account. One kept on Plitzi —
+edited in the builder — is the Plitzi MCP's. Never both on one space.
+
+## What to read
+
+| The task                                                                   | Read                                            |
+| -------------------------------------------------------------------------- | ----------------------------------------------- |
+| Start a project, its modes, scripts and port                               | [projects](reference/projects.md)               |
+| An element of your own, a plugin package, packing and uploading one        | [plugins](reference/plugins.md)                 |
+| A space on Plitzi as a project, and back (`create --from`, `space pull`, `space push`) | [from-space](reference/from-space.md)           |
+| The space's own server code (`functions`, `runtime`)                       | [functions](reference/functions.md)             |
+| Something does not work                                                    | [troubleshooting](reference/troubleshooting.md) |

package/skills/plitzi-cli/reference/from-space.md

@@ -1,4 +1,4 @@
-# A space on Plitzi, as a project (`create --from`, `pull`, `push`)
+# A space on Plitzi, as a project (`create --from`, `space pull`, `space push`)
 
 `create --from <space>` (its permanent URL or id) writes a server project holding everything the space is made of, and
 serving it with nothing of Plitzi's — neither its servers nor its CDN:
@@ -17,19 +17,19 @@ pinned) says otherwise. Read the report it prints: a
 plugin or runtime uploaded before Plitzi kept sources comes across built only (`vendor/`), and a space with visitor
 roles needs sign-in of its own (the report says how).
 
-`pull` brings the project up to date: what changed on the space alone is written, what changed here alone is kept,
+`space pull` brings the project up to date: what changed on the space alone is written, what changed here alone is kept,
 and when one file changed on both it writes **nothing** and names them — keep your changes aside and pull again, or
 `--force` to take the space's copy. It never touches `.env`, and only adds to `package.json`. What the project was given
 is recorded in `.plitzi/space.json`: commit it. It follows the version the project was made from; `pull --environment
 … --revision …` moves it to another, `--revision latest` lets go of a pin.
 
-`push` is the way back: what changed in the project, as the space's **draft** — publishing stays the builder's. At a
+`space push` is the way back: what changed in the project, as the space's **draft** — publishing stays the builder's. At a
 terminal it lists the parts with what changed ticked; otherwise it sends what changed, or the parts named:
-`push space functions` (`space`, `functions`, `data`, `runtime`, `plugins`, `files`). Plugins and the files of
+`space push space functions` (`space`, `functions`, `data`, `runtime`, `plugins`, `files`). Plugins and the files of
 `public/assets/` go up first (each file at the same path under the space's `assets/`), then the functions, the data, the
 runtime, and the pages, actions and connectors last. Only `public/assets/` reaches the space's CDN: put a file the space
 names there, never elsewhere in `public/`. It is refused when the draft was edited in the builder since the
 project last had it — pull first, or `--force` to replace it — and a project that never had the space may only take a
 space nobody has worked on without `--force`. It pushes to the space the CLI is connected to, which must be the one
-the project came from, and records what it sent in `.plitzi/space.json`, so `pull` works afterwards — on a project that
+the project came from, and records what it sent in `.plitzi/space.json`, so `space pull` works afterwards — on a project that
 started on its own too.

package/skills/plitzi-cli/reference/functions.md

@@ -4,9 +4,9 @@ A space's own server code — TypeScript tasks its actions run as steps, and rou
 `src/functions/` in a project is a **working copy** of it. The contract (`defineFunctions`, `ctx`) is typed in
 `@plitzi/sdk-server/functions`, whose `.d.ts` documents every field; what matters for the CLI:
 
-- **Pull before you edit, push when done.** `pull` refuses to overwrite what is not pushed (`--force` throws it
-  away); `push` refuses when the space changed since the pull — someone saved in the builder. Then: keep your changes
-  aside, `pull`, apply them again, `push`. Never `--force` over somebody else's work to get past it.
+- **Pull before you edit, push when done.** `functions pull` refuses to overwrite what is not pushed (`--force` throws it
+  away); `functions push` refuses when the space changed since the pull — someone saved in the builder. Then: keep your
+  changes aside, `functions pull`, apply them again, `functions push`. Never `--force` over somebody else's work to get past it.
 - **A push is checked, not just stored.** A problem comes back as `src/functions/<file>:<line> <message>` and nothing is
   saved — fix it and push again. `index.ts` must default-export `defineFunctions({ … })`; files import each other by
   relative path and `@plitzi/sdk-server/functions`, nothing else. `src/data/` is read with `ctx.data('x.json')`, never
@@ -21,7 +21,7 @@ A space's own server code — TypeScript tasks its actions run as steps, and rou
 ## A space's runtime (`runtime`)
 
 What a function cannot be — Node packages, a connection held open, state across requests — is the space's **runtime**:
-`src/runtime/index.ts` (`plitzi add runtime`), default-exporting `defineRuntime` from `@plitzi/sdk-server/runtime` (its
+`src/runtime/index.ts` (`plitzi runtime add`), default-exporting `defineRuntime` from `@plitzi/sdk-server/runtime` (its
 `.d.ts` documents it). The project's server runs it as Plitzi does, so try it with `npm start` before pushing.
 
 - `runtime push` packs it (`--entry` for another file) as the draft's runtime; publishing deploys it. Its source goes
@@ -30,4 +30,3 @@ What a function cannot be — Node packages, a connection held open, state acros
   reads the value from stdin (`printf %s "$V" | …`), never echo it in a command line; `vars unset NAME` removes one.
 - `runtime size small|medium|large`, `stop`, `start` — the draft's unless `--environment` names a published one.
 - It needs a plan that includes runtimes and a private bucket on the space's CDN; a refusal says which is missing.
-

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

@@ -0,0 +1,75 @@
+# Elements of your own, and plugin packages
+
+## Elements of your own (`plugin add`)
+
+A plugin is a React component the space renders — a map, a chart, a seat picker: whatever is not text in a box. **Never
+start one from a blank file**: `add plugin <name>` writes it in the shape the platform, the builder and the linter all
+read.
+
+```bash
+plitzi plugin add seat-picker                                  # one; asks what the builder calls it and what it is for
+plitzi plugin add seat-picker legend                           # several at once
+plitzi plugin add ticker --prop interval:number=5000 --prop paused:boolean --trigger onTick:count --callback reset --headless
+```
+
+**Say its shape and it is written in it**: `--prop name:type=default` (string, number, boolean; `list`/`json` for data
+a binding fills) per attribute — typed, bindable, with a control in its panel; `--trigger onTick:count` per event and
+what a flow reads, fired with its `use<Name>Events()` hook; `--callback reset` per action a flow calls; `--headless`
+for one with nothing to see. Without them it writes a counter showing the three ways an element talks to a space.
+
+Each is a folder (`src/plugins/SeatPicker/` in a project `create` wrote):
+
+| File | What it holds |
+| --- | --- |
+| `SeatPicker.tsx` | the component. Its props ARE the element's attributes; render through `RootElement` |
+| `declaration.ts` | its `type`, the `triggers` (events) it fires, the `callbacks` (actions) it answers, its default attributes — data only |
+| `Settings.tsx` | its panel in the builder |
+| `index.ts` | the three put together |
+
+- **Registered by itself**: every folder of `src/plugins` is, under its name in camelCase (`SeatPicker` → `seatPicker`).
+  Elsewhere the command prints the line that registers it (for `render()`, `<PlitziSdk>` or a page server).
+- **Host it** with `custom({ renderType: 'seatPicker', … })` in `src/space/` — or a Custom element in the builder.
+- **Checked like a built-in element**: its folder's `declaration.ts` is found by itself and handed to
+  `authorSpace(space, { plugins })`: flows on its events, steps to its actions and its attributes are
+  refused when wrong; `declaredTrigger(declaration, 'onPick')` and `declaredCallback(declaration, 'reset', { on: 'seats' })`
+  build them typed. A plugin written by hand is added to that list.
+- **A new event or action** is declared in `declaration.ts` and registered by the component FROM there — never only
+  in the component, or neither the builder nor the linter knows it exists.
+- A name that is a built-in type (`button`, `form`) is refused: a space could not tell the two apart.
+- **A server half** (`--server`): `functions/index.ts` in its folder — routes under `/fn/plugins/<type>/`
+  (`usePluginRoute`), steps `<type>.<action>`, its own `kv`, none of the space's credentials.
+
+## Plugin packages (`create --plugin`)
+
+Elements any space can load, published on their own, with a Vite preview to write them in:
+
+```bash
+plitzi create seat-picker --plugin
+plitzi create packages/seat-picker --plugin --name @acme/plitzi-plugin-seat-picker --elements legend,price-tag
+```
+
+Its scripts: `start` (the elements inside a space, hot-replaced), `visual`, `typecheck`, `lint`. Add more elements with
+`plugin add` from inside it — they are listed in `src/elements.ts` and `src/declarations.ts`, which the package
+publishes from. A package's element is authored as a TYPE of its own: `defineElement<SeatPickerAttributes>(declaration)`.
+
+## Building and shipping (`plugin pack`, `plugin upload`)
+
+```bash
+plitzi plugin pack                              # in a plugin package: every element
+plitzi plugin pack src/plugins/SeatPicker       # an element of a project; several folders → one plugin, the first its main
+plitzi plugin upload                            # the zip pack left, onto the space whoami names, installed there
+```
+
+`pack` writes one ES module (React and the SDK kept out — the page provides them), `plugin-manifest.json` from the
+declarations with integrity hashes, and the zip the builder takes under Resources. `upload` checks the manifest,
+sends the zip to one of the space's CDNs (`--cdn`) and installs it — a plugin already there moves to the new version with
+its settings kept. `--plugin-version` sets the version the manifest carries. The plugin's source — every file it
+imports, followed from its entry — is kept beside it on the space (`runtime push` does the same for a runtime), which
+is what `create --from` brings back; `plitzi source pack` writes what would be kept to a file, to look at.
+
+A self-hosted page server does not need `pack`: it compiles a plugin from its source (`action: 'compile'`).
+
+The same server decides its own say over the space's **feature flags**: `createServer({ flags: { newCheckout: true } })`
+(or a function of `{ spaceId, environment }` when it serves several). It overrides what the space declares — only for
+flags the space declares — and is overridden by the SDK's `flags` prop and a tester's dev tools. Declaring the flags
+themselves is the space's (`flags` in the spec; see the authoring skill's feature flags).

package/skills/plitzi-cli/reference/projects.md

@@ -0,0 +1,42 @@
+# Projects
+
+## `create`
+
+| | `--source local` | `--source cloud` |
+| --- | --- | --- |
+| `--mode server` | A page server of your own, rendering the space in `src/space/`. No account | Your page server, rendering the live space from Plitzi (secret self-hosting key in `.env`) |
+| `--mode client` | Vite + the SDK in the browser, no server, no account | The SDK fetches the space with the public render key |
+
+What a project gives you, so you use it rather than rebuild it:
+
+| Script | What it is for |
+| --- | --- |
+| `start` | serve it — in client mode Vite, which hot-replaces on save. The server prints only what goes wrong; `-- --verbose` adds every request |
+| `start:dev` | server mode: restarted on a save to its code; a plugin is swapped in the open page. Options in `src/config/serverOptions.ts`, actions in `src/actions/`; `plitzi/` is the CLI's, never edit it |
+| `author` | author `src/space/`: every problem at once (file:line, what to change), then the suggestions (`[suggest]`: a shorter way to the same page, the most elements saved first); `-- --json` for a tool |
+| `lint:space` | how `src/space/` is written, at file:line, and authoring's suggestions; `-- --max-warnings 0`. On purpose: `// plitzi-lint-disable-next-line <code> -- why` (a suggestion: `quiet` on its element) |
+| `npx plitzi space fix` | what `author` reports that has one fix, as a diff of your source; `--write` writes it, formatted, and keeps it only if the space then authors with it gone and nothing new |
+| `npx plitzi element where <id\|class\|words>` | where the code writes an element: file:line and the call — edit it there, not the files around it. `npx plitzi element edit <id> --set content="…"` writes an attribute in it, `remove <id>` takes it out, `move <id> --before <id>` reorders it — each checked |
+| `check -- /path --width 1440,390` | whether a page is whole, in text: elements on screen, overflow, console, refused requests, failed flows, a binding its data lacks; `--state`, `--element <id>`: what it holds; `--ssr`: SSR misses; `--as <user>`; `--json` |
+| `npx plitzi page import <url>` | a page the user owns, as a start: tokens, its blocks' layout, lists as `data/*.json` — never the words. **Only when the user asks**; a site not on this machine needs `--account`: ask first |
+| `shot -- /path --width 390 --scheme dark` | a picture of one page — `--clip <element>` one element, `--frames 4` what moves, `--compare <url>` what differs from another site |
+| `visual` | a browser asserts every element the space names is visible |
+| `typecheck`, `lint`, `format` | before calling a change done |
+
+**Which port.** `start` takes 8080, or the next free one — printed, and written to `tmp/dev-server.json` for `check`,
+`shot` and `visual`. `PORT` chooses one (a taken one is then an error). `/health` answers with the space's name.
+
+Data with no backend, server mode: `src/data/*.json`, never served — a provider with `runtime: 'server'` and `query:
+'/data/x.json'` reads it on the server. Client mode: `public/data/`, fetched — public. Learn a file's fields with
+`data describe`, never by reading it.
+
+**`public/` is on the internet**: never a secret there. `tmp/`, `state/` (its `kv`) ignored; `.plitzi/` committed.
+`--dry-run` on a command that writes or sends says what it would do, and does none of it.
+
+A local space starts as a tour of the platform with a plugin of the project's own; **`--template blank`** as tokens, a
+layout and one empty page — for a project about to be a specific site; **`--template catalog`** as a small shop
+(layout, card component, data in `src/data`, a filtered list, a page per product), a file per part — the one to read
+when unsure how a whole site is put together.
+
+The space itself is written with `@plitzi/sdk-authoring` — see the `plitzi-authoring` skill, which `create` copies into
+`.claude/skills/` beside this one.

package/skills/plitzi-cli/reference/troubleshooting.md

@@ -0,0 +1,12 @@
+# When something does not work
+
+| What you see | What it is |
+| --- | --- |
+| `create` printed questions and wrote nothing | nobody answered the three choices — ask the user, pass them as flags |
+| `start` says the port is in use | `PORT` is set to a taken port — unset it to take the next free one, or choose another |
+| A page that is not this project's, or `page shot` refuses the port | another server answers there — `curl 127.0.0.1:<port>/health` names it; `tmp/dev-server.json` has this project's port |
+| "Custom Component … Not Found", or a flow on a plugin's event never runs | `doctor` names the folder whose type or declaration is off |
+| "not laid out as Plitzi reads it" | each misplaced part, with its fix; `doctor --fix` |
+| `upload` opens a browser | there is no session, or no space chosen — the person completes it there |
+| The upload went to the wrong space | `plitzi space use` chooses another; check `whoami` first |
+| `space pull` wrote nothing and named files | they changed here and on the space — set your changes aside and pull again, or `--force` |