AI guidance
AGENTS.md, agent docs, and hot reload r/R in generated projects.
Every kasy new project ships an AI guidance package (Cursor, Claude Code,
Copilot, MCP). It is not end-user app documentation. It is the contract for
editing the codebase with an assistant.
This page lives in kasy.dev/docs (the Docs section of the site), not on the
marketing landing page. The files below ship inside the project after kasy new.
Full index in the repo: docs/agent-guidance.md. Master contract:
AGENTS.md.
File map
| File | For | What it is |
|---|---|---|
AGENTS.md | AI + dev | Master contract (golden rules, architecture, Browser QA) |
CLAUDE.md | Claude Code | Points to AGENTS.md |
DESIGN_SYSTEM.md | AI + dev | Tokens, typography, components, semantics |
docs/agent-guidance.md | AI + dev | This map, inside the project |
docs/agent-browser-qa.md | AI | Checklist when testing in the browser |
.cursor/rules/kasy-agent-contract.mdc | Cursor | Always-on: analyze, reload r/R, terminal |
.cursor/rules/kasy-design-system.mdc | Cursor | Always-on: kit UI |
.cursor/skills/kasy-project/SKILL.md | Cursor | Workflow entry → AGENTS.md |
Firebase, Supabase, and API backends get the same package. Backend patches only change the data layer.
r vs R
With kasy run or kasy run --web already running, after the AI finishes an edit:
| Change | Command |
|---|---|
| Prettier button, layout, colour, text, style | r (hot reload) |
Bug, provider, route, initState, main(), logic | R (hot restart) |
Sent r but terminal shows error or “hot reload rejected” | R |
F5 in the browser tab does not recompile Dart.
How to send reload:
- MCP (preferred):
reload_app(action=reloadfor UI,action=restartfor logic). Web only (kasy run --web). iOS/Android: terminalr/R. kasy runterminal (typerorRand read the output).- Device preview toolbar (
randRbuttons on the preview bar).
The AI can use the terminal when the environment allows shell access. It should not pretend there is no terminal. If blocked, ask the user or use the preview toolbar.
Live session
Saving a Dart file does not update the running app by itself. With kasy run
active, send r or R to the process (terminal or preview toolbar).
Terminal and toolbar use the same dev bridge.
The kasy run --web watcher updates the status dot on save (analyze). To see
Dart changes in the running app, you still need r or R (you, or the AI
after finishing a task with a live session).
Browser QA
When the AI navigates, fills fields, or validates a flow in the browser:
full checklist in docs/agent-browser-qa.md in the project. Technical
context (semantics, JS bridge): Web guide → Browser QA. MCP: browser_qa_guide.
Skill vs AGENTS.md
AGENTS.md is already the contract for Claude Code and tools that read the repo.
The kasy-project skill in .cursor/skills/ is a Cursor entry workflow
(marketing-aligned). It does not duplicate the contract; it points to AGENTS.md
and r/R reload rules.
Structured questions (MCP)
When the assistant needs several decisions (create project, run platform, configure credentials), the Kasy MCP instructs the AI not to paste numbered lists in chat.
- MCP form: clients without AskQuestion only.
create_projectwithuseElicitationForm: trueand missingdirectory/backend. In Cursor, use AskQuestion and pass all args; never call withoutdirectory/backend. - IDE quiz: in Cursor, AskQuestion step by step (backend, region, push on Supabase/API). Google is ON by default (independent of push); do not ask Google separately. Without a companion, credentials later via
configure_google_login. - Plain text: last resort. One question at a time. License keys and OAuth = plain text, not quizzes.
Related
- Web guide (port 5555, preview, hot reload)
- Kasy MCP (
browser_qa_guide,run_app) - Design system (tokens in the app)
Last updated on 08/23/2026