konpeki 0.1.0 → 0.2.0

package/.agents/skills/authoring-visuals/SKILL.md

@@ -75,7 +75,18 @@ canvas request, run `npm exec --no -- konpeki wait <composition.json>` alongside
 **Build it** submits a request; it does not launch an agent. On receiving it,
 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.
-Respect the selected component/page scope and preserve unrelated edits.
+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
+`npm exec --no -- konpeki 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 `konpeki 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 [canvas workflow](../../../docs/workflow.md) for the full handoff contract.
 Never bypass revision checks or mutate hidden browser storage to replace the

package/README.md

@@ -1,4 +1,4 @@
-# Konpeki
+![Konpeki — A shared canvas for you and your agents](slides/github-cover/cover.png)
 
 **An editable canvas for agent-made visuals. Create a single explanation or a
 whole presentation, then revise it together.**
@@ -15,32 +15,15 @@ editable JSON, or use **Present** for a chrome-free presentation.
 Requires **Node.js 24+**, npm, a coding agent that can edit files and run commands,
 and a browser.
 
-For agent-led installation, give your agent [SETUP.md](SETUP.md) and your brief.
-For a manual quickstart:
-
-```sh
-mkdir konpeki-workspace
-cd konpeki-workspace
-npm init -y
-npm install --save-dev konpeki@0.1.0
-cp node_modules/konpeki/slides/introducing-konpeki/composition.json introduction.json
-npm exec --no -- konpeki preview introduction.json
-```
-
-Open the exact URL printed by `preview`. Browser edits save to the composition
-file; valid agent edits appear on the same canvas. In a remote environment, use
-its authenticated preview mechanism rather than sharing a local address.
-
-Open the workspace in your coding agent and ask it to read
-`node_modules/konpeki/SETUP.md`. The installed package includes the authoring skill,
-design guidance and examples; skills inside dependencies may need to be read
-explicitly. Keep your documents outside `node_modules`. Give your brief in the
-agent's prompt field:
+Give your coding agent the public setup URL and your brief. The guide covers
+installation; no repository clone or manual package installation is needed first:
 
 ```text
-Use Konpeki to turn these notes into a three-slide explanation for engineers.
-Make the request flow and failure handling easy to follow. Preserve facts and
-caveats. Save editable composition JSON, then render, inspect and fix the result.
+Read https://raw.githubusercontent.com/vcfgdev/konpeki/main/SETUP.md
+and set up Konpeki in this workspace.
+Turn these notes into a three-slide explanation for engineers. Make the request
+flow and failure handling easy to follow. Preserve facts and caveats. Save editable composition
+JSON, open the preview, then render, inspect and fix the result.
 
 [Paste notes or provide source files.]
 ```
@@ -50,6 +33,24 @@ approval” when you want a checkpoint. Supply a visual direction or leave it op
 [authoring modes](AUTHORING.md#authoring-mode) provide defaults without requiring
 you to choose fonts, colors or layouts first.
 
+The package includes the authoring skill, design guidance and examples—no GitHub
+clone is required. Keep your documents outside `node_modules`.
+
+## Try an editable example
+
+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):
+
+```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
+```
+
+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.
+
 ## Examples and guides
 
 - [Example gallery](slides/README.md): 18 fictional examples and an editable

package/SETUP.md

@@ -25,7 +25,7 @@ agent. An in-app browser is convenient but not required.
   reuse the same CLI version. Do not edit files inside `node_modules`.
 
 ```sh
-npm install --save-dev konpeki@0.1.0
+npm install --save-dev konpeki@0.1.1
 ```
 
 In a new empty directory, run `npm init -y` first. Run subsequent commands from

package/composition/README.md

@@ -1,6 +1,6 @@
 # Composition contract
 
-`konpeki-composition/v18` describes one or more bounded visual pages
+`konpeki-composition/v1` describes one or more bounded visual pages
 shared by a person and coding agent. It is a visual intent contract, while the
 Konpeki canvas is its editor and presentation preview. Component rectangles are
 preferences; factual fidelity and readable
@@ -9,67 +9,44 @@ default is `none`; rules/dividers are separate appearance parameters. Editor
 guides never enter the contract. The contract is tool-agnostic: no Konpeki
 package, repository checkout, or separate authoring kit is required.
 
-Schema identifiers are immutable compatibility boundaries. New fields or
-vocabularies that an older reader could reject require a new identifier. Konpeki
-migrates compatible v1–v4 single-slide documents to a one-slide deck on import
-or load. V1 and v2 obsolete
-authoring-kit targets are removed; v3 callouts and comparisons become configured
-Text blocks without changing component IDs, geometry, slots, relationships or
-orders. V5 Evidence becomes Visual; Process and System map become a typed
-Diagram; and the Page-number component becomes a slide setting. V7 makes the
-Headline optional while retaining its singleton and reading-order constraints
-when present. V8 adds standalone Image, Icon and Shape primitives, Pie visuals,
-Text-block logical order and empty slides; v7 Image visuals migrate to Image
-components. V9 adds a first-class Table primitive with content-derived dimensions,
-header placement, grid treatment, density and color scheme. V10 adds optional
-slide-coordinate preferred rectangles to explicit diagram nodes so circular,
-branched and asymmetric topology can preserve authored geometry. V11 merges
-Headline and Footnote into Text-block roles, renames Visual to Chart, moves Icon
-and Shape into Diagram nodes, and renames Diagram `template` to `layout`. Schema
-v12 replaces Diagram's coarse process/system and layout pair with 32 semantic
-grammars adapted from the MIT-licensed Diagram Design taxonomy. The previous six
-layouts become derived implementation engines; all v11 combinations migrate
-deterministically. Diagram owns structural grammars while Chart owns the six
-scale-based historical grammars (bar, line, radar, treemap, scatter and Sankey).
-Pie and Annotated detail are additional Konpeki Chart grammars. V13 lets any of
-the same five semantic components own an optional self-contained SVG interior.
-V14 adds a structured vector interior: lines, shapes, paths and text have stable
-IDs, editable attributes and parent relationships. Legacy SVG remains an opaque
-compatibility fallback. The composition is authoritative for both outer geometry
-and editable vector internals. V15 adds explicit theme bindings to vector styles;
-v14 documents migrate with their literal styles unchanged. Current exports are
-always v18. Consumers must reject unknown future versions rather than interpreting them as v18. The JSON
-Schema `$id` and deterministic compiler version are versioned with this contract.
+Schema identifiers are immutable compatibility boundaries. This is the first
+public contract, so current exports use v1 and unknown versions are rejected.
+The JSON Schema `$id` and deterministic compiler version are versioned with this
+contract.
 
-V18 adds Diagram and Chart `appearance.selection`: `auto` delegates form selection
-to the agent; `explicit` makes the diagram type or chart template binding. Omission
-means explicit, never permission to switch. New canvas diagrams and charts use auto.
-Older documents migrate to explicit because their selection provenance is unknown.
-Type/template, artwork and geometry remain
-unchanged. The agent must ask before changing an explicit form or component kind,
-and may not silently reset it to auto. This is a handoff requirement, not a runtime
-permission barrier against arbitrary external file edits.
-The form picker remains available for finished vectors and legacy SVG as well as
+The contract has five semantic component kinds: Text block, Diagram, Chart,
+Image and Table. Any component can own optional self-contained SVG or structured
+vector artwork. Structured lines, shapes, paths and text have stable IDs,
+editable attributes and parent relationships. Opaque SVG remains a supported
+fallback. The composition is authoritative for both outer geometry and editable
+vector internals.
+
+Diagram and Chart `appearance.selection` controls form choice: `auto` delegates
+selection to the agent; `explicit` makes the diagram type or chart template
+binding. Omission means explicit, never permission to switch. New canvas diagrams
+and charts use auto. The agent must ask before changing an explicit form or
+component kind, and may not silently reset it to auto. This is a handoff
+requirement, not a runtime permission barrier against arbitrary external file edits.
+The form picker remains available for finished vectors and opaque SVG as well as
 drafts. Changing the requirement preserves existing artwork; it does not redraw it.
 Sankey topology cannot be discarded by selecting another template, even in Auto.
 
-V17 makes each page's `canvas.width` and `canvas.height` integers from 256 to 4096.
+Each page's `canvas.width` and `canvas.height` are integers from 256 to 4096.
 `innerPadding` is nonnegative and must leave a content area. Component rectangles
 must fit their owning page. `intendedViewingSize` accepts `presentation`, `social`,
-`article` or `custom`. Existing v16 decks migrate without geometry or content changes.
+`article` or `custom`.
 The JSON key `slides` remains the ordered page collection for compatibility; it
 does not restrict the document to presentations. Resizing does not transform content.
 
-V16 gives ordinary Text blocks plain `content` and optional `textStyle`: size
+Ordinary Text blocks have plain `content` and optional `textStyle`: size
 (8–240 slide pixels), weight (400/500/600), lineHeight (1–3), color
 (ink/muted/accent), and font (heading/body). Newlines are preserved and lines wrap
 inside the component. Missing content is empty; new manually added blocks start
 with editable “Text”. `intent` is separate agent guidance and never supplies live
-displayed copy. Legacy non-vector blocks copy their formerly displayed intent to
-content once on import; legacy custom visuals remain untouched. Custom visuals,
-when present, still own rendering. Ordinary text should not use custom visuals.
-Layout/purpose metadata from older drafts remains agent guidance rather than fake
-placeholder lines. Use separate Text blocks when independently positioned copy is needed.
+displayed copy. Custom visuals, when present, still own rendering. Ordinary text
+should not use custom visuals. Layout and purpose metadata remains agent guidance
+rather than displayed copy. Use separate Text blocks when independently positioned
+copy is needed.
 
 ### Theme-linked vector styles
 

package/composition/compile.ts

@@ -117,7 +117,7 @@ function compileSlidePlan(slide: CompositionSlide, index: number) {
     const custom = component.customVisual
       ? component.customVisual.format === "vector"
         ? ` Custom visual — ${component.customVisual.elements.length} editable vector elements in a ${component.customVisual.viewBox.width}×${component.customVisual.viewBox.height} local viewport, ${component.customVisual.fit ?? "contain"} fit; preserve element IDs and edit individual geometry or styling while this component ID and preferred rectangle own slide placement.`
-        : ` Custom visual — legacy self-contained SVG, ${component.customVisual.viewBox.width}×${component.customVisual.viewBox.height} local viewport, ${component.customVisual.fit ?? "contain"} fit; convert its source to editable vector elements when revising while this component ID and preferred rectangle own slide placement.`
+        : ` Custom visual — opaque self-contained SVG, ${component.customVisual.viewBox.width}×${component.customVisual.viewBox.height} local viewport, ${component.customVisual.fit ?? "contain"} fit; convert its source to editable vector elements when revising while this component ID and preferred rectangle own slide placement.`
       : "";
     return `- ${componentLabel(component)}, ${placement(component, slide)}: ${component.intent?.trim() || "Use its content-slot instructions."} Appearance — ${appearance(component)}.${grammar}${custom} Required slots — ${slotLabels}.`;
   });

package/composition/document.ts

@@ -8,29 +8,14 @@ import {
   type CompositionSlide,
   type ContentSlot,
   type Rect,
-  type SemanticRelationship,
-  type ThemeId,
-  type AuthoringMode,
 } from "./types.ts";
 import { validateComposition } from "./validate.ts";
 import { appearanceOptions } from "./schema.ts";
 import { diagramDefinition } from "./visualizations.ts";
 
 export type Draft = CompositionDocument;
-type LegacyDraft = {
-  title: string;
-  audience: string;
-  question: string;
-  themeId: ThemeId;
-  themeMode: "paper" | "night";
-  authoringMode?: AuthoringMode;
-  components: CompositionComponent[];
-  readingOrder: string[];
-  paintOrder: string[];
-  relationships: SemanticRelationship[];
-};
 export type StoredDraftResult =
-  { ok: true; draft: Draft; migrated: boolean } | { ok: false };
+  { ok: true; draft: Draft } | { ok: false };
 export type ParsedComposition =
   | { ok: true; document: CompositionDocument }
   | { ok: false; message: string };
@@ -574,78 +559,6 @@ export function duplicateComponent(draft: Draft, id: string, slideId?: string):
   };
   return validMutation(draft, next);
 }
-function legacyToComposition(draft: LegacyDraft): unknown {
-  const components = draft.components;
-  const rawComponents = components as unknown as Array<
-    {
-      id: string;
-      kind: string;
-      slotIds: string[];
-      appearance?: { role?: string };
-      intent?: string;
-    }
-  >;
-  const contentSlots = rawComponents.flatMap((component) =>
-    component.slotIds.map((id) => {
-      const kind = component.kind;
-      const source =
-        kind === "footnote" ||
-        (kind === "text-block" && component.appearance?.role === "footnote");
-      const role = source
-        ? "source"
-        : kind === "headline" ||
-            (kind === "text-block" && component.appearance?.role === "title")
-          ? "takeaway"
-          : ["visual", "evidence", "chart"].includes(kind)
-            ? "evidence"
-            : kind === "image"
-              ? "image"
-              : kind === "table"
-                ? "table"
-                : ["diagram", "process"].includes(kind)
-                  ? "process-step"
-                  : kind === "text-block"
-                    ? "body"
-                    : "entity";
-      const base = {
-        id,
-        label: componentLabels[component.kind as CompositionComponent["kind"]] ??
-          kind.replaceAll("-", " "),
-        required: true,
-        instruction: component.intent?.trim() || `Describe ${kind.replaceAll("-", " ")} content.`,
-      };
-      return role === "source"
-        ? {
-            ...base,
-            role,
-            targets: rawComponents
-              .filter((candidate) => candidate.id !== component.id)
-              .map((candidate) => candidate.id),
-          }
-        : { ...base, role };
-    }),
-  );
-  return {
-    schema: "konpeki-composition/v3",
-    title: draft.title,
-    ...(draft.authoringMode ? { authoringMode: draft.authoringMode } : {}),
-    theme: { id: draft.themeId, mode: draft.themeMode },
-    slide: {
-      id: "slide-1",
-      canvas: canvasSize,
-      innerPadding: canvasPadding,
-      audience: draft.audience,
-      question: draft.question,
-      intendedViewingSize: "presentation",
-      contentSlots,
-      components,
-      groups: [],
-      readingOrder: draft.readingOrder.map((id) => ({ kind: "component", id })),
-      paintOrder: draft.paintOrder,
-      relationships: draft.relationships,
-    },
-  };
-}
 export function serializeDraft(draft: Draft) {
   return JSON.stringify({ version: 2, document: draft });
 }
@@ -664,31 +577,9 @@ export function parseStoredDraft(raw: string): StoredDraftResult {
       return {
         ok: true,
         draft: { ...result.document, title: document.title },
-        migrated: result.document.schema !== document.schema,
       };
     }
-    const legacy = (parsed?.version === 1 ? parsed.draft : parsed) as LegacyDraft;
-    if (
-      !legacy ||
-      typeof legacy.title !== "string" ||
-      typeof legacy.audience !== "string" ||
-      typeof legacy.question !== "string" ||
-      !Array.isArray(legacy.readingOrder) ||
-      !legacy.readingOrder.every((id: unknown) => typeof id === "string")
-    )
-      return { ok: false };
-    const document = legacyToComposition(legacy) as { title: string };
-    const result = validateComposition({
-      ...document,
-      title: document.title.trim() || "Untitled composition",
-    });
-    if (!result.ok)
-      return { ok: false };
-    return {
-      ok: true,
-      draft: { ...result.document, title: document.title },
-      migrated: true,
-    };
+    return { ok: false };
   } catch {
     return { ok: false };
   }

package/composition/schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://vcfgdev.github.io/konpeki/composition/v18/schema.json",
+  "$id": "https://vcfgdev.github.io/konpeki/composition/v1/schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "additionalProperties": false,
   "properties": {
@@ -11,7 +11,7 @@
       "type": "string"
     },
     "schema": {
-      "const": "konpeki-composition/v18"
+      "const": "konpeki-composition/v1"
     },
     "slides": {
       "items": {
@@ -2987,6 +2987,6 @@
     "title",
     "slides"
   ],
-  "title": "konpeki-composition/v18",
+  "title": "konpeki-composition/v1",
   "type": "object"
 }

package/composition/schema.ts

@@ -309,7 +309,7 @@ const components = componentKinds.map((kind) => {
 });
 export const schema = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
-  $id: "https://vcfgdev.github.io/konpeki/composition/v18/schema.json",
+  $id: "https://vcfgdev.github.io/konpeki/composition/v1/schema.json",
   title: compositionSchema,
   ...object(
     {

package/composition/types.ts

@@ -1,26 +1,7 @@
 import type { ChartTemplate, DiagramType } from "./visualizations.ts";
 export type { ChartTemplate, DiagramType } from "./visualizations.ts";
 
-export const compositionSchema = "konpeki-composition/v18" as const;
-export const legacyCompositionSchemas = [
-  "konpeki-composition/v1",
-  "konpeki-composition/v2",
-  "konpeki-composition/v3",
-  "konpeki-composition/v4",
-  "konpeki-composition/v5",
-  "konpeki-composition/v6",
-  "konpeki-composition/v7",
-  "konpeki-composition/v8",
-  "konpeki-composition/v9",
-  "konpeki-composition/v10",
-  "konpeki-composition/v11",
-  "konpeki-composition/v12",
-  "konpeki-composition/v13",
-  "konpeki-composition/v14",
-  "konpeki-composition/v15",
-  "konpeki-composition/v16",
-  "konpeki-composition/v17",
-] as const;
+export const compositionSchema = "konpeki-composition/v1" as const;
 export type CanvasSize = { width: number; height: number };
 export const canvasSize = { width: 1920, height: 1080 } as const;
 export const canvasPadding = {