konpeki 0.3.0 → 0.4.0

package/SETUP.md

@@ -1,147 +1,83 @@
-# Set up Konpeki for your coding agent
+# Set up Konpeki
 
-Install the `konpeki` skill once, then give your agent a creation brief:
+Use Node.js 24+ and the matching Konpeki 0.4.0 runtime and skill. A repository
+version or locally packed tarball does not establish that the npm release exists.
 
-```text
-Use Konpeki to turn these launch notes into a product announcement.
-```
-
-Opening and inspecting the editable preview is part of the skill, not an extra
-instruction the person has to remember. Covers, social graphics, charts,
-diagrams and presentations use the same workflow. Keep the brief and revisions
-in agent chat; the browser edits, reviews, presents and exports the document.
-Konpeki supplies no hosted AI service or additional model subscription.
-
-## 1. Install the skill or plugin
+## npm package
 
-Use the host's skill installer to install the complete
-[`skills/konpeki`](skills/konpeki/) directory from
-`vcfgdev/konpeki`. Keep its `scripts/` and `assets/` directories. In Codex, ask the skill installer:
+Check the exact version before installing:
 
-```text
-Install the konpeki skill from vcfgdev/konpeki, at skills/konpeki.
+```sh
+npm view konpeki@0.4.0 version
 ```
 
-Other agents may use another installer or skill location. Follow their documented
-mechanism; there is no universal slash command. If a host does not discover skills,
-read the installed `SKILL.md` directly. Do not overwrite existing agent guidance.
-
-If you previously installed `authoring-visuals`, replace that installed skill
-with `konpeki` rather than keeping both copies. The runtime package is unchanged.
-
-### Choose init or generate
-
-| Mode | Codex CLI / IDE | Claude Code standalone skill |
-| --- | --- | --- |
-| Open the editor without generating | `$konpeki init [composition.json]` | `/konpeki init [composition.json]` |
-| Create or revise from your materials | `$konpeki generate [brief]` | `/konpeki generate [brief]` |
-
-`generate` automatically prepares the runtime when needed. It uses materials
-already supplied in chat, referenced files and the current canvas; it does not
-require `init` first or a repeated brief. Natural-language “Use Konpeki to…”
-creation requests also select generate. Follow-up feedback continues the same
-document without another command. Other GUIs may use skill selection, and plugin
-installations may namespace the skill. These modes are not terminal subcommands.
-
-For `init`, choose the supplied path or the document already active in the
-conversation; otherwise use `slides/untitled/composition.json`. After resolving
-the runtime below, run:
+If it returns `0.4.0`, install in the workspace that will author your documents:
 
 ```sh
-node "<installed-skill>/scripts/prepare-document.mjs" "<cli>" "<composition.json>"
-node "<cli>" preview "<composition.json>"
+npm install --save-exact konpeki@0.4.0
+npx --no-install konpeki browser install
 ```
 
-The helper validates existing files without rewriting them. For a missing file,
-it validates and writes the bundled blank document without overwriting a file
-created concurrently. Invalid data is preserved, not replaced with a sample.
-Reuse an already running preview for the same file. Open and verify its exact
-session URL as described below, then stop: init does not generate or start a
-review listener. The starter works with the pinned published runtime; it does
-not import TypeScript from `node_modules` or require an unreleased `init` CLI.
+Run commands with `npx --no-install konpeki`. If the version is unavailable, use
+one of the local paths below; do not substitute the incompatible 0.3.x runtime.
 
-### Optional Codex plugin packaging
+## Source checkout
 
-The root `plugin.json` packages that same skill, without MCP servers, hooks or
-credentials. `.agents/plugins/marketplace.json` exposes it as a repo marketplace.
-On a compatible Codex client, add the repository marketplace with:
+With [mise](https://mise.jdx.dev/) installed, use the pinned toolchain:
 
 ```sh
-codex plugin marketplace add vcfgdev/konpeki
+git clone https://github.com/vcfgdev/konpeki.git
+cd konpeki
+mise trust
+mise install
+mise exec -- pnpm install --frozen-lockfile
+mise exec -- node bin/konpeki.mjs browser install
 ```
 
-Then install Konpeki from that source in the desktop plugin directory and test it
-in a new conversation. Install either the standalone skill or the plugin, not
-both. This is repository distribution, not a listing in OpenAI's public directory.
-It becomes available from the remote repository after these files are published.
-Native Codex GUI installation needs a separate client smoke test; package checks
-alone do not establish host compatibility.
+The browser is needed for inspection and export, not preview or artifact viewing.
+On minimal Linux hosts, its system libraries may require administrator-approved
+installation with `mise exec -- pnpm exec playwright install-deps chromium`.
 
-## 2. Let the skill prepare the runtime
+Run the checkout CLI as `mise exec -- node bin/konpeki.mjs`. The authoring loop
+is in the [skill](skills/konpeki/SKILL.md); CLI rules are in
+[html/README.md](html/README.md).
 
-Check Node.js 24+, npm, command/file access and the host's browser capabilities.
-Follow host approval and toolchain rules if prerequisites are missing.
+## Local tarball
 
-From the user's document workspace, run:
+From a prepared trusted checkout, build and pack without publishing:
 
 ```sh
-node "<installed-skill>/scripts/ensure-runtime.mjs"
+mise exec -- pnpm install --frozen-lockfile
+mise exec -- pnpm pack
 ```
 
-The script reuses a compatible workspace installation, surrounding Konpeki
-checkout, or cached runtime. If none exists, obtain any required host approval
-and rerun with `--install`. It installs the pinned `konpeki@0.3.0` release in a
-user cache, without adding project dependencies or changing project guidance.
-Missing/incompatible runtimes are never reported ready. The script prints JSON
-with `root`, `cli` and `version`; installation diagnostics go to stderr.
+Install the resulting `.tgz` by local path in the workspace that will author the
+document, for example `npm install --no-save /path/to/konpeki-0.4.0.tgz`. This is
+a local package install, not evidence of an npm release. Run its CLI with
+`npx --no-install konpeki` and install its browser before inspection or export.
 
-Use the returned absolute `root` for resources and `cli` for commands. Do not rely
-on repo-relative paths from a copied skill. Keep documents outside the runtime.
-For manual project-local npm installation, see [Manual npm start](README.md#manual-npm-start).
-Repository contributors instead use the [mise setup](docs/development.md); users
-of the published package do not need mise.
+## Skill helpers
 
-## 3. Generate, validate and open the visual
-
-Follow the installed skill and the runtime's `AUTHORING.md`, composition contract
-and design resources. Use the brief already supplied; ask only for information
-needed for faithful work. Do not ask the person to repeat their prompt in the
-canvas. Continue the current document when revising or following init. Save new
-work to an unused `slides/<name>/composition.json`, with brief/source notes,
-unless the person chooses another destination. Preserve existing documents.
-
-For an installation check, validate the bundled example:
+Install the authoring skill separately:
 
 ```sh
-node "<cli>" validate "<root>/slides/introducing-konpeki/composition.json"
+npx skills add vcfgdev/konpeki -g
 ```
 
-After authoring the user's document:
+`ensure-runtime.mjs` takes no arguments. It discovers either the containing
+checkout or a compatible locally installed `konpeki` package and prints its CLI
+location; it does not download or modify a runtime.
+
+`prepare-document.mjs` takes `<cli> <document.html>`. It creates the starter HTML,
+`theme.css`, and `theme-base.css` beside the document. It validates the result
+and never overwrites existing files. The default theme loads IBM Plex Sans and
+Mono from Google Fonts, so preview and export need network access. For offline
+rendering, adapt the document's theme to use licensed local or embedded fonts.
 
 ```sh
-node "<cli>" validate "slides/<name>/composition.json"
-node "<cli>" preview "slides/<name>/composition.json"
+node node_modules/konpeki/skills/konpeki/scripts/prepare-document.mjs node_modules/konpeki/runtime/konpeki.mjs document.html
 ```
 
-Reuse an existing preview for that file when available. Keep the process running
-using the host's supported service mechanism. Open the exact printed session URL
-in the in-app browser when supported, otherwise the regular browser. Preserve its
-query string and never publish its capability token. In remote workspaces, use
-authenticated preview/port forwarding, not a remote loopback address.
-
-Verify that the browser loads the intended document, then render, inspect and
-repair the result as directed by the skill. The file-backed canvas saves browser
-edits to that document and loads valid external edits. Setup is complete when
-validation succeeds and the intended composition opens—not merely when a server
-process starts. If browser inspection is unavailable, report that limitation.
-
-Return the document path, usable preview link and verification outcome. Continue
-revisions in agent chat. For submitted canvas reviews, generate checks `request`,
-claims a `submitted` request with `wait`, applies the notes against the latest
-document, and acknowledges it with `finish` only after validation and inspection.
-Coordinate ownership before resuming an already `working` request.
-
-An ongoing listener runs only when explicitly requested and supported by the host.
-Otherwise, use **Copy prompt** after **Build it**, or resume generate in agent chat.
-The [canvas workflow](docs/workflow.md) describes this handoff; the button cannot
-wake an idle agent, and an open preview is not a live agent connection.
+From a source checkout, use
+`mise exec -- node skills/konpeki/scripts/prepare-document.mjs bin/konpeki.mjs document.html`.
+See [Upgrading from 0.3.x](README.md#upgrading-from-03x) before migrating old work.

package/docs/development.md

@@ -1,257 +1,52 @@
 # Development
 
-Clone `https://github.com/vcfgdev/konpeki.git` with the required repository access.
-Use [mise](https://mise.jdx.dev/getting-started.html) to install the Node.js and
-pnpm versions pinned in `mise.toml`. On macOS, install mise with `brew install mise`.
-From the repository root:
+Use the versions pinned by `mise.toml`, run commands through `mise exec --`, and
+preserve `pnpm-lock.yaml`.
 
-```sh
-mise trust
-mise install
-mise exec -- pnpm install --frozen-lockfile
-```
-
-Mise manages the toolchain; pnpm manages dependencies through `pnpm-lock.yaml`.
-Run the commands below from that repository root with an activated mise shell,
-or prefix them with `mise exec --` (for example, `mise exec -- pnpm test`).
-No global Node.js or pnpm installation is required. npm for packing and publishing
-comes with the pinned Node.js; use `mise exec -- npm pack` to select it explicitly.
-
-Development and regression checks require a repository checkout, not an npm
-tarball, which excludes tests and review scripts.
-
-## Development server and demo hosting
-
-```sh
-pnpm dev
-```
-
-For a production preview, run `pnpm build` then `pnpm preview`. The build produces
-a static site in `dist` for a root or subdirectory. Use
-`?example=introducing-konpeki` or `?example=custom-visual` to open a bundled editable
-example. Each example has an isolated browser-local working copy that survives
-reload. The Browser menu supports JSON import/download, starting blank and
-resetting the example. These actions never replace another example or the normal
-local draft. Invalid stored data remains untouched until an explicit reset.
-
-Deploy only the static `dist` output for the public playground, not a file-session
-server. Imported documents stay in that browser; there is no account, cloud sync,
-AI generation or Build/notes handoff in standalone mode. Downloaded JSON can be
-opened in a file-backed session with a coding agent. Browser storage is not a
-backup. Hosting shares bundled examples, not private drafts or an AI service.
-No deployment is automatic. In a remote environment, expose a review server
-through its authenticated preview mechanism, not a loopback address.
-
-The source CLI's `preview` chooses the next available port if its default is
-occupied. An explicit `--port <number>` fails rather than silently changing the
-requested port; `--port 0` asks the OS for a free port. `--json` prints one readiness
-record with `type`, `compositionPath` and the exact session-bearing `url` after
-listening. Treat that URL as a capability, not public logging data. This is a
-startup signal, not proof that the browser loaded the right composition.
+## Architecture
 
-### GitHub Pages
-
-The public playground is hosted at
-[vcfgdev.github.io/konpeki](https://vcfgdev.github.io/konpeki/?example=introducing-konpeki).
-The example query opens the introduction; the root URL opens the ordinary local
-draft. Each visitor's edits stay in their own browser, not in the deployed site.
-
-`.github/workflows/pages.yml` deploys only when explicitly dispatched on `main`:
-
-```sh
-gh workflow run pages.yml --repo vcfgdev/konpeki --ref main
-```
-
-The workflow uses the pinned mise/pnpm toolchain, runs typecheck and tests, builds
-with the Pages base path, and uploads only `dist`. The deployment job publishes
-that artifact to the `github-pages` environment. Repository **Settings → Pages →
-Source** must be **GitHub Actions**. Ordinary pushes run CI but do not redeploy;
-package releases remain separate. Inspect the public example after deployment,
-including reload, fonts, editing, JSON download and Present.
-
-Existing example working copies survive deployments. Download any edits before
-choosing **Browser → Reset example** to load a newly published example.
-
-## Skill and plugin packaging
-
-`skills/konpeki/` is the canonical portable skill. The repo's
-`.agents/skills/konpeki` symlink enables local discovery without a second
-copy. The root Agent Plugins `plugin.json` and repo marketplace expose the same
-skill to compatible Codex clients; no MCP, hook or hosted AI is involved. Review
-native-client installation separately from the npm smoke test.
-
-The skill dispatches `init` (open only) and `generate` (create/revise, including
-implicit setup). These are agent modes, not CLI subcommands. Its portable
-`scripts/prepare-document.mjs` validates through the resolved CLI and exclusively
-creates a blank file, or validates an existing file without rewriting it. The
-bundled `assets/blank.json` matches `initialDraft(true)` in
-`composition/document.ts`; onboarding tests enforce that contract. Keep scripts
-and assets when copying the skill. No TypeScript import from `node_modules` is
-needed, so a copied skill also supports the existing published runtime.
-
-Its `scripts/ensure-runtime.mjs` pins the release runtime. It performs
-no installation without `--install`, and never updates project dependencies.
-When preparing a new release, deliberately update its pin and the plugin version
-together with the package version after testing the target runtime. The current
-pin is 0.3.0; local CLI/playground changes do not republish that npm version.
-
-## Implementation reference
-
-- `src/` contains the shared canvas application for editing and presentation.
-  The [versioned composition contract](../composition/README.md) preserves
-  content, relationships and visual intent across human and agent revisions.
-- `bin/` contains the file-session CLI and its revision-checked persistence.
-- [AUTHORING.md](../AUTHORING.md) owns design defaults, factual fidelity and review.
-  [Design resources](../design/README.md) provide palettes, themes and semantic
-  patterns; these are choices, not mandatory layouts.
-- `lib/text.tsx` supplies measured `Text` and `Paragraphs` with string or rich-text
-  runs. Overset content is flagged, not automatically shrunk or hidden. Await
-  `fontsReady` from `lib/typeface.ts` before measuring.
-- `lib/slide.tsx` supplies specimen `Panel`, `Relationship` and 1920×1080 `Sheet`
-  components. `Panel` shares one heading/body size; `Relationship` is a short
-  directional glyph. Convert their SVG output to composition vectors for the canvas.
-- `lib/layouts.ts` supplies fixed-gutter regions, not a content-fitting solver.
-- Retained React chart references use Nivo `Bar`, `Line` and `Sankey` with
-  `chartDefaults(palette)` from `lib/charts.ts` spread before chart-specific props.
-  Keep data, dimensions, scales and semantic colors in the deck. Use explicit
-  label colors and `linkBlendMode="normal"` for Sankey.
-
-### React/SVG drawing references
-
-The retained `slides/*/index.tsx` files are presentation-runtime-independent
-drawing references. They are checked as source but are not discovered as routes
-or executed by a second presentation runtime. New decks use composition JSON;
-a trusted build may render React to SVG, then convert supported elements into
-the owning component's editable vector payload.
-
-To migrate the retained architecture reference into the shared canvas:
-
-```sh
-pnpm example:migrate-page slides/architecture/index.tsx all /tmp/architecture-composition.json
-```
+Static HTML and CSS are the only document source. `html/source.ts` validates and
+revises source, `html/server.ts` exposes the authenticated preview and local
+assets, and `html/browser.ts` uses Playwright for inspection and PNG/PDF export.
+The React preview UI lives in `html/preview.tsx`; its small shared board,
+alignment, positioning, and style modules live under `src/`.
 
-Drag the resulting JSON onto the canvas, edit its vectors, and use **Present**.
-Replace `all` with a zero-based page index for one page. This command executes
-trusted local React source; never use it on untrusted JSX. It rejects unsupported
-SVG elements rather than silently flattening them. Review converted typography
-and geometry in the browser; conversion is not a fidelity guarantee.
-The bundled `?example=react-page-migration` preview uses the same format.
-Its working copy autosaves in that browser. Download JSON or use a file-backed
-session to retain edits outside browser storage.
-
-## Package contents
-
-`package.json` explicitly allowlists the npm payload: the source-based Vite
-runtime and file-session CLI, authoring guidance and design resources, and named
-curated examples with editable source and prompts. New example directories are
-not included automatically. Gallery screenshots, tests, research fixtures,
-browser review scripts, original branding assets, lockfiles and UI build output
-stay in the repository.
-
-`npm pack` builds the JavaScript CLI in `runtime/` automatically because Node
-cannot load its TypeScript source from inside `node_modules`. That generated
-CLI is included in the package.
-
-Run `pnpm check:package` before preparing a release. It checks npm's file selection,
-required resources, excluded development files and relative imports. For an
-installation smoke test, use `npm pack --pack-destination <temporary-dir>`, install
-the tarball in an empty project, then run its `konpeki validate` and `konpeki preview`
-commands against a composition outside the installed package. Do not publish
-until that isolated preview works. Publish the tested tarball rather than
-rebuilding during publication. Packing locally does not publish anything.
-
-## Tag releases
-
-`.github/workflows/publish.yml` stages releases on bare version tags such as `0.2.1`
-(no `v` prefix). The tag must equal `package.json`'s version.
-The workflow installs the mise toolchain and frozen dependencies, runs typecheck,
-tests, build and package checks, then installs a tarball in an isolated directory
-to validate a composition and build the packaged canvas. It stages that same
-tarball for maintainer approval; it does not publish directly. Browser review
-remains a pre-release responsibility.
-
-Before the first tag release, configure **Trusted publishing → GitHub Actions**
-in the `konpeki` package settings on npmjs.com:
-
-- Organization or user: `vcfgdev`
-- Repository: `konpeki`
-- Workflow filename: `publish.yml`
-- Environment name: leave empty
-- Leave **Allow npm publish** unchecked (staged publishing only)
-
-The workflow uses GitHub-hosted runners and OIDC (`id-token: write`); no npm
-token secret is needed. Staged publishing requires npm 11.15.0 or newer and
-Node 22.14.0 or newer; the pinned toolchain meets both requirements.
-npm generates provenance automatically for public repositories;
-private repositories do not receive provenance.
-
-After updating the package version, completing release checks and pushing the
-release commit, explicitly create and push its matching tag:
-
-```sh
-VERSION=0.2.1
-git tag "$VERSION"
-git push origin "$VERSION"
-```
-
-Replace `0.2.1` with the version in `package.json`. Published versions cannot be
-republished. Pushing a matching tag submits the tested package to npm's staging
-area. After the workflow succeeds, review the release in npmjs.com's **Staged
-Packages** tab and click **Approve**, completing 2FA to publish it. Alternatively,
-use an authenticated local CLI:
-
-```sh
-mise exec -- npm stage list konpeki
-mise exec -- npm stage view <stage-id>
-mise exec -- npm stage approve <stage-id>
-```
-
-Approval makes the version public. Reject an incorrect staged release instead
-of approving it (`npm stage reject <stage-id>`).
+`bin/konpeki.mjs` is the HTML-only CLI entry. `scripts/build-cli.mjs` bundles it
+to `runtime/konpeki.mjs` so npm consumers can run it without TypeScript support.
 
 ## Verification
 
 ```sh
-pnpm check
-pnpm test
-pnpm build
-pnpm check:package
-```
-
-With the dev server running and `agent-browser` installed:
-
-```sh
-node scripts/check-canvas.mjs http://localhost:4318 .amp/in/artifacts
-node scripts/check-pages.mjs http://localhost:4318 .amp/in/artifacts/pages
-```
-
-For the Build it lifecycle, `node scripts/check-build.mjs` starts its own
-disposable file session. It checks pending requests, agent refresh, failure
-recovery and reduced motion, and captures the affected states. Add an output
-directory and `--record` to also record the animation.
-
-`node scripts/check-notes.mjs` checks page/vector note scopes, draft isolation,
-reload persistence, CLI claim/finish, clarification and cancellation in a disposable
-file-backed browser session. It accepts a screenshot directory as its first argument.
-
-These checks exercise all five component kinds, empty slides, JSON round trips,
-vector editing/history and fitted line dragging. They capture editor and
-presentation states at two sizes; inspect the images because assertions alone
-do not establish visual correctness.
-
-Documentation changes need link and instruction checks. Deck changes need
-typecheck, build, relevant fixture checks and actual visual inspection. Shared
-component, theme or dependency changes also need the full test suite and
-representative affected decks. A build can report a large-framework-chunk advisory.
-
-Render affected pages at presentation and review sizes after fonts load. Inspect
-text, clipping, relationships, contrast and cross-page consistency. Repair issues
-and inspect fresh captures. Keep browser checks scoped to factual and layout
-contracts, not universal taste. Record untested outputs and limitations with
-the example; screenshots do not prove PDF/PPTX or cross-application fidelity.
-
-When adding examples, preserve the exact creative requests, editable source,
-source facts and reviewed images as described in [AUTHORING.md](../AUTHORING.md).
-Examples demonstrate capabilities; there is no separate benchmark suite or
-aesthetic score. Check font language subsets and license notices when
-redistributing assets; dependencies retain their own licenses.
+mise exec -- pnpm install --frozen-lockfile
+mise exec -- pnpm exec playwright install chromium
+mise exec -- pnpm check
+mise exec -- pnpm test
+mise exec -- pnpm build
+mise exec -- pnpm check:package
+mise exec -- pnpm audit --prod
+```
+
+Before a release, install the generated tarball in a disposable directory and
+exercise runtime discovery, starter preparation, HTML validation, inspection,
+PNG/PDF export, and preview. Audit the installed package too: npm consumers can
+resolve dependencies differently from the repository lockfile. Exercise the
+preview's comment and copy-and-clear flow from that installation, not only a
+source checkout.
+
+## Release
+
+1. Finish the verification above and commit the exact release candidate. Keep
+   `package.json`, `plugin.json` and the skill's runtime version aligned. Describe
+   breaking changes in the README's upgrade section and the release notes.
+2. Obtain explicit approval before pushing or tagging. The release tag must
+   exactly match the package version (`0.4.0`, not `v0.4.0`).
+3. Pushing the approved tag starts **Stage package release**. It checks the code,
+   installs and exercises the tarball, then stages that tarball on npm. A green
+   workflow means staged, not published.
+4. The maintainer reviews and approves the staged package through npm's approval
+   flow. Verify the published version with `npm view konpeki@0.4.0 version` and
+   smoke-test a registry installation before announcing availability.
+
+GitHub release creation and the manual Pages deployment are separate actions;
+neither is authorized by permission to push a tag. Never publish, push, deploy,
+or tag without explicit permission for that action.

package/docs/workflow.md

@@ -1,110 +1,8 @@
-# Canvas workflow
+# Workflow
 
-Start with [Use with your agent](../README.md#use-with-your-agent) and give your
-coding agent a brief in its prompt field. Install the complete skill directory;
-its bootstrap script finds or installs the runtime separately. Skill discovery
-varies by agent: Codex CLI/IDE uses `$konpeki`, while the standalone Claude Code
-skill uses `/konpeki`. Other clients may use skill selection or natural language.
-`init` opens a blank or existing file-backed editor without generating; `generate`
-creates or revises a visual, opens its preview and inspects it, with setup implicit.
-A creation brief without a mode selects generate. Follow-up reviews continue the
-same document without repeating a command. These are skill modes, not terminal
-subcommands. **Build it** is an optional revision handoff, not a required first-run
-step; opening the editor does not start a review listener.
+The canonical authoring and revision loop lives in the
+[Konpeki skill](../skills/konpeki/SKILL.md).
 
-## Documents and exports
-
-New documents live in `slides/<name>/composition.json`, with `PROMPT.md`, source
-notes and reviewed images alongside. Keep the editable composition under version
-control. The canvas is the source of truth for editing and presentation; download
-its JSON for handoff and drag returned JSON onto the canvas to continue.
-
-One page is a complete creation. Presets cover Presentation (1920×1080), Square
-post (1080×1080), Portrait post (1080×1350), Link preview / OG (1200×630), and
-Article header (1600×600). The document contract supports 256–4096 pixels per side.
-Pages in one document may use different sizes. Changing size never stretches
-content and is refused when existing components would fall outside the page.
-Recompose for a new aspect ratio instead of stretching or cropping.
-
-**Export PNG** saves the active page at its declared dimensions without editor
-controls. JSON remains the editable source; PNG is an image. Fresh documents and
-added pages are empty. **Present** uses the same renderer for any page sequence.
-
-Standard Chart, Diagram and Table illustrations are structural drafts. Finished
-artwork can remain owned by its semantic component as editable vector elements.
-Retained React/SVG examples are drawing references, not another deck runtime.
-
-## File-backed editing with an agent
-
-The CLI interface is `konpeki <command>`. After local installation, use
-`npm exec --no -- konpeki <command>` from your workspace. In a repository checkout,
-use the development shim `pnpm konpeki <command>` instead:
-
-```sh
-npm exec --no -- konpeki validate slides/my-visual/composition.json
-npm exec --no -- konpeki preview slides/my-visual/composition.json
-```
-
-`preview` prints a capability-bearing local URL. Open that exact URL. Valid
-browser edits are saved atomically to the composition file; a revision hash
-prevents overwriting concurrent external changes. When an agent updates the same
-file, the canvas loads the valid revision and keeps the previous document in Undo.
-
-An agent waiting for a person's revision request runs:
-
-```sh
-npm exec --no -- konpeki wait slides/my-visual/composition.json
-```
-
-In the file-backed canvas, select a component or an inner vector element and
-write a **Revision note** in the left panel's **Notes** tab. With nothing selected, the note targets
-the page. **Add note** saves feedback without starting a build; add notes to several
-targets, then choose **Build it** to submit them together. Numbered canvas pins
-return to their note and selection. Pins and notes never appear in presentations
-or PNG exports. Direct text, geometry and attribute edits still save normally.
-
-**Build it** saves the composition and submits its exact revision, selected page,
-component and optional vector-element ID, plus all unresolved notes. Without notes,
-it requests a build from the saved composition and selected scope as before.
-`wait` atomically claims one submitted request, marks it working, prints the
-machine-readable v2 request and exits. It does not launch or wake an agent.
-Until claimed, the canvas asks you to contact your coding agent and offers
-**Copy prompt** for the handoff. “Agent working” means claimed, not a live
-agent heartbeat. Only one request per document can be active. Connection errors
-keep an active request locked until completion or cancellation.
-
-The agent must reread the named composition and preserve newer human edits.
-Follow each note's target IDs, not just the active page; never silently retarget
-a deleted element. After validating, rendering and inspecting all requested
-changes, explicitly finish using the ID returned by `wait`:
-
-```sh
-npm exec --no -- konpeki finish slides/my-visual/composition.json <request-id> --message "Updated and checked"
-```
-
-Only this acknowledgement resolves the submitted notes and unlocks editing.
-File changes alone do not complete the request; explicit no-op completion is
-valid when the requested result is already present. If blocked, finish with
-`--status needs-clarification --message "What needs clarification?"` or
-`--status failed --message "What failed"`. Notes stay unresolved for a retry.
-Do not mark a partly applied batch done. **Cancel request** unlocks the editor
-and keeps notes, but cannot stop an agent process; stop that agent before retrying.
-
-Feedback is stored next to the document as `composition.json.review.json`, separate
-from artwork and exports. Retain that file with the composition when moving work.
-Browser reloads and preview restarts preserve notes and request status. To inspect
-or recover an already claimed request after an interruption, run:
-
-```sh
-npm exec --no -- konpeki request slides/my-visual/composition.json
-```
-
-Coordinate with the previous worker before resuming; `wait` does not claim an
-already working request a second time. Do not edit the sidecar manually while a
-preview or agent is updating it. Existing v1 temporary requests are not migrated;
-finish them before upgrading, then resubmit if needed. Browser-local drafts and
-hosted examples do not expose revision notes or **Build it** because no local
-agent owns their files.
-
-Browser screenshots do not establish PDF/PPTX editability, font embedding or
-cross-application fidelity. Inspect every requested export separately.
+Use the [HTML, files, theme, and CLI reference](../html/README.md) for document
+rules and tool behavior, the [authoring floor](../skills/konpeki/floor.md) for
+bans and the review checklist, and [AUTHORING.md](../AUTHORING.md) for judgment.