@mindstudio-ai/remy 0.1.8 → 0.1.10

package/dist/prompt/.notes.md

@@ -0,0 +1,138 @@
+# Prompt System — Design Notes & Decisions
+
+Notes from the initial build of the prompt system (March 2026).
+
+## Architecture Decisions
+
+### Source → Compile → Include pipeline
+
+We have a two-stage pipeline for platform documentation:
+
+1. **Sources** (`docs/developer-guide/` at project root) — raw platform docs, maintained directly in the repo
+2. **Compiled** (`compiled/`) — distilled fragments optimized for agent consumption
+3. **Template** (`index.ts`) — assembles everything into the final prompt
+
+Compiled fragments are generated in a human-in-the-loop LLM session and committed to git. The compilation step lets us optimize for the agent audience without cluttering the source docs.
+
+### Compilation is manual and sequential
+
+The `compiled/README.md` has detailed instructions for the LLM doing compilation. Key rules:
+- Work through one source file at a time, sequentially
+- Present each draft for review before moving on
+- Preserve specifics when condensing — examples, edge cases, and enumerated constraints are the highest-value content. "Ensure data integrity, including checking for duplicate keys and null foreign references" should NOT become "ensure data integrity"
+- Manual sources (design notes, media CDN) are already prompt-ready and may go in nearly as-is
+
+### Prompt section ordering
+
+Based on Anthropic's long-context research and analysis of Claude Code / Codex / Cursor prompts:
+
+1. **Identity** (top — primacy effect, anchors persona)
+2. **Reference docs** (bulk — platform docs, SDK, MSFM, project context)
+3. **Behavioral instructions** (bottom — recency effect, 30% improvement per Anthropic)
+
+The model attends most strongly to the beginning and end (U-shaped curve). Large reference docs go in the middle where they're available for lookup. Actionable instructions go at the end where the model follows them most precisely.
+
+### XML tags for structure
+
+All reference doc blocks are wrapped in descriptive XML tags (`<platform_docs>`, `<mindstudio_agent_sdk_docs>`, etc.) per Anthropic's guidance. Claude is specifically tuned to attend to XML structure. Each compiled fragment gets its own inner tag (`<platform>`, `<tables>`, `<methods>`, etc.) for clear delineation.
+
+### Template system
+
+The prompt builder uses a simple `{{filename}}` include syntax resolved by a single regex. Dynamic parts (project context, phase flag, LSP conditional) use standard JS template literals. No handlebars library, no condition blocks — just string interpolation + file includes.
+
+All static/compiled files are loaded with `requireFile` which throws on missing files. Only project-level context (CLAUDE.md, mindstudio.json, file listing) uses soft loading since those depend on the working directory.
+
+## Research-Informed Decisions
+
+### Prompt engineering for coding agents
+
+From extensive research into Claude Code, Codex, Cursor, Aider, and academic papers:
+
+- **Negative instructions perform worse than positive ones.** "Don't add comments" activates "adding comments." We rewrote all negatives as positive directives.
+- **Tool-specific guidance belongs in tool descriptions, not the system prompt.** Avoids duplication and keeps the prompt focused on principles.
+- **The "AI Purple Problem"** — LLMs converge on generic aesthetics (Inter font, purple gradients, three-boxes-with-icons layout). The design fragment explicitly calls these out as anti-patterns and pushes for distinctiveness.
+- **Examples in prompts are high-value but expensive.** We keep code examples in the compiled fragments (the agent copies patterns directly) but removed style/formatting examples from the base instructions.
+
+### LSP tool simplification
+
+Research showed agents rarely use position-dependent LSP tools (definition, references, hover, symbols) — they require knowing the file and line first, which means the agent already read the file. We slimmed down to just `lspDiagnostics` (with code actions for suggested fixes) and `restartProcess`.
+
+### Design quality prompting
+
+From research into v0, Lovable, Bolt, and Anthropic's `<frontend_aesthetics>` cookbook:
+
+- LLMs converge on the statistical median of training data — explicitly override generic defaults
+- Specific avoidance lists work: ban generic fonts, purple gradients, predictable layouts
+- Committed color palettes beat timid even distribution
+- Typography is the single fastest way to give an interface identity
+- The design fragment references iOS, Stripe, Notion, Linear as quality benchmarks and Dribbble/Behance/Mobbin as visual standards
+
+## SDK Usage
+
+The source docs originally showed `mindstudio.executeStep('generateText', ...)` which was wrong. The correct API is `new MindStudioAgent()` with direct method calls (`agent.generateText(...)`, `agent.sendEmail(...)`, etc.). No constructor args needed inside methods — credentials come from the execution environment. We fixed both the compiled fragment and the upstream source doc in youai-api.
+
+The SDK ships `llms.txt` at the package root with full signatures for all 170+ actions. The compiled fragment references this path (`dist/methods/node_modules/@mindstudio-ai/agent/llms.txt`) so the agent knows where to look up specific action details.
+
+## Behavioral Instruction Architecture (March 21, 2026)
+
+### Splitting behavioral instructions by concern
+
+The original `instructions.md` was a catch-all for workflow, principles, communication, verification details, log paths, and coding conventions. It was overloaded — too many concerns in one file, which likely diluted the signal on individual rules.
+
+We split into three behavioral files in the recency zone (bottom of the prompt):
+- **`intake.md`** — intake mode behavior (already existed)
+- **`authoring.md`** — spec authoring behavior (already existed)
+- **`coding.md`** — code authoring behavior (new)
+- **`instructions.md`** — workflow, general principles, communication style (trimmed)
+
+The parallel between `authoring.md` (how to write specs) and `coding.md` (how to write code) is intentional. Two distinct disciplines, two files.
+
+### XML tags vs. bare markdown for behavioral sections
+
+The behavioral instruction files at the bottom of the prompt are wrapped in XML tags (`<intake_mode_instructions>`, `<spec_authoring_instructions>`, `<code_authoring_instructions>`) — except for `instructions.md`, which is left as bare markdown at the very end. The reasoning: XML tags create a subtle framing of "here's a reference block to consult," while bare text at the terminal position reads more like direct commands. Leaving `instructions.md` unwrapped may give it additional weight on top of the recency effect. This is a hypothesis worth testing, not a proven fact.
+
+The LSP guidance (`lsp.md`) is nested inside `<code_authoring_instructions>` since it's only relevant during code work.
+
+### Verification calibration: the 80/20 problem
+
+The agent was going overboard on post-build verification — screenshotting every page, running browser tests on every flow, being extremely thorough when "mostly working" would be sufficient. The issue was that `instructions.md` listed every verification tool with guidance on when to use each one, which the agent interpreted as "use all of these after every build."
+
+The fix was moving verification guidance to `coding.md` with an explicit 80/20 framing: spot-check the main happy paths, and if those work, trust that the edges are probably fine. The user can surface issues in chat. `runAutomatedBrowserTest` is reserved for interactive flows that can't be verified from a screenshot, or when the user reports something broken. This reframes the default posture from "verify everything" to "verify the critical path."
+
+### Mandatory SDK tool usage for model IDs
+
+The agent was guessing model IDs when writing code that calls AI models via the MindStudio SDK. Model IDs change frequently across providers (OpenAI, Anthropic, Google, etc.) and plausible-looking IDs are often wrong.
+
+The fix was three-layered:
+1. **`coding.md`** — hard rule in the behavioral instructions (recency zone): always use `askMindStudioSdk` before writing any SDK code, with expanded guidance on preferring the SDK over custom API connectors
+2. **`askMindStudioSdk.ts` tool description** — strengthened to frame model ID lookup as mandatory, not optional
+3. **`sdk-actions.md`** — existing mentions kept as reinforcement (middle zone, lower attention, but contextually relevant when the model is looking at SDK reference)
+
+The redundancy across three locations is intentional. The model might skip the behavioral instruction, or might not consult the reference docs, but the tool description is right there at decision time when it's choosing whether to call the tool or guess.
+
+### Negative vs. positive instruction framing — a more nuanced take
+
+Our initial research said "negative instructions perform worse than positive ones" and we rewrote all negatives as positives. After further discussion, the picture is more nuanced. There are two distinct mechanisms:
+
+**Case 1: Tendencies the model already has.** Overengineering, gold-plating, verbose output, adding unnecessary abstractions. The model is already inclined to do these things. Naming them in a negative instruction ("don't overengineer") activates the exact concept you're trying to suppress, but the concept was already active anyway. The real issue here is that negative framing is weaker than positive framing — "keep solutions minimal" gives the model something to aim for, while "don't overengineer" only says what to avoid. **For ingrained tendencies, prefer positive framing** because the activation cost is zero (already activated) and the positive frame gives better behavioral guidance.
+
+**Case 2: Specific things the model wasn't considering.** "Don't use regex backtracking," "don't use xyz-framework." If the model wasn't going to reach for this concept, mentioning it introduces it into the context window and primes the model to consider it. This is the classic "don't think about elephants" problem. **For things the model wouldn't do unprompted, don't mention them at all.**
+
+**The exception to Case 2: common defaults the model gravitates toward.** Purple gradients, Inter font, three-box-with-icons layouts, `useEffect` for data fetching. These are statistical medians from training data that the model will produce unprompted. Naming them as anti-patterns is worth the activation cost because they were going to happen anyway. This is why the design fragment's avoidance list works.
+
+**Where we landed on overengineering in `coding.md`:** We use a hybrid approach — lead with the positive directive ("match the scope of changes to what was asked, solve the current problem with the minimum code required") then follow with specific negative examples that draw bright lines ("a bug fix is just a bug fix, not an opportunity to refactor the surrounding code"). The negatives here aren't introducing new concepts; they're pushing back against things the model was already going to do.
+
+### Efficiency: avoiding redundant exploration
+
+Coding agents waste significant context and tool calls re-reading files they've already seen or re-researching things a subagent already looked up. We added a principle to `instructions.md`: "Work with what you already know." This applies broadly (spec work, intake, coding) so it lives in the general principles rather than `coding.md`. The framing is positive ("prefer acting on information you have") rather than negative ("don't re-read files").
+
+This was inspired by similar guidance in Claude Code's own system prompt, which is explicit about not duplicating work that subagents have done and not re-reading files unnecessarily.
+
+## What's Not Done
+
+- **Streaming tool output** — writeSpec and editSpec are tagged as streaming candidates but execute with full input for now. Deferred until the platform API supports streaming tool input fields.
+- **Auto-diagnostics after edit** — could auto-run lspDiagnostics after editFile/writeFile and append errors to the tool result. Depends on sidecar latency.
+
+### Removed: compile/recompile tools
+
+We removed the compile and recompile tools. Instead of a separate "compile" step, the flow is: intake conversation → write spec → pause for user review → build everything in one turn using the spec as the master plan. The agent writes methods, tables, interfaces, and manifest updates directly, guided by the spec. No separate compiler agent needed.

package/dist/prompt/actions/buildFromInitialSpec.md

@@ -0,0 +1,7 @@
+This is an automated action triggered by the user pressing "Build" in the editor after reviewing the spec.
+
+The user has reviewed the spec and is ready to build. Build everything in one turn: methods, tables, interfaces, manifest updates, and scenarios, using the spec as the master plan.
+
+When code generation is complete, verify your work: use `runScenario` to seed test data, then use `runMethod` to confirm a method works, then use `runAutomatedBrowserTest` to smoke-test the main UI flow. The dev database is a disposable snapshot, so don't worry about being destructive. Fix any errors before finishing.
+
+When everything is working, call `setProjectOnboardingState({ state: "onboardingFinished" })`.

package/dist/prompt/actions/publish.md

@@ -0,0 +1,12 @@
+This is an automated action triggered by the user pressing "Publish" in the editor.
+
+The user wants to deploy their app. Pushing to the `main` branch triggers a production deploy.
+
+Review the current state of the working tree — what has changed since the last commit, what's been committed since the last push, and the overall shape of recent work. Write a user-friendly changelog with `presentPublishPlan` — summarize what changed in plain language ("added vendor approval workflow", "fixed invoice totals", "updated the dashboard layout"). Reference specific code or file paths only when it helps clarity. This is what the user will see before deploying.
+
+If approved:
+- Stage and commit any uncommitted changes with a clean, descriptive commit message
+- Push to main
+- Let the user know their app is deploying
+
+If dismissed, acknowledge and do nothing.

package/dist/prompt/actions/sync.md

@@ -0,0 +1,19 @@
+This is an automated action triggered by the user pressing "Sync" in the editor.
+
+The user has manually edited files since the last sync. The `refs/sync-point` git ref marks the last known-good sync state. It's created using a temporary git index that captures the full working tree (including unstaged changes) as a tree object — so it represents exactly what the files looked like at sync time, not just what was committed.
+
+To see what the user changed, run: `git diff refs/sync-point -- src/ dist/`
+
+This compares the sync-point tree against the current working tree. Do not add `HEAD` or any other ref — the command as written diffs directly against the working tree, which is what you want.
+
+In the diff output: lines prefixed with `-` are what was in the file at last sync. Lines prefixed with `+` are the user's current edits. Sync should bring the other side in line with the `+` side.
+
+Analyze the changes and write a sync plan with `presentSyncPlan` — a clear markdown summary of what changed and what you intend to update. Write it for a human: describe changes in plain language ("renamed the greeting field", "added a note about error handling"), not as a list of file paths and code diffs. Reference specific code or file paths only when it helps clarity. The user will review and approve before you make changes.
+
+If approved:
+- If spec files (`src/`) changed, update the corresponding code in `dist/` to match
+- If code files (`dist/`) changed, update the corresponding spec in `src/` to match
+- If both changed, reconcile — spec is the source of truth for intent, but respect code changes that add implementation detail
+- When all files are synced, call `clearSyncStatus`
+
+If dismissed, acknowledge and do nothing.

package/dist/prompt/compiled/README.md

@@ -0,0 +1,100 @@
+# Compiled Prompt Fragments
+
+This directory contains distilled prompt fragments generated from the source
+docs in `docs/developer-guide/` (project root). These are loaded by `../index.ts` and injected
+into Remy's system prompt at runtime.
+
+## How to compile
+
+The compilation is done manually in a session with an LLM (Claude Code or
+similar). Work through the source docs and compile them into prompt-ready
+fragments.
+
+### Step 1: Compile with an LLM
+
+Open a session and ask it to work through the compilation. Give it these
+instructions:
+
+---
+
+**You will compile source docs into prompt fragments for Remy, a coding agent
+that builds MindStudio apps. The compiled fragments go in `src/prompt/compiled/`
+and are loaded into the agent's system prompt at runtime.**
+
+**Work through this one source file at a time, sequentially.** For each one:
+1. Read the source doc thoroughly
+2. Decide whether it should become its own fragment, be merged with a related
+   source, or be skipped entirely
+3. Present your draft of the compiled fragment
+4. Wait for review and feedback before moving to the next one
+
+Do not parallelize this work. Do not generate multiple fragments at once. Each
+fragment deserves careful attention — these are the instructions a coding agent
+will follow to build real products, and mistakes here propagate into every app
+it builds.
+
+Source files are in `docs/developer-guide/` at the project root.
+
+## How to think about compilation
+
+**Your audience is an LLM acting as a coding agent.** It needs to produce
+correct code, not learn concepts. Everything you write should be optimized
+for an agent that is actively building a MindStudio app and needs to get
+the details right.
+
+### What to keep
+
+- **API signatures, parameter types, return types, and code examples.**
+  These must be exactly right. The agent will copy these patterns directly
+  into the code it writes. A wrong type or a missing parameter means broken
+  code in production.
+- **Concrete examples, specific error cases, explicit constraints, enumerated
+  edge cases.** These are the highest-value content. A source doc that says
+  "ensure data integrity, including checking for duplicate keys, null foreign
+  references, and orphaned records" — the specific checks ARE the value.
+  Collapsing that to "ensure data integrity" loses the actionable detail.
+- **Tables and structured reference data.** Manifest fields, db predicates,
+  interface config schemas, role API methods — these are lookup references
+  the agent will consult while writing code. Keep them complete.
+- **Rules and constraints that affect correctness.** "Only packages declared
+  in package.json are available at runtime" is the kind of detail that
+  prevents hard-to-debug errors.
+
+### What to strip
+
+- **Setup instructions, installation steps, CLI commands.** The agent isn't
+  setting up a dev environment — it's writing code inside one.
+- **Platform internals and deployment pipeline details.** How the platform
+  builds and deploys is not the agent's concern.
+- **Conceptual explanations and philosophy.** "Why" something was designed
+  a certain way is rarely useful mid-task. Keep the "what" and "how."
+- **Marketing language, feature pitches, comparative positioning.**
+- **Cross-references to other docs** ("see Section X for details"). The
+  fragment should be self-contained.
+
+### Fragment format
+
+```markdown
+# Fragment Title
+
+Brief one-line context.
+
+## Section
+...content...
+```
+
+No YAML frontmatter. No meta-commentary. Just the reference content the
+agent needs. Each fragment should make sense on its own — the agent may
+not see all fragments in every session.
+
+---
+
+### Step 2: Review
+
+Read through the compiled fragments and verify code examples are accurate.
+The LLM may hallucinate API details — cross-check against the source docs.
+
+### Step 3: Commit
+
+The compiled fragments are committed to git. They're the snapshot the agent
+uses at runtime.

package/dist/prompt/compiled/auth.md

@@ -0,0 +1,77 @@
+# Roles & Auth
+
+MindStudio apps use role-based access control. Roles are defined in the manifest, assigned to users in the editor, and enforced in methods. The backend is the authority — methods enforce access control via `auth.requireRole()`. The frontend can read roles for conditional rendering, but enforcement always happens server-side.
+
+**Roles are optional.** Many apps don't need them — single-user apps, internal tools, simple utilities. If the app doesn't have multiple user types with different permissions, skip roles entirely. Only add them when the app explicitly needs to distinguish who can do what.
+
+## Defining Roles
+
+In `mindstudio.json`:
+
+```json
+{
+  "roles": [
+    { "id": "requester", "name": "Requester", "description": "Can submit vendor requests and purchase orders." },
+    { "id": "approver", "name": "Approver", "description": "Reviews and approves purchase orders." },
+    { "id": "admin", "name": "Administrator", "description": "Full access to all app functions." },
+    { "id": "ap", "name": "Accounts Payable", "description": "Processes invoices and payments." }
+  ]
+}
+```
+
+- `id` — kebab-case, used in code (`auth.requireRole('admin')`)
+- `name` — display name shown in the editor
+- `description` — what this role can do (useful for the agent and for users in the role assignment UI)
+
+Roles are synced to the platform on deploy. Adding or removing roles in the manifest creates or deletes them on the next push.
+
+## Backend Auth API
+
+```typescript
+import { auth } from '@mindstudio-ai/agent';
+```
+
+### `auth.requireRole(...roles)`
+
+Throws a 403 error if the current user doesn't have **any** of the specified roles. Use at the top of methods to gate access.
+
+```typescript
+auth.requireRole('admin');                // single role
+auth.requireRole('admin', 'approver');    // any of these
+```
+
+### `auth.hasRole(...roles)`
+
+Returns `boolean`. Same logic as `requireRole` but doesn't throw. Use for conditional behavior within a method.
+
+### `auth.userId`
+
+The current user's UUID. Always available.
+
+### `auth.roles`
+
+Array of role names assigned to the current user.
+
+### `auth.getUsersByRole(role)`
+
+Returns an array of user IDs that have the specified role. Useful for things like "notify all admins."
+
+## Frontend Auth
+
+```typescript
+import { auth } from '@mindstudio-ai/interface';
+
+auth.userId;            // current user's ID
+auth.name;              // display name
+auth.email;             // email address
+auth.profilePictureUrl; // URL or null
+```
+
+The frontend SDK provides display-only auth context. Role checking for UI purposes (showing/hiding elements) is done by reading role data from the backend:
+
+```typescript
+const { isAdmin, pendingCount } = await api.getDashboard();
+{isAdmin && <AdminPanel />}
+```
+
+The frontend is untrusted — anyone can modify JavaScript in the browser. Access control must be enforced server-side in methods. The frontend shows or hides UI based on role data from the backend, but the backend is the authority.

package/dist/prompt/compiled/design.md

@@ -0,0 +1,250 @@
+# Frontend Design Notes
+
+Design standards for web interfaces in MindStudio apps.
+
+## Quality Bar
+
+Every interface must feel like a polished, shipping product — not a
+prototype, not a starter template, not a homework assignment. The standard
+is iOS and Apple's bundled iOS apps, Notion, Stripe. If it wouldn't look
+good on Dribbble, Behance, or Mobbin, it's not done.
+
+MindStudio apps are end-user products. The interface is the product. Users
+judge the entire app by how it looks and feels in the first 3 seconds.
+
+## Design System from the Spec
+
+The brand spec files in `src/interfaces/@brand/` define the app's visual identity at the brand level: a small palette of named colors and font choices with one or two anchor styles. These are brand decisions, not implementation details. Derive the full design system (CSS variables, component styles, spacing, borders, etc.) from these foundations.
+
+Set up a lightweight theme layer early (CSS variables or a small tokens file) so brand colors and type styles are defined once and referenced everywhere. Map brand colors to semantic roles (background, text, accent, surface, border) and derive any additional shades you need. Keep it simple: a handful of CSS variables for colors and a few reusable text style classes or utilities for typography.
+
+**When brand spec files are present, always use the defined fonts and colors in generated code.** Do not pick your own fonts or colors when the spec defines them. Reference colors semantically (as CSS variables or named constants) rather than scattering raw hex values through the codebase.
+
+### Colors block format
+
+A `` ```colors `` fenced block in a `type: design/color` spec file declares 3-5 brand colors with evocative names, hex values, and descriptions. The names are brand identity names (not CSS property names), and the descriptions explain the color's role in the brand:
+
+```colors
+Midnight:
+  value: "#000000"
+  description: Primary background and dark surfaces
+Charcoal:
+  value: "#1C1C1E"
+  description: Elevated surfaces and containers
+Snow:
+  value: "#F5F5F7"
+  description: Primary text and foreground elements
+Smoke:
+  value: "#86868B"
+  description: Secondary text and supporting content
+```
+
+Derive additional implementation colors (borders, focus states, hover states, disabled states) from the brand palette rather than expecting them to be specified.
+
+### Typography block format
+
+A `` ```typography `` fenced block in a `type: design/typography` spec file declares fonts (with source URLs) and one or two anchor styles (typically Display and Body). Derive additional styles (labels, buttons, captions, overlines) from these anchors:
+
+```typography
+fonts:
+  Satoshi:
+    src: https://api.fontshare.com/v2/css?f[]=satoshi@400,500,600,700&display=swap
+  Clash Grotesk:
+    src: https://api.fontshare.com/v2/css?f[]=clash-grotesk@400,500,600&display=swap
+
+styles:
+  Display:
+    font: Satoshi
+    size: 40px
+    weight: 600
+    letterSpacing: -0.03em
+    lineHeight: 1.1
+    description: Page titles and hero text
+  Body:
+    font: Satoshi
+    size: 16px
+    weight: 400
+    lineHeight: 1.5
+    description: Default reading text
+```
+
+## Be Distinctive
+
+AI-generated interfaces tend to converge on the same generic look: safe
+fonts, timid colors, predictable layouts. Fight this actively. Every
+interface should have character and intentionality — it should look like a
+designer made deliberate choices, not like it was generated from a template.
+
+**Typography must be a conscious choice.** Pick fonts that are beautiful,
+distinctive, and appropriate for the product's personality. Generic system
+fonts and overused defaults make everything look the same. Typography is
+the single fastest way to give an interface identity.
+
+**Commit to a color palette.** One or two dominant colors with sharp accents
+outperform timid, evenly-distributed palettes. Draw inspiration from the
+app's domain — a finance tool might use deep greens and golds; a creative
+tool might use bold, saturated primaries. The palette should feel intentional
+and owned, not randomly selected.
+
+**Backgrounds create atmosphere.** Solid white or solid gray is the safe
+default and the enemy of distinctiveness. Layer subtle gradients, use warm
+or cool tints, add geometric patterns or contextual textures. The background
+sets the mood before the user reads a single word.
+
+**Layouts should surprise.** Avoid the predictable patterns: three equal
+boxes with icons, centered hero with subtitle, generic card grid. Use
+asymmetry, varied column widths, creative negative space, unexpected
+compositions. Study Behance and Mobbin for layout inspiration. Every screen
+should feel considered, not generated.
+
+## App-Like, Not Web-Page-Like
+
+Interfaces run fullscreen in the user's browser or a wrapped webview mobile
+app. They should feel like native apps, not websites.
+
+- **No long scrolling pages.** Use structured layouts: cards, split panes,
+  steppers, tabs, grouped sections that fit the viewport. The interface
+  should feel like a single-purpose tool, not a document.
+- **On mobile**, scrolling may be necessary, but use sticky headers, fixed
+  CTAs, and anchored navigation to keep key actions within reach.
+- Think of every screen as something the user opens, uses, and closes —
+  not something they read.
+
+## Visual Design
+
+- **Typography:** Strong hierarchy — clear distinction between headings,
+  body, labels, and captions. Use weight and size, not just color, to
+  create hierarchy. Choose fonts that elevate the interface and give it
+  personality.
+- **Color:** Clean, vibrant, intentional. Use color to communicate state
+  and guide attention, not to decorate. Commit to a direction — bold and
+  saturated, or muted and editorial — and follow through consistently.
+- **Spacing:** Consistent and generous. Padding and margins should be
+  uniform across all components — nothing should feel cramped or uneven.
+  White space is a feature, not wasted space.
+- **Components:** Every component (buttons, inputs, cards, modals, lists)
+  should look like it belongs to the same design system. Consistent border
+  radii, consistent shadows, consistent padding. If two buttons on the
+  same screen look different for no reason, that's a bug.
+
+## Animation
+
+Use motion to make interactions feel polished, not to show off. Focus on
+high-impact moments: a well-orchestrated page load with staggered reveals
+creates more delight than scattered micro-interactions everywhere.
+
+- Transitions between states should be smooth but fast.
+- Streaming content should flow into containers that grow naturally without
+  pushing sibling elements around.
+- No parallax, no cheesy scroll effects, no bounce/elastic easing, no
+  gratuitous loading animations.
+
+## Layout Stability
+
+Layout shift is never acceptable. Elements jumping around as content loads
+or streams in makes an interface feel broken.
+
+- Reserve space for content that hasn't arrived yet. Use fixed/min-height
+  containers, skeletons, or aspect-ratio boxes.
+- Images must always have explicit dimensions so the browser reserves space
+  before the image loads.
+- Loading-to-loaded transitions should swap content in-place without
+  changing container size.
+- Buttons must not change size during loading states. Use a fixed width or
+  `min-width`, and swap the label for a spinner or short text that fits the
+  same space. "Submit" becoming "Submitting..." should not make the button
+  wider and push adjacent elements around.
+- Conditional UI should use opacity/overlay transitions, not insertion into
+  flow that displaces existing content.
+
+## Responsive Design
+
+Every interface must work on both desktop and mobile.
+
+- Use the full viewport. Backgrounds should extend to edges.
+- On desktop, use the space — multi-column layouts, sidebars, spacious
+  cards. Avoid narrow centered columns with empty gutters on a wide screen.
+- On mobile, stack gracefully. Prioritize content and actions.
+- Test at both extremes. A layout that only looks good at one breakpoint
+  is not done.
+
+## Forms
+
+Forms should feel like interactions, not paperwork.
+
+- Group related fields visually. Use cards or sections, not a flat list.
+- Inline validation — show errors as the user types, not after submit.
+  Validation must never introduce layout shift.
+- Loading states after submission. Always indicate that something is
+  happening.
+- Disabled states should be visually distinct but not jarring.
+- Even data entry can be beautiful. Pay attention to alignment, padding,
+  and spacing. Consistency is key.
+
+## Data Fetching and Updates
+
+The UI should feel instant. Never make the user wait for a server round-trip
+to see the result of their own action.
+
+- **Optimistic updates.** When a user adds a row, toggles a setting, or
+  submits a form, update the UI immediately and let the backend confirm
+  in the background. If the backend fails, revert and show an error.
+- **Use SWR for data fetching** (`useSWR` from the `swr` package). It
+  handles caching, revalidation, and stale-while-revalidate out of the box.
+  Prefer SWR over manual `useEffect` + `useState` fetch patterns.
+- **Mutate after actions.** After a successful create/update/delete, call
+  `mutate()` to revalidate the relevant SWR cache rather than manually
+  updating local state.
+- **Skeleton loading.** Show skeletons that mirror the layout on initial
+  load. Never show a blank page or centered spinner while data is loading.
+
+## What Good Looks Like
+
+- A dashboard that feels like Linear — clean data, clear hierarchy, every
+  pixel intentional.
+- A form that feels like Stripe Checkout — focused, calm, confident.
+- A settings page that feels like iOS Settings — organized, scannable,
+  no clutter.
+- A list view that feels like Notion — flexible, spacious, information-dense
+  without feeling crowded.
+
+## What to Actively Avoid
+
+These are the hallmarks of generic AI-generated interfaces. Every one of
+them makes an interface look like it was auto-generated rather than designed.
+
+- **Generic fonts.** Overused defaults that strip away all personality.
+  Instead: pick a distinctive Google Font that fits the app's character.
+- **Purple or indigo anything.** Purple gradients, purple buttons, purple
+  accents. This is the #1 AI-generated aesthetic cliché. Instead: use
+  a color palette that fits the app's domain — greens for finance, warm
+  neutrals for productivity, bold primaries for creative tools, or just
+  confident grayscale.
+- **Colored left-border callout boxes.** Rounded divs with a thick colored
+  `border-left` — the generic "info card" pattern. Instead: use typography,
+  spacing, and background tints to create hierarchy. If you need to call
+  something out, use a full subtle background or a top border.
+- **Three equal boxes with icons.** The default AI landing page layout.
+  Instead: use asymmetric layouts, varied column widths, or a single
+  focused content area.
+- **Timid color palettes.** Evenly distributed, non-committal colors.
+  Instead: one or two dominant colors with sharp accents. Commit to a
+  direction.
+- **Card-heavy nested layouts.** Cards inside cards, everything boxed.
+  Instead: use space, typography, and dividers to create hierarchy without
+  extra containers.
+- **Inconsistent spacing.** 12px here, 20px there, 8px somewhere else.
+  Instead: define a spacing scale (4/8/12/16/24/32/48/64) and use it
+  everywhere.
+- **Components from different visual languages.** Rounded buttons next to
+  square inputs, shadows mixed with flat design. Instead: pick one system
+  and apply it consistently.
+- **Long scrolling forms with no visual grouping.** Instead: group fields
+  into sections with clear headings, cards, or stepped flows.
+- **Cramped layouts.** Text pressed against edges, no room to breathe.
+  Instead: generous padding, comfortable margins, let the content float.
+- **Loading states that are just a centered spinner on a blank page.**
+  Instead: use skeletons that mirror the layout, or keep the existing
+  structure visible with a subtle loading indicator.
+- **Any interface where the first reaction is "this looks like a demo" or
+  "this looks like it was made with a website builder."**