Change a Local-First AI Design Desktop App Within Its Fixed Product Rules

## Treat the Agent Guide as the Source of Truth When Instruction Files Disagree Read this file before making changes. Other agent instruction files in the repository may lag behind the current plan; where they disagree with this one, this one wins. Internal design documents such as a vision doc, a principles doc, or the current release plan are useful extra context when they exist in your checkout. The internal docs directory is gitignored, so maintainers keep plans, handoffs, and research locally while public contributors may have none of it. - Never block public-contributor work on files that only maintainers can see. - Never cite a path under the gitignored docs directory in a public review comment unless that file also exists in the public checkout. - When those docs are missing, rely on this file, public issues and pull requests, and the README. ## Treat Each Design as a Long-Running Session With Its Own Workspace The product is not a single-prompt generator. Each unit of work is a long-running agent session backed by a real workspace on the user's machine, and 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-system documents. - A design owns a workspace. There is no sealed/open split: the workspace filesystem is the source of truth for artifacts and assets. - The agent edits source files in the workspace; the preview runtime renders those sources into a viewable document; exporters turn the rendered or source document into standard outputs such as HTML, PDF, PPTX, ZIP, or Markdown. - Keep one canonical source entry file for the current format (for example a JSX component file), and reserve the standalone HTML file for exports or legacy workspace files. - Borrowing proven coding-agent mechanics is intended; the product boundary is that domain-specific tools and the local-first workspace model are what you add on top. ## Keep the Fixed Rules: No Bundled Model Runtimes and Bring-Your-Own-Key Only These are project commitments, not preferences. Do not trade them away for convenience. 1. No bundled model runtimes. Do not ship inference engines, language interpreters, browser binaries, or model weights inside the installer. Use system installs, or lazy-download with user-visible consent. 2. Bring-your-own-key only. No hosted account, proxied API, or telemetry by default. User credentials stay in human-readable local config. 3. Local-first storage. Sessions live as append-only session files plus real workspace files. Existing data in the legacy embedded database may be migrated, but do not add new tables there for sessions, chat history, comments, snapshots, or design files. 4. Every design has a workspace. Nothing important may exist only inside a session record. 5. Anything shipped, bundled, linked, imported by app code, or distributed to users must be permissively licensed and compatible with the project license. Reject copyleft, source-available, proprietary, and unclear third-party assets in that set. Workflow-only CI and release tooling may use copyleft licenses when it is not vendored, bundled, linked, or copied into the product; document why, and keep its output limited to ordinary metadata or manifests. 6. Lazy-load heavy features. Exporters, web capture, scaffolds, skills, reference assets, and image generation must load on demand rather than at application start. 7. Reuse the underlying agent framework's primitives first. It owns sessions, built-in tools, shell execution, event streaming, the model registry, provider registration, and capability data, unless a domain-specific need proves otherwise. 8. Reference data is data, not model memory. Take brand and style values from the workspace design document, user files, official assets, or published sources. Never invent brand colors or specifications from memory. 9. Changes should stay compatible, upgradeable, lean, and elegant, and should follow the project's detailed principles checklist when one is present. ## Add AI-Readable Files Like llms.txt When Building Websites When 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. - Add an `/llms.txt` file with a concise Markdown overview of the site, the author or organization, key pages, canonical project or product descriptions, and links to machine-readable resources. - Add an `/llms-full.txt` file when the site has enough substantive public content to justify a fuller AI-readable context file. - 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. - Maintain `sitemap.xml` and make sure it covers the important public pages. Mention webmaster-tools submission when it is relevant. - Add appropriate JSON-LD structured data where useful, such as person, organization, website, article, software application, FAQ, or creative-work types. - Prefer clean Markdown or JSON machine-readable endpoints for important entities such as profiles, projects, posts, docs, releases, FAQs, and product facts. - Keep the content truthful, source-backed, and non-spammy. The goal is to help AI systems understand and cite real existing content accurately, not to generate low-quality filler. ## Route All Model Calls and Tools Through the Shared Agent Framework - Build on the shared agent framework and its model abstraction layer rather than a hand-rolled equivalent. - Use the framework's built-in tools for read, write, edit, shell, grep, find, and list operations instead of writing parallel versions. - Gate every tool call through the framework's tool-call hook and the application's permission UI. - Read model capabilities from the framework's model description fields, such as accepted input types, reasoning support, cost, context window, and maximum output tokens. Do not hard-code capability tables. - Register custom providers through the framework's provider registration API. Do not build a parallel provider SDK layer. - All model calls go through the framework's model abstraction. Do not import vendor SDKs directly in application code. ## Keep Sessions in Append-Only Files and Designs in the User Workspace - A design is a session. Session history lives under the application's user-data directory as append-only session files. - Design source files, generated markup and styles, assets, exports, and the workspace-level agent and design documents live in the user workspace, not in an application database. - Workspace settings live in a versioned settings file that carries an explicit schema version field. - The personal local settings file is per-user and must stay gitignored. - The legacy embedded database is data to migrate, not the current storage model. Do not extend it with new feature state. ## Use Only the Built-In Tools Plus a Short List of Design Tools The tool surface is the framework's built-ins plus a short list of domain tools: - `ask(questions)` renders structured questions and waits for the user. - `scaffold(kind, path)` copies a curated starter into the workspace. - `skill(name)` lazy-loads skill text from a manifest. - `preview(path)` renders artifacts and returns console errors, asset errors, a DOM outline, metrics, and screenshots for vision models. - `gen_image(prompt, path)` writes generated images to disk when capability and provider configuration allow it. - `tweaks(blocks)` declares editable controls across files. - `todos(items)` shows task state for complex turns. - `done(path)` ends a turn after a preview self-check. Do not reintroduce a verifier subagent, a snippet-capture tool, a custom shell tool, a custom list-files tool, or agent-written working memory unless the plan changes. ## Keep the Four Kinds of Design Resources Apart The design document follows the published specification and can be both input and output. Agent-generated multi-screen work keeps visual consistency by updating that document as tokens emerge. Built-in reference systems must carry attribution, source, license metadata, and a "not affiliated" note, and built-in skills use the standard skill-file format. Skill and scaffold manifests must carry license and source metadata. The four resource kinds are not interchangeable: - Markdown skills are method rules. They tell the agent how to work; they do not copy files into a workspace. - Reference design systems are read-only, loaded by name as a skill. Do not edit them for a project; translate the choices you adopt into the workspace design document. - Scaffolds are concrete starter and source assets copied into the workspace. They may be any text format as long as the manifest describes them accurately. - Design-skill snippets are copyable component patterns exposed through the virtual filesystem. They are source snippets, not method rules and not brand authority. The workspace design document is the project-specific baton. Once it exists it is authoritative for the current design, and generated work should preserve or repair it rather than treating it as one more preset. ## Review Starter Templates as Product Code, With Matching File Extensions - Treat starter and scaffold assets as product code, not prompt filler. Review the actual file contents as well as the manifest before changing or adding a preset. - Keep source format and filename extension aligned. Full HTML documents belong in `.html` files, component starters in the component extension, style snippets in `.css`. The copy tool should preserve the source extension, but the asset itself must still be correctly named and described. - Built-in HTML starters must be self-contained and previewable in the current runtime. Do not add CDN or third-party runtime scripts to scaffold assets. If a starter needs runtime behavior, use local plain HTML, CSS, and JavaScript, or an application-provided lazy-loaded dependency with a clear license path. - Avoid weak placeholder copy such as "Deck title", "Page content", "Replace this", or "Point one". Use neutral, usable sample content and expose the obvious replacement points through the starter's declared tweak defaults. - Manifest descriptions must say which format a starter is and must call out extension-sensitive assets, especially files an agent might otherwise copy under the wrong extension. - When touching the scaffolds tree, audit for extension and content mismatches, external network URLs, stale placeholder copy, and manifest drift. Add or update focused scaffold and runtime tests when the change affects copy paths, preview classification, or tool behavior. ## Stick to the Chosen Tools and Read Versions From the Lockfile - One package manager for the whole repository. Never mix in a second one. - Use the repository's chosen build orchestrator, single lint-and-format tool, unit test runner, and end-to-end test runner rather than introducing alternatives. - TypeScript in strict mode with verbatim module syntax and bundler resolution. No `any`. - Conventional Commits for messages, and a changeset tool for versioning. Do not hand-edit the changelog. Pin the runtime version in both the version file and the engines field. - Exact package versions live in the manifests and the lockfile. Read those files instead of trusting stale documentation. - Frontend choices are already settled: the chosen view library and build tool, utility CSS with CSS variables, one lightweight state library, accessible headless primitives wrapped in the shared UI package, one icon set, native forms with form data, and CSS transitions for animation. Do not introduce competing state, animation, or component libraries. - Application chrome must use the shared UI package's tokens. Generated design sources and exports may define their own visual system. - The repository splits the application shell, agent core, provider integration, preview runtime, shared UI, artifact schemas, exporters, templates, and shared types into separate packages. Put code in the package that owns the concern. ## Write a Plan File for Larger Tasks and Keep Edits Scoped - For non-trivial architecture or product work, read the vision, principles, and current-plan documents when they exist locally; otherwise rely on this file and public discussion. - Write a durable local plan file for tasks spanning more than about five tool calls or more than three files. Do not create planning churn for small, direct fixes. - Use separate worktrees for parallel or unrelated feature work. Do not mix two unrelated branches in one checkout. - Check the research queue before touching the sandbox, inline comments, tweak controls, exporters, framework capabilities, scaffolds, skills, or reference assets when that file exists locally. - Keep edits scoped and avoid drive-by refactors. - Before adding a shipped or runtime dependency, check its license, install size, alternatives, and whether it can be a peer dependency. For workflow-only tools, document why they are not bundled and whether their output affects distributed artifacts. - Add or update unit test coverage for feature work, and broaden tests when changing migrations, permissions, tool hooks, or shared contracts. - Prefer a manifest plus switch logic over a registry until two real callers need more. - Comment only where the reason would surprise the next maintainer. ## Sort Commands Into Four Permission Levels and Show Why One Was Blocked There is a single permission model with escalating tiers: - Tier 0: workspace-local reads and writes, simple file commands, and read-only version-control commands may run without interruption. - Tier 1: installs, build commands, non-local network fetches, and commands outside the working directory ask once and may then be allowlisted. - Tier 2: publishing, pushing, privilege escalation, and other high-blast-radius commands ask every time. - Tier 3: destructive system commands, piping a downloaded script straight into a shell, and writes to system directories are blocked without an explicit override. Do not hide blocked tool calls. Show the command, the path, the tier, and the reason it was blocked. ## Do Not Import Vendor SDKs or Add Tracking Without Opt-In - Adding dependency directories, build outputs, environment files, generated release artifacts, or private local files to version control. - Importing model-vendor SDKs in application code, or writing tests that mock the model at the vendor SDK level. Mock at the core or framework boundary instead. - Adding tracking, analytics, account flows, cloud sync, or auto-update without an explicit opt-in experience. - Hard-coding user paths. Respect platform directory conventions, the application's path APIs, and workspace roots. - Adding new legacy-database-backed feature state for session or design data. - Introducing a heavier grouping abstraction above the workspace. Multiple sessions may share a workspace, but the sidebar lists sessions. - Exposing session branching, undo and version rollback, external tool-server support, or community skill installation unless the plan changes. - Using raw console calls in the main process, core, providers, exporters, or shared packages. Use the project logger.