{"owner":"OpenCoworkAI","repo":"open-codesign","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md"],"skills":{"AGENTS.md":"# AGENTS.md - Open CoDesign\n\nInstructions for Codex and other AI coding agents working in this repository. Read this before making changes.\n\n`CLAUDE.md` may lag behind the current plan. For Codex work, treat this file as the public source of truth. If local internal docs such as `docs/VISION.md`, `docs/PRINCIPLES.md`, or `docs/v0.2-plan.md` exist, use them as additional context; if they are missing, do not block public-contributor work on them.\n\n## What This Project Is\n\nOpen CoDesign is an open-source desktop design agent. It turns prompts, local files, skills, scaffolds, brand systems, and model output into design artifacts on the user's laptop.\n\nThe v0.2 direction is no longer a single-prompt generator. Each design is a long-running pi session with a real workspace. The agent can read and edit files, run permissioned commands, ask structured questions, preview artifacts, expose tweak controls, generate images when the configured model supports it, and produce `DESIGN.md` design-system artifacts.\n\nThe original inspiration was Claude Design. The product boundary is now clearer: Open CoDesign borrows proven coding-agent mechanics, then adds design-specific tools and a local-first workspace model.\n\nProduct model: a `Design` owns a workspace. The agent edits design source files in that workspace; the preview runtime turns those sources into a rendered web document; exporters turn the rendered/source document into standard outputs such as HTML, PDF, PPTX, ZIP, or Markdown. In v0.2 the default source entry is `App.jsx`; `index.html` is reserved for standalone exports or legacy workspace files.\n\n`docs/` is gitignored. Maintainers may have internal plans, handoffs, and research locally; public contributors may not. Do not cite `docs/**` in public PR review comments unless the file exists in the public checkout.\n\n## Hard Constraints\n\nThese are project commitments, not preferences:\n\n1. No bundled model runtimes. Do not ship Ollama, llama.cpp, Python, browser binaries, or model weights inside the installer. Use system installs or lazy-download with user-visible consent.\n2. BYOK only. No hosted account, proxied API, or telemetry by default. User credentials stay in human-readable local config.\n3. Local-first storage. v0.2 uses pi JSONL sessions plus real workspace files. Existing v0.1 SQLite data may be migrated, but do not add new SQLite tables for sessions, chat history, comments, snapshots, or design files.\n4. Every design has a workspace. No sealed/open split in v0.2. The workspace filesystem is the source of truth for artifacts and assets.\n5. Shipped app/runtime dependencies, bundled assets, scaffolds, skills, brand refs, and copied code must be MIT-compatible permissive. Reject GPL, AGPL, SSPL, proprietary deps, and unclear copied assets in anything that is bundled, linked, imported by app code, or distributed to users. Workflow-only CI/release tools may use copyleft licenses when they are not vendored, bundled, linked, or copied into the product; document the reason and keep their outputs limited to ordinary metadata or manifests.\n6. Lazy-load heavy features. PPTX export, web capture, scaffolds, skills, brand refs, and image generation must load on demand rather than at app start.\n7. Reuse pi primitives first. `pi-coding-agent` owns sessions, built-in tools, bash execution, event streaming, model registry, provider registration, and capability data unless a design-specific need proves otherwise.\n8. Brand values are data, not model memory. Use `DESIGN.md`, user files, official CSS/SVG/screenshots, or brand URLs. Do not invent brand hex values from memory.\n9. PRs should stay compatible, upgradeable, lean, and elegant. If `docs/PRINCIPLES.md` is present, use its Principles 5b wording as the detailed checklist.\n\n## AI Visibility For Web Work\n\nWhen building or updating any website, project homepage, product page, personal site, documentation site, blog, or public project page, include AI visibility in the default delivery scope unless the user explicitly opts out.\n\n- Add `/llms.txt` with a concise Markdown overview of the site, author or organization, key pages, canonical project or product descriptions, and links to machine-readable resources.\n- Add `/llms-full.txt` when the site has enough substantive public content to justify a fuller AI-readable context file.\n- Configure `robots.txt` deliberately: allow search and retrieval crawlers that help AI systems cite or retrieve public content, and treat training crawlers as a separate policy decision.\n- Maintain `sitemap.xml` and make sure it covers important public pages. Mention Google Search Console and Bing Webmaster Tools submission when relevant.\n- Add appropriate JSON-LD structured data where useful, such as `Person`, `Organization`, `WebSite`, `BlogPosting`, `SoftwareApplication`, `FAQPage`, or `CreativeWork`.\n- Prefer clean Markdown or JSON machine-readable endpoints for important entities such as profiles, projects, posts, docs, releases, FAQs, and product facts.\n- Keep the content truthful, source-backed, and non-spammy. The goal is to help AI systems understand and cite existing real content accurately, not to generate low-quality SEO filler.\n\n## Current Architecture Direction\n\n### Agent Runtime\n\n- Use `pi-coding-agent` and `pi-ai`.\n- Use pi built-ins for `read`, `write`, `edit`, `bash`, `grep`, `find`, and `ls`.\n- Gate tools through the pi `tool_call` hook and the Open CoDesign permission UI.\n- Read capabilities from pi `Model<T>` fields such as `input`, `reasoning`, `cost`, `contextWindow`, and `maxTokens`.\n- Register custom providers through `pi.registerProvider()`. Do not build a parallel provider SDK layer.\n- All LLM calls go through `pi-ai`; do not import provider SDKs directly in app code.\n\n### Storage\n\n- Design equals pi session.\n- Session history lives under app user data as pi JSONL.\n- Design source files, generated JSX/HTML/CSS, assets, exports, `AGENTS.md`, and `DESIGN.md` live in the user workspace.\n- Workspace settings live in `.codesign/settings.json` with `schemaVersion`.\n- `settings.local.json` is personal and should stay gitignored.\n- v0.1 SQLite is legacy data to migrate, not the v0.2 storage model.\n\n### Tools\n\nThe v0.2 tool surface is pi's seven built-ins plus Open CoDesign design tools:\n\n- `ask(questions)` renders structured questions and waits for the user.\n- `scaffold(kind, path)` copies a curated starter into the workspace.\n- `skill(name)` lazy-loads skill text from a manifest.\n- `preview(path)` renders artifacts and returns console errors, asset errors, DOM outline, metrics, and screenshots for vision models.\n- `gen_image(prompt, path)` writes generated images to disk when capability and provider config allow it.\n- `tweaks(blocks)` declares editable controls across files.\n- `todos(items)` shows task state for complex turns.\n- `done(path)` ends a turn after preview self-check.\n\nDo not reintroduce a verifier subagent, snip tool, custom bash tool, custom list-files tool, or agent-written working memory for v0.2 unless the plan changes.\n\n### Design System\n\n- `DESIGN.md` follows the Google spec and can be both input and output.\n- Agent-generated multi-screen work should keep visual consistency by updating `DESIGN.md` as tokens emerge.\n- Built-in brand refs must include attribution, source, license metadata, and a \"not affiliated\" note.\n- Built-in skills use the agentskills-style `SKILL.md` format.\n- Skill and scaffold manifests should carry license and source metadata.\n\n### Resource Boundaries\n\n- Markdown skills in `apps/desktop/resources/templates/skills/*.md` are method rules. They tell the agent how to work; they do not copy files into a workspace.\n- Brand refs in `apps/desktop/resources/templates/brand-refs/*/DESIGN.md` are reference-only design systems loaded as `skill(\"brand:<slug>\")`. Do not edit them for a project; translate adopted choices into the workspace `DESIGN.md`.\n- Scaffolds in `apps/desktop/resources/templates/scaffolds/**` are concrete starter/source assets copied by `scaffold(kind, destPath)`. They can be JSX, HTML, CSS, Markdown, or other text formats if the manifest describes them accurately.\n- Design-skill snippets in `apps/desktop/resources/templates/design-skills/*.jsx` are copyable JSX component patterns exposed through the virtual filesystem as `skills/<file>.jsx`. They are source snippets, not markdown skills and not brand authority.\n- Workspace `DESIGN.md` is the project-specific design-system baton. It is authoritative for the current design once present, and generated work should preserve or repair it rather than treating it as another preset.\n\n### Built-In Starters And Scaffolds\n\n- Treat starter/scaffold assets as product code, not prompt filler. Review the actual file contents as well as the manifest before changing or adding presets.\n- Keep source format and filename extension aligned. Full HTML documents must live as `.html`, JSX/React starters as `.jsx`, and CSS snippets as `.css`. The `scaffold()` tool should preserve the source extension when copying, but the preset asset itself should still be correctly named and described.\n- Built-in HTML starters should be self-contained and previewable in the current runtime. Do not add Reveal.js, React, Babel, Chart.js, or other CDN/runtime scripts to scaffold assets. If a starter needs runtime behavior, use local plain HTML/CSS/JS or an app-provided/lazy-loaded dependency with a clear license path.\n- Avoid weak placeholder copy such as \"Deck title\", \"Page content\", \"Replace this\", or \"Point one\". Use neutral, usable sample content and expose obvious replacement points through `TWEAK_DEFAULTS` when the starter is JSX.\n- Manifest descriptions should say when a starter is HTML or CSS and should call out extension-sensitive assets, especially files that agents might otherwise copy into `_starters/*.jsx`.\n- When touching `apps/desktop/resources/templates/scaffolds/**`, audit for extension/content mismatches, external network URLs, stale placeholder copy, and manifest drift. Add or update focused scaffold/runtime tests when the change affects copy paths, preview classification, or tool details.\n\n## Stack and Conventions\n\n- Package manager: `pnpm` only. Never use `npm` or `yarn`.\n- Build orchestration: Turborepo.\n- Lint and format: Biome.\n- Tests: Vitest for unit tests, Playwright for E2E.\n- TypeScript: strict mode, `verbatimModuleSyntax`, bundler resolution, no `any`.\n- Commits: Conventional Commits.\n- Versioning: Changesets. Do not hand-edit `CHANGELOG.md`.\n- Node: 22 LTS, pinned by `.nvmrc` and `engines`.\n- Exact package versions live in `package.json`, workspace manifests, and `pnpm-lock.yaml`. Read those files instead of trusting stale docs.\n\n### Frontend\n\n- React + Vite + Tailwind v4 + CSS variables.\n- State uses Zustand. Do not introduce Redux, Recoil, or MobX.\n- Components use Radix primitives and custom shadcn-style wrappers in `packages/ui`.\n- Icons use `lucide-react`.\n- Forms use native `<form>` and `FormData`.\n- Animations use Tailwind transitions. Do not introduce framer-motion or motion.\n- App chrome must use `packages/ui` tokens. Generated design sources and exports may define their own visual system.\n- Sandbox preview remains Electron iframe `srcdoc` plus runtime tooling. `App.jsx` JSX source is wrapped by the runtime for preview/export; exported `index.html` is the standalone deliverable.\n\n## Repository Layout\n\n```\napps/\n  desktop/           # Electron app shell, main process, renderer\npackages/\n  core/              # Agent orchestration, prompts, design tools\n  providers/         # pi integration and provider compatibility shims\n  runtime/           # Sandbox renderer and preview runtime\n  ui/                # Shared app UI tokens and components\n  artifacts/         # Artifact schemas and bundle formats\n  exporters/         # PDF / PPTX / ZIP exporters, lazy-loaded\n  templates/         # Built-in examples and starter templates\n  shared/            # Shared types, utils, schemas\ndocs/                # Internal vision, plans, principles, research; gitignored\nexamples/            # Public demo reproductions\n```\n\n## Doing Tasks Here\n\n- For non-trivial architecture or product work, read `docs/VISION.md`, `docs/PRINCIPLES.md`, and `docs/v0.2-plan.md` when they exist locally. Public checkouts may not have `docs/`; in that case rely on this file, public issues/PRs, and README context.\n- Use planning files in `.Codex/workspace/` for tasks spanning more than five tool calls or more than three files when a durable local plan would help. Do not create planning churn for small, direct fixes.\n- Use git worktrees for parallel or unrelated feature work. Do not mix two unrelated branches in one checkout.\n- Check `docs/RESEARCH_QUEUE.md` before touching sandbox, inline comments, tweaks, PPTX, pi capabilities, scaffolds, skills, or brand refs when that file exists locally.\n- Keep edits scoped. Avoid drive-by refactors.\n- Before adding a shipped/runtime dependency, check license, install size, alternatives, and whether it can be a peer dep. For workflow-only tools, document why they are not bundled and whether their outputs affect distributed artifacts.\n- Add or update Vitest coverage for feature work. Broaden tests when changing migrations, permissions, tool hooks, or shared contracts.\n- Prefer manifest and switch logic over registries until two real callers need more.\n- Comment only when the reason would surprise the next maintainer.\n\n## Permission Model\n\nOpen CoDesign uses one permission model with tiers:\n\n- Tier 0: workspace-local reads/writes, simple file commands, and read-only git may run without interruption.\n- Tier 1: installs, build commands, non-local network fetches, and cwd-external commands ask once and can be allowlisted.\n- Tier 2: publishing, pushing, sudo, and high-blast-radius commands ask every time.\n- Tier 3: destructive system commands, `curl | sh`, and system-directory writes are blocked without override.\n\nDo not hide blocked tool calls. Show the command, path, tier, and reason.\n\n## Things to Avoid\n\n- Adding `node_modules`, build outputs, `.env*`, generated release artifacts, or private local files to git.\n- Importing `@anthropic-ai/sdk`, `openai`, `@google/genai`, or other provider SDKs in app code.\n- Writing tests that mock the LLM at the SDK level. Mock at the core or pi boundary.\n- Adding tracking, analytics, account flows, cloud sync, or auto-update without explicit opt-in UX.\n- Hard-coding user paths. Respect XDG, Electron `app.getPath()`, and workspace roots.\n- Adding new SQLite-backed feature state for v0.2 session/design data.\n- Introducing `project` as a product abstraction in v0.2. Multiple sessions can share a workspace, but the sidebar lists sessions.\n- Exposing session branching UI, undo/version rollback, MCP support, or community skill installation in v0.2 unless the plan changes.\n- Using `console.*` in `apps/desktop/src/main/**`, `packages/core/**`, `packages/providers/**`, `packages/exporters/**`, or `packages/shared/**`. Use the project logger.\n\n## Useful Commands\n\n```bash\npnpm i\npnpm dev\npnpm test\npnpm test:e2e\npnpm lint\npnpm typecheck\npnpm build\npnpm changeset\n```\n","CLAUDE.md":"# CLAUDE.md — Open CoDesign\n\nInstructions for Claude Code (and any AI coding agent) working in this repository. Read this before making changes.\n\n## What this project is\n\nopen-codesign is an Electron desktop app that turns natural-language prompts into design artifacts (HTML prototypes, PDFs, PPTX decks, marketing assets). It's the open-source counterpart to Anthropic's Claude Design, with multi-provider model support via `pi-ai` and a local-first storage model.\n\nThe full vision and locked decisions live in `docs/VISION.md` when the internal docs are present locally. Public checkouts may not have `docs/`; in that case use `AGENTS.md`, public issues/PRs, and README context instead of blocking.\n\n> Note: `docs/` is gitignored — internal team materials (research, roadmaps, handoffs) live there but are not part of the public repo. Clone contributors will not have this directory; team members will find it present locally after cloning and copying the internal docs back.\n\n## Hard constraints (do not violate)\n\nThese are project-level commitments, not preferences:\n\n1. **No bundled model runtimes.** No Ollama, llama.cpp, Python, or browser binaries shipped in the installer. Use system installs or lazy-download on demand.\n2. **BYOK only.** No proxied API calls, no cloud account, no telemetry by default. User credentials stay in `~/.config/open-codesign/config.toml` (plaintext, file mode 0600 — matching Claude Code / Codex / gh CLI conventions).\n3. **Local-first storage.** v0.2 design state is file/session based and local-first. Do not add new SQLite-backed session/design feature state.\n4. **Permissive shipped dependencies.** Shipped app/runtime dependencies, bundled assets, scaffolds, skills, brand refs, and copied code must be MIT-compatible permissive. Workflow-only CI/release tools may use copyleft licenses when they are not vendored, bundled, linked, or copied into the product; document the reason.\n5. **Lazy-load heavy features.** PPTX export, web capture, codebase scan, etc. must dynamic-import on first use, not on app start.\n6. **Compatibility, upgradeability, no bloat, elegance** — the four PRINCIPLES §5b checks. Every PR description must mark all four green.\n\n## Stack & conventions\n\n- **Package manager**: `pnpm` only. Never use `npm` or `yarn`. Workspace declared in `pnpm-workspace.yaml`.\n- **Build orchestration**: Turborepo.\n- **Lint + format**: Biome (single tool, no ESLint + Prettier).\n- **Tests**: Vitest (unit) + Playwright (E2E). New features require at least one Vitest test.\n- **TypeScript**: `strict: true`, `verbatimModuleSyntax: true`, `moduleResolution: \"bundler\"`. No `any`.\n- **Commits**: Conventional Commits, enforced by commitlint.\n- **Versioning**: Changesets. Don't hand-edit `CHANGELOG.md`.\n- **Node**: 22 LTS (pinned via `.nvmrc` + `engines`).\n- **Model layer**: All LLM calls go through `@mariozechner/pi-ai`. Don't import provider SDKs directly in app code; if pi-ai lacks a feature, add it to `packages/providers` as a thin extension.\n\n### Frontend stack (locked)\n\n- **UI framework**: React 19 + Vite 6\n- **Styles**: Tailwind v4 + CSS variables (tokens in `packages/ui`)\n- **State**: Zustand (do not introduce Redux / Recoil / MobX)\n- **Routing**: native `useState` view switching at first; TanStack Router only when route count > 5\n- **Components**: Radix UI primitives + custom shadcn-style wrappers in `packages/ui`\n- **Icons**: `lucide-react` (only)\n- **Forms**: native `<form>` + `FormData` (do not introduce react-hook-form / formik)\n- **Animations**: Tailwind transitions (do not introduce framer-motion / motion)\n- **Sandbox renderer**: Electron iframe `srcdoc` + esbuild-wasm + import maps (see `docs/research/03-sandbox-runtime.md`)\n- **Electron version**: latest stable, but NOT 41.x (cross-origin isolation regression)\n- **Storage**: file/session-backed design state; TOML files for config (no electron-store blob)\n\n## Repository layout\n\n```\napps/\n  desktop/           # Electron app shell (main + renderer)\npackages/\n  core/              # Generation orchestration (prompt → artifact pipeline)\n  providers/         # pi-ai adapter + custom provider extensions\n  runtime/           # Sandbox renderer (iframe-based preview)\n  ui/                # Shared design system (aligned with open-cowork tokens)\n  artifacts/         # Artifact schema (HTML / React / SVG / PPTX)\n  exporters/         # PDF / PPTX / ZIP exporters (lazy-loaded)\n  templates/         # Built-in demo prompts and starter templates\n  shared/            # Types, utils, zod schemas\ndocs/                # Vision, roadmap, principles, RFCs (gitignored — internal only)\nexamples/            # Reproductions of Claude Design public demos\n```\n\n## Doing tasks here\n\n- **Read `docs/VISION.md` and `docs/PRINCIPLES.md` when available** for any non-trivial change. Public contributors may not have internal docs.\n- **Use the planning-with-files workflow** for any task spanning > 5 tool calls or > 3 files. Plans live in `.claude/workspace/`.\n- **Use git worktrees for parallel work.** See `docs/COLLABORATION.md` for the workflow. Never run two unrelated feature branches in the same checkout.\n- **Check `docs/RESEARCH_QUEUE.md` when available** before starting work that touches sandbox / inline-comment / slider / PPTX / pi-ai capabilities — research may still be pending and decisions unresolved.\n- **Respect the lean budget.** Before adding a dependency: search for a tiny alternative, consider inlining, ask if it can be a peer dep.\n- **UI must use `packages/ui` tokens.** Don't hard-code colors, fonts, or spacing in app code. If a token is missing, add it to `packages/ui` first.\n- **No \"design for the future\" abstractions.** Three similar lines is fine. Don't introduce factories, plugin systems, or config-driven dispatch unless we have two real callers.\n- **No comments explaining what code does.** Names should do that. Only comment the *why* when it's surprising.\n- **Schema-version everything that lives on disk.** Config files, SQLite tables, IPC payloads, exported bundle formats — all carry a `schemaVersion` field so we can migrate without breaking older installs.\n\n## Things to avoid\n\n- ❌ Adding `node_modules`, build outputs, or `.env*` files to git\n- ❌ Importing from a provider SDK (`@anthropic-ai/sdk`, `openai`, `@google/genai`) in app code\n- ❌ Writing tests that mock the LLM at the SDK level — mock at the `core` boundary instead\n- ❌ Adding tracking, analytics, or auto-update without explicit opt-in UX\n- ❌ Hard-coding any path; respect XDG base dirs / Electron `app.getPath()`\n- ❌ Synchronous I/O in the main process\n- ❌ `console.*` in `apps/desktop/src/main/**`, `packages/core/**`, `packages/providers/**`, `packages/exporters/**`, `packages/shared/**` — use `getLogger()` (main) or the injected `CoreLogger` (core/providers/exporters). Biome enforces this.\n\n## Useful commands\n\n```bash\npnpm i                  # install (uses Corepack-pinned pnpm)\npnpm dev                # start Electron + Vite renderer\npnpm test               # vitest watch\npnpm test:e2e           # playwright\npnpm lint               # biome check\npnpm typecheck          # tsc --noEmit across workspace\npnpm build              # produce signed Mac/Win installers\npnpm changeset          # record a release-worthy change\n```\n\n## Open questions / pending research\n\nSee `docs/RESEARCH_QUEUE.md`. Don't prematurely lock in answers to questions still under investigation.\n"},"files":{"AGENTS.md":"# AGENTS.md - Open CoDesign\n\nInstructions for Codex and other AI coding agents working in this repository. Read this before making changes.\n\n`CLAUDE.md` may lag behind the current plan. For Codex work, treat this file as the public source of truth. If local internal docs such as `docs/VISION.md`, `docs/PRINCIPLES.md`, or `docs/v0.2-plan.md` exist, use them as additional context; if they are missing, do not block public-contributor work on them.\n\n## What This Project Is\n\nOpen CoDesign is an open-source desktop design agent. It turns prompts, local files, skills, scaffolds, brand systems, and model output into design artifacts on the user's laptop.\n\nThe v0.2 direction is no longer a single-prompt generator. Each design is a long-running pi session with a real workspace. The agent can read and edit files, run permissioned commands, ask structured questions, preview artifacts, expose tweak controls, generate images when the configured model supports it, and produce `DESIGN.md` design-system artifacts.\n\nThe original inspiration was Claude Design. The product boundary is now clearer: Open CoDesign borrows proven coding-agent mechanics, then adds design-specific tools and a local-first workspace model.\n\nProduct model: a `Design` owns a workspace. The agent edits design source files in that workspace; the preview runtime turns those sources into a rendered web document; exporters turn the rendered/source document into standard outputs such as HTML, PDF, PPTX, ZIP, or Markdown. In v0.2 the default source entry is `App.jsx`; `index.html` is reserved for standalone exports or legacy workspace files.\n\n`docs/` is gitignored. Maintainers may have internal plans, handoffs, and research locally; public contributors may not. Do not cite `docs/**` in public PR review comments unless the file exists in the public checkout.\n\n## Hard Constraints\n\nThese are project commitments, not preferences:\n\n1. No bundled model runtimes. Do not ship Ollama, llama.cpp, Python, browser binaries, or model weights inside the installer. Use system installs or lazy-download with user-visible consent.\n2. BYOK only. No hosted account, proxied API, or telemetry by default. User credentials stay in human-readable local config.\n3. Local-first storage. v0.2 uses pi JSONL sessions plus real workspace files. Existing v0.1 SQLite data may be migrated, but do not add new SQLite tables for sessions, chat history, comments, snapshots, or design files.\n4. Every design has a workspace. No sealed/open split in v0.2. The workspace filesystem is the source of truth for artifacts and assets.\n5. Shipped app/runtime dependencies, bundled assets, scaffolds, skills, brand refs, and copied code must be MIT-compatible permissive. Reject GPL, AGPL, SSPL, proprietary deps, and unclear copied assets in anything that is bundled, linked, imported by app code, or distributed to users. Workflow-only CI/release tools may use copyleft licenses when they are not vendored, bundled, linked, or copied into the product; document the reason and keep their outputs limited to ordinary metadata or manifests.\n6. Lazy-load heavy features. PPTX export, web capture, scaffolds, skills, brand refs, and image generation must load on demand rather than at app start.\n7. Reuse pi primitives first. `pi-coding-agent` owns sessions, built-in tools, bash execution, event streaming, model registry, provider registration, and capability data unless a design-specific need proves otherwise.\n8. Brand values are data, not model memory. Use `DESIGN.md`, user files, official CSS/SVG/screenshots, or brand URLs. Do not invent brand hex values from memory.\n9. PRs should stay compatible, upgradeable, lean, and elegant. If `docs/PRINCIPLES.md` is present, use its Principles 5b wording as the detailed checklist.\n\n## AI Visibility For Web Work\n\nWhen building or updating any website, project homepage, product page, personal site, documentation site, blog, or public project page, include AI visibility in the default delivery scope unless the user explicitly opts out.\n\n- Add `/llms.txt` with a concise Markdown overview of the site, author or organization, key pages, canonical project or product descriptions, and links to machine-readable resources.\n- Add `/llms-full.txt` when the site has enough substantive public content to justify a fuller AI-readable context file.\n- Configure `robots.txt` deliberately: allow search and retrieval crawlers that help AI systems cite or retrieve public content, and treat training crawlers as a separate policy decision.\n- Maintain `sitemap.xml` and make sure it covers important public pages. Mention Google Search Console and Bing Webmaster Tools submission when relevant.\n- Add appropriate JSON-LD structured data where useful, such as `Person`, `Organization`, `WebSite`, `BlogPosting`, `SoftwareApplication`, `FAQPage`, or `CreativeWork`.\n- Prefer clean Markdown or JSON machine-readable endpoints for important entities such as profiles, projects, posts, docs, releases, FAQs, and product facts.\n- Keep the content truthful, source-backed, and non-spammy. The goal is to help AI systems understand and cite existing real content accurately, not to generate low-quality SEO filler.\n\n## Current Architecture Direction\n\n### Agent Runtime\n\n- Use `pi-coding-agent` and `pi-ai`.\n- Use pi built-ins for `read`, `write`, `edit`, `bash`, `grep`, `find`, and `ls`.\n- Gate tools through the pi `tool_call` hook and the Open CoDesign permission UI.\n- Read capabilities from pi `Model<T>` fields such as `input`, `reasoning`, `cost`, `contextWindow`, and `maxTokens`.\n- Register custom providers through `pi.registerProvider()`. Do not build a parallel provider SDK layer.\n- All LLM calls go through `pi-ai`; do not import provider SDKs directly in app code.\n\n### Storage\n\n- Design equals pi session.\n- Session history lives under app user data as pi JSONL.\n- Design source files, generated JSX/HTML/CSS, assets, exports, `AGENTS.md`, and `DESIGN.md` live in the user workspace.\n- Workspace settings live in `.codesign/settings.json` with `schemaVersion`.\n- `settings.local.json` is personal and should stay gitignored.\n- v0.1 SQLite is legacy data to migrate, not the v0.2 storage model.\n\n### Tools\n\nThe v0.2 tool surface is pi's seven built-ins plus Open CoDesign design tools:\n\n- `ask(questions)` renders structured questions and waits for the user.\n- `scaffold(kind, path)` copies a curated starter into the workspace.\n- `skill(name)` lazy-loads skill text from a manifest.\n- `preview(path)` renders artifacts and returns console errors, asset errors, DOM outline, metrics, and screenshots for vision models.\n- `gen_image(prompt, path)` writes generated images to disk when capability and provider config allow it.\n- `tweaks(blocks)` declares editable controls across files.\n- `todos(items)` shows task state for complex turns.\n- `done(path)` ends a turn after preview self-check.\n\nDo not reintroduce a verifier subagent, snip tool, custom bash tool, custom list-files tool, or agent-written working memory for v0.2 unless the plan changes.\n\n### Design System\n\n- `DESIGN.md` follows the Google spec and can be both input and output.\n- Agent-generated multi-screen work should keep visual consistency by updating `DESIGN.md` as tokens emerge.\n- Built-in brand refs must include attribution, source, license metadata, and a \"not affiliated\" note.\n- Built-in skills use the agentskills-style `SKILL.md` format.\n- Skill and scaffold manifests should carry license and source metadata.\n\n### Resource Boundaries\n\n- Markdown skills in `apps/desktop/resources/templates/skills/*.md` are method rules. They tell the agent how to work; they do not copy files into a workspace.\n- Brand refs in `apps/desktop/resources/templates/brand-refs/*/DESIGN.md` are reference-only design systems loaded as `skill(\"brand:<slug>\")`. Do not edit them for a project; translate adopted choices into the workspace `DESIGN.md`.\n- Scaffolds in `apps/desktop/resources/templates/scaffolds/**` are concrete starter/source assets copied by `scaffold(kind, destPath)`. They can be JSX, HTML, CSS, Markdown, or other text formats if the manifest describes them accurately.\n- Design-skill snippets in `apps/desktop/resources/templates/design-skills/*.jsx` are copyable JSX component patterns exposed through the virtual filesystem as `skills/<file>.jsx`. They are source snippets, not markdown skills and not brand authority.\n- Workspace `DESIGN.md` is the project-specific design-system baton. It is authoritative for the current design once present, and generated work should preserve or repair it rather than treating it as another preset.\n\n### Built-In Starters And Scaffolds\n\n- Treat starter/scaffold assets as product code, not prompt filler. Review the actual file contents as well as the manifest before changing or adding presets.\n- Keep source format and filename extension aligned. Full HTML documents must live as `.html`, JSX/React starters as `.jsx`, and CSS snippets as `.css`. The `scaffold()` tool should preserve the source extension when copying, but the preset asset itself should still be correctly named and described.\n- Built-in HTML starters should be self-contained and previewable in the current runtime. Do not add Reveal.js, React, Babel, Chart.js, or other CDN/runtime scripts to scaffold assets. If a starter needs runtime behavior, use local plain HTML/CSS/JS or an app-provided/lazy-loaded dependency with a clear license path.\n- Avoid weak placeholder copy such as \"Deck title\", \"Page content\", \"Replace this\", or \"Point one\". Use neutral, usable sample content and expose obvious replacement points through `TWEAK_DEFAULTS` when the starter is JSX.\n- Manifest descriptions should say when a starter is HTML or CSS and should call out extension-sensitive assets, especially files that agents might otherwise copy into `_starters/*.jsx`.\n- When touching `apps/desktop/resources/templates/scaffolds/**`, audit for extension/content mismatches, external network URLs, stale placeholder copy, and manifest drift. Add or update focused scaffold/runtime tests when the change affects copy paths, preview classification, or tool details.\n\n## Stack and Conventions\n\n- Package manager: `pnpm` only. Never use `npm` or `yarn`.\n- Build orchestration: Turborepo.\n- Lint and format: Biome.\n- Tests: Vitest for unit tests, Playwright for E2E.\n- TypeScript: strict mode, `verbatimModuleSyntax`, bundler resolution, no `any`.\n- Commits: Conventional Commits.\n- Versioning: Changesets. Do not hand-edit `CHANGELOG.md`.\n- Node: 22 LTS, pinned by `.nvmrc` and `engines`.\n- Exact package versions live in `package.json`, workspace manifests, and `pnpm-lock.yaml`. Read those files instead of trusting stale docs.\n\n### Frontend\n\n- React + Vite + Tailwind v4 + CSS variables.\n- State uses Zustand. Do not introduce Redux, Recoil, or MobX.\n- Components use Radix primitives and custom shadcn-style wrappers in `packages/ui`.\n- Icons use `lucide-react`.\n- Forms use native `<form>` and `FormData`.\n- Animations use Tailwind transitions. Do not introduce framer-motion or motion.\n- App chrome must use `packages/ui` tokens. Generated design sources and exports may define their own visual system.\n- Sandbox preview remains Electron iframe `srcdoc` plus runtime tooling. `App.jsx` JSX source is wrapped by the runtime for preview/export; exported `index.html` is the standalone deliverable.\n\n## Repository Layout\n\n```\napps/\n  desktop/           # Electron app shell, main process, renderer\npackages/\n  core/              # Agent orchestration, prompts, design tools\n  providers/         # pi integration and provider compatibility shims\n  runtime/           # Sandbox renderer and preview runtime\n  ui/                # Shared app UI tokens and components\n  artifacts/         # Artifact schemas and bundle formats\n  exporters/         # PDF / PPTX / ZIP exporters, lazy-loaded\n  templates/         # Built-in examples and starter templates\n  shared/            # Shared types, utils, schemas\ndocs/                # Internal vision, plans, principles, research; gitignored\nexamples/            # Public demo reproductions\n```\n\n## Doing Tasks Here\n\n- For non-trivial architecture or product work, read `docs/VISION.md`, `docs/PRINCIPLES.md`, and `docs/v0.2-plan.md` when they exist locally. Public checkouts may not have `docs/`; in that case rely on this file, public issues/PRs, and README context.\n- Use planning files in `.Codex/workspace/` for tasks spanning more than five tool calls or more than three files when a durable local plan would help. Do not create planning churn for small, direct fixes.\n- Use git worktrees for parallel or unrelated feature work. Do not mix two unrelated branches in one checkout.\n- Check `docs/RESEARCH_QUEUE.md` before touching sandbox, inline comments, tweaks, PPTX, pi capabilities, scaffolds, skills, or brand refs when that file exists locally.\n- Keep edits scoped. Avoid drive-by refactors.\n- Before adding a shipped/runtime dependency, check license, install size, alternatives, and whether it can be a peer dep. For workflow-only tools, document why they are not bundled and whether their outputs affect distributed artifacts.\n- Add or update Vitest coverage for feature work. Broaden tests when changing migrations, permissions, tool hooks, or shared contracts.\n- Prefer manifest and switch logic over registries until two real callers need more.\n- Comment only when the reason would surprise the next maintainer.\n\n## Permission Model\n\nOpen CoDesign uses one permission model with tiers:\n\n- Tier 0: workspace-local reads/writes, simple file commands, and read-only git may run without interruption.\n- Tier 1: installs, build commands, non-local network fetches, and cwd-external commands ask once and can be allowlisted.\n- Tier 2: publishing, pushing, sudo, and high-blast-radius commands ask every time.\n- Tier 3: destructive system commands, `curl | sh`, and system-directory writes are blocked without override.\n\nDo not hide blocked tool calls. Show the command, path, tier, and reason.\n\n## Things to Avoid\n\n- Adding `node_modules`, build outputs, `.env*`, generated release artifacts, or private local files to git.\n- Importing `@anthropic-ai/sdk`, `openai`, `@google/genai`, or other provider SDKs in app code.\n- Writing tests that mock the LLM at the SDK level. Mock at the core or pi boundary.\n- Adding tracking, analytics, account flows, cloud sync, or auto-update without explicit opt-in UX.\n- Hard-coding user paths. Respect XDG, Electron `app.getPath()`, and workspace roots.\n- Adding new SQLite-backed feature state for v0.2 session/design data.\n- Introducing `project` as a product abstraction in v0.2. Multiple sessions can share a workspace, but the sidebar lists sessions.\n- Exposing session branching UI, undo/version rollback, MCP support, or community skill installation in v0.2 unless the plan changes.\n- Using `console.*` in `apps/desktop/src/main/**`, `packages/core/**`, `packages/providers/**`, `packages/exporters/**`, or `packages/shared/**`. Use the project logger.\n\n## Useful Commands\n\n```bash\npnpm i\npnpm dev\npnpm test\npnpm test:e2e\npnpm lint\npnpm typecheck\npnpm build\npnpm changeset\n```\n","CLAUDE.md":"# CLAUDE.md — Open CoDesign\n\nInstructions for Claude Code (and any AI coding agent) working in this repository. Read this before making changes.\n\n## What this project is\n\nopen-codesign is an Electron desktop app that turns natural-language prompts into design artifacts (HTML prototypes, PDFs, PPTX decks, marketing assets). It's the open-source counterpart to Anthropic's Claude Design, with multi-provider model support via `pi-ai` and a local-first storage model.\n\nThe full vision and locked decisions live in `docs/VISION.md` when the internal docs are present locally. Public checkouts may not have `docs/`; in that case use `AGENTS.md`, public issues/PRs, and README context instead of blocking.\n\n> Note: `docs/` is gitignored — internal team materials (research, roadmaps, handoffs) live there but are not part of the public repo. Clone contributors will not have this directory; team members will find it present locally after cloning and copying the internal docs back.\n\n## Hard constraints (do not violate)\n\nThese are project-level commitments, not preferences:\n\n1. **No bundled model runtimes.** No Ollama, llama.cpp, Python, or browser binaries shipped in the installer. Use system installs or lazy-download on demand.\n2. **BYOK only.** No proxied API calls, no cloud account, no telemetry by default. User credentials stay in `~/.config/open-codesign/config.toml` (plaintext, file mode 0600 — matching Claude Code / Codex / gh CLI conventions).\n3. **Local-first storage.** v0.2 design state is file/session based and local-first. Do not add new SQLite-backed session/design feature state.\n4. **Permissive shipped dependencies.** Shipped app/runtime dependencies, bundled assets, scaffolds, skills, brand refs, and copied code must be MIT-compatible permissive. Workflow-only CI/release tools may use copyleft licenses when they are not vendored, bundled, linked, or copied into the product; document the reason.\n5. **Lazy-load heavy features.** PPTX export, web capture, codebase scan, etc. must dynamic-import on first use, not on app start.\n6. **Compatibility, upgradeability, no bloat, elegance** — the four PRINCIPLES §5b checks. Every PR description must mark all four green.\n\n## Stack & conventions\n\n- **Package manager**: `pnpm` only. Never use `npm` or `yarn`. Workspace declared in `pnpm-workspace.yaml`.\n- **Build orchestration**: Turborepo.\n- **Lint + format**: Biome (single tool, no ESLint + Prettier).\n- **Tests**: Vitest (unit) + Playwright (E2E). New features require at least one Vitest test.\n- **TypeScript**: `strict: true`, `verbatimModuleSyntax: true`, `moduleResolution: \"bundler\"`. No `any`.\n- **Commits**: Conventional Commits, enforced by commitlint.\n- **Versioning**: Changesets. Don't hand-edit `CHANGELOG.md`.\n- **Node**: 22 LTS (pinned via `.nvmrc` + `engines`).\n- **Model layer**: All LLM calls go through `@mariozechner/pi-ai`. Don't import provider SDKs directly in app code; if pi-ai lacks a feature, add it to `packages/providers` as a thin extension.\n\n### Frontend stack (locked)\n\n- **UI framework**: React 19 + Vite 6\n- **Styles**: Tailwind v4 + CSS variables (tokens in `packages/ui`)\n- **State**: Zustand (do not introduce Redux / Recoil / MobX)\n- **Routing**: native `useState` view switching at first; TanStack Router only when route count > 5\n- **Components**: Radix UI primitives + custom shadcn-style wrappers in `packages/ui`\n- **Icons**: `lucide-react` (only)\n- **Forms**: native `<form>` + `FormData` (do not introduce react-hook-form / formik)\n- **Animations**: Tailwind transitions (do not introduce framer-motion / motion)\n- **Sandbox renderer**: Electron iframe `srcdoc` + esbuild-wasm + import maps (see `docs/research/03-sandbox-runtime.md`)\n- **Electron version**: latest stable, but NOT 41.x (cross-origin isolation regression)\n- **Storage**: file/session-backed design state; TOML files for config (no electron-store blob)\n\n## Repository layout\n\n```\napps/\n  desktop/           # Electron app shell (main + renderer)\npackages/\n  core/              # Generation orchestration (prompt → artifact pipeline)\n  providers/         # pi-ai adapter + custom provider extensions\n  runtime/           # Sandbox renderer (iframe-based preview)\n  ui/                # Shared design system (aligned with open-cowork tokens)\n  artifacts/         # Artifact schema (HTML / React / SVG / PPTX)\n  exporters/         # PDF / PPTX / ZIP exporters (lazy-loaded)\n  templates/         # Built-in demo prompts and starter templates\n  shared/            # Types, utils, zod schemas\ndocs/                # Vision, roadmap, principles, RFCs (gitignored — internal only)\nexamples/            # Reproductions of Claude Design public demos\n```\n\n## Doing tasks here\n\n- **Read `docs/VISION.md` and `docs/PRINCIPLES.md` when available** for any non-trivial change. Public contributors may not have internal docs.\n- **Use the planning-with-files workflow** for any task spanning > 5 tool calls or > 3 files. Plans live in `.claude/workspace/`.\n- **Use git worktrees for parallel work.** See `docs/COLLABORATION.md` for the workflow. Never run two unrelated feature branches in the same checkout.\n- **Check `docs/RESEARCH_QUEUE.md` when available** before starting work that touches sandbox / inline-comment / slider / PPTX / pi-ai capabilities — research may still be pending and decisions unresolved.\n- **Respect the lean budget.** Before adding a dependency: search for a tiny alternative, consider inlining, ask if it can be a peer dep.\n- **UI must use `packages/ui` tokens.** Don't hard-code colors, fonts, or spacing in app code. If a token is missing, add it to `packages/ui` first.\n- **No \"design for the future\" abstractions.** Three similar lines is fine. Don't introduce factories, plugin systems, or config-driven dispatch unless we have two real callers.\n- **No comments explaining what code does.** Names should do that. Only comment the *why* when it's surprising.\n- **Schema-version everything that lives on disk.** Config files, SQLite tables, IPC payloads, exported bundle formats — all carry a `schemaVersion` field so we can migrate without breaking older installs.\n\n## Things to avoid\n\n- ❌ Adding `node_modules`, build outputs, or `.env*` files to git\n- ❌ Importing from a provider SDK (`@anthropic-ai/sdk`, `openai`, `@google/genai`) in app code\n- ❌ Writing tests that mock the LLM at the SDK level — mock at the `core` boundary instead\n- ❌ Adding tracking, analytics, or auto-update without explicit opt-in UX\n- ❌ Hard-coding any path; respect XDG base dirs / Electron `app.getPath()`\n- ❌ Synchronous I/O in the main process\n- ❌ `console.*` in `apps/desktop/src/main/**`, `packages/core/**`, `packages/providers/**`, `packages/exporters/**`, `packages/shared/**` — use `getLogger()` (main) or the injected `CoreLogger` (core/providers/exporters). Biome enforces this.\n\n## Useful commands\n\n```bash\npnpm i                  # install (uses Corepack-pinned pnpm)\npnpm dev                # start Electron + Vite renderer\npnpm test               # vitest watch\npnpm test:e2e           # playwright\npnpm lint               # biome check\npnpm typecheck          # tsc --noEmit across workspace\npnpm build              # produce signed Mac/Win installers\npnpm changeset          # record a release-worthy change\n```\n\n## Open questions / pending research\n\nSee `docs/RESEARCH_QUEUE.md`. Don't prematurely lock in answers to questions still under investigation.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md - Open CoDesign\n\nInstructions for Codex and other AI coding agents working in this repository. Read this before making changes.\n\n`CLAUDE.md` may lag behind the current plan. For Codex work, treat this file as the public source of truth. If local internal docs such as `docs/VISION.md`, `docs/PRINCIPLES.md`, or `docs/v0.2-plan.md` exist, use them as additional context; if they are missing, do not block public-contributor work on them.\n\n## What This Project Is\n\nOpen CoDesign is an open-source desktop design agent. It turns prompts, local files, skills, scaffolds, brand systems, and model output into design artifacts on the user's laptop.\n\nThe v0.2 direction is no longer a single-prompt generator. Each design is a long-running pi session with a real workspace. The agent can read and edit files, run permissioned commands, ask structured questions, preview artifacts, expose tweak controls, generate images when the configured model supports it, and produce `DESIGN.md` design-system artifacts.\n\nThe original inspiration was Claude Design. The product boundary is now clearer: Open CoDesign borrows proven coding-agent mechanics, then adds design-specific tools and a local-first workspace model.\n\nProduct model: a `Design` owns a workspace. The agent edits design source files in that workspace; the preview runtime turns those sources into a rendered web document; exporters turn the rendered/source document into standard outputs such as HTML, PDF, PPTX, ZIP, or Markdown. In v0.2 the default source entry is `App.jsx`; `index.html` is reserved for standalone exports or legacy workspace files.\n\n`docs/` is gitignored. Maintainers may have internal plans, handoffs, and research locally; public contributors may not. Do not cite `docs/**` in public PR review comments unless the file exists in the public checkout.\n\n## Hard Constraints\n\nThese are project commitments, not preferences:\n\n1. No bundled model runtimes. Do not ship Ollama, llama.cpp, Python, browser binaries, or model weights inside the installer. Use system installs or lazy-download with user-visible consent.\n2. BYOK only. No hosted account, proxied API, or telemetry by default. User credentials stay in human-readable local config.\n3. Local-first storage. v0.2 uses pi JSONL sessions plus real workspace files. Existing v0.1 SQLite data may be migrated, but do not add new SQLite tables for sessions, chat history, comments, snapshots, or design files.\n4. Every design has a workspace. No sealed/open split in v0.2. The workspace filesystem is the source of truth for artifacts and assets.\n5. Shipped app/runtime dependencies, bundled assets, scaffolds, skills, brand refs, and copied code must be MIT-compatible permissive. Reject GPL, AGPL, SSPL, proprietary deps, and unclear copied assets in anything that is bundled, linked, imported by app code, or distributed to users. Workflow-only CI/release tools may use copyleft licenses when they are not vendored, bundled, linked, or copied into the product; document the reason and keep their outputs limited to ordinary metadata or manifests.\n6. Lazy-load heavy features. PPTX export, web capture, scaffolds, skills, brand refs, and image generation must load on demand rather than at app start.\n7. Reuse pi primitives first. `pi-coding-agent` owns sessions, built-in tools, bash execution, event streaming, model registry, provider registration, and capability data unless a design-specific need proves otherwise.\n8. Brand values are data, not model memory. Use `DESIGN.md`, user files, official CSS/SVG/screenshots, or brand URLs. Do not invent brand hex values from memory.\n9. PRs should stay compatible, upgradeable, lean, and elegant. If `docs/PRINCIPLES.md` is present, use its Principles 5b wording as the detailed checklist.\n\n## AI Visibility For Web Work\n\nWhen building or updating any website, project homepage, product page, personal site, documentation site, blog, or public project page, include AI visibility in the default delivery scope unless the user explicitly opts out.\n\n- Add `/llms.txt` with a concise Markdown overview of the site, author or organization, key pages, canonical project or product descriptions, and links to machine-readable resources.\n- Add `/llms-full.txt` when the site has enough substantive public content to justify a fuller AI-readable context file.\n- Configure `robots.txt` deliberately: allow search and retrieval crawlers that help AI systems cite or retrieve public content, and treat training crawlers as a separate policy decision.\n- Maintain `sitemap.xml` and make sure it covers important public pages. Mention Google Search Console and Bing Webmaster Tools submission when relevant.\n- Add appropriate JSON-LD structured data where useful, such as `Person`, `Organization`, `WebSite`, `BlogPosting`, `SoftwareApplication`, `FAQPage`, or `CreativeWork`.\n- Prefer clean Markdown or JSON machine-readable endpoints for important entities such as profiles, projects, posts, docs, releases, FAQs, and product facts.\n- Keep the content truthful, source-backed, and non-spammy. The goal is to help AI systems understand and cite existing real content accurately, not to generate low-quality SEO filler.\n\n## Current Architecture Direction\n\n### Agent Runtime\n\n- Use `pi-coding-agent` and `pi-ai`.\n- Use pi built-ins for `read`, `write`, `edit`, `bash`, `grep`, `find`, and `ls`.\n- Gate tools through the pi `tool_call` hook and the Open CoDesign permission UI.\n- Read capabilities from pi `Model<T>` fields such as `input`, `reasoning`, `cost`, `contextWindow`, and `maxTokens`.\n- Register custom providers through `pi.registerProvider()`. Do not build a parallel provider SDK layer.\n- All LLM calls go through `pi-ai`; do not import provider SDKs directly in app code.\n\n### Storage\n\n- Design equals pi session.\n- Session history lives under app user data as pi JSONL.\n- Design source files, generated JSX/HTML/CSS, assets, exports, `AGENTS.md`, and `DESIGN.md` live in the user workspace.\n- Workspace settings live in `.codesign/settings.json` with `schemaVersion`.\n- `settings.local.json` is personal and should stay gitignored.\n- v0.1 SQLite is legacy data to migrate, not the v0.2 storage model.\n\n### Tools\n\nThe v0.2 tool surface is pi's seven built-ins plus Open CoDesign design tools:\n\n- `ask(questions)` renders structured questions and waits for the user.\n- `scaffold(kind, path)` copies a curated starter into the workspace.\n- `skill(name)` lazy-loads skill text from a manifest.\n- `preview(path)` renders artifacts and returns console errors, asset errors, DOM outline, metrics, and screenshots for vision models.\n- `gen_image(prompt, path)` writes generated images to disk when capability and provider config allow it.\n- `tweaks(blocks)` declares editable controls across files.\n- `todos(items)` shows task state for complex turns.\n- `done(path)` ends a turn after preview self-check.\n\nDo not reintroduce a verifier subagent, snip tool, custom bash tool, custom list-files tool, or agent-written working memory for v0.2 unless the plan changes.\n\n### Design System\n\n- `DESIGN.md` follows the Google spec and can be both input and output.\n- Agent-generated multi-screen work should keep visual consistency by updating `DESIGN.md` as tokens emerge.\n- Built-in brand refs must include attribution, source, license metadata, and a \"not affiliated\" note.\n- Built-in skills use the agentskills-style `SKILL.md` format.\n- Skill and scaffold manifests should carry license and source metadata.\n\n### Resource Boundaries\n\n- Markdown skills in `apps/desktop/resources/templates/skills/*.md` are method rules. They tell the agent how to work; they do not copy files into a workspace.\n- Brand refs in `apps/desktop/resources/templates/brand-refs/*/DESIGN.md` are reference-only design systems loaded as `skill(\"brand:<slug>\")`. Do not edit them for a project; translate adopted choices into the workspace `DESIGN.md`.\n- Scaffolds in `apps/desktop/resources/templates/scaffolds/**` are concrete starter/source assets copied by `scaffold(kind, destPath)`. They can be JSX, HTML, CSS, Markdown, or other text formats if the manifest describes them accurately.\n- Design-skill snippets in `apps/desktop/resources/templates/design-skills/*.jsx` are copyable JSX component patterns exposed through the virtual filesystem as `skills/<file>.jsx`. They are source snippets, not markdown skills and not brand authority.\n- Workspace `DESIGN.md` is the project-specific design-system baton. It is authoritative for the current design once present, and generated work should preserve or repair it rather than treating it as another preset.\n\n### Built-In Starters And Scaffolds\n\n- Treat starter/scaffold assets as product code, not prompt filler. Review the actual file contents as well as the manifest before changing or adding presets.\n- Keep source format and filename extension aligned. Full HTML documents must live as `.html`, JSX/React starters as `.jsx`, and CSS snippets as `.css`. The `scaffold()` tool should preserve the source extension when copying, but the preset asset itself should still be correctly named and described.\n- Built-in HTML starters should be self-contained and previewable in the current runtime. Do not add Reveal.js, React, Babel, Chart.js, or other CDN/runtime scripts to scaffold assets. If a starter needs runtime behavior, use local plain HTML/CSS/JS or an app-provided/lazy-loaded dependency with a clear license path.\n- Avoid weak placeholder copy such as \"Deck title\", \"Page content\", \"Replace this\", or \"Point one\". Use neutral, usable sample content and expose obvious replacement points through `TWEAK_DEFAULTS` when the starter is JSX.\n- Manifest descriptions should say when a starter is HTML or CSS and should call out extension-sensitive assets, especially files that agents might otherwise copy into `_starters/*.jsx`.\n- When touching `apps/desktop/resources/templates/scaffolds/**`, audit for extension/content mismatches, external network URLs, stale placeholder copy, and manifest drift. Add or update focused scaffold/runtime tests when the change affects copy paths, preview classification, or tool details.\n\n## Stack and Conventions\n\n- Package manager: `pnpm` only. Never use `npm` or `yarn`.\n- Build orchestration: Turborepo.\n- Lint and format: Biome.\n- Tests: Vitest for unit tests, Playwright for E2E.\n- TypeScript: strict mode, `verbatimModuleSyntax`, bundler resolution, no `any`.\n- Commits: Conventional Commits.\n- Versioning: Changesets. Do not hand-edit `CHANGELOG.md`.\n- Node: 22 LTS, pinned by `.nvmrc` and `engines`.\n- Exact package versions live in `package.json`, workspace manifests, and `pnpm-lock.yaml`. Read those files instead of trusting stale docs.\n\n### Frontend\n\n- React + Vite + Tailwind v4 + CSS variables.\n- State uses Zustand. Do not introduce Redux, Recoil, or MobX.\n- Components use Radix primitives and custom shadcn-style wrappers in `packages/ui`.\n- Icons use `lucide-react`.\n- Forms use native `<form>` and `FormData`.\n- Animations use Tailwind transitions. Do not introduce framer-motion or motion.\n- App chrome must use `packages/ui` tokens. Generated design sources and exports may define their own visual system.\n- Sandbox preview remains Electron iframe `srcdoc` plus runtime tooling. `App.jsx` JSX source is wrapped by the runtime for preview/export; exported `index.html` is the standalone deliverable.\n\n## Repository Layout\n\n```\napps/\n  desktop/           # Electron app shell, main process, renderer\npackages/\n  core/              # Agent orchestration, prompts, design tools\n  providers/         # pi integration and provider compatibility shims\n  runtime/           # Sandbox renderer and preview runtime\n  ui/                # Shared app UI tokens and components\n  artifacts/         # Artifact schemas and bundle formats\n  exporters/         # PDF / PPTX / ZIP exporters, lazy-loaded\n  templates/         # Built-in examples and starter templates\n  shared/            # Shared types, utils, schemas\ndocs/                # Internal vision, plans, principles, research; gitignored\nexamples/            # Public demo reproductions\n```\n\n## Doing Tasks Here\n\n- For non-trivial architecture or product work, read `docs/VISION.md`, `docs/PRINCIPLES.md`, and `docs/v0.2-plan.md` when they exist locally. Public checkouts may not have `docs/`; in that case rely on this file, public issues/PRs, and README context.\n- Use planning files in `.Codex/workspace/` for tasks spanning more than five tool calls or more than three files when a durable local plan would help. Do not create planning churn for small, direct fixes.\n- Use git worktrees for parallel or unrelated feature work. Do not mix two unrelated branches in one checkout.\n- Check `docs/RESEARCH_QUEUE.md` before touching sandbox, inline comments, tweaks, PPTX, pi capabilities, scaffolds, skills, or brand refs when that file exists locally.\n- Keep edits scoped. Avoid drive-by refactors.\n- Before adding a shipped/runtime dependency, check license, install size, alternatives, and whether it can be a peer dep. For workflow-only tools, document why they are not bundled and whether their outputs affect distributed artifacts.\n- Add or update Vitest coverage for feature work. Broaden tests when changing migrations, permissions, tool hooks, or shared contracts.\n- Prefer manifest and switch logic over registries until two real callers need more.\n- Comment only when the reason would surprise the next maintainer.\n\n## Permission Model\n\nOpen CoDesign uses one permission model with tiers:\n\n- Tier 0: workspace-local reads/writes, simple file commands, and read-only git may run without interruption.\n- Tier 1: installs, build commands, non-local network fetches, and cwd-external commands ask once and can be allowlisted.\n- Tier 2: publishing, pushing, sudo, and high-blast-radius commands ask every time.\n- Tier 3: destructive system commands, `curl | sh`, and system-directory writes are blocked without override.\n\nDo not hide blocked tool calls. Show the command, path, tier, and reason.\n\n## Things to Avoid\n\n- Adding `node_modules`, build outputs, `.env*`, generated release artifacts, or private local files to git.\n- Importing `@anthropic-ai/sdk`, `openai`, `@google/genai`, or other provider SDKs in app code.\n- Writing tests that mock the LLM at the SDK level. Mock at the core or pi boundary.\n- Adding tracking, analytics, account flows, cloud sync, or auto-update without explicit opt-in UX.\n- Hard-coding user paths. Respect XDG, Electron `app.getPath()`, and workspace roots.\n- Adding new SQLite-backed feature state for v0.2 session/design data.\n- Introducing `project` as a product abstraction in v0.2. Multiple sessions can share a workspace, but the sidebar lists sessions.\n- Exposing session branching UI, undo/version rollback, MCP support, or community skill installation in v0.2 unless the plan changes.\n- Using `console.*` in `apps/desktop/src/main/**`, `packages/core/**`, `packages/providers/**`, `packages/exporters/**`, or `packages/shared/**`. Use the project logger.\n\n## Useful Commands\n\n```bash\npnpm i\npnpm dev\npnpm test\npnpm test:e2e\npnpm lint\npnpm typecheck\npnpm build\npnpm changeset\n```\n","category":"root","tokens":3784},{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md — Open CoDesign\n\nInstructions for Claude Code (and any AI coding agent) working in this repository. Read this before making changes.\n\n## What this project is\n\nopen-codesign is an Electron desktop app that turns natural-language prompts into design artifacts (HTML prototypes, PDFs, PPTX decks, marketing assets). It's the open-source counterpart to Anthropic's Claude Design, with multi-provider model support via `pi-ai` and a local-first storage model.\n\nThe full vision and locked decisions live in `docs/VISION.md` when the internal docs are present locally. Public checkouts may not have `docs/`; in that case use `AGENTS.md`, public issues/PRs, and README context instead of blocking.\n\n> Note: `docs/` is gitignored — internal team materials (research, roadmaps, handoffs) live there but are not part of the public repo. Clone contributors will not have this directory; team members will find it present locally after cloning and copying the internal docs back.\n\n## Hard constraints (do not violate)\n\nThese are project-level commitments, not preferences:\n\n1. **No bundled model runtimes.** No Ollama, llama.cpp, Python, or browser binaries shipped in the installer. Use system installs or lazy-download on demand.\n2. **BYOK only.** No proxied API calls, no cloud account, no telemetry by default. User credentials stay in `~/.config/open-codesign/config.toml` (plaintext, file mode 0600 — matching Claude Code / Codex / gh CLI conventions).\n3. **Local-first storage.** v0.2 design state is file/session based and local-first. Do not add new SQLite-backed session/design feature state.\n4. **Permissive shipped dependencies.** Shipped app/runtime dependencies, bundled assets, scaffolds, skills, brand refs, and copied code must be MIT-compatible permissive. Workflow-only CI/release tools may use copyleft licenses when they are not vendored, bundled, linked, or copied into the product; document the reason.\n5. **Lazy-load heavy features.** PPTX export, web capture, codebase scan, etc. must dynamic-import on first use, not on app start.\n6. **Compatibility, upgradeability, no bloat, elegance** — the four PRINCIPLES §5b checks. Every PR description must mark all four green.\n\n## Stack & conventions\n\n- **Package manager**: `pnpm` only. Never use `npm` or `yarn`. Workspace declared in `pnpm-workspace.yaml`.\n- **Build orchestration**: Turborepo.\n- **Lint + format**: Biome (single tool, no ESLint + Prettier).\n- **Tests**: Vitest (unit) + Playwright (E2E). New features require at least one Vitest test.\n- **TypeScript**: `strict: true`, `verbatimModuleSyntax: true`, `moduleResolution: \"bundler\"`. No `any`.\n- **Commits**: Conventional Commits, enforced by commitlint.\n- **Versioning**: Changesets. Don't hand-edit `CHANGELOG.md`.\n- **Node**: 22 LTS (pinned via `.nvmrc` + `engines`).\n- **Model layer**: All LLM calls go through `@mariozechner/pi-ai`. Don't import provider SDKs directly in app code; if pi-ai lacks a feature, add it to `packages/providers` as a thin extension.\n\n### Frontend stack (locked)\n\n- **UI framework**: React 19 + Vite 6\n- **Styles**: Tailwind v4 + CSS variables (tokens in `packages/ui`)\n- **State**: Zustand (do not introduce Redux / Recoil / MobX)\n- **Routing**: native `useState` view switching at first; TanStack Router only when route count > 5\n- **Components**: Radix UI primitives + custom shadcn-style wrappers in `packages/ui`\n- **Icons**: `lucide-react` (only)\n- **Forms**: native `<form>` + `FormData` (do not introduce react-hook-form / formik)\n- **Animations**: Tailwind transitions (do not introduce framer-motion / motion)\n- **Sandbox renderer**: Electron iframe `srcdoc` + esbuild-wasm + import maps (see `docs/research/03-sandbox-runtime.md`)\n- **Electron version**: latest stable, but NOT 41.x (cross-origin isolation regression)\n- **Storage**: file/session-backed design state; TOML files for config (no electron-store blob)\n\n## Repository layout\n\n```\napps/\n  desktop/           # Electron app shell (main + renderer)\npackages/\n  core/              # Generation orchestration (prompt → artifact pipeline)\n  providers/         # pi-ai adapter + custom provider extensions\n  runtime/           # Sandbox renderer (iframe-based preview)\n  ui/                # Shared design system (aligned with open-cowork tokens)\n  artifacts/         # Artifact schema (HTML / React / SVG / PPTX)\n  exporters/         # PDF / PPTX / ZIP exporters (lazy-loaded)\n  templates/         # Built-in demo prompts and starter templates\n  shared/            # Types, utils, zod schemas\ndocs/                # Vision, roadmap, principles, RFCs (gitignored — internal only)\nexamples/            # Reproductions of Claude Design public demos\n```\n\n## Doing tasks here\n\n- **Read `docs/VISION.md` and `docs/PRINCIPLES.md` when available** for any non-trivial change. Public contributors may not have internal docs.\n- **Use the planning-with-files workflow** for any task spanning > 5 tool calls or > 3 files. Plans live in `.claude/workspace/`.\n- **Use git worktrees for parallel work.** See `docs/COLLABORATION.md` for the workflow. Never run two unrelated feature branches in the same checkout.\n- **Check `docs/RESEARCH_QUEUE.md` when available** before starting work that touches sandbox / inline-comment / slider / PPTX / pi-ai capabilities — research may still be pending and decisions unresolved.\n- **Respect the lean budget.** Before adding a dependency: search for a tiny alternative, consider inlining, ask if it can be a peer dep.\n- **UI must use `packages/ui` tokens.** Don't hard-code colors, fonts, or spacing in app code. If a token is missing, add it to `packages/ui` first.\n- **No \"design for the future\" abstractions.** Three similar lines is fine. Don't introduce factories, plugin systems, or config-driven dispatch unless we have two real callers.\n- **No comments explaining what code does.** Names should do that. Only comment the *why* when it's surprising.\n- **Schema-version everything that lives on disk.** Config files, SQLite tables, IPC payloads, exported bundle formats — all carry a `schemaVersion` field so we can migrate without breaking older installs.\n\n## Things to avoid\n\n- ❌ Adding `node_modules`, build outputs, or `.env*` files to git\n- ❌ Importing from a provider SDK (`@anthropic-ai/sdk`, `openai`, `@google/genai`) in app code\n- ❌ Writing tests that mock the LLM at the SDK level — mock at the `core` boundary instead\n- ❌ Adding tracking, analytics, or auto-update without explicit opt-in UX\n- ❌ Hard-coding any path; respect XDG base dirs / Electron `app.getPath()`\n- ❌ Synchronous I/O in the main process\n- ❌ `console.*` in `apps/desktop/src/main/**`, `packages/core/**`, `packages/providers/**`, `packages/exporters/**`, `packages/shared/**` — use `getLogger()` (main) or the injected `CoreLogger` (core/providers/exporters). Biome enforces this.\n\n## Useful commands\n\n```bash\npnpm i                  # install (uses Corepack-pinned pnpm)\npnpm dev                # start Electron + Vite renderer\npnpm test               # vitest watch\npnpm test:e2e           # playwright\npnpm lint               # biome check\npnpm typecheck          # tsc --noEmit across workspace\npnpm build              # produce signed Mac/Win installers\npnpm changeset          # record a release-worthy change\n```\n\n## Open questions / pending research\n\nSee `docs/RESEARCH_QUEUE.md`. Don't prematurely lock in answers to questions still under investigation.\n","category":"root","tokens":1852}]}