@plume-press/cli 0.6.0 → 0.7.0

package/README.md

@@ -1,3 +1,46 @@
 # @plume-press/cli
 
-Use Node 22.13 or newer. Run `npx plume init` in your website directory: it creates `plume.schema.ts` and a local CMS, and adds the Plume SDK to package.json. Run `npx plume local schema` after editing collection definitions. Import `defineSchema` from `@plume-press/cli/schema` in `plume.schema.ts`. Make your build script `plume build -- <your build command>`: it checks the committed `plume.lock` with Plume (`PLUME_ENDPOINT`, default `https://app.plume.press`; no token; the same command builds production and your host's preview deployments) and writes `.plume/binding.json` for the SDK before your build runs. Run `npx plume --help` for every command.
+Use Node.js 22.13 or newer. Install the scoped package in your website project before using its plume command. These examples use npm; keep your project's chosen package manager.
+
+```sh
+npm install --save-dev @plume-press/cli@0.7.0
+npx plume init --check
+npx plume --help
+```
+
+## Inspect and start locally
+
+init --check returns offline JSON facts and next actions for a root Next.js or Astro integration. It reads declarations, file presence and environment example names, without running schema/configuration code, reading .env values, writing files, installing packages or contacting Plume. Presence is not proof that runtime, builds or pages work.
+
+```sh
+npx plume init
+npm install
+```
+
+init creates an account-free local CMS, an empty plume.schema.ts when missing, and discoverable .agents/skills/plume-local/SKILL.md and .agents/skills/plume-integration/SKILL.md guides. It preserves existing schema, records, chosen package versions and custom Skills. It adds missing SDK/CLI dependencies to package.json but does not install them; run your package-manager install afterward. A hosted checkout with plume.lock is refused by init; init --check can inspect it.
+
+Import defineSchema from @plume-press/cli/schema, then run npx plume local schema after safe schema additions. Local record commands take JSON on stdin; npx plume --help explains them. Local content is not a publication; local media uploads and destructive schema migrations are unsupported.
+
+## Connect and integrate pages
+
+npx plume connect opens browser approval for a Site Admin and asks for transfer confirmation in the terminal. One-time local-content transfer needs a published schema-only Update and plume.lock, an untouched hosted content store, no open Updates and no active writer. It supports at most 100 records/1 MiB of content JSON and rejects media. Follow the printed git pull --ff-only command after a transfer.
+
+A successful connection saves nonsecret Site/editor URL facts in Git-ignored .plume/site.json and creates the integration Skill only if absent. Ask your repository agent to use that guide to wire actual Next.js/Astro pages into existing components and verify them. It distinguishes private session preview, fixed prepared/static bindings and explicitly selected public SSR latest once per request. It does not scaffold arbitrary frameworks, configure deploy hooks, publish changes or certify the website.
+
+## Check a connected build
+
+Use plume build -- <your existing framework build command> in the build script. The wrapper checks the committed plume.lock and matching plume.schema.ts against the sealed content version, writes .plume/binding.json, then runs the framework. It performs no publication. PLUME_ENDPOINT defaults to https://app.plume.press; build validation needs no token. The same fixed binding can build a prepared host preview or production artifact. Schema files execute locally as trusted framework configuration does.
+
+## Export a Site
+
+A Site Admin can prepare a one-hour private export authorization in Plume: Settings → Repository → Export content and Media. Export works without Git or a build. Keep the downloaded authorization file private and run:
+
+```sh
+npx plume export --authorization ./plume-export.json --out ./site-export.zip
+```
+
+The ZIP captures the Published schema and raw Items/Singletons (including Hidden and incomplete Items), plus every current Site storage object at the captured cutoff, including unused uploads. Open Updates, historical revisions, private previews and operational data are excluded. External links/embeds remain links. The authorization endpoint must match PLUME_ENDPOINT (default https://app.plume.press).
+
+The authorization token stays out of arguments and the ZIP. Redirects, changed/missing source assets, expired authorization and interrupted transfers fail; only a complete ZIP becomes the requested output, and existing files/symlinks are never overwritten. The manifest records completion, source, observation interval and checksums; media.jsonl maps original keys/IDs to safe storage paths.
+
+The archive includes a local loader example for an agent to adapt your existing components. Keep raw export data private and filter Hidden Items from public rendering. Export does not rewrite or publish the repository, and is not a static-publication SDK.