konpeki 0.2.0 → 0.3.0

package/docs/development.md

@@ -29,13 +29,71 @@ 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. Example links do not autosave; open a composition in a file-backed
-session to preserve edits.
+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.
+
+### 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`:
 
-Hosting shares bundled examples, not private drafts, arbitrary documents or an
-AI service. No deployment is automatic. In a remote environment, expose the
-server through its authenticated preview mechanism; a local address is not a
-shareable URL.
+```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
 
@@ -78,7 +136,8 @@ trusted local React source; never use it on untrusted JSX. It rejects unsupporte
 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.
-Example previews do not autosave; use a file-backed session to save edits.
+Its working copy autosaves in that browser. Download JSON or use a file-backed
+session to retain edits outside browser storage.
 
 ## Package contents
 
@@ -103,7 +162,7 @@ rebuilding during publication. Packing locally does not publish anything.
 
 ## Tag releases
 
-`.github/workflows/publish.yml` stages releases on bare version tags such as `0.1.1`
+`.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
@@ -130,11 +189,12 @@ After updating the package version, completing release checks and pushing the
 release commit, explicitly create and push its matching tag:
 
 ```sh
-git tag 0.1.1
-git push origin 0.1.1
+VERSION=0.2.1
+git tag "$VERSION"
+git push origin "$VERSION"
 ```
 
-Replace `0.1.1` with the new version. `0.1.0` is already published and cannot be
+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,

package/docs/workflow.md

@@ -1,9 +1,16 @@
 # Canvas workflow
 
-Start with the [quickstart](../README.md#start-in-your-coding-agent) and give your
-coding agent a brief in its prompt field. Keep the skill with the project:
-copying `SKILL.md` alone does not install Konpeki. Skill discovery varies by
-agent; there is no universal `/konpeki` command.
+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.
 
 ## Documents and exports
 

package/index.html

@@ -4,10 +4,26 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#ffffff" />
+    <link rel="icon" type="image/png" sizes="128x128" href="/src/assets/konpeki-mark.png" />
     <meta
       name="description"
-      content="An editable canvas for agent-made visuals. Create a single explanation or a whole presentation, then revise it together."
+      content="Try Konpeki's editable canvas. Edit an example, create a page, export PNG or download editable JSON. No account needed; changes stay in your browser."
     />
+    <meta property="og:type" content="website" />
+    <meta property="og:site_name" content="Konpeki" />
+    <meta property="og:title" content="Konpeki — Browser playground" />
+    <meta property="og:description" content="Try Konpeki's editable canvas. Edit an example, create a page, export PNG or download editable JSON. No account needed; changes stay in your browser." />
+    <meta property="og:url" content="https://vcfgdev.github.io/konpeki/?example=introducing-konpeki" />
+    <meta property="og:image" content="https://vcfgdev.github.io/konpeki/og.png" />
+    <meta property="og:image:type" content="image/png" />
+    <meta property="og:image:width" content="1280" />
+    <meta property="og:image:height" content="640" />
+    <meta property="og:image:alt" content="Konpeki — Create clear visuals with your coding agent. Blue brush mark and editable canvas illustrations." />
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content="Konpeki — Browser playground" />
+    <meta name="twitter:description" content="Try Konpeki's editable canvas. Edit an example, create a page, export PNG or download editable JSON. No account needed; changes stay in your browser." />
+    <meta name="twitter:image" content="https://vcfgdev.github.io/konpeki/og.png" />
+    <meta name="twitter:image:alt" content="Konpeki — Create clear visuals with your coding agent. Blue brush mark and editable canvas illustrations." />
     <title>Konpeki</title>
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "konpeki",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A shared editable canvas for agent-made visuals",
   "license": "Apache-2.0",
   "repository": {
@@ -20,13 +20,19 @@
   "files": [
     "AGENTS.md",
     "AUTHORING.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
     "SETUP.md",
     "docs/workflow.md",
     "docs/development.md",
-    ".agents/skills/authoring-visuals/SKILL.md",
+    "plugin.json",
+    "skills/konpeki/SKILL.md",
+    "skills/konpeki/scripts/*.mjs",
+    "skills/konpeki/assets/blank.json",
     "runtime/konpeki.mjs",
     "index.html",
     "vite.config.ts",
+    "public/og.png",
     "src/main.tsx",
     "src/app/*.tsx",
     "src/components/*.tsx",

package/plugin.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "konpeki",
+  "version": "0.3.0",
+  "description": "Create editable visuals with your coding agent.",
+  "repository": "https://github.com/vcfgdev/konpeki",
+  "license": "Apache-2.0",
+  "extensions": {
+    "com.openai": {
+      "interface": {
+        "displayName": "Konpeki",
+        "shortDescription": "Create editable visuals with your coding agent",
+        "category": "Productivity",
+        "defaultPrompt": [
+          "Use Konpeki to turn these launch notes into a product announcement.",
+          "Use Konpeki to create a cover for this article.",
+          "Use Konpeki to turn this data into a chart for a presentation."
+        ]
+      }
+    }
+  }
+}

package/runtime/konpeki.mjs

@@ -31,6 +31,12 @@ var themeIds = [
 	"graphite"
 ];
 var themeModes = ["paper", "night"];
+var typographyIds = [
+	"plex-sans",
+	"noto-sans",
+	"plex-serif",
+	"hanken-grotesk"
+];
 var vectorElementKinds = [
 	"g",
 	"rect",
@@ -715,8 +721,9 @@ var schema = {
 		authoringMode: enumeration(authoringModes),
 		theme: object({
 			id: enumeration(themeIds),
-			mode: enumeration(themeModes)
-		}),
+			mode: enumeration(themeModes),
+			typography: enumeration(typographyIds)
+		}, ["id", "mode"]),
 		slides: array(object({
 			id: text,
 			name: text,
@@ -1321,7 +1328,7 @@ function fileSessionPlugin({ compositionPath, token, onBuildRequest }) {
 var root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 function usage() {
 	console.error(`Usage:
-  konpeki preview <composition.json> [--host <host>] [--port <port>]
+  konpeki preview <composition.json> [--host <host>] [--port <port>] [--json]
   konpeki validate <composition.json>
   konpeki wait <composition.json>
   konpeki request <composition.json>
@@ -1337,34 +1344,55 @@ async function preview(input) {
 	const token = randomBytes(24).toString("base64url");
 	const host = option("--host", "127.0.0.1");
 	const port = Number(option("--port", "4318"));
-	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("Port must be an integer from 1 to 65535.");
+	const json = process.argv.includes("--json");
+	if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error("Port must be an integer from 0 to 65535 (0 chooses a free port).");
 	const server = await createServer({
 		root,
 		configFile: resolve(root, "vite.config.ts"),
+		logLevel: json ? "silent" : "info",
 		server: {
 			host,
 			port,
-			strictPort: true
+			strictPort: process.argv.includes("--port"),
+			fs: { allow: [root, ...[
+				"ibm-plex-sans",
+				"ibm-plex-serif",
+				"noto-sans",
+				"hanken-grotesk"
+			].map((font) => dirname(fileURLToPath(import.meta.resolve(`@fontsource/${font}/package.json`))))] }
 		},
 		plugins: [fileSessionPlugin({
 			compositionPath,
 			token,
 			onBuildRequest: ({ request }) => {
 				if (!request) return;
-				console.log(`\nBuild requested for ${request.compositionPath}`);
-				console.log(`Revision: ${request.revision}`);
-				console.log(`Instruction: ${request.instruction}`);
-				console.log(`Run: konpeki wait ${JSON.stringify(request.compositionPath)}\n`);
+				console.error(`\nBuild requested for ${request.compositionPath}`);
+				console.error(`Revision: ${request.revision}`);
+				console.error(`Instruction: ${request.instruction}`);
+				console.error(`Run: konpeki wait ${JSON.stringify(request.compositionPath)}\n`);
 			}
 		})]
 	});
-	await server.listen();
+	try {
+		await server.listen();
+	} catch (error) {
+		await server.close();
+		throw error;
+	}
 	const address = server.httpServer?.address();
 	const actualPort = address && typeof address === "object" ? address.port : port;
 	const displayHost = host === "0.0.0.0" || host === "::" ? "localhost" : host;
-	console.log(`Konpeki is editing ${compositionPath}`);
-	console.log(`http://${displayHost}:${actualPort}/?session=${encodeURIComponent(token)}`);
-	console.log(`Waiting for edits and Build it requests. Press Ctrl+C to stop.`);
+	const url = `http://${displayHost.includes(":") ? `[${displayHost}]` : displayHost}:${actualPort}/?session=${encodeURIComponent(token)}`;
+	if (json) console.log(JSON.stringify({
+		type: "ready",
+		compositionPath,
+		url
+	}));
+	else {
+		console.log(`Konpeki is editing ${compositionPath}`);
+		console.log(url);
+		console.log(`Waiting for edits and Build it requests. Press Ctrl+C to stop.`);
+	}
 }
 async function validate(input) {
 	const result = await readCompositionFile(resolve(input));

package/skills/konpeki/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: konpeki
+description: Opens the Konpeki editor with init, or generates and revises editable visuals with generate. Use when asked to use Konpeki or create covers, social graphics, product announcements, charts, diagrams, article headers or presentations.
+compatibility: Requires Node.js 24+, npm, a coding agent with file and command access, and a browser. Runtime installation needs network access and the host's approval.
+---
+
+# Konpeki
+
+Use one of two modes from the invocation or conversation:
+
+- **init [composition.json]**: prepare the runtime and open a blank or existing
+  file-backed editor. Stop when it is ready; do not generate artwork or claim to
+  be listening for reviews.
+- **generate [brief / materials]**: create or revise the visual, open its preview,
+  inspect and repair it, then handle feedback in the same conversation. Prepare
+  the runtime automatically; a separate init command is never required.
+
+A creation brief without a mode, including “Use Konpeki to…”, means **generate**.
+Bare “Konpeki” with no brief opens the editor as **init**. Follow-up feedback stays
+with the current document; users need not repeat the skill or their materials.
+Use existing chat, attachments, referenced files and canvas intent as inputs.
+Ask only for missing information needed for faithful work, not a repeated brief.
+
+Invocation belongs to the host: Codex CLI/IDE uses `$konpeki init` or
+`$konpeki generate …`; a standalone Claude Code skill uses `/konpeki init` or
+`/konpeki generate …`. Other clients may use skill selection or natural language;
+plugin installations may namespace the skill. These are agent workflows, not
+`konpeki init` / `konpeki generate` terminal commands.
+
+## 0. Find the runtime once
+
+From the user's chosen workspace, run the script bundled beside this skill:
+
+```sh
+node "<absolute-path-to-this-skill>/scripts/ensure-runtime.mjs"
+```
+
+It reuses a compatible workspace installation, the surrounding Konpeki checkout,
+or a previously installed cache. If none exists, follow the host's permission
+flow, then rerun with `--install`. This installs the pinned npm release in a
+user cache, not in the user's project, and does not change their agent guidance.
+If Node.js 24+ or npm is missing, report that prerequisite and follow the host's
+toolchain setup rules; never claim the runtime is ready when setup failed.
+
+The script returns JSON with `root` (runtime resources) and `cli` (the executable
+path). In the instructions below, `<root>` and `<cli>` mean those returned absolute
+paths. Quote paths in shell commands. They may be outside the skill directory;
+do not assume a copied skill contains the runtime. Read resources from `<root>`
+and keep authored documents in the user's workspace, outside the runtime/cache.
+
+## init — open the editor without generating
+
+Use the explicit document path, otherwise the document already active in this
+conversation. With neither, use `slides/untitled/composition.json`. If several
+documents are plausible, ask which to open instead of guessing.
+
+Run the bundled helper with the resolved CLI and chosen destination:
+
+```sh
+node "<absolute-path-to-this-skill>/scripts/prepare-document.mjs" "<cli>" "<composition.json>"
+```
+
+It creates a validated blank page only when the file is missing. Existing files
+are validated without rewriting them, and unreadable files are left untouched.
+It returns `{ compositionPath, created }`; this means the document is prepared,
+not that its browser is open. Do not replace a failed document with an example.
+
+Follow **Open the file-backed preview** below. Verify the intended document loads,
+then return its path and usable editor link. For a new document, verify an empty
+page with editing controls. Stop here until the person asks to generate or revise.
+Do not start an agent listener just because an editor is open.
+
+## generate — interpret the brief
+
+Read `<root>/AGENTS.md` and `<root>/AUTHORING.md`. Use the user's existing prompt as the
+brief; do not ask them to repeat it in the canvas. Establish the source facts,
+audience, takeaway and destination. Ask only when missing facts or conflicting
+requirements prevent a faithful result.
+
+Continue the document opened by init or the current conversation unless the
+person requests a new one. Before changing an existing document, inspect
+`node "<cli>" request "<composition.json>"`. Claim a `submitted` request with
+`wait` and follow **Review handoff** below. A `working` request may belong to
+another agent; coordinate ownership before resuming, rather than claiming it again.
+With no active request, work from the brief and current composition normally.
+
+Use `default` authoring mode unless requested otherwise. Explicit visual
+preferences override taste defaults, not factual fidelity or readability. Use
+the comparison workflow in `<root>/AUTHORING.md`
+only when requested or accepted. A single page is a complete creation; choose
+dimensions for its destination rather than assuming a slide deck.
+
+### Author or revise the composition
+
+Read `<root>/composition/README.md`. For a new visual,
+create `slides/<name>/composition.json` unless the user supplies another path.
+Use an unused destination; do not overwrite a different document at that path.
+Save the creative brief in `PROMPT.md` and substantial facts, citations and asset
+provenance in `SOURCE.md`. Separate assumptions from supplied facts. Preserve
+creative requests accurately, but omit private coordination and environment or
+agent metadata; label excerpts and redactions rather than calling them verbatim.
+
+For revisions, reread the current file first. Preserve unrelated content,
+component/vector IDs and human-edited geometry. Honor explicit chart or diagram
+choices. Recompose for a new aspect ratio instead of stretching or cropping.
+
+Prefer native text and semantic components. When standard drafts cannot express
+the visual, use editable vectors inside their owning component. Reuse
+`<root>/design/README.md` and reference examples as needed.
+Trusted React may generate SVG for conversion, but imported JSX must not execute
+in the canvas or become a second document source.
+
+### Validate, render and repair
+
+```sh
+node "<cli>" validate "<composition.json>"
+```
+
+Follow **Open the file-backed preview** below, then inspect
+every affected page and requested theme at presentation and smaller review sizes
+after fonts load. Check factual fidelity, text bounds, contrast, reading order
+and relationships. Repair consequential issues and inspect fresh renders.
+
+Follow `<root>/docs/development.md` verification guidance for
+code changes. Validation alone is not visual review. If a required check cannot
+run, state the limitation; do not claim it passed. Honor requested checkpoints;
+otherwise continue to finished output.
+
+### Deliver and continue revisions
+
+Return the composition path, usable preview, reviewed images or requested
+exports, source attribution and verification limitations. Verify exports
+separately; browser images do not prove editable PDF/PPTX or font fidelity.
+Include any generator source while keeping composition JSON authoritative.
+
+Accept follow-up chat feedback without requiring another generate invocation.
+Reread the current composition each time, preserve human edits, and repeat the
+render/repair checks. For canvas feedback, the person submits notes with **Build
+it**. A submitted request can be handled by invoking generate again or by an
+agent already waiting for it. Do not treat unsent notes as a submitted request.
+
+## Open the file-backed preview
+
+Reuse a known live preview for the same absolute document path; verify it still
+loads that document. Otherwise start:
+
+```sh
+node "<cli>" preview "<composition.json>"
+```
+
+Keep the process alive using the host's supported service mechanism. Open the
+exact printed session URL in the host's in-app browser when available, otherwise
+the person's regular browser. For a remote workspace, use its authenticated
+preview or port forwarding and preserve the session query; a remote loopback URL
+is not a usable handoff. Session URLs grant editing access: do not publish them.
+Verify the intended document actually loads before calling setup complete. If
+browser access is unavailable, return the usable link and state it was not checked.
+Do not substitute the standalone playground: it cannot save to the agent's file
+or submit canvas review requests.
+
+## Review handoff
+
+When explicitly waiting for ongoing canvas reviews, run
+`node "<cli>" wait "<composition.json>"` alongside the preview using the host's
+supported long-running tool. Report whether a listener is actually running.
+**Build it** cannot wake an idle agent. Without a listener, use its **Copy prompt**
+handoff or ask the person to resume generate in agent chat; do not claim a permanent
+connection. On receiving a request,
+reread the named file and compare its revision with the request. If it changed,
+reconcile against the latest document instead of applying a stale rewrite.
+Apply every attached note to its named page, component or vector-element ID;
+without notes, respect the selected scope. Preserve unrelated edits and stable
+IDs. A request is already marked working when `wait` returns; it is not deleted.
+Validate, render, inspect and repair the result, then run
+`node "<cli>" finish "<composition.json>" <request-id> --message "Updated and checked"`.
+File changes alone do not resolve notes. If blocked, finish with
+`--status needs-clarification --message "..."` or `--status failed --message "..."`;
+unresolved notes remain for retry. Never mark a partially handled batch done.
+Use `node "<cli>" request "<composition.json>"` to recover an interrupted request and
+verify it is still active before further writes. Cancellation does not stop your
+process: stop work if the request is no longer active. Do not edit the feedback
+sidecar directly. Return to `wait` only when the person requested a continuing loop.
+
+See `<root>/docs/workflow.md` for the full handoff contract.
+Never bypass revision checks or mutate hidden browser storage to replace the
+document. Do not publish without permission.

package/skills/konpeki/assets/blank.json

@@ -0,0 +1,23 @@
+{
+  "schema": "konpeki-composition/v1",
+  "title": "Untitled composition",
+  "theme": { "id": "plex", "mode": "paper" },
+  "slides": [
+    {
+      "id": "slide-1",
+      "name": "Page 01",
+      "canvas": { "width": 1920, "height": 1080 },
+      "innerPadding": { "top": 72, "right": 112, "bottom": 0, "left": 112 },
+      "pageNumber": { "style": "none", "color": "muted" },
+      "audience": "Decision makers",
+      "question": "What should the audience understand or decide?",
+      "intendedViewingSize": "presentation",
+      "contentSlots": [],
+      "components": [],
+      "groups": [],
+      "readingOrder": [],
+      "paintOrder": [],
+      "relationships": []
+    }
+  ]
+}

package/skills/konpeki/scripts/ensure-runtime.mjs

@@ -0,0 +1,69 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// A copied skill must resolve a known runtime, not follow repo-relative links.
+const version = "0.3.0";
+const probeDocument = fileURLToPath(new URL("../assets/blank.json", import.meta.url));
+function runtime(root) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    if (pkg.name !== "konpeki" || pkg.version !== version) return;
+    const cli = join(root, pkg.bin.konpeki);
+    const sourceCLI = join(root, "bin/konpeki.mjs");
+    if (!["AGENTS.md", "AUTHORING.md", "composition/README.md", "design/README.md", "docs/workflow.md"]
+      .every(path => existsSync(join(root, path)))) return;
+    // The development checkout runs TypeScript directly on the pinned Node.
+    for (const candidate of new Set([cli, sourceCLI])) {
+      if (!existsSync(candidate)) continue;
+      const probe = spawnSync(process.execPath, [candidate, "validate", probeDocument], {
+        stdio: "ignore",
+        timeout: 10_000,
+      });
+      if (probe.status === 0) return { root, cli: candidate, version };
+    }
+  } catch {
+    // Missing or incompatible installations are not modified.
+  }
+}
+
+try {
+  if (Number(process.versions.node.split(".")[0]) < 24)
+    throw new Error("Konpeki needs Node.js 24+. Use your host's approved toolchain setup, then retry.");
+  if (process.argv.slice(2).some(arg => arg !== "--install"))
+    throw new Error("Usage: node ensure-runtime.mjs [--install]");
+  let workspace;
+  try {
+    workspace = dirname(createRequire(join(process.cwd(), "package.json")).resolve("konpeki/package.json"));
+  } catch {}
+  const bundled = fileURLToPath(new URL("../../../", import.meta.url));
+  const cacheBase = process.platform === "win32"
+    ? process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local")
+    : process.env.XDG_CACHE_HOME || join(homedir(), ".cache");
+  const cache = resolve(cacheBase, "konpeki", version);
+  const cachedRoot = join(cache, "node_modules", "konpeki");
+  let found = (workspace && runtime(workspace)) || runtime(bundled) || runtime(cachedRoot);
+  if (!found) {
+    if (!process.argv.includes("--install"))
+      throw new Error(`Konpeki ${version} is not installed. After the host approves installation, rerun with --install. This uses a user cache and leaves project dependencies unchanged.`);
+    mkdirSync(cache, { recursive: true });
+    // Explicit local prefix prevents npm from walking up into an ancestor project.
+    // Resolve "." from the absolute cwd; no user path enters Windows shell text.
+    const result = spawnSync("npm", ["install", "--prefix=.", "--global=false", "--save-exact", "--no-audit", "--no-fund", `konpeki@${version}`], {
+      cwd: cache,
+      stdio: ["inherit", 2, 2],
+      shell: process.platform === "win32",
+    });
+    if (result.error || result.status !== 0)
+      throw new Error("Konpeki installation failed. Check npm/network access and retry; the runtime is not ready.");
+    found = runtime(cachedRoot);
+    if (!found) throw new Error("The installed Konpeki runtime is incomplete or incompatible.");
+  }
+  console.log(JSON.stringify(found));
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/skills/konpeki/scripts/prepare-document.mjs

@@ -0,0 +1,40 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+try {
+  const [cli, input, ...extra] = process.argv.slice(2);
+  if (!cli || !input || extra.length)
+    throw new Error("Usage: node prepare-document.mjs <cli> <composition.json>");
+  const compositionPath = resolve(input);
+  function validate(path) {
+    // Use the published JS CLI, not TypeScript imports from node_modules.
+    const result = spawnSync(process.execPath, [cli, "validate", path], {
+      stdio: ["ignore", 2, 2],
+    });
+    if (result.error || result.status !== 0)
+      throw new Error("Document validation failed; existing files were not changed.");
+  }
+  let created = false;
+  if (!existsSync(compositionPath)) {
+    if (existsSync(`${compositionPath}.review.json`))
+      throw new Error("Review data exists without its composition. Restore the document or choose a new path.");
+    const template = fileURLToPath(new URL("../assets/blank.json", import.meta.url));
+    validate(template);
+    const blank = readFileSync(template);
+    mkdirSync(dirname(compositionPath), { recursive: true });
+    try {
+      writeFileSync(compositionPath, blank, { flag: "wx" });
+      created = true;
+    } catch (error) {
+      // Another initializer may have created it; reopen, never replace it.
+      if (error.code !== "EEXIST") throw error;
+    }
+  }
+  validate(compositionPath);
+  console.log(JSON.stringify({ compositionPath, created }));
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}