konpeki 0.3.1 → 0.4.0

package/README.md

@@ -1,124 +1,116 @@
-![Konpeki — Create clear visuals with your coding agent](slides/github-cover/cover.png)
+# Konpeki
+
+Konpeki helps a coding agent turn a brief and source material into finished
+visuals: covers, social graphics, diagrams, charts, explainers, documents, and
+presentations. Ordinary HTML and CSS are the editable source. Konpeki validates
+that source, inspects the rendered pages, opens a review preview, and exports PNG
+or PDF.
+
+PNG and PDF are the delivery artifacts; recipients do not need Konpeki,
+Playwright, or Chromium to view them. Konpeki requires no account or hosted AI
+service. Your coding agent's pricing and data handling still apply.
+
+## How it works
+
+The [Konpeki skill](skills/konpeki/SKILL.md) owns the authoring workflow. The
+agent reads shared guidance, the matching [output guide](skills/konpeki/SKILL.md#choose-the-output-guide),
+and relevant content patterns. Guides cover landscape slides, résumés, multi-page
+documents, one-pagers/cards, and covers/social graphics without imposing fixed
+layouts. The agent writes static HTML with fixed-size pages, then repeats a
+short loop until the pages are sound:
+
+1. `validate` checks the source contract: explicit pages, stable IDs, local
+   resources, and no scripts.
+2. `inspect` renders the pages in the pinned Chromium and reports overflow,
+   clipping, text overlap, low contrast, small text, font fallback, theme
+   compliance, and [authoring floor](skills/konpeki/floor.md) rules as JSON.
+3. `render` exports a page or document and prints the review checklist for the
+   judgment calls no check covers. It refuses to write output while errors
+   remain and never overwrites an existing file.
+
+`preview` opens a local board where a person can comment on elements and make
+small source-backed moves, then copy that feedback back to the agent.
+
+Automated checks do not establish factual correctness or visual quality. Supply
+the facts and approved assets; examples and placeholders are not evidence about
+real products.
+
+## Quick start
+
+Use Node.js 24+ and install the exact version in your document workspace.
+Check availability with `npm view konpeki@0.4.0 version`; if the registry does not
+have it, use a [source checkout or local tarball](SETUP.md) instead. The 0.3.x
+runtime is incompatible with this workflow.
 
-**Create clear visuals with your coding agent.** Konpeki is an opinionated design
-framework for covers, social graphics, visual explanations and presentations.
-
-Give your coding agent notes, source material and a brief. Konpeki provides the
-canvas, design guidance, typography and semantic components for the intended
-format and dimensions.
+```sh
+npm install --save-exact konpeki@0.4.0
+npx --no-install konpeki browser install
+```
 
-People and agents edit the same composition. Export a page as PNG, download its
-editable JSON, or use **Present** for a chrome-free presentation.
+Create a starter with its theme beside it, then run the loop:
 
-## Use with your agent
+```sh
+node node_modules/konpeki/skills/konpeki/scripts/prepare-document.mjs node_modules/konpeki/runtime/konpeki.mjs work/document.html
+npx --no-install konpeki validate work/document.html
+npx --no-install konpeki inspect work/document.html
+npx --no-install konpeki render work/document.html --page 1 --format png --scale 2 --output work/page-1.png
+npx --no-install konpeki render work/document.html --format pdf --output work/document.pdf
+npx --no-install konpeki preview work/document.html
+```
 
-Requires **Node.js 24+**, npm, a coding agent that can edit files and run commands,
-and a browser.
+The browser is needed for `inspect`, `check` and `render`, not for `preview`. On
+minimal Linux hosts, Chromium may need system libraries; see [SETUP.md](SETUP.md).
 
-Install once, choosing your agent when prompted:
+To let your coding agent do the authoring, install the skill separately:
 
 ```sh
 npx skills add vcfgdev/konpeki -g
 ```
 
-Start a new conversation or reload your agent's skills. **Send this to your agent:**
-
-> Use Konpeki to create a one-page explainer of how a browser, API and database work together.
-
-Replace the example with your own brief and materials. Your agent prepares the
-runtime, creates editable JSON in your workspace, opens the canvas and checks the
-result. No clone or separate `init` step. First use may require installation and
-browser permissions; remote workspaces need authenticated preview forwarding.
-
-Keep revisions in the same conversation. Canvas notes use **Build it** and its
-copyable handoff unless an agent listener is active; the button cannot wake an
-idle agent. See [setup details and optional commands](SETUP.md) for other install
-methods, or give that guide's [raw URL](https://raw.githubusercontent.com/vcfgdev/konpeki/main/SETUP.md)
-to your agent with your brief.
-
-## Try the editor in your browser
-
-[Open the editable Konpeki example](https://vcfgdev.github.io/konpeki/?example=introducing-konpeki).
-
-The browser-only playground lets you edit an example or start blank, keep a local
-working copy, import/download editable JSON, export PNG and present. It requires
-no account or AI service. Browser-local data is not cloud backup; download JSON
-to keep or move your work. Continue with your coding agent using that file.
-
-The [GitHub Pages playground](docs/development.md#github-pages) does not connect
-to an agent or expose **Build it**. The agent-led workflow above is the route
-from a prompt to a finished visual.
-
-## Showcase
-
-Illustrative examples with editable text and vector artwork. Click a preview to
-view it full-size, or download its JSON and choose **Demo Mode → Import** in the
-[playground](https://vcfgdev.github.io/konpeki/).
-
-<table>
-  <tr>
-    <td width="50%" align="center" valign="top">
-      <a href="slides/gallery/architecture.png"><img src="slides/gallery/architecture.png" width="420" alt="Harbor Market order-platform architecture"></a><br>
-      <strong>Explain a system</strong><br>
-      Order handling, events and fulfillment<br>
-      <a href="slides/gallery/architecture.json">Editable JSON</a>
-    </td>
-    <td width="50%" align="center" valign="top">
-      <a href="slides/gallery/sankey.png"><img src="slides/gallery/sankey.png" width="420" alt="Proportional Sankey showing a fictional 1,000-user trial cohort"></a><br>
-      <strong>Communicate data</strong><br>
-      Trial users, activation and outcomes<br>
-      <a href="slides/gallery/sankey.json">Editable JSON</a>
-    </td>
-  </tr>
-  <tr>
-    <td width="50%" align="center" valign="top">
-      <a href="slides/gallery/release.png"><img src="slides/gallery/release.png" width="420" alt="Clearpath 0.4 portrait release announcement in orange"></a><br>
-      <strong>Announce a release</strong><br>
-      A portrait social graphic for Clearpath<br>
-      <a href="slides/gallery/release.json">Editable JSON</a>
-    </td>
-    <td width="50%" align="center" valign="top">
-      <a href="slides/gallery/explainer.png"><img src="slides/gallery/explainer.png" width="420" alt="Folio one-page explainer showing accepted and rejected document saves"></a><br>
-      <strong>Teach a concept</strong><br>
-      One-page guide to preventing stale saves<br>
-      <a href="slides/gallery/explainer.json">Editable JSON</a>
-    </td>
-  </tr>
-</table>
-
-[Browse the gallery](slides/README.md) for briefs, sources and more examples.
-
-## Manual npm start
-
-For a manual start, install [Konpeki from npm](https://www.npmjs.com/package/konpeki)
-in your workspace (run `npm init -y` first in a new, empty directory):
+Installing the skill does not install the runtime. The skill's
+`ensure-runtime.mjs` finds a Konpeki 0.4.0 checkout or a `konpeki` package
+installed in the current workspace, and never downloads one.
 
-```sh
-npm install --save-dev konpeki@latest
-curl -fL https://raw.githubusercontent.com/vcfgdev/konpeki/main/slides/introducing-konpeki/composition.json -o introduction.json
-npm exec --no -- konpeki preview introduction.json
-```
+## Upgrading from 0.3.x
+
+0.4.0 replaces JSON compositions and the previous editing engine with static
+HTML/CSS. Old JSON files do not open in this version, and there is no automatic
+conversion. Keep an isolated 0.3.x installation for old work, or recreate it in
+HTML while preserving its facts, assets and intended layout.
+
+- Delivery formats are PNG and PDF; SVG can be authored inline, but is not an
+  export format. Inspection and export require the pinned Chromium.
+- Review uses browser-local comments and **Copy & clear**, not the old
+  `wait` / `request` / `finish` CLI protocol. Update the skill and runtime together.
+- Cobalt is the single bundled theme. Its Google Fonts dependency requires
+  network access unless you adapt the theme to local or embedded fonts.
+- Review includes opt-in [Vim keyboard navigation and element hints](html/README.md#keyboard-review).
+
+The [public comment preview](https://vcfgdev.github.io/konpeki/) opens the
+packaged starter. Use the CLI's `preview` to review your own document; local
+changes stay local until a separately authorized release or deployment.
+
+## Theme
 
-Open the exact URL printed by `preview`. Browser edits save to your downloaded file;
-valid agent edits appear on the same canvas. In a remote environment, use its
-authenticated preview mechanism rather than sharing a local address.
+Konpeki bundles one theme, Cobalt: cobalt blue on a light canvas with IBM Plex
+Sans and Mono from Google Fonts. Its CSS contract lets a brief supply its own
+visual treatment by adapting a copy; composition stays in HTML and page-owned CSS.
 
-## Examples and guides
+The default theme needs access to Google Fonts during preview, inspection, and
+export. Exports fail if fonts cannot load or glyphs fall back to installed fonts.
+For offline or reproducible rendering, use licensed local or embedded fonts in
+the document's theme. Finished PNGs and PDFs need no network access.
 
-- [Native example gallery](slides/README.md): editable diagrams, data graphics,
-  a social announcement and a one-page explainer, plus the product introduction
-  and repository cover. Older React/SVG drawing references remain separate.
-- [Agent-led setup](SETUP.md) and [authoring guidance](AUTHORING.md).
-- [Canvas workflow](docs/workflow.md): page sizes, export and agent handoff.
-- [Development](docs/development.md): architecture, demo hosting, packaging and checks.
-- [Composition contract](composition/README.md) and [design resources](design/README.md).
-- [Contributing](CONTRIBUTING.md) and [security policy](SECURITY.md).
+## Documentation
 
-Konpeki requires no account or hosted AI service. Your coding agent's pricing
-and data handling still apply. Supply facts and approved assets; examples and
-component placeholders are not evidence about real products.
+- [Konpeki skill](skills/konpeki/SKILL.md): the authoring and revision workflow
+- [HTML, files, theme, and CLI](html/README.md)
+- [Theme contract](html/theme.md) and [theme authoring](html/theme-authoring.md)
+- [Authoring floor: bans, defaults and review checklist](skills/konpeki/floor.md)
+- [Editorial and visual judgment](AUTHORING.md)
+- [Setup](SETUP.md), [development](docs/development.md) and
+  [contributing](CONTRIBUTING.md)
 
 ## License
 
-[Apache-2.0](LICENSE). Dependencies and bundled fonts retain their own licenses;
-external design references are credited where used.
+[Apache-2.0](LICENSE). Fonts and other dependencies retain their own licenses.

package/SETUP.md

@@ -1,163 +1,83 @@
-# Set up Konpeki for your coding agent
+# Set up Konpeki
 
-Requires **Node.js 24+**, npm, a coding agent with file and command access, and a browser.
+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.
 
-Install once, choosing your agent when prompted:
+## npm package
 
-```sh
-npx skills add vcfgdev/konpeki -g
-```
-
-Start a new conversation or reload your agent's skills. **Send this to your agent:**
-
-> Use Konpeki to create a one-page explainer of how a browser, API and database work together.
-
-Or use your own brief and materials. The agent prepares the runtime, creates the
-document, opens the canvas and checks the result; no separate `init` step is
-needed. Allow any required installation/browser permissions. Remote workspaces
-need authenticated preview forwarding. Keep revisions in the same conversation.
-
-## Other installers
-
-For an unattended install, select a single agent (Amp example):
+Check the exact version before installing:
 
 ```sh
-npx skills add vcfgdev/konpeki -g -a amp -y
-```
-
-This avoids auto-selecting unrelated agent targets when no terminal prompt is available.
-
-You can also use your agent's native skill installer:
-
-```text
-Install the konpeki skill from vcfgdev/konpeki, at skills/konpeki.
+npm view konpeki@0.4.0 version
 ```
 
-Install the complete [`skills/konpeki`](skills/konpeki/) directory, including
-`scripts/` and `assets/`. Follow the host's documented skill location; if it 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.
-
-## Optional commands
-
-| 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.
-
-## Agent setup reference
+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`.
 
-The installed skill handles these steps; the person does not need to run them manually.
+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).
 
-### Prepare the runtime
+## Local tarball
 
-Check Node.js 24+, npm, command/file access and the host's browser capabilities.
-Follow host approval and toolchain rules if prerequisites are missing.
-
-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.1` 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.
-
-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.
-
-### Generate, validate and open the visual
+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.
 
-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.
+## Skill helpers
 
-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.