# Caspian Agent Guide ## Purpose This workspace is a Caspian application plus a packaged copy of the Caspian docs. **This file is the first-party Caspian reference and the required first read for every task — do not skip it and do not start implementing before it.** The "Caspian Core Contracts" section below is the condensed, always-read digest of how Caspian actually works — feature gates, the Jinja/PulsePoint brace dialects, the authoring model, the props-passing contract, the closed PulsePoint template/API surface, and the data flows. It exists because tasks fail when an agent implements from generic framework intuition instead of these shipped contracts; reading it first is what lets a feature land correctly in one pass. The packaged docs under `node_modules/caspian-utils/dist/docs/` remain the deep per-feature layer to open when a task touches that surface. When you work here, use `caspian.config.json` and the code that actually runs as the source of truth for this project. Use workspace file instructions under `.github/instructions/**/*.instructions.md` as the task-specific instruction layer when they match the work, and use the packaged markdown docs under `node_modules/caspian-utils/dist/docs/` as the AI-facing Caspian feature and task-reference layer. Do not treat the existence of a packaged doc as proof that the feature is enabled in this project. ## Caspian Core Contracts (Read Before Any Analysis) Every rule in this section describes shipped behavior of the Caspian runtime this app runs on. Implement against these contracts, not framework intuition. When any claim here disagrees with `caspian.config.json`, the app code, or the installed runtime, the code wins — and this section should then be fixed together with the matching packaged doc. **This is the digest, not the full documentation.** It exists to stop the highest-frequency implementation failures; it does not replace the packaged docs under `node_modules/caspian-utils/dist/docs/`, which remain the canonical deep layer per feature. Each subsection below ends with a "Deep dive" pointer — open that doc before implementing anything nontrivial on that surface, and use the "Task Routing" section further down to pick the right doc for the task as a whole. Never conclude from this digest alone that a detail, option, or edge case does not exist. ### Feature gates (`caspian.config.json`) This workspace currently enables: `tailwindcss`, `mcp`, `prisma`, `typescript`, `websocket`; `backendOnly: false`; components are scanned under `src/`. Re-read the file when in doubt — it is the single source of truth for optional features. A packaged doc existing never proves a feature is enabled. If a disabled feature is requested, ask first, then enable the flag and follow the Caspian update workflow. Deep dive: `node_modules/caspian-utils/dist/docs/index.md` (the docs manifest and retrieval order) and `commands.md` (scaffold and update workflows). ### The three brace dialects — the #1 source of broken implementations Every template in this app is authored inside `html(r"""...""")` and rendered through Jinja **before** the PulsePoint compiler ever sees it. Three brace forms coexist and must never be confused: | Syntax | Layer | Meaning | | --------------------- | -------------------- | ------------------------------------------------------------------ | | `{{ value }}` | Server (Jinja) | Python-to-HTML interpolation at render time. Autoescaped. | | `{{ value \| json }}` | Server (Jinja) | Safe serialization of a server value into a ` """, attributes=attributes) ``` `{{ attributes }}` on the root **and** `attributes=attributes` into `html(...)` are both required. A named Python parameter is consumed out of `**props`, so it must be listed explicitly in the defaults dict or it never reaches the root. Value-type contract (forwarding fixes presence, not type): | Attribute on the rendered root | `pp.props.x` | | ---------------------------------------------- | ------------------------------------------------------------------- | | `volume="{vol}"` — brace expression | real type, evaluated in the **parent's** scope | | `volume="0"` — literal from a server value | the **string** `"0"` (`volume === 0` is false) | | valueless attribute | boolean `true` | | `class`, `for` — JS reserved words | dropped; `pp.props.class` never exists | | value was `None`/`False`/`""`/empty collection | attribute omitted by `get_attributes` → `undefined` (never `false`) | Design rules: read booleans defensively (`!!pp.props.playing`); coerce server literals before strict comparison; avoid native-attribute collisions (`title` makes a tooltip — prefer `user-name`); camelCase round-trips through kebab-case (`isFullscreen` ↔ `is-fullscreen`). `get_attributes` aliases: `className`/`class_name` → `class`, `htmlFor`/`html_for` → `for`, `defaultValue` → `defaultvalue`, `defaultChecked` → `defaultchecked`. When Tailwind is enabled, `merge_classes(...)` emits a live `{twMerge(...)}` expression — pass it straight through, never wrap or re-merge it, and pop the incoming `class` from `props` first. `pp-ref` on an `x-*` tag is parent-owned and binds the component's concrete DOM root (forwarded through composition hosts). A component can opt out by declaring an explicit `ppRef` parameter. For a child-defined imperative API, pass a parent ref as an ordinary prop and publish with `pp.imperativeHandle(pp.props.controlRef, () => ({...}), [])` — never author `pp-ref-forward`. Deep dive: `node_modules/caspian-utils/dist/docs/components.md` "Receiving Props In A Python Component", "Every Prop A Template Reads Must Be Forwarded To The Root", and "HTML Attribute Helper Contract" (the full `get_attributes`/`merge_classes` behavior and end-to-end examples). ### PulsePoint templates — plain HTML, never JSX The React comparison covers exactly two things: the `pp.*` hook API inside `