# Building on the That Open Platform — Agent Guide

You are an AI assistant helping a user build a **BIM app** or **cloud component** on the
That Open Platform using **`@thatopen/services`** (the `thatopen` CLI + client library).

**Read this file first, then immediately load all indexes listed below before doing anything else.**

> This guide is tool-agnostic: it works with any AI (Claude, Codex, your own). All local docs it
> references ship inside the `@thatopen/services` package under `docs/`.

---

## Session start — load all indexes in parallel

Do this before answering any question or writing any code. These are compact description indexes:

| What | Where |
|---|---|
| Platform built-ins | `node_modules/@thatopen/services/docs/builtin/paths.json` |
| Platform client API | `node_modules/@thatopen/services/docs/client/paths.json` |
| CLI commands | `node_modules/@thatopen/services/docs/cli/paths.json` |
| Rate limits + how to save data | `node_modules/@thatopen/services/docs/rate-limits.md` |
| Engine components (`OBC`, `OBF`) | `https://raw.githubusercontent.com/ThatOpen/engine_components/refs/heads/main/examples/paths.json` |
| Fragments (`FRAGS`) | `https://raw.githubusercontent.com/ThatOpen/engine_fragment/refs/heads/main/examples/paths.json` |
| UI components (`BUI`) | `https://raw.githubusercontent.com/ThatOpen/engine_ui-components/refs/heads/main/examples/paths.json` — **skip** entries whose path contains `packages/obc` or `bim-grid` |

Once you have these, you know everything available on the platform. Only then fetch a specific example file when you need implementation details.

> **Path resolution:** all `path` entries inside the local indexes (`docs/`, `src/`) are relative to the `@thatopen/services` package root — prepend `node_modules/@thatopen/services/` when reading any of those files.

---

## How to work

- **The scaffold is already a complete, working viewer** (model loading, spatial tree, properties).
  **Run it first** (`npm run dev`) to see it work, *then* extend it — don't rebuild a viewer from scratch.
- **Do the thing they asked for.** If the request already says what to build, build it. Stop and ask only when you are about to change files you did not create, when the request can be read two ways that mean different work, or when the next step is destructive.
- If something already exists in the indexes, use it — don't reimplement it.
- **The scaffold already listens on the platform channel** (`src/setups/channel.ts`):
  external tools (an MCP server, a CLI) command the app through `AppCommands`, and
  tabs collaborate through `AppCollabEvents`. Extend those maps instead of opening
  sockets — apps cannot hold their own connection. Walkthrough:
  `node_modules/@thatopen/services/src/core/examples/channel.ts`.

## Hard rules (always apply)

1. **Never write to the platform on every change.** No autosave per keystroke,
   per drag, or inside a render loop. Keep work in progress **in memory** — the
   production sandbox has NO origin storage (`localStorage`, `sessionStorage`,
   IndexedDB and cookies **throw** on its opaque origin; dev mode hides this) —
   and call the platform on an **explicit user save** (or a timer no
   faster than once every 30 seconds). Writes are capped at **30 per minute**;
   crossing that returns `429` and the write is **lost**, not queued.
   If the user asks for autosave, build it against local storage and say so.
   Read `node_modules/@thatopen/services/docs/rate-limits.md` before writing any
   save, sync, or polling code — it has the per-endpoint limits and the pattern.

2. **All UI must be built with Lit**, using the web components from `@thatopen/ui` (`BUI`) — `bim-button`, `bim-panel`, `bim-panel-section`, `bim-toolbar`, `bim-dropdown`, `bim-input`, and the rest of `packages/core`. Always consult the design system before writing any UI: `https://raw.githubusercontent.com/ThatOpen/engine_ui-components/refs/heads/main/DESIGN.md`.