# AI Agent Guide for Rip

**Purpose:** This document helps AI assistants understand and work with the Rip language compiler and its ecosystem of packages.

**What is Rip:** An elegant reactive language that compiles to modern JavaScript (ES2022), featuring zero dependencies, self-hosting capability, and built-in reactivity primitives.

Detailed subsystem notes live in nested `AGENTS.md` files in the relevant directories (`src/`, `docs/`, `packages/ui/`, `packages/vscode/`, `packages/stamp/`, `test/types/`).

---

## Quick Start

### Essential Commands

```bash
# Debug any code
echo 'your code' | ./bin/rip -t  # Tokens (lexer)
echo 'your code' | ./bin/rip -s  # S-expressions (parser)
echo 'your code' | ./bin/rip -c  # JavaScript (codegen)

# Run tests
bun run test
bun test/runner.js test/rip/FILE.rip

# Rebuild parser (after grammar changes)
bun run parser

# Build browser bundle
bun run build

# Serve an app (watches *.rip, HTTPS, mDNS)
rip server

# Schema migrations (diff declared :models vs the database)
rip schema status [models.rip]
rip schema make <name> [models.rip] [--allow-lossy] [--allow-destructive]
rip schema migrate [models.rip]

# Interactive REPL (toggle .tokens, .sexp, .js modes)
./bin/rip
```

### File Editing Rules

| File                      | Can Edit? | Notes                                                  |
| ------------------------- | --------- | ------------------------------------------------------ |
| `src/compiler.js`         | Yes       | Code emitter (`CodeEmitter`); main compiler work       |
| `src/lexer.js`            | Yes       | Lexer and rewriter                                     |
| `src/types.js`            | Yes       | Type system sidecar                                    |
| `src/components.js`       | Yes       | Component system sidecar                               |
| `src/schema/`    | Yes       | Schema feature subdirectory (`schema` keyword) — entry `schema.js`, runtime fragments, loaders, `dts.js`. Imported from sibling modules as `./schema/schema.js`. |
| `src/grammar/grammar.rip` | Carefully | Run `bun run parser` after changes                     |
| `src/parser.js`           | Never     | Generated file                                         |
| `src/sourcemaps.js`       | Yes       | Source map generator                                   |
| `src/browser.js`          | Yes       | Browser entry point                                    |
| `rip-loader.js`           | Yes       | Bun plugin for `.rip` compilation and import rewriting |
| `src/grammar/solar.rip`   | Never     | Given parser generator                                 |
| `test/rip/*.rip`          | Yes       | Test files                                             |

### Critical Rules

- **Never guess what code does — verify it.** Before claiming something is unnecessary, redundant, or works a certain way, read the source. This applies to Rip internals, packages, and external dependencies alike. If you can't verify, say so.
- **Never edit `src/parser.js`** — it is generated (`bun run test:parser-fresh`, part of `test:all`, regenerates it and fails on any hand-edit or staleness)
- **Never edit `src/grammar/solar.rip`** — it is given
- **Never commit without running tests** — `bun run test` must pass
- **Never add dependencies** — zero dependencies is a core principle
- **Never read or execute scripts directly** — use `bun run <name>`
- **Never write `x ? y` in Rip** — binary existential was removed; use `x ?? y` or full ternary `x ? y : z`
- **Never write `await fn(args)` in `.rip` source when `fn!` will do** — the dammit operator is the idiomatic form. `fetch! url` compiles to `await fetch(url)`; `User.find! 1` to `await User.find(1)`; `user.save!` to `await user.save()`. Reserve raw `await` for JS interop in `.js` files, tests that document the await→!  equivalence, and the rare cases where `fn!` is ambiguous with a dammit-returning expression.
- Run `bun run parser` after grammar changes
- Run `bun run build` after codegen, `components.js`, `browser.js`, or `app.rip` changes
- Run `bun run build:schema-runtime` after editing any `src/schema/runtime-*.js` fragment (CI's `test:schema-fresh` fails on staleness)
- **Every fenced `coffee` block in `docs/RIP-SCHEMA.md` must compile** — `bun run test:docs` enforces it (part of `test:all`). Annotate intentional exceptions with `<!-- doctest: skip -->` (fragments/templates) or `<!-- doctest: fail -->` (documented compile errors) on the line above the fence. When editing that doc, run `bun run test:docs` before committing.
- Run `bun run bump` for the standard release flow
- **In a typed Rip codebase, always run `rip check` after edits.** A project is typed if its `package.json` has `rip.strict: true` or `rip.checkAll: true`, or any `.rip` files use `:` type annotations. `rip check` catches both type errors and shadow-TypeScript emitter bugs that the runtime won't surface.
- **If a `@rip-lang/*` package advertises a typed public API, keep it honest with `rip check --audit`.** A package "claims to be typed" if its entry file has `:` type annotations on exported symbols, or if downstream typed code imports it. For those, run `rip check --audit` before publishing or merging API changes — it runs the normal type check and walks the public surface for `any` leaks. A clean exit (0) means the source type-checks and every export is fully typed for consumers. Untyped packages with no typed consumers can stick with plain `rip check`.
- **When working on the compiler, lexer, or source-map machinery, use `rip check --sourcemap`** to verify that every identifier round-trips through the generated source map (i.e. hover and go-to-def work in editors). This is a compiler-development diagnostic, not a package-quality check — gaps usually mean the audit's skip list is incomplete or that codegen lost a binding, both of which are compiler-side concerns.

## Compilation Pipeline

```text
Rip Source -> Lexer -> emitTypes -> Parser -> S-Expressions -> CodeEmitter -> JavaScript
                       (types.js)           (arrays + .loc)                  + source map
                          ↓
                       file.d.ts (when types: "emit")
```

**Key insight:** S-expressions are simple arrays like `["=", "x", 42]`, not large AST objects.

Detailed compiler, lexer, and component internals are in `src/AGENTS.md`.

---

## Common Tasks

### Fix a Bug in Codegen

```bash
echo 'failing code' | ./bin/rip -s
rg "GENERATORS" src/compiler.js
bun run test
```

### Add a Grammar Rule

```bash
# Edit src/grammar/grammar.rip
bun run parser
# Add codegen in src/compiler.js if needed
bun run test
```

## Testing

Test helpers:

```coffee
test "name", "x = 42; x", 42
code "name", "x + y", "(x + y)"
fail "name", "invalid syntax"
```

Test files live in `test/rip/`.

Component testing notes are in `src/AGENTS.md`. Type-system and audit guidance is in `packages/vscode/AGENTS.md` and `test/types/AGENTS.md`.

---

## Packages

The `packages/` directory contains optional packages written in Rip, with zero dependencies, running on Bun.

### Package export style

**Prefer named-only exports** for new `@rip-lang/*` packages. The rest of the typical package surface (types, classes, helpers) is already named-only, so adding a default for the main value just creates a second way to import the same thing.

**Hard rule:** if a package's entry point exports a typed value — e.g. `export http = makeInstance()` where `makeInstance` returns a typed instance — do **not** also re-export it as default. The default-export binding loses the inferred type through Rip's DTS pipeline, so downstream `import http from '@rip-lang/http'` sees `any` while `import { http }` correctly sees `HttpInstance`. Named-only avoids that footgun entirely.

A few existing packages still ship `export default` (`@rip-lang/time`, `packages/script`). That's tolerated for backwards compatibility — don't churn published APIs solely to enforce the style — but don't add new defaults.

**Annotate the public surface at minimum.** Ideally every binding in a package is typed, but realistically that bar is hard to enforce. The practical contract: every `export` must reach consumers with a fully-typed signature (what `rip check --audit` measures). Always annotate:

- exported `def`/`class`/`type`/`interface` declarations and their parameters/return types
- the return type of any exported function whose body assembles a shape that needs to match a public contract (e.g. `makeInstance(): HttpInstance` in [packages/http/http.rip](packages/http/http.rip))
- fields of exported types/interfaces

Internal helpers, locals, and private types may rely on inference — but annotate them too when it helps readability or pins down a tricky shape.

### Browser-safe packages

Packages that should be auto-discovered and bundled into the browser bundle by `@rip-lang/server`'s `serve()` middleware must opt in via `package.json`:

```json
{
  "name": "@rip-lang/http",
  "rip": { "browser": true }
}
```

With this flag set, the `serve()` middleware walks the app's declared `@rip-lang/*` dependencies, compiles each package's entry, and stores its modules under the `_pkg/<pkg>/` bundle prefix (see [packages/app/AGENTS.md](packages/app/AGENTS.md)). Bare specifiers like `import { http } from '@rip-lang/http'` are rewritten at compile time to the bundle-relative path.

Server-only packages (`@rip-lang/server`, `@rip-lang/db`, anything that touches `node:*`, `Bun.*`, or the filesystem) must **not** set this flag. If a browser-bound component file imports a package that lacks `rip.browser: true`, the bundler errors with *"package X is not browser-safe (declares no `rip.browser` entry)"* rather than producing a broken bundle.

Rule of thumb: if every public API in the package works in a browser (uses only `fetch`, DOM, or pure JS), set `rip.browser: true`. Otherwise leave it off.

### @rip-lang/server

Sinatra-style web framework with magic `@` context, validation helpers, file serving, middleware composition, multi-worker process management, hot reloading, automatic HTTPS, mDNS, and request queueing.

Key ideas:

- handlers use `@req`, `@json()`, `@send()`, `@session`
- `read()` validates params and body
- `post '/x', input: SomeSchema, ->` validates the JSON body through a Rip schema before the handler runs (400 with structured issues; parsed value at `@input`) and contributes to the auto-generated `GET /openapi.json`
- `@send(path, type?)` serves files
- `use()` composes middleware

```coffee
import { get, use, start, notFound } from '@rip-lang/server'

get '/', -> { message: 'Hello!' }
get '/css/*', -> @send "public/#{@req.path.slice(5)}"
notFound -> @send 'index.html', 'text/html; charset=UTF-8'
start port: 3000
```

### Rip App

Application framework built into Rip — stash, resource, timing, components store, file-based router, renderer, launch, and shared ARIA helpers. Lives in `packages/app/index.rip`, compiled into `rip.min.js` so a single `<script src="rip.min.js">` is enough to build a complete app. `<script type="text/rip">` sources compile into one shared scope, and the framework renders with fine-grained DOM updates.

(Rip UI is the separate widget package at `packages/ui/` — `Dropdown`, `MultiSelect`, `Combobox`, etc. — distributed as `@rip-lang/ui`. The two terms do not overlap.)

Key ideas:

- shared scope across all Rip script tags
- bundle mode via `data-src`
- stash seeded from `data-state`
- file-based routing
- hot reload through `/watch`
- router auto-sets `aria-current` (`page` exact, `true` prefix) on in-document anchors; per-anchor `data-router-ignore` opts out of SPA interception, `data-router-noscroll` opts out of scroll reset
- typed projects get compile-time route checking: `<a href: "...">`, `router.push`, and per-route `@params` are narrowed against a `__RipRoutes` union built from `app/routes/`. Anchor `href` uses a `const`-generic conditional — `/`-prefixed string literals must satisfy `__RipRoutes`, while external schemes (`https:`, `mailto:`), fragments (`#x`), and dynamic `string` values fall through. Typos like `<a href: "/crat">` or `@router.push "/bogus"` fire `TS2322`/`TS2345`. `router.replace` stays at `string` (query-string mutation pattern).

Component naming in render templates:

- **PascalCase** names are child components — must start with uppercase, contain at least one lowercase letter, and have no underscores (`App`, `AuthScreen`, `HomeSection`)
- **ALL_CAPS** names are regular variables/constants, not components (`DEFAULT_SCREEN`, `SECTIONS`, `MAX_RETRIES`)
- **Lowercase** names are DOM elements (`div`, `span`, `button`)

Stash reactivity in components:

- Inside a component's `render`, expressions rooted at `this` (`@app.data...`, component members) or at a `for`-loop iter var whose collection is reactive (e.g. `item.qty` inside `for item in @items`) are tracked as reactive by the compiler
- Shared-scope variables are treated as static — they render once and never update
- To use stash data reactively, declare a component-local binding: `theme = @app.data.theme`
- Iter-var tracking covers direct member access only — `item.foo`, `item[0]`, `item.a.b`. Aliases (`local = item; local.foo`) and destructuring (`for {qty} in items`) are not tracked

```coffee
import { get, use, start, notFound } from '@rip-lang/server'
import { serve } from '@rip-lang/server/middleware'

dir = import.meta.dir
use serve dir: dir, title: 'My App', watch: true
get '/css/*', -> @send "#{dir}/css/#{@req.path.slice(5)}"
notFound -> @send "#{dir}/index.html", 'text/html; charset=UTF-8'
start port: 3000
```

### Other Packages

- `@rip-lang/db` — DuckDB server with official UI and ActiveRecord-style client
- `@rip-lang/swarm` — worker-thread job runner
- `@rip-lang/csv` — CSV parser and writer
- `@rip-lang/http` — zero-dependency HTTP client
- `@rip-lang/print` — syntax-highlighted code printer
- `@rip-lang/validate` — the validation/normalization vocabulary (browser-safe): `read()` validators and `~:name` schema coercers from one table; `@rip-lang/server` depends on it and re-exports its surface
- `@rip-lang/time` — tiny immutable date/time library with IANA timezones + Duration (US-English, zero runtime deps; dayjs is devDependency for parity tests)
- `packages/ui/` — headless UI widgets written in Rip
- `packages/vscode/` — VS Code / Cursor extension

### Package Development

- packages use `workspace:*` linking
- after modifying a package locally, run `bun install` from the project root
- packages written in Rip need the loader, so run from the root or use `rip server`
- `import.meta.dir` resolves to the package's actual filesystem path
- `@rip-lang/server` binds `this` to the request context

### Dev machine setup — run from source, not from npm

The dev workflow in this repo is to **run everything out of the checkout**, not from installed npm packages. Three scripts enforce that:

| Script | When it runs | What it does |
| --- | --- | --- |
| `bun run link-global` | once per machine, manual | Symlinks CLIs (`rip`, `rip-db`, `rip-print`, `rip-server`) into `~/.bun/bin/`, symlinks `rip-lang` and every `@rip-lang/<pkg>` into `~/node_modules/` and `~/.bun/install/global/node_modules/`, and strips any npm-installed `rip-lang` from bun's global manifest so `bun i -g anything` can't silently shadow the workspace |
| `bun run link-local` | auto, every `bun install` (postinstall) | Replaces every `node_modules/.bun/rip-lang@*/node_modules/rip-lang/` cache inside this repo with a symlink to the repo root, plus re-links top-level `node_modules/rip-lang` |
| `bun run link-check` | auto, every `bun install` (postinstall) | Guardrail: verifies `require.resolve('rip-lang/package.json')` lands inside the repo. If a stale tarball is shadowing the workspace it fails fast with a `rm -rf node_modules bun.lock && bun install` remediation |

After `bun run link-global`, every `rip server` invocation — from any cwd — executes `packages/server/server.rip` in this workspace via `packages/server/bin/rip-server` and its `import.meta.url` lookup. Edits to `packages/server/*` are picked up on the next run. **No publish, no `bun add -g`, no copy of `@rip-lang/server` anywhere — only symlinks pointing back at this repo.**

The `bin/rip` subcommand dispatch (`bin/rip-<name>` → `bin/<name>` → `packages/*/bin/rip-<name>` → local `node_modules/.bin` → PATH) converges on the workspace at either step 3 (when cwd is inside the repo) or step 5 (when `rip-server` on the global PATH is the link-global symlink). Either path runs workspace code.

Use `bun run bump` for full rip-lang releases; publishing `@rip-lang/server` and friends to npm is for downstream consumers outside this repo, not for using them locally.

Widget conventions and gotchas are in `packages/ui/AGENTS.md`. Browser runtime details are in `docs/AGENTS.md`.

---

## Source Maps

Rip emits inline Source Map V3 data URLs.

- every s-expression node carries source location info
- the code generator builds output-to-source mappings
- `SourceMapGenerator` in `src/sourcemaps.js` emits VLQ mappings
- `toReverseMap()` provides generated-to-source lookup used by the VS Code extension

```bash
rip -m example.rip
rip -cm example.rip
```

---

## Language Features

> **CRITICAL — `?` operator rules (AI agents read this carefully):**
>
> - `x ? y : z` — VALID (ternary, requires both `: z` branch)
> - `x ? y` — **INVALID, DO NOT USE** (binary existential was removed)
> - `x ?? y` — VALID (nullish coalescing, replaces the old `x ? y`)
> - `x?` — VALID (existence check, compiles to `x != null`)
>
> The most common AI mistake is writing `x ? y` to mean "if x exists, use y".
> That syntax does not exist in Rip. Always use `x ?? y` for nullish coalescing
> or `x ? y : z` for a full ternary. There is no two-operand `?` form.

> **CRITICAL — no comma before a trailing `->` arrow:**
>
> - `sketch "xy" ->` — CORRECT
> - `sketch "xy", ->` — WRONG (unnecessary comma)
> - `get '/path' ->` — CORRECT
> - `get '/path', ->` — WRONG
>
> When a `->` function is the last argument to a call, do **not** put a comma
> before it. The arrow implicitly closes the argument list. This applies to
> all calls: `get`, `post`, `sketch`, `test`, `setTimeout`, etc.

> **CRITICAL — use the dammit operator, not raw `await`, in `.rip` source:**
>
> - `fetch! url` — CORRECT (compiles to `await fetch(url)`)
> - `await fetch(url)` — WRONG in `.rip` source (JS idiom leaking in)
> - `User.find! 1` — CORRECT
> - `user.save!` — CORRECT (no parens needed)
> - `User.where(active: true).all!` — CORRECT (dammit only on the
>   terminating call in a chain; `.where/.order/.limit` are sync)
> - `await User.find(1)` — WRONG (write `User.find! 1`)
>
> `!` is Rip's native async marker. It handles the `await`, inserts the
> call parens if absent, and reads more cleanly in a chain. Reserve raw
> `await` for JS/TS interop files, test fixtures that document the
> equivalence, or the rare case where `fn!` is ambiguous with a
> dammit-returning expression (basically never).

> **CRITICAL — don't shadow Rip's injected globals:**
>
> Rip auto-injects these helpers into `globalThis` at the top of every
> compiled file (see the Standard Library table below): `p`, `pp`,
> `warn`, `kind`, `assert`, `abort`, `exit`, `noop`, `rand`, `sleep`,
> `todo`, `raise`, `zip`. If you declare a local variable with the same
> name, the compiler emits code that silently mis-references them, with
> failure modes that don't mention shadowing at all — common ones
> include strict-mode "Duplicate parameter name" errors and
> "`x` is not defined" at runtime:
>
> - `p = navigator.clipboard.writeText(...)` — WRONG (shadows `globalThis.p` = `console.log`)
> - `prom = navigator.clipboard.writeText(...)` — CORRECT
> - `warn = condition ? 'yellow' : 'red'` — WRONG (shadows `globalThis.warn` = `console.warn`)
> - `lvl = condition ? 'yellow' : 'red'` — CORRECT
>
> If you catch yourself using a short name that matches any Standard
> Library helper, rename. One-letter names like `p` are particularly
> risky.

> **CRITICAL — boolean prop shorthand is a literal `true`, not a variable:**
>
> Inside a `render` block, a bare identifier in a PascalCase component
> arg list is shorthand for `name: true` (JSX semantics):
>
> - `Btn outline, link` — `Btn({outline: true, link: true})`
> - `Btn outline, "Save"` — `Btn({outline: true, children: "Save"})`
> - `Btn outline: false` — explicit value still wins, stays `false`
>
> The bare identifier is **always** the literal `true`, even when a
> same-named local binding exists in scope. To pass a variable, write
> the prop explicitly:
>
> - `Btn outline` — `{outline: true}` (always, no scope lookup)
> - `Btn outline: outline` — passes the local `outline` variable
>
> Scope: PascalCase component calls inside `render` only. DOM element
> calls (`div outline` — text child) and imperative calls outside
> `render` (`Btn(outline)` — positional arg) are unaffected.

> **CRITICAL — `:` is the type-annotation separator everywhere; `::` is prototype access only (e.g. `String::trim`), never a type operator:**
>
> - `x: number = 0` — CORRECT (typed declaration)
> - `def foo(opts: { host?: string, port?: number })` — CORRECT
> - `def greet(name: string): string` — CORRECT (param + return type)
> - `x:: number` — ERROR (`::` is not a type annotation; use a single `:`)
>
> Typed destructuring uses an *external* type, TS-style — annotate the whole
> pattern, not each binding:
>
> - `def foo({name, age}: { name: string, age: number })` — CORRECT
> - `def foo({name: string})` — WRONG (that's a rename to a binding called `string`)
>
> Rule of thumb: a single `:` after a name/param/`)`/pattern is a type; fields
> inside a `{ ... }` type literal also use `:` (TS-style). `::` only ever means
> `.prototype`.

### Removed (from CoffeeScript / Rip 2.x)

| Feature                            | Replacement                                           |
| ---------------------------------- | ----------------------------------------------------- |
| postfix spread/rest (`x...`)       | prefix only: `...x`                                   |
| prototype access (`x::y`, `x?::y`) | `.prototype` or class syntax                          |
| **binary existential (`x ? y`)**   | **`x ?? y` (NEVER use `x ? y`, it is not valid Rip)** |
| `is not` contraction               | `isnt`                                                |
| `for x from iterable`              | `for x as iterable`                                   |
| type-suffix `T?` / `T??` / `T!`    | write `T \| undefined`, `T \| null \| undefined`, `NonNullable<T>` (use `?:` for prop/param/field optionality) |

### Added

| Feature               | Syntax           | Purpose                                    |
| --------------------- | ---------------- | ------------------------------------------ |
| ternary operator      | `x ? a : b`      | JS-style ternary (must have both branches) |
| postfix ternary       | `a if x else b`  | Python-style ternary                       |
| `for...as` iteration  | `for x as iter`  | iterable loop                              |
| `as!` async shorthand | `for x as! iter` | shorthand for `for await`                  |
| presence check        | `x?!`            | truthy-or-undefined Houdini operator       |
| optional chain assign | `x?.prop = val`  | guarded assignment                         |
| tagged template `$`   | `sh $"cmd #{x}"` | injection-safe tagged template             |
| dotted keys           | `{a.b: 1}`       | flat string key in object literals         |
| map literal           | `*{a: 1}`        | real `Map` with any key type               |
| symbol literal        | `:redo`          | interned symbol via `Symbol.for('redo')`   |
| optional prop / param | `name?: T`      | `?` before `:` marks the name optional (params, type fields, props) |
| boolean prop shorthand | `Btn outline, link` | JSX-style `{outline: true, link: true}` for child components in `render` |
| type cast             | `x as Type`      | type-checker-only assertion, **erased at runtime** — narrows for ALL expression forms (identifier, member, call/index/paren result); grammar reduces an opaque-string marker to `['cast', expr, typeStr]` (never parses a type). TS precedence: looser than arithmetic/member/call, tighter than relational; left-assoc chains |

### Kept

| Feature               | Syntax                    | Compiles to          |
| --------------------- | ------------------------- | -------------------- |
| existence check       | `x?`                      | `(x != null)`        |
| optional chaining     | `a?.b`, `a?.[0]`, `a?.()` | JS optional chaining |
| optional shorthand    | `a?[0]`, `a?(x)`          | `a?.[0]`, `a?.(x)`   |
| nullish coalescing    | `a ?? b`                  | `a ?? b`             |
| dammit operator       | `fetchData!`              | `await fetchData()`  |

---

## Quick Reference

### Unique Operators

| Operator    | Name             | Example                      |
| ----------- | ---------------- | ---------------------------- |
| `!`         | Dammit           | `fetchData!`                 |
| `!`         | Void             | `def process!`               |
| `=!`        | Readonly         | `MAX =! 100`                 |
| `?!`        | Presence         | `@checked?!`                 |
| `?`         | Existence        | `x?`                         |
| `//`        | Floor div        | `7 // 2`                     |
| `%%`        | True mod         | `-1 %% 3`                    |
| `:=`        | State            | `count := 0`                 |
| `~=`        | Computed         | `doubled ~= count * 2`       |
| `<=>`       | Two-way bind     | `value <=> name`             |
| `=~`        | Match            | `str =~ /pat/`               |
| `.new()`    | Constructor      | `User.new()`                 |
| `::`        | Prototype        | `String::trim`               |
| `as`        | Type cast        | `x as Foo` (runtime-erased)  |
| `if...else` | Postfix ternary  | `"a" if cond else "b"`       |
| `[-n]`      | Negative index   | `arr[-1]`                    |
| `*`         | String repeat    | `"-" * 40`                   |
| `<` `<=`    | Chained          | `1 < x < 10`                 |
| `.=`        | Method assign    | `x .= trim()`                |
| `?.=`       | Optional assign  | `el?.style.display = "none"` |
| `=`         | Render text      | `= item.textContent`         |
| `*>`        | Merge assign     | `*>obj = {a: 1}`             |
| `not in`    | Not in           | `x not in arr`               |
| `loop n`    | Repeat N         | `loop 5 -> body`             |
| `it`        | Implicit param   | `-> it > 5`                  |
| `or return` | Guard            | `x = get() or return err`    |
| `?? throw`  | Nullish guard    | `x = get() ?? throw err`     |
| `%w`        | Word literal     | `%w[foo bar baz]`            |
| `$"..."`    | Tagged template  | `sh $"cmd #{val}"`           |
| `a.b:`      | Dotted key       | `{host.name: "x"}`          |
| `*{ }`      | Map literal      | `*{/pat/: val, a: 1}`       |
| `:name`     | Symbol literal   | `:redo`, `:skip`, `:active`  |
| `.{ }`      | Pick             | `user.{firstName, lastName}` |
| `?.{ }`     | Optional pick    | `maybeUser?.{a, b}`          |

### Standard Library

Rip injects helpers via `globalThis` in compiled output, the CLI REPL, and the browser REPL.

| Function          | Description                                              |
| ----------------- | -------------------------------------------------------- |
| `abort(msg?)`     | log to stderr, exit with code 1                          |
| `assert(v, msg?)` | throw if falsy                                           |
| `exit(code?)`     | exit process                                             |
| `kind(v)`         | lowercase type name                                      |
| `noop()`          | no-op                                                    |
| `p(...args)`      | `console.log` shorthand                                  |
| `pp(v)`           | pretty-print with depth-unlimited inspect, returns value |
| `pr(v)`           | pretty-print in Rip syntax, returns value                |
| `pj(v)`           | pretty-print as JSON, returns value                      |
| `raise(a, b?)`    | throw error                                              |
| `rand(a?, b?)`    | random number                                            |
| `sleep(ms)`       | promise-based delay                                      |
| `todo(msg?)`      | throw not implemented                                    |
| `warn(...args)`   | `console.warn` shorthand                                 |
| `zip(...arrays)`  | zip arrays pairwise                                      |

The four print helpers cover four mental modes:

- `p`  — raw `console.log` (variadic, what you reach for first).
- `pp` — depth-unlimited inspect (when `console.log` truncates with `[Object]`).
- `pr` — Rip syntax (when you want to copy into a `.rip` file or round-trip through `compile`).
- `pj` — JSON syntax (when you want to feed the output to `curl`, jq, or a JSON tool).

`pr` falls back to deep inspect when given a value that has no faithful Rip-literal form (class instances, `Date`, `BigInt`, `Map`, etc.) — so it's safe to call on any value during debugging.

The strict `stringify(value)` is also exported from `rip-lang` for tools that need to emit `.rip` files programmatically; it throws on non-literal values rather than falling back, preserving the round-trip property.

All helpers use `??=` so they can be overridden.

### Tagged Templates (`$"..."`)

The `$` prefix turns a string into a tagged template literal, preventing injection
attacks across shell commands, SQL queries, HTML output, and any other context
where interpolated values must not become code.

```coffee
sh  $"incus init #{image} #{name}"          # shell — safe argv
sql $"SELECT * FROM users WHERE id = #{id}" # SQL — parameterized query
html $"<p>Hello, #{name}</p>"               # HTML — escaped output
```

The `$` works with all string forms:

| Syntax       | Interpolation | Tagged template      |
| ------------ | ------------- | -------------------- |
| `$"..."`     | yes           | yes                  |
| `$'...'`     | no            | yes                  |
| `$"""..."""` | yes           | yes — tagged heredoc |
| `$'''...'''` | no            | yes — tagged heredoc |

How it works: the `$` is a visual bridge between an identifier and a string.
The lexer rewriter strips the `$` and attaches the string directly to the
preceding identifier, triggering the existing `Value String` → `tagged-template`
grammar rule. The compiler emits a JavaScript tagged template literal.

The receiving function detects mode via `kind(args[0])`:
- `'array'` with `.raw` → tagged template (strings + values separated)
- `'array'` without `.raw` → plain argv array (direct exec)
- `'string'` → regular string (shell interpretation)

### Symbol Literals (`:name`)

Ruby-style symbol literals. `:name` compiles to `Symbol.for('name')` — globally
interned, so `:redo === :redo` is true everywhere without imports.

```coffee
status = :active
x = :redo

# Symbols are real JavaScript symbols
typeof :redo            # "symbol"
:redo is :redo          # true (interned)
:redo isnt :skip        # true

# Use anywhere a value is expected
arr = [:a, :b, :c]
obj = {status: :active}
fn :redo, :skip         # implicit call with symbol args

# Switch on symbols
switch state
  when :ready then start()
  when :done then finish()

# Interned — matches Symbol.for
:test is Symbol.for("test")  # true
```

The colon must be immediately followed by an identifier character (no space).
This is unambiguous with all other colon uses in Rip:

| Syntax | Meaning |
| --- | --- |
| `:redo` | Symbol literal |
| `:=` | Reactive assign |
| `::` | Prototype access (`String::trim`) |
| `name:` | Property key |
| `? a : b` | Ternary branch (space after `:`) |

### Error Suppression (`try` without `catch`)

In Rip, a bare `try` compiles to `try {} catch {}` in JavaScript. This is
functionally identical to `try ... catch then null`, which adds a useless
`null;` statement inside the catch. **Prefer bare `try`** for fire-and-forget
error suppression — it's cleaner and the intent is obvious.

```coffee
# Preferred — bare try
try unlinkSync(path)
try server.stop()

# Avoid — redundant catch
try unlinkSync(path) catch then null
try
  proc.kill()
catch
  null
```

Use an explicit `catch` only when the catch body does actual work:

```coffee
# Good — catch does real work
try
  pkg = JSON.parse(readFileSync(path, 'utf8'))
catch
  console.log 'version unknown'

# Good — catch with error variable
try
  something()
catch e
  console.error "failed: #{e.message}"
```

### Reactivity

Rip reactivity is built into the language, not imported from a library.

| Operator | Name            | Output                             |
| -------- | --------------- | ---------------------------------- |
| `=`      | assign          | `let x; x = value`                 |
| `:=`     | state           | `const x = __state(value)`         |
| `~=`     | computed        | `const x = __computed(() => expr)` |
| `~>`     | effect          | `__effect(() => { ... })`          |
| `=!`     | readonly        | `const x = value`                  |
| `offer`  | context provide | state + `setContext(...)`          |
| `accept` | context consume | `getContext(...)`                  |

Three-tier state model:

| Tier           | Scope               | Mechanism                           | Example                   |
| -------------- | ------------------- | ----------------------------------- | ------------------------- |
| Props          | parent to child     | `value <=> x`, `placeholder: "..."` | configuring a widget      |
| Offer / Accept | ancestor to subtree | keywords                            | tabs sharing active state |
| Stash          | app-wide            | shared reactive proxy               | auth state, theme         |

Two-way binding (`<=>`) compiles to an effect that pushes signal state into the DOM plus an event listener that writes DOM changes back. On components, the parent passes the signal via `__bind_propName__` so parent and child share the same signal object.

Implementation details are in `src/AGENTS.md`.

### Schemas

Rip schemas are a first-class language keyword that covers runtime
validation, domain shapes, enums, reusable field bundles, and DB-backed
models — one `schema` block declares the whole thing and shadow
TypeScript types fall out automatically.

| Kind      | Use for                                                    |
| --------- | ---------------------------------------------------------- |
| `:input`  | request-body / form validator (the default)                |
| `:shape`  | validator + instance methods + computed getters            |
| `:enum`   | closed set of `:symbol` members                            |
| `:mixin`  | reusable field group, composed via `@mixin Name`           |
| `:union`  | discriminated union: `@on :kind` + 2+ constituent schema names; `.parse` dispatches O(1) on the tag |
| `:model`  | DB-backed: ORM (`find`/`where`/`create`/`save`/`destroy`), transactions (`schema.transaction! ->`), eager loading (`.includes(:orders)`), scopes (`@scope :active, -> @where(active: true)`, `@defaultScope`), DDL (`.toSQL()`), migrations (`rip schema status/make/migrate`, renames via `{was: "old"}` / `@tableWas`), hooks (12, incl. `afterCommit`/`afterRollback`), relations |

Body forms (six declarative line shapes):

| Form                     | Example                                         |
| ------------------------ | ----------------------------------------------- |
| Field                    | `name! 1..50` (type slot optional, defaults to `string`) |
| Coerced field            | `age? ~integer` ("coerce, then validate" — also `~number`, `~boolean`, `~date`) |
| Named-coercer field      | `ssn? ~:ssn` — registry-backed; @rip-lang/server registers its full `read()` validator vocabulary (`~:id`, `~:money`, `~:phone`, `~:date`, …); apps add more via `schema.registerCoercer` |
| Inline field transform   | `email!, -> it.email.toLowerCase()`            |
| Directive                | `@timestamps`, `@mixin Name`, `@belongs_to User?` |
| Refinement               | `@ensure "msg"[, :field], (u) -> pred`; async via `@ensure!` (schema becomes `parseAsync!`-only) |
| Method                   | `name: -> body`                                 |
| Computed getter (lazy)   | `name: ~> body`                                 |
| Eager-derived field      | `name: !> body` (materialized once, stored as own property) |

Cross-field invariants use `@ensure`:

```coffee
Signup = schema :input
  password!  8..100
  password2! 8..100
  @ensure "passwords must match", (u) -> u.password is u.password2
```

Full reference: [`docs/RIP-SCHEMA.md`](./docs/RIP-SCHEMA.md). Compiler
internals and parser invariants: [`src/AGENTS.md`](./src/AGENTS.md).

---

## Loader and CLI

The loader (`rip-loader.js`) is a Bun plugin preloaded by `bin/rip` or `bunfig.toml`.

Responsibilities:

1. compile `.rip` files on the fly via `compileToJS()`
2. rewrite `@rip-lang/*` imports to absolute paths after compilation

The import rewrite is necessary because Bun worker threads do not respect `NODE_PATH`, and `onResolve` does not fire for imports introduced by `onLoad`-compiled source.

`bin/rip` sets `NODE_PATH` to include its parent `node_modules` directory and passes `env: process.env` into child process spawns. This works around Bun not inheriting `process.env` changes unless `env` is passed explicitly.

Known Bun bugs:

| Bug                                                                      | Workaround                                    |
| ------------------------------------------------------------------------ | --------------------------------------------- |
| `process.env` changes not inherited by `spawn` / `spawnSync`             | pass `env: process.env` explicitly            |
| `NODE_PATH` ignored by worker threads                                    | rewrite imports to absolute paths in `onLoad` |
| plugin `onResolve` does not fire for imports in `onLoad`-compiled source | rewrite imports inside `onLoad`               |
| `require.resolve({ paths })` ignores `paths` in plugin handlers          | use `import.meta.resolve`                     |

---

## API Route Handler Pattern

API route handlers in `**/api/routes/*.rip` follow five phases: **auth, read, meta, work, send**.

1. **auth** — Who is the caller? Use a scope helper (`userScope!`, `adminScope!`) or mark as `# public`. Exits 401/403 on failure.
2. **read** — What did they send? `read 'name', 'validator'` for all inputs. No logic, no queries.
3. **meta** — Derived values and preconditions. Construct variables from auth + read, load related records, check error conditions. Bail before any mutations.
4. **work** — Do the thing. Create records, update state, call services. Everything needed should already be in named variables.
5. **send** — The final expression. Usually an object literal for JSON, but could be HTML, a file via `@send`, a redirect, etc.

Guidelines:

- Omit phases that don't apply — no empty comments.
- Use phase comments (`# auth`, `# read`, etc.) when the handler is long enough to benefit from visual separation.
- Public endpoints use `# public` instead of a scope call.
- Early exits belong to their phase — auth failures in auth, preconditions in meta.
- Use `error!` for HTTP errors, `notice!` for user-facing messages, `bail!` to destroy session and force-logout.

```coffee
post '/create' ->
  # auth
  user = userScope!

  # read
  week     = read 'week', 'int!'
  slot     = read 'slot', 'text!'
  children = read 'children', 'json'

  # meta
  needed = children?.length or 1
  spots = sql! '...', [week, slot, 'available', needed]
  error! 'Not enough spots', 409 unless spots.data?.length >= needed

  # work
  booking = Booking.create!({ user_id: user.id, week, slot, children: children or [] })
  for row in spots.data
    sql! '...', ['booked', booking.id, row[0]]

  # send
  { bookingId: booking.id }
```

---

## Reflect Before Finalizing

Before finalizing your work, take a moment to step back.

Review what you've built. Read through the changes as if seeing them for the first time.

Ensure everything is clean, clear, consistent, correct, concise, and efficient.

Question your approach. Now that you've implemented this, is there anything you'd do differently? Are the data structures right? Is information flowing through the system in the most natural way? If you were starting over with what you know now, would you make the same choices?

Look for improvements. If something feels off, fix it now rather than noting it for later. Small refactors compound — clean code invites more clean code.

Gather more context if you're uncertain. Pull up related code. Trace through the system. Sometimes the right answer becomes obvious once you see more of the picture.

Do the work, not the meta-work. Improve the code itself. Don't write reflection documents.

---

**For AI assistants:** Trust the tests, use the debug tools, follow existing patterns, and consult the nested `AGENTS.md` files for deeper subsystem details.