# Building Rask apps with AI assistants

Rask ships first-class guidance for AI coding tools, so an assistant can scaffold and extend a
Rask app correctly without you re-explaining the conventions.

## What's included

- **`llms.txt`** (repo root) — the index AI tools read first. One dense entry per guide carries the rules
  that make Rask code compile (the chain not `new`, the children indexer, required steps versus optional
  setters, the root rendering into `<body>`, routing and lifecycle, scoped CSS/TypeScript, callbacks, forms,
  auth) and links the guide behind each. A generated project ships no `AGENTS.md` of its own — point your
  assistant at `llms.txt`.
- **`AGENTS.md`** (repo root) — for an assistant working **on Rask itself**: the gate, the repo's
  workflows, how a change lands. It is not app guidance.
- **The published set on rask.sh**, for an assistant that reads the web rather than a checkout:
  [`https://rask.sh/llms.txt`](https://rask.sh/llms.txt) indexes every guide with a one-line summary,
  [`https://rask.sh/llms-full.txt`](https://rask.sh/llms-full.txt) is every app-building guide in one
  file, and each guide's Markdown sits at its page's address plus `.md` — for example
  [`https://rask.sh/docs/guides/cqrs.md`](https://rask.sh/docs/guides/cqrs.md). They are generated from the
  same `docs/` at every site publish, with the links rewritten to resolve on the site.
- **The `docs/` set** — a task guide for each subsystem (getting-started, elements & the DSL, routing,
  lifecycle, composition (every element event as MDN's type, keyboard values as the generated `Keys`/`Codes`
  constants), subscriptions, forms, js-interop, browser APIs, authentication, data access, HTTP & files,
  PWA, CQRS, diagnostics, testing, accessibility — typed `Aria*` steps and `AriaRole` constants generated from
  the WAI-ARIA spec, so an assistant writes `.AriaExpanded(open)` rather than guessing at `.Aria("expanded", "true")`
  strings, … — the full curated list is in the on-site guides index) plus the
  Tailwind, compiled at build time (`docs/tailwind.md`: utilities scanned from your own C# source, zero-JS
  interactivity, typed utility classes). Each guide embeds its examples as live demos, so the source
  a user reads on GitHub and the running showcase stay in lockstep.

## Islands

When a user already has front-end components, an assistant should host them rather than rewrite them:
a React, Preact, Solid, Vue, Svelte, Angular or Lit file becomes an ordinary Rask component by
deriving a `partial` class from the matching base (`ReactComponent`, `VueComponent`, …) beside it, and
a real Blazor component by deriving from `BlazorComponent<T>`. `rask new MyApp --islands react`
scaffolds a working pair. The rules that are easy to get wrong — props declared in C#, a Lit element
written without decorators, no Rask markup inside an island, no `AddRaskBlazor()` call needed — are in
[islands](https://rask.sh/docs/guides/islands/) and [Blazor components](https://rask.sh/docs/guides/blazor-components/), and in their `llms.txt` entries.

## How to use it

1. Scaffold: `rask new MyApp`.
2. Point your assistant at Rask's `llms.txt` — the repo-root file, or `https://rask.sh/llms.txt` if it reads the web.
3. Ask for features in plain language — the assistant follows the conventions and links to
   `docs/diagnostics.md` when it hits a `RASKxxx` compile diagnostic.
4. Ship it: `rask deploy --host user@box --domain app.example.com` builds and runs it on a single
   host over SSH with automatic HTTPS.

## Keeping it accurate

The repo-root `llms.txt` and this guide are part of the public API surface: when a user-facing
behavior changes, they're updated in the same commit (see `docs/development-workflow.md`). GitHub is
the single source of truth — these files are committed, not local-only.