konpeki 0.2.0 → 0.3.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;
+}

package/slides/README.md

@@ -1,153 +1,56 @@
-# Decks and examples
+# What can I make with Konpeki?
 
-The image gallery below is for the repository checkout. The npm package includes
-editable examples and prompts but omits gallery PNGs; view this page and its
-screenshots in the repository, or render the source locally.
+Reviewed examples with editable text and vector artwork. Scenarios and data
+are illustrative; these are finished documents, not one-click templates.
 
-## Introducing Konpeki
+Download an example's JSON and choose **Demo Mode → Import** in the
+[playground](https://vcfgdev.github.io/konpeki/). For revision notes and agent
+handoff, open it in a [file-backed preview](../docs/workflow.md#file-backed-editing-with-an-agent).
+Playground edits stay in your browser.
 
-[Introducing Konpeki](introducing-konpeki/README.md) is a six-slide factual product
-introduction authored in the shared canvas's editable composition format.
-Open `?example=introducing-konpeki` in the running application, or download
-its [composition JSON](introducing-konpeki/composition.json) and use **Open**.
+## Explain a system
 
-## Retained drawing references
+An order platform's request handling, data, events and fulfillment.
 
-Each retained example contains its approved `PROMPT.md`, editable `index.tsx`, and final
-PNGs in `screenshots/`. Generation logs, environment records, review reports and
-superseded captures are not included. Subjects and datasets in these retained
-references are fictional; they are not another presentation runtime.
+[Editable JSON](gallery/architecture.json) ·
+[Brief](gallery/PROMPT.md#architecture) · [Source](gallery/SOURCE.md#architecture)
 
-## Representative charts
+![Editable order-platform architecture](gallery/architecture.png)
 
-### Line chart — Tide, page 1
+## Communicate data
 
-Two time series on a shared scale, direct labels, a target line, an event marker
-and an explicit gap for missing data. [Editable source](line-chart/index.tsx).
+A proportional Sankey follows 1,000 trial users through activation and outcomes.
 
-![Line chart with a target and missing-data gap](line-chart/screenshots/page-1.png)
+[Editable JSON](gallery/sankey.json) ·
+[Brief](gallery/PROMPT.md#sankey) · [Source](gallery/SOURCE.md#sankey)
 
-### Grouped bar chart — Birch, page 1
+![Editable trial-user flow with proportional ribbons](gallery/sankey.png)
 
-Horizontal before/after bars with a shared zero baseline and direct values.
-[Editable source](bar-chart/index.tsx).
+## Announce a release
 
-![Grouped horizontal before-and-after bars](bar-chart/screenshots/page-1.png)
+A 1080×1350 Clearpath release announcement: preview, review and export Markdown.
 
-### Vertical bar chart — Fieldnote, page 1
+[Editable JSON](gallery/release.json) ·
+[Brief](gallery/PROMPT.md#release) · [Source](gallery/SOURCE.md#release)
 
-Zero-based columns compare processing throughput with direct values.
-[Editable source](vertical-bar-charts/index.tsx).
+![Clearpath portrait announcement](gallery/release.png)
 
-![Vertical bars comparing indexing throughput](vertical-bar-charts/screenshots/page-1.png)
+## Teach a concept
 
-### Two charts side by side — Fieldnote, page 2
+A 1200×1600 Folio explainer shows a stale save, its rejection and recovery choices.
 
-Throughput on the left and visibility delay on the right show the trade-off,
-with separate units, zero-based scales and acceptance thresholds.
-[Editable source](vertical-bar-charts/index.tsx).
+[Editable JSON](gallery/explainer.json) ·
+[Brief](gallery/PROMPT.md#explainer) · [Source](gallery/SOURCE.md#explainer)
 
-![Side-by-side throughput and visibility-delay bar charts](vertical-bar-charts/screenshots/page-2.png)
+![Folio optimistic-concurrency explainer](gallery/explainer.png)
 
-### Stacked bar chart — Fern, page 1
+## More examples
 
-Direct-count segments compare completion before and after a hint, with the same
-denominator for every task. [Editable source](research-brief/index.tsx).
+- [Introducing Konpeki](introducing-konpeki/README.md): six-page product overview.
+- [Repository cover](github-cover/README.md): 1280×640 social preview.
+- [React/SVG drawing references](drawing-references.md): 18 older examples, not editor-importable documents.
 
-![Stacked bars showing task completion counts](research-brief/screenshots/page-1.png)
-
-## Representative content layouts
-
-### Two columns — Fern, page 2
-
-Parallel columns separate observed evidence from researchers' interpretations.
-[Editable source](research-brief/index.tsx).
-
-![Two-column observations and interpretations](research-brief/screenshots/page-2.png)
-
-### Three columns — Lantern, page 2
-
-Three aligned time-based columns distinguish rollback, partial recovery and
-backlog clearance. [Editable source](incident-workflow/index.tsx).
-
-![Three-column incident recovery stages](incident-workflow/screenshots/page-2.png)
-
-### Main panel and sidebar — Patchnote, page 2
-
-A large illustrative draft panel pairs with a narrower human-review checklist.
-[Editable source](product-introduction/index.tsx).
-
-![Draft interface with a review sidebar](product-introduction/screenshots/page-2.png)
-
-## Representative diagrams and structured information
-
-### Architecture diagram — Parcel Relay, page 1
-
-Named components and attached connectors explain acceptance and delivery.
-[Editable source](architecture/index.tsx).
-
-![Event acceptance and delivery architecture](architecture/screenshots/page-1.png)
-
-### Sequence diagram — Parcel Relay, page 3
-
-Two participant lifelines show a lost response and retry of the same event.
-[Editable source](architecture/index.tsx).
-
-![Timeout and retry sequence diagram](architecture/screenshots/page-3.png)
-
-### Gantt chart — Harbor, page 1
-
-A shared calendar axis compares baseline, completed and forecast work, with
-dependencies and release gates. [Editable source](delivery-plan/index.tsx).
-
-![Gantt chart with dependencies and gates](delivery-plan/screenshots/page-1.png)
-
-### Sankey chart — Brook, page 1
-
-Proportional flows carry 120 tickets from intake through handling to outcomes,
-with direct counts and conservation at each stage.
-[Editable source](sankey/index.tsx).
-
-![Sankey chart of support ticket routing and outcomes](sankey/screenshots/page-1.png)
-
-### Evidence table — Harbor, page 2
-
-Aligned stage–evidence rows use horizontal rules to make gate requirements easy
-to compare. [Editable source](delivery-plan/index.tsx).
-
-![Stage and evidence requirements table](delivery-plan/screenshots/page-2.png)
-
-## All examples
-
-The selections above demonstrate distinct visual patterns rather than ranking
-decks. All final screenshots remain available below.
-
-| Example | Prompt | Final screenshots |
-| --- | --- | --- |
-| Patchnote — product introduction | [Prompt](product-introduction/PROMPT.md) | [Images](product-introduction/screenshots/) |
-| Parcel Relay — architecture | [Prompt](architecture/PROMPT.md) | [Images](architecture/screenshots/) |
-| Fieldnote — experiment | [Prompt](experiment/PROMPT.md) | [Images](experiment/screenshots/) |
-| Lantern — incident workflow | [Prompt](incident-workflow/PROMPT.md) | [Images](incident-workflow/screenshots/) |
-| Moss — comparison | [Prompt](comparison/PROMPT.md) | [Images](comparison/screenshots/) |
-| Juniper — migration | [Prompt](migration/PROMPT.md) | [Images](migration/screenshots/) |
-| Clearpath — OG images | [Prompt](og-images/PROMPT.md) | [Images](og-images/screenshots/) |
-| Alder — article briefing | [Prompt](article-brief/PROMPT.md) | [Images](article-brief/screenshots/) |
-| Waymark — results explanation | [Prompt](results-explanation/PROMPT.md) | [Images](results-explanation/screenshots/) |
-| Dockline — retrospective | [Prompt](retrospective/PROMPT.md) | [Images](retrospective/screenshots/) |
-| Fern — research briefing | [Prompt](research-brief/PROMPT.md) | [Images](research-brief/screenshots/) |
-| Cedar Support — decision memo | [Prompt](decision-memo/PROMPT.md) | [Images](decision-memo/screenshots/) |
-| Harbor — delivery plan | [Prompt](delivery-plan/PROMPT.md) | [Images](delivery-plan/screenshots/) |
-| Folio — teaching | [Prompt](teaching/PROMPT.md) | [Images](teaching/screenshots/) |
-| Tide — line chart | [Prompt](line-chart/PROMPT.md) | [Images](line-chart/screenshots/) |
-| Birch — bar chart | [Prompt](bar-chart/PROMPT.md) | [Images](bar-chart/screenshots/) |
-| Fieldnote — vertical and paired bar charts | [Prompt](vertical-bar-charts/PROMPT.md) | [Images](vertical-bar-charts/screenshots/) |
-| Brook — Sankey chart | [Prompt](sankey/PROMPT.md) | [Images](sankey/screenshots/) |
-
-The `index.tsx` files are retained presentation-runtime-independent React/SVG
-drawing references, not runnable routes or a second deck format. Agents can
-inspect and adapt their techniques, then convert supported SVG primitives into
-editable vector elements in the owning composition component.
-Shared authoring resources live in `design/` and `lib/`.
-
-Screenshots reflect the final reviewed browser renders, including manual repairs.
-They do not establish PDF/PPTX, cross-browser or cross-application fidelity.
+These four gallery exports are repository-only; their authoring projects are
+maintained separately. They are not bundled in npm or the hosted playground.
+The introduction and cover JSONs are included in npm; the playground bundles
+the introduction. View this gallery in the repository for its screenshots.

package/slides/drawing-references.md

@@ -0,0 +1,32 @@
+# React/SVG drawing references
+
+These 18 fictional examples preserve the earlier authoring approach: React/SVG
+source, original briefs and reviewed screenshots. Use them for drawing, typography
+and layout techniques; **they cannot be imported directly into the editor**.
+For editable documents, see the [native gallery](README.md).
+
+To adapt trusted source, follow the [conversion guide](../docs/development.md#reactsvg-drawing-references)
+and inspect the result in the canvas. These files are not runnable app routes.
+npm includes source and briefs; screenshots remain in the repository and show
+the historical browser renders, not export or cross-application fidelity.
+
+| Example / source | Brief | Screenshots |
+| --- | --- | --- |
+| [Patchnote — product introduction](product-introduction/index.tsx) | [Brief](product-introduction/PROMPT.md) | [Images](product-introduction/screenshots/) |
+| [Parcel Relay — architecture and sequence](architecture/index.tsx) | [Brief](architecture/PROMPT.md) | [Images](architecture/screenshots/) |
+| [Fieldnote — experiment](experiment/index.tsx) | [Brief](experiment/PROMPT.md) | [Images](experiment/screenshots/) |
+| [Lantern — incident workflow](incident-workflow/index.tsx) | [Brief](incident-workflow/PROMPT.md) | [Images](incident-workflow/screenshots/) |
+| [Moss — comparison](comparison/index.tsx) | [Brief](comparison/PROMPT.md) | [Images](comparison/screenshots/) |
+| [Juniper — migration](migration/index.tsx) | [Brief](migration/PROMPT.md) | [Images](migration/screenshots/) |
+| [Clearpath — OG images](og-images/index.tsx) | [Brief](og-images/PROMPT.md) | [Images](og-images/screenshots/) |
+| [Alder — article briefing](article-brief/index.tsx) | [Brief](article-brief/PROMPT.md) | [Images](article-brief/screenshots/) |
+| [Waymark — results explanation](results-explanation/index.tsx) | [Brief](results-explanation/PROMPT.md) | [Images](results-explanation/screenshots/) |
+| [Dockline — retrospective](retrospective/index.tsx) | [Brief](retrospective/PROMPT.md) | [Images](retrospective/screenshots/) |
+| [Fern — research and stacked bars](research-brief/index.tsx) | [Brief](research-brief/PROMPT.md) | [Images](research-brief/screenshots/) |
+| [Cedar Support — decision memo](decision-memo/index.tsx) | [Brief](decision-memo/PROMPT.md) | [Images](decision-memo/screenshots/) |
+| [Harbor — delivery plan and Gantt](delivery-plan/index.tsx) | [Brief](delivery-plan/PROMPT.md) | [Images](delivery-plan/screenshots/) |
+| [Folio — teaching](teaching/index.tsx) | [Brief](teaching/PROMPT.md) | [Images](teaching/screenshots/) |
+| [Tide — line chart](line-chart/index.tsx) | [Brief](line-chart/PROMPT.md) | [Images](line-chart/screenshots/) |
+| [Birch — grouped bar chart](bar-chart/index.tsx) | [Brief](bar-chart/PROMPT.md) | [Images](bar-chart/screenshots/) |
+| [Fieldnote — vertical and paired bars](vertical-bar-charts/index.tsx) | [Brief](vertical-bar-charts/PROMPT.md) | [Images](vertical-bar-charts/screenshots/) |
+| [Brook — Sankey chart](sankey/index.tsx) | [Brief](sankey/PROMPT.md) | [Images](sankey/screenshots/) |

package/slides/github-cover/PROMPT.md

@@ -0,0 +1,21 @@
+# Brief
+
+> i'd like a cover image for github repo. build it with konpeki
+
+## Adaptation
+
+- Assumed a 1280×640 GitHub social preview; unspecified mode resolved to default.
+- Use the existing blue mark, white canvas and IBM Plex Sans. Lead with “Konpeki”
+  and “Create clear visuals with your coding agent.”
+- Arrange different canvas sizes on a consistent grid, with white backgrounds
+  and text, image, chart, diagram and table motifs. Avoid labels or a single
+  workflow that suggests these are the only possible outputs.
+- A generated concept informed placement; the final uses editable text and
+  vectors, not a flattened concept image.
+
+## Sources
+
+- Product: [README](../../README.md) and [workflow](../../docs/workflow.md).
+- Brand: [project mark](../../src/assets/konpeki-mark.png) and bundled IBM Plex
+  Sans under its existing font license.
+- Canvas motifs are conceptual, not screenshots.

package/slides/github-cover/README.md

@@ -0,0 +1,21 @@
+# GitHub repository cover
+
+[composition.json](composition.json) holds the editable text and vectors;
+[cover.png](cover.png) is its 1280×640 Konpeki PNG export.
+The varied canvas sizes illustrate possible formats, not a fixed workflow.
+
+Open from the repository root, edit, then choose **Export PNG**:
+
+```sh
+mise exec -- pnpm konpeki preview slides/github-cover/composition.json
+```
+
+Refresh [public/og.png](../../public/og.png) for the playground's social cards.
+Uploading the cover to GitHub's repository social-preview setting is separate.
+
+[Brief and sources](PROMPT.md). [author.ts](author.ts) reconstructs the initial
+composition using Node.js and ImageMagick; **it overwrites canvas edits**.
+
+Original review: validation, typecheck and build passed; all five components and
+IBM Plex Sans loaded. Inspected the 1280×640 export and a 640×320 copy for alignment,
+clipping and legibility.

package/slides/github-cover/author.ts

@@ -0,0 +1,67 @@
+import {execFileSync} from 'node:child_process';
+import {writeFileSync} from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {assertComposition} from '../../composition/validate.ts';
+import {compositionSchema, type CompositionComponent, type CompositionDocument, type VectorElement} from '../../composition/types.ts';
+
+// Reproduce the existing mark's alpha silhouette as editable vector geometry.
+const mask=execFileSync('magick',[fileURLToPath(new URL('../../src/assets/konpeki-mark.png',import.meta.url)),'-alpha','extract','-threshold','50%','-depth','8','gray:-']);
+let outline='';
+for(let y=0;y<128;y++)for(let x=0;x<128;x++){
+  if(mask[y*128+x]<128)continue;
+  const start=x;
+  while(x+1<128&&mask[y*128+x+1]>=128)x++;
+  outline+=`M${start} ${y}h${x-start+1}v1H${start}Z`;
+}
+const ink='#202630',blue='#007fb5',lightGray='#b2bdc2';
+const text=(id:string,content:string,x:number,y:number,width:number,height:number,size:number,weight:400|600=600):CompositionComponent=>({
+  id,kind:'text-block',content,slotIds:[`${id}-content`],preferredRect:{x,y,width,height},
+  textStyle:{size,weight,lineHeight:1.18,color:'ink',font:'heading'},
+  appearance:{role:id==='brand'?'title':'body',alignment:'start',border:'none',rule:'none'},
+});
+const elements:VectorElement[]=[
+  {id:'cover-frame',kind:'rect',attributes:{x:10,y:8,width:260,height:140,rx:8,fill:'#ffffff',stroke:blue,'stroke-width':2.5}},
+  {id:'cover-mark',kind:'rect',attributes:{x:28,y:28,width:42,height:42,rx:4,fill:blue}},
+  {id:'cover-title',kind:'rect',attributes:{x:86,y:29,width:144,height:13,rx:3,fill:lightGray}},
+  {id:'cover-copy-1',kind:'rect',attributes:{x:86,y:53,width:112,height:7,rx:3,fill:lightGray}},
+  {id:'cover-copy-2',kind:'rect',attributes:{x:28,y:102,width:164,height:7,rx:3,fill:lightGray}},
+  {id:'cover-accent',kind:'rect',attributes:{x:211,y:96,width:39,height:28,rx:4,fill:'#eaf6fb'}},
+  {id:'square-frame',kind:'rect',attributes:{x:292,y:8,width:140,height:140,rx:8,fill:'#ffffff',stroke:blue,'stroke-width':2.5}},
+  {id:'square-title',kind:'rect',attributes:{x:311,y:28,width:82,height:10,rx:3,fill:lightGray}},
+  {id:'square-bar-1',kind:'rect',attributes:{x:314,y:93,width:18,height:31,rx:3,fill:blue}},
+  {id:'square-bar-2',kind:'rect',attributes:{x:342,y:72,width:18,height:52,rx:3,fill:'#5cb9df'}},
+  {id:'square-bar-3',kind:'rect',attributes:{x:370,y:52,width:18,height:72,rx:3,fill:'#9adbed'}},
+  {id:'square-baseline',kind:'path',attributes:{d:'M307 126H410',fill:'none',stroke:lightGray,'stroke-width':2}},
+  {id:'portrait-frame',kind:'rect',attributes:{x:10,y:172,width:145,height:230,rx:8,fill:'#ffffff',stroke:blue,'stroke-width':2.5}},
+  {id:'portrait-title',kind:'rect',attributes:{x:28,y:193,width:94,height:11,rx:3,fill:lightGray}},
+  {id:'portrait-visual',kind:'rect',attributes:{x:28,y:224,width:109,height:81,rx:5,fill:'#eaf6fb'}},
+  {id:'portrait-rule',kind:'path',attributes:{d:'M45 285L76 247 96 270 122 236',fill:'none',stroke:blue,'stroke-width':4}},
+  {id:'portrait-copy-1',kind:'rect',attributes:{x:28,y:326,width:92,height:7,rx:3,fill:lightGray}},
+  {id:'portrait-copy-2',kind:'rect',attributes:{x:28,y:344,width:108,height:7,rx:3,fill:lightGray}},
+  {id:'portrait-copy-3',kind:'rect',attributes:{x:28,y:362,width:74,height:7,rx:3,fill:lightGray}},
+  {id:'slide-frame',kind:'rect',attributes:{x:180,y:172,width:252,height:144,rx:8,fill:'#ffffff',stroke:blue,'stroke-width':2.5}},
+  {id:'slide-title',kind:'rect',attributes:{x:199,y:190,width:115,height:11,rx:3,fill:lightGray}},
+  {id:'diagram-path',kind:'path',attributes:{d:'M305 251V270H231V278M305 270H379V278',fill:'none',stroke:lightGray,'stroke-width':3}},
+  {id:'diagram-parent',kind:'rect',attributes:{x:284,y:215,width:42,height:36,rx:7,fill:blue}},
+  {id:'diagram-child-1',kind:'rect',attributes:{x:210,y:278,width:42,height:25,rx:6,fill:'#eaf6fb',stroke:blue,'stroke-width':2}},
+  {id:'diagram-child-2',kind:'rect',attributes:{x:358,y:278,width:42,height:25,rx:6,fill:'#eaf6fb',stroke:blue,'stroke-width':2}},
+  {id:'table-frame',kind:'rect',attributes:{x:180,y:338,width:252,height:64,rx:8,fill:'#ffffff',stroke:blue,'stroke-width':2.5}},
+  {id:'table-header',kind:'rect',attributes:{x:181,y:339,width:250,height:20,rx:7,fill:'#eaf6fb'}},
+  {id:'table-grid',kind:'path',attributes:{d:'M250 339V401M330 339V401M181 359H431M181 380H431',fill:'none',stroke:lightGray,'stroke-width':2}},
+  {id:'table-emphasis',kind:'rect',attributes:{x:196,y:365,width:38,height:8,rx:3,fill:blue}},
+];
+const components:CompositionComponent[]=[
+  text('brand','Konpeki',150,120,480,110,84),
+  {id:'brand-mark',kind:'image',slotIds:['brand-mark-content'],preferredRect:{x:64,y:143,width:66,height:66},customVisual:{format:'vector',viewBox:{x:0,y:0,width:128,height:128},description:'Konpeki blue brush mark',elements:[{id:'mark-silhouette',kind:'path',attributes:{d:outline,fill:blue}}]}},
+  text('promise','Create clear visuals',64,302,680,90,62),
+  text('audience','with your coding agent.',64,400,660,76,44,400),
+  {id:'visual-family',kind:'image',slotIds:['visual-family-content'],preferredRect:{x:772,y:106,width:444,height:412},customVisual:{format:'vector',viewBox:{x:0,y:0,width:444,height:412},description:'Aligned white canvases using Konpeki text, image, bar chart, line chart, diagram and table components.',elements}},
+];
+const document:CompositionDocument={schema:compositionSchema,title:'Konpeki GitHub cover',authoringMode:'default',theme:{id:'plex',mode:'paper'},slides:[{
+  id:'github-cover',name:'GitHub repository cover',canvas:{width:1280,height:640},innerPadding:{top:64,right:64,bottom:64,left:64},pageNumber:{style:'none',color:'muted'},
+  audience:'Developers discovering Konpeki on GitHub',question:'What can I create with Konpeki and my coding agent?',intendedViewingSize:'social',components,
+  contentSlots:components.map(c=>({id:c.slotIds[0],label:c.id,role:'body',required:true,instruction:c.kind==='text-block'?c.content??'':c.customVisual?.description??''})),
+  groups:[],relationships:[],readingOrder:components.map(c=>({kind:'component',id:c.id})),paintOrder:components.map(c=>c.id),
+}]};
+assertComposition(document);
+writeFileSync(new URL('composition.json',import.meta.url),JSON.stringify(document,null,2)+'\n');