konpeki 0.1.0

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

@@ -0,0 +1,82 @@
+---
+name: authoring-visuals
+description: Creates and revises editable Konpeki visuals from source material. Use for social graphics, article headers, visual explanations and presentations, including revisions to an existing composition.
+---
+
+# Authoring visuals with Konpeki
+
+Deliver an editable composition and visually reviewed output. This skill needs
+the surrounding Konpeki runtime and resources; if they are unavailable, follow
+[SETUP.md](../../../SETUP.md) first. Paths here are relative to this file;
+run commands below from the user's workspace with Konpeki installed locally.
+For repository development, substitute `pnpm konpeki` for
+`npm exec --no -- konpeki`. Keep authored documents outside `node_modules`.
+
+## 1. Interpret the brief
+
+Read [project rules](../../../AGENTS.md) and
+[authoring policy](../../../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.
+
+Use `default` authoring mode unless requested otherwise. Explicit visual
+preferences override taste defaults, not factual fidelity or readability. Use
+the policy's [comparison workflow](../../../AUTHORING.md#explore-an-uncertain-direction)
+only when requested or accepted. A single page is a complete creation; choose
+dimensions for its destination rather than assuming a slide deck.
+
+## 2. Author or revise the composition
+
+Read the [composition contract](../../../composition/README.md). For a new visual,
+create `slides/<name>/composition.json` unless the user supplies another 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
+[design resources](../../../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.
+
+## 3. Validate, render and repair
+
+```sh
+npm exec --no -- konpeki validate slides/<name>/composition.json
+npm exec --no -- konpeki preview slides/<name>/composition.json
+```
+
+Reuse an active file-backed preview for the same document when available. Open
+the exact session URL, or its host-approved remote preview equivalent. 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 [verification guidance](../../../docs/development.md#verification) 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.
+
+## 4. 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.
+
+Keep revision requests in agent chat by default. When explicitly waiting for a
+canvas request, run `npm exec --no -- konpeki wait <composition.json>` alongside the preview.
+**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.
+
+See [canvas workflow](../../../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/AGENTS.md

@@ -0,0 +1,33 @@
+# Konpeki
+
+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.
+
+## Choose the relevant guide
+
+- First-time setup: [SETUP.md](SETUP.md).
+- Creating or revising visuals: [authoring-visuals](.agents/skills/authoring-visuals/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).
+
+## Shared rules
+
+- 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.

package/AUTHORING.md

@@ -0,0 +1,233 @@
+# Authoring visuals
+
+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.
+
+## Destination and surface
+
+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.
+  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.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,70 @@
+# Konpeki
+
+**An editable canvas for agent-made visuals. Create a single explanation or a
+whole presentation, then revise it together.**
+
+Give your coding agent notes, source material and a brief. Konpeki provides the
+shared canvas, design guidance, typography and semantic components for social
+graphics, article headers, visual explanations and presentations.
+
+People and agents edit the same composition. Export a page as PNG, download its
+editable JSON, or use **Present** for a chrome-free presentation.
+
+## Start in your coding agent
+
+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:
+
+```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.
+
+[Paste notes or provide source files.]
+```
+
+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.
+
+## Examples and guides
+
+- [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).
+
+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.
+
+## License
+
+[Apache-2.0](LICENSE). Dependencies and bundled fonts retain their own licenses;
+external design references are credited where used.