konpeki 0.3.0 → 0.4.0

package/AGENTS.md

@@ -1,33 +1,26 @@
-# Konpeki
+# Konpeki repository guidance
 
-Konpeki is a shared editable canvas for people and coding agents. The agent owns
-the conversation; composition JSON owns the document; the browser edits and
-presents that same document.
+## Read by responsibility
 
-## Choose the relevant guide
+- Authoring workflow: [skills/konpeki/SKILL.md](skills/konpeki/SKILL.md)
+- HTML, local files, theme, diagnostics, preview, and CLI:
+  [html/README.md](html/README.md)
+- Bans, defaults and review checklist: [skills/konpeki/floor.md](skills/konpeki/floor.md)
+- Editorial and visual judgment: [AUTHORING.md](AUTHORING.md)
+- Environment setup: [SETUP.md](SETUP.md)
+- Implementation work: [docs/development.md](docs/development.md)
 
-- First-time setup: [SETUP.md](SETUP.md).
-- Opening the editor, creating or revising visuals: [Konpeki skill](skills/konpeki/SKILL.md)
-  and [AUTHORING.md](AUTHORING.md), which owns design and factual-fidelity rules.
-- Changing the application: [development guidance](docs/development.md) and
-  the [composition contract](composition/README.md).
-- Browser/file handoff: [canvas workflow](docs/workflow.md).
+Use the toolchain pinned in `mise.toml`; run repository commands through
+`mise exec --` unless it is already active. Use pnpm, preserve the lockfile, and
+do not install tools globally.
 
-## Shared rules
+Preserve unrelated work, supplied facts and provenance, stable IDs, and deliberate
+human edits. Reread source before revising it. Automated checks do not replace
+visual or factual review.
 
-- For repository development, use the toolchain pinned in `mise.toml`. Run
-  commands through `mise exec --` unless the mise environment is already active.
-  Use pnpm and preserve the dependency lockfile; do not install tools globally.
-- Keep drafting, editing and presentation on the shared composition canvas.
-  Retained React/SVG examples are drawing references, not a parallel deck runtime.
-  Example geometry is not a design requirement.
-- Preserve unrelated work, human edits and stable component/vector IDs. Reread
-  the current composition before revising it; do not overwrite a newer revision.
-- Complete requested implementation, rendering, inspection and repair unless
-  the person requests a checkpoint. Ask when missing facts prevent faithful work.
-- Scale checks using [verification guidance](docs/development.md#verification).
-  Inspect affected renders for visual changes; tests alone are not visual review.
-- Keep creative briefs and factual provenance with examples. Exclude private
-  chat, coordination transcripts, workspace paths, credentials and agent/model
-  or timezone metadata. Label excerpts, adaptations and redactions honestly.
-- Do not push, publish or deploy without permission.
+Keep taste rules in `floor.md`, one ID each. A rule agents keep breaking gets an
+`inspect` check under the same ID, with passing and failing fixtures from real
+output; a rule without a check stays on the review checklist. Name the output
+that prompted a floor change.
+
+Never publish, push, deploy, or tag without explicit permission.

package/AUTHORING.md

@@ -1,233 +1,72 @@
-# Authoring visuals
+# Authoring judgment
 
-Make visually compelling pages that explain the material clearly.
-This file owns design guidance. The brief overrides taste defaults; preserve
-accuracy and readability. Components, specimens and historical studies are
-resources to adapt freely.
+This guide owns editorial and visual judgment that no rule can settle. For
+workflow steps, use the [Konpeki skill](skills/konpeki/SKILL.md); for the bans,
+defaults and review checklist, use its [authoring floor](skills/konpeki/floor.md);
+for source and tool rules, use the [HTML reference](html/README.md).
 
-## Destination and surface
+## Accuracy and editorial judgment
 
-A single page is a complete creation. The brief may request a social graphic,
-Open Graph preview, article header, standalone explanation or presentation.
-Choose page dimensions for that destination, within 256–4096 pixels per side;
-do not assume 16:9 or invent extra pages. Record the destination in
-`intendedViewingSize` (`social`, `article`, `presentation` or `custom`).
-For another aspect ratio, recompose deliberately rather than stretching artwork,
-silently cropping evidence or shrinking essential text. Each page can have its own size.
-
-Return finished, inspected output by default. Do not require people to sketch,
-choose component types or approve an outline unless they ask for that checkpoint.
-Treat supplied sketches as partial direction and preserve deliberate human edits.
-The slide-oriented guidance below also applies to single visual pages where relevant.
-
-## Requirements
-
-- Preserve facts, sources, units, denominators, bounds and meaningful caveats.
+- Preserve facts, sources, units, denominators, bounds, and meaningful caveats.
   Distinguish evidence from interpretation; never invent data or filler.
-- Keep all essential content readable at the intended viewing size. Check
-  captions and sources as carefully as body text. Do not hide overflow, truncate
-  required copy or automatically shrink text to fit.
-- Represent relationships honestly: correct arrow directions, clear label/value
-  associations, appropriate chart scales and zero baselines for amount bars.
-  Do not rely on color alone to distinguish meanings.
-- Use licensed assets and real font weights; verify fonts load before measuring
-  text.
-- Keep slide order, outer component geometry, reading/paint order and semantic
-  relationships in the Konpeki composition document. Use the same canvas for
-  editing and presentation preview.
-- When standard components cannot express the artwork, attach editable vector
-  elements to the owning component. The composition owns both the component's
-  outer geometry and stable IDs for its internal lines, shapes, paths and text.
-  React may generate SVG in a trusted build step, but convert supported SVG
-  primitives into the vector tree rather than making React a second deck source.
-
-## Writing tone
-
-Write like a builder explaining their work to a capable peer: plainspoken,
-concrete and concise. Give each slide a main point and state it in the headline.
-Cut hype, repetition and rhetorical “not X, but Y” framing. Keep names consistent,
-explain unfamiliar terms and retain enough context to make sense without narration.
-
-Start the slide's reading order with its main headline. By default, omit brand
-eyebrows above it and section labels that repeat it. Do not add a numbered
-micro-heading merely because the slide belongs to a sequence; retain numbers
-when they explain actual steps or provide useful page navigation.
-Keep an extra label only when removing it would lose necessary context,
-navigation or required attribution, or when the user explicitly requests it.
-Apply this test when composing shared slide frames as well as individual pages.
-
-Omit recurring metadata footers by default. Put deck-wide product names,
-generic source descriptions and provenance in the example's README/source record
-or introduce them once where useful. Keep page-specific citations, units and
-meaningful caveats next to the evidence they qualify; preserve legally required
-attribution and make fictional data clear where it is presented. Useful page
-numbers may stand alone without a footer strip or separator. A table's closing
-rule ends the table, not the page; do not add a page-bottom rule for metadata.
-
-Make each page answer one identifiable audience question. In a worked example,
-carry named actors, current state and consequences through the explanation.
-Explain what a choice changes: abstract labels such as “keep, revise or replace”
-are not enough without their concrete outcomes. Place implementation requirements
-with the mechanism they constrain and limitations with the claims they qualify;
-do not turn an action-oriented page into an equal-weight collection of steps,
-requirements and unrelated caveats. Preserve essential limitations visibly,
-redistributing them across the deck rather than hiding them in notes. Use names
-instead of pronouns when multiple actors make the reference ambiguous.
-
-## Taste and creative freedom
-
-### Authoring mode
-
-Offer exactly two modes: `default` and `dynamic`. Use `default` when omitted.
-Default preserves the pre-revision visual rules; dynamic removes the specific
-restrictions listed below. It grants freedom, not a requirement to add decoration,
-more colors or more diagrams. This is an authoring instruction, not a runtime
-switch or a model-specific setting.
-
-| Rule | `default` — original rules | `dynamic` — relaxed rules |
-| --- | --- | --- |
-| Unspecified theme | Minimalist white canvas, dark text, sans-serif and one restrained main accent. Beige and light violet only when requested. Additional semantic chart/status colors are allowed. | Same background, font and main-accent defaults. Expressiveness comes from composition and visual explanation, not an automatic theme change. |
-| Emphasis and containers | Prefer typography, placement and whitespace. Keep containers restrained; use fills for state, meaningful boundaries or highlighted evidence, not decorative emphasis. | Color fields, tinted panels and shapes may also provide hierarchy, grouping, rhythm and emphasis. Remove competing layers, not containers as a category. |
-| Subheadings | Give subheadings enough typographic emphasis to distinguish them from supporting text. | Hierarchy may also come from placement, color or grouping without extra type contrast. |
-| Drawing style | Keep text/data crisp; Rough.js is opt-in by user or template choice. | Choose crisp or hand-drawn treatment to suit the direction; text/data remain legible. |
-| Arrows | Use arrows for relationships that placement and wording do not already make clear. Default to open, stroked heads unless the user or notation calls for another form. | Arrows may reinforce prose when useful; open or filled heads are valid. |
-| Framing | No decorative top/bottom ribbons or side rails. Match surrounding padding to differently proportioned artwork rather than adding contrasting bands. | Bands and rails may support composition or emphasis; compose surrounding space deliberately. |
-
-Dynamic does not imply a dark or colored canvas. Make the composition more
-expressive before changing the theme. Keep the white canvas and sans-serif
-fallback unless the user supplies another direction; use accent fills locally
-for emphasis, grouping or visual explanation rather than recoloring the page.
-
-In both modes, explicit brand, palette, typeface and visual references override
-taste defaults, never accuracy or readability. Choose explanation structure and
-depth from the source, audience and brief, not extra parameters. Tinted text cards
-alone do not constitute a visual explanation. Never invent relationships or
-supporting facts to satisfy a mode.
-
-Palette/background, font pairing, illustration style, audience, tone, delivery
-format, viewing size and page count are brief choices or constraints. They are
-not additional numeric knobs.
-Do not expose separate container-count, arrow-count, hue, corner-radius or
-"creativity" sliders: choose these implementation details to serve the brief.
-
-Resolve conflicts in this order: accuracy/readability requirements, explicit
-content and delivery constraints, specific visual directions, then authoring mode
-and its default. With a fixed page count, recompose or remove optional repetition
-rather than shrinking text to fit; ask for a scope/page-count decision if required
-content cannot fit legibly. Never silently drop it or add pages.
-
-Apply the mode deck-wide, with page-level variation where content warrants it.
-Record the requested setting (or `unspecified`) and resolved setting in the adaptation
-record in `PROMPT.md`, separately from verbatim user wording. Do not retroactively
-label historical outputs as if they were generated with this parameter.
-
-The parameter is usable through the existing authoring workflow, but its
-reliability has not been established by earlier examples. Compare actual renders
-on the same brief, not counts of shapes or an aesthetic score.
-
-### Palette, type and visual explanation
-
-For font-family choices, consider IBM Plex Sans for technical explanations,
-Noto Sans for neutral typography or Hanken Grotesk for a product-oriented feel.
-Reuse the project's established typeface when one exists. Inter is acceptable;
-choose for readability, language coverage and fit with the brief rather than
-novelty. These are suggestions, not a closed list. Keep font roles consistent
-and verify the required weights load.
-
-Choose a coherent deck-wide palette and treatment within the selected mode or
-explicit user direction. Keep font roles consistent and the reading order clear.
-Keep chart and status meanings stable, and provide labels or other cues when a
-distinction carries information. Apply the mode table to emphasis and containers.
-
-Consider a diagram, annotated artifact or visual comparison when relationships
-are central to the point. Use it when it makes those relationships easier to
-grasp, even if prose could describe them. Supporting words and visuals can
-reinforce each other. Do not require a diagram on every page or invent causal,
-temporal or quantitative meaning to justify one.
-
-Use whitespace and alignment for independent paragraphs and heading–description
-pairs; columns alone do not require borders. Use horizontal rules when they help
-readers track corresponding items across columns. When rules establish table
-rows or paired rows, give the group a clear ending before notes or conclusions,
-usually a closing bottom rule. Do not add separators to every paragraph.
-Align a short row heading with the first line of its description, rather than
-centering it against a multiline paragraph. Apply the mode's subheading guidance
-and verify that headings are distinguishable from their supporting text.
-
-Use the mode's arrow policy. Keep arrow meaning and treatment consistent, and
-align anchors and labels with the objects they refer to. Do not imply a transition
-or dependency that the evidence does not support.
-
-Use the mode's framing policy; do not add recurring metadata strips merely to
-fill space. Use the intended ratio where supported. Inspect both the preview
-and requested export.
-
-Find optional themes, palettes and semantic patterns in the
-[design index](design/README.md). Choose visuals for the audience's question
-and the relationships to explain.
-
-## Workflow and review
-
-Ground the story in the brief and sources: audience, takeaway and delivery needs.
-Use lightweight page drafts when they help resolve story, density or pacing;
-they are not a required deliverable for every edit. State material assumptions
-and proceed with reasonable composition choices within the design defaults.
-Ask when missing evidence or conflicting requirements prevent a faithful result.
-Honor an explicit draft-review checkpoint; otherwise continue to the requested output.
-
-Reuse the kit where useful. Use deck-local SVG/React as trusted drawing source
-when existing components weaken the explanation, then convert its supported
-primitives to composition vectors. Do not replace the editable composition with
-framework source. No new runtime or template framework is needed.
-
-A completed slide implementation includes runnable source, source notes and
-inspected captures at presentation and review sizes. Check factual fidelity,
-readability, clipping and visual relationships, plus coherence across pages and
-any requested variants. Before delivery, inspect each page's reading order and
-apply the [text review](design/review/text.md), including redundant hierarchy.
-Readable, in-bounds text can still repeat the headline unnecessarily. Record
-the page-level evidence and repair findings without waiting for user feedback.
-Repair consequential issues and inspect fresh renders
-before delivery. Use [development checks](docs/development.md#verification) for relevant code checks
-and [focused visual review](design/visual-review.md) for applicable review guidance.
-Specimen geometry assertions and aesthetic scores are not design requirements.
-Do not add an aesthetic linter.
-
-For each new example, save `slides/<name>/PROMPT.md` before authoring: the exact
-initial prompt, supplied source material or links, and explicit visual preferences
-(including none). Preserve creative follow-ups accurately and record material
-assumptions and manual edits separately. Exclude private coordination transcripts,
-agent/model identifiers, generation timestamps and environment metadata. Keep input
-facts and datasets in `SOURCE.md` when substantial. These records explain why
-the example looks and reads as it does, as well as supporting reproduction.
-Mark adaptation prompts and reconstructed history honestly; do not invent an
-original prompt for an inherited specimen. Never commit secrets or private
-material without permission; record any redaction.
-
-Report verification limitations and only behavior actually tested. Browser
-images do not establish PDF/PPTX or cross-application fidelity. Inspect requested
-exports separately; if a delivery target is unsupported, explain the limitation.
-
-### Explore an uncertain direction
-
-When the user is unsure about the mode, offer two candidates of one representative
-page: `default` and `dynamic`. Generate them when requested or accepted, not
-automatically for every deck. Keep wording, evidence, caveats and viewing size
-fixed. Honor the same explicit visual constraints; otherwise let each mode's
-theme policy apply. Render and inspect both, label the modes and explain the
-differences. Let the user choose before applying the mode across the deck.
-
-When a design choice matters and the brief does not settle it, choose one page
-and one primary axis: composition, density, hierarchy or wording. Render two or
-three named alternatives with the same facts, evidence and chosen theme.
-Vary the answer, not just the tint. For architecture, an ownership map, request
-journey and failure-boundary view can test which structure explains the point.
-Keep required relationships visible in every candidate.
-
-Show candidates at the same viewing size and explain what each makes easier
-and what it sacrifices. For an exploration-only request, recommend a direction
-and let the user choose. When implementation is requested, choose and carry it
-through unless the user requested a selection checkpoint.
-Promote the selected direction and remove temporary comparison scaffolding;
-retain alternatives only when requested. This is optional exploration, not a
-required extra round for every deck.
+- Give each page one identifiable audience question, answered by its headline.
+- Keep names consistent and explain unfamiliar terms. Put citations, units, and
+  caveats next to the evidence they qualify; preserve required attribution.
+- If fixed page count and required content conflict, ask for a scope decision
+  rather than dropping content or making it illegible.
+
+## Adapt content to the format
+
+Read the matching [output guide](skills/konpeki/SKILL.md#choose-the-output-guide)
+for slides, résumés, long documents, one-pagers/cards, or covers/social graphics.
+Use [content patterns](skills/konpeki/references/patterns.md) for text with visuals,
+charts, tables, comparisons, processes, systems, or annotations in the work.
+They guide decisions, not fixed templates or a placement grid.
+
+Specify required facts per format, not on every page of a multi-format set.
+Keep a qualification wherever its claim appears, and retain required disclosure.
+Preserve the same headline wording across announcement formats; change its
+line breaks, not the promise. Avoid breaks that strand articles or prepositions.
+
+Review link cards at about 500px wide, slides at presentation distance and print
+pages at actual size. The minimum-size diagnostic is a floor, not a target for
+body text. Use print running heads, page numbers and recurring source references
+when they help navigate a multi-page document; remove repetitive metadata from
+standalone graphics.
+
+## Visual judgment
+
+The brief, brand, and references choose the visual language, but never override
+accuracy or readability. The selected theme owns repeatable treatments; this
+guide and other design skills own their use. Konpeki bundles one theme, Cobalt:
+cobalt ink on warm paper. A brief-specific theme adapted from it is an equally
+valid starting point.
+
+For Cobalt, use square corners, precise alignment and an asymmetric layout led
+by a strong headline. That is this theme's taste, not a restriction on a
+brief-specific theme or meaningful chart geometry. A custom theme may carry
+short companion `NOTES.md` with its own look-specific guidance.
+
+Use complete type roles rather than accumulating near-identical treatments, and
+the same rule treatment for the same purpose. Color distinguishes roles: accent
+for the main claim or path, muted ink for supporting copy, categorical colors
+for identity, sequential colors for amount. Token compliance does not establish
+good composition or honest visual encoding.
+
+Budget space for the headline, chart or table, sources and caveats together.
+Prefer flow or grid rows over absolute positions for text that can wrap after a
+theme swap. Avoid guessed fixed-height paragraph boxes and manual line breaks
+that imitate wrapping. Judge visible text as well as its CSS box: line height,
+padding, and font metrics affect perceived gaps and alignment. On contrasting
+fields, explicitly set the ink of nested type roles and code too: their defaults
+may replace the parent's color.
+
+Use diagrams, annotated artifacts, charts, or comparisons only when they make
+real relationships easier to grasp. Use arrows sparingly and keep semantic
+colors consistent.
+
+Resolve conflicts in this order: accuracy and readability; the floor's bans;
+explicit content and delivery constraints; specific visual direction; then the
+floor's defaults and these taste notes. Finished work is the default: do not
+impose a questionnaire, diagram choice, or outline checkpoint unless the user
+asks for one.

package/CONTRIBUTING.md

@@ -1,25 +1,12 @@
 # Contributing to Konpeki
 
-Thanks for helping improve Konpeki. Bug reports, focused fixes and additions that
-strengthen the shared human-agent canvas are welcome.
+Bug reports and focused improvements are welcome. Search existing issues first,
+and discuss large contract changes before implementing them. Never include
+private documents, credentials, or proprietary source material in issues,
+fixtures, or screenshots. Report vulnerabilities via [SECURITY.md](SECURITY.md).
 
-## Before opening a change
-
-- Search existing issues before filing a new one.
-- Use an issue to discuss large features or changes to the composition contract
-  before investing in an implementation.
-- Do not include private compositions, credentials or proprietary source material
-  in issues, fixtures or screenshots.
-- Report security concerns through the process in [SECURITY.md](SECURITY.md), not
-  through a public issue.
-
-## Development
-
-Follow [docs/development.md](docs/development.md) to install the pinned Node.js and
-pnpm toolchain. Keep changes scoped and preserve existing composition compatibility
-unless a contract change has been agreed in advance.
-
-Before opening a pull request, run:
+Follow [docs/development.md](docs/development.md) for the pinned toolchain and
+verification guidance. Before opening a pull request, run:
 
 ```sh
 mise exec -- pnpm check
@@ -28,9 +15,9 @@ mise exec -- pnpm build
 mise exec -- pnpm check:package
 ```
 
-UI changes also require visual inspection using the relevant browser checks in
-[docs/development.md](docs/development.md#verification). Include the affected
-states and verification performed in the pull request description.
+Include affected states and verification in the pull request description. UI
+changes require visual inspection. Releases and deployments require maintainer
+approval.
 
-By submitting a contribution, you agree that it is licensed under the repository's
+By submitting a contribution, you agree that it is licensed under the
 [Apache-2.0 license](LICENSE).

package/README.md

@@ -1,107 +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.
-
-People and agents edit the same composition. Export a page as PNG, download its
-editable JSON, or use **Present** for a chrome-free presentation.
-
-## Use with your agent
-
-Requires **Node.js 24+**, npm, a coding agent that can edit files and run commands,
-and a browser.
-
-Install the [Konpeki skill](skills/konpeki/) with your agent's
-skill installer. Install the whole directory, including `scripts/` and `assets/`, not just
-`SKILL.md`. For example, ask a Codex skill installer:
-
-```text
-Install the konpeki skill from vcfgdev/konpeki, at skills/konpeki.
+```sh
+npm install --save-exact konpeki@0.4.0
+npx --no-install konpeki browser install
 ```
 
-Then choose a mode, or just give it a brief:
-
-| Workflow | Codex CLI / IDE | Claude Code standalone skill |
-| --- | --- | --- |
-| Open a blank or existing editor; no generation | `$konpeki init` | `/konpeki init` |
-| Create, inspect and revise a visual | `$konpeki generate …` | `/konpeki generate …` |
-
-`init` accepts a composition JSON path and preserves existing work. `generate`
-uses the materials already in your conversation and prepares the runtime if
-needed; there is no required init step. Plugin installations may namespace the
-skill. Other hosts can select the skill or use natural language:
+Create a starter with its theme beside it, then run the loop:
 
-> Use Konpeki to turn these launch notes into a product announcement.
-
-Or ask for an article cover, a social graphic, a chart, a diagram or a presentation.
-Natural-language creation requests select `generate` automatically.
-The skill reuses a compatible runtime or, with permission, installs the pinned
-npm release in a user cache. It creates editable JSON in your workspace, opens
-the preview and visually checks the result. You do not need to clone Konpeki,
-edit a package manifest, or repeat your prompt in a blank canvas.
-
-First-run installation, browser permissions and remote preview forwarding depend
-on your agent host. If skills are unavailable, give the agent the public
-[SETUP.md](https://raw.githubusercontent.com/vcfgdev/konpeki/main/SETUP.md) URL and
-your brief together. The setup guide also covers the optional Codex plugin package.
+```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
+```
 
-Ask for revisions in the same conversation. Add “Stop after the outline for
-approval” when you want a checkpoint. Supply a visual direction or leave it open;
-[authoring modes](AUTHORING.md#authoring-mode) provide defaults without requiring
-you to choose fonts, colors or layouts first.
+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).
 
-Canvas review notes use **Build it** and an active agent listener, or the
-button's copyable handoff to resume the agent. Opening the editor alone does not
-connect or wake an agent. The skill modes are not terminal CLI subcommands.
+To let your coding agent do the authoring, install the skill separately:
 
-## Try the editor in your browser
+```sh
+npx skills add vcfgdev/konpeki -g
+```
 
-[Open the editable Konpeki example](https://vcfgdev.github.io/konpeki/?example=introducing-konpeki).
+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.
 
-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.
+## Upgrading from 0.3.x
 
-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.
+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.
 
-## Manual npm start
+- 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).
 
-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):
+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.
 
-```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
-```
+## 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.
 
-- [Example gallery](slides/README.md): 18 fictional examples and an editable
-  Konpeki introduction. Retained React/SVG examples are drawing references;
-  new editable documents use composition JSON.
-- [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.