retiam 1.0.0 → 1.0.2

package/readme.md

@@ -1,145 +1,439 @@
-# Retiam
-
-Retiam is a TypeScript animation engine built on WebGPU. Write scenes for mathematical explanations, data visualizations, and 2D or 3D animation, then preview them in a browser, render video, or export an interactive web embed.
-
-**[Documentation](https://abhilasbiswas.github.io/retiam-docs/)** · [Getting started](https://abhilasbiswas.github.io/retiam-docs/getting-started/) · [Examples](https://abhilasbiswas.github.io/retiam-docs/examples-catalog/) · [API reference](https://abhilasbiswas.github.io/retiam-docs/api-core/)
-
-## Features
-
-- **Scene authoring:** compose entities, groups, layouts, cameras, and interaction with TypeScript.
-- **Animation and timing:** choreograph transitions with asynchronous timelines, easing, tracks, and value trackers.
-- **Mathematical graphics:** create coordinate systems, plots, vector geometry, LaTeX equations, text, and highlighted code.
-- **Rendering:** combine 2D paths, 3D meshes, lighting, shadows, compute effects, and post-processing.
-- **Specialized libraries:** add charts, graphs, physics, procedural shapes, sketch styling, and emphasis animations through separate imports.
-- **Audio and output:** work with audio, narration, and subtitles; inspect snapshots, render video, or share scenes as web components.
-
-## Getting started
-
-Install Retiam in your own TypeScript application:
-
-```bash
-npm install retiam
-npm install --save-dev typescript vite @webgpu/types
-```
-
-Follow the [installation guide](https://abhilasbiswas.github.io/retiam-docs/installation/) for the complete project structure, TypeScript configuration, and browser entry point. To use an unpublished checkout, run `npm pack` in this repository and install the generated `.tgz` file in your application.
-
-For Vite applications, preserve Retiam's packaged module and asset URLs by excluding it from dependency prebundling in `vite.config.ts`:
-
-```typescript
-import { defineConfig } from "vite";
-
-export default defineConfig({
-  optimizeDeps: { exclude: ["retiam"] },
-});
-```
-
-Retiam requires a WebGPU-capable browser and compatible GPU. Serve browser applications over HTTPS or localhost.
-
-### Your first scene
-
-Save this as `scenes/FirstScene.ts`. Scenes define their animation in an asynchronous `run()` method; durations are in milliseconds.
-
-```typescript
-import { Scene, Circle, Create, FadeOut, CameraModel, hex } from "retiam";
-
-export default class FirstScene extends Scene {
-  async run() {
-    this.clearColor(hex("#090E1B"));
-    this.camera.model = CameraModel.ORTHOGRAPHIC;
-    this.camera.orthoScale = 12;
-    this.camera.position.set([0, 0, 20]);
-    this.camera.lookAt([0, 0, 0]);
-
-    const circle = new Circle(1, { fill: hex("#38BDF8") });
-    circle.move([-2, 0, 0]);
-    this.add(circle);
-
-    await this.play(new Create(circle, { duration: 1200 }));
-    await this.play(circle.animate.move([2, 0, 0]), { duration: 1000 });
-    await this.wait(800);
-    await this.play(new FadeOut(circle, { duration: 600 }));
-    await this.wait(400);
-  }
-}
-```
-
-Start the scene from your application's browser entry point, `src/main.ts`:
-
-```typescript
-import FirstScene from "../scenes/FirstScene";
-
-const canvas = document.querySelector<HTMLCanvasElement>("#canvas");
-if (!canvas) throw new Error("Missing scene canvas.");
-
-const scene = new FirstScene();
-await scene.start(canvas);
-window.addEventListener("pagehide", () => scene.destroy(), { once: true });
-```
-
-The host page needs a `<canvas id="canvas"></canvas>` with an explicit CSS display size. Continue with [your first scene](https://abhilasbiswas.github.io/retiam-docs/first-scene/) for animation, camera, and lifecycle guidance.
-
-## CLI and video rendering
-
-Use the CLI to analyze scenes, capture PNG snapshots, and render video:
-
-```bash
-npx retiam lint scenes/FirstScene.ts --json
-npx retiam snapshot scenes/FirstScene.ts --times 1.0,2.5,4.0 --json
-npx retiam render scenes/FirstScene.ts -w 1920 -h 1080 -f 60 -d 4000 -o outputs/video
-```
-
-Render and snapshot commands require the optional Puppeteer dependency and a working Chrome/WebGPU setup. Video rendering also requires FFmpeg on your `PATH`.
-
-```bash
-npm install --save-dev puppeteer
-```
-
-For rendering and snapshots, your project must include an `index.html` host that loads the scene selected by the CLI's `file` query parameter. Use the host from the [installation guide](https://abhilasbiswas.github.io/retiam-docs/installation/#create-a-consumer-application). Render duration (`-d`) is in milliseconds; output (`-o`) is a directory.
-
-See [rendering and export](https://abhilasbiswas.github.io/retiam-docs/export/) for project setup and encoding options, or follow [package-based embeds](https://abhilasbiswas.github.io/retiam-docs/export/#embed-from-npm) to bundle a scene for another website. Run `npx retiam help` for the command reference.
-
-## Libraries
-
-Import shared scene primitives from `retiam` and specialized functionality from its own entry point.
-
-| Import | Purpose |
-| --- | --- |
-| `retiam` | Scenes, entities, animations, cameras, geometry, text, and core math |
-| `retiam/shapes` | Procedural 2D paths and 3D meshes |
-| `retiam/charts` | Cartesian and polar charts, scales, themes, and tooltips |
-| `retiam/graphs` | Graphs, layouts, automata, and tapes |
-| `retiam/highlights` | Emphasis and attention animations |
-| `retiam/physics` | 2D and 3D physics integrations |
-| `retiam/rough` | Optional RoughJS styling integration |
+# Retiam
+
+Retiam is a TypeScript animation engine built on WebGPU. Write scenes for mathematical explanations, data visualizations, and 2D or 3D animation, then preview them in a browser, render video, or export an interactive web embed.
+
+**[Documentation](https://abhilasbiswas.github.io/retiam-docs/)** · [Getting started](https://abhilasbiswas.github.io/retiam-docs/getting-started/) · [Examples](https://abhilasbiswas.github.io/retiam-docs/examples-catalog/) · [API reference](https://abhilasbiswas.github.io/retiam-docs/api-core/)
+
+## Features
+
+- **Scene authoring:** compose entities, groups, layouts, cameras, and interaction with TypeScript.
+- **Animation and timing:** choreograph transitions with asynchronous timelines, easing, tracks, and value trackers.
+- **Mathematical graphics:** create coordinate systems, plots, vector geometry, LaTeX equations, text, and highlighted code.
+- **Rendering:** combine 2D paths, 3D meshes, lighting, shadows, compute effects, and post-processing.
+- **Specialized libraries:** add charts, graphs, physics, procedural shapes, sketch styling, and emphasis animations through separate imports.
+- **Audio and output:** work with audio, narration, and subtitles; inspect snapshots, render video, or share scenes as web components.
+- **Retiam Studio:** edit scenes alongside a live preview, tune supported values with inspectors, and control playback from your generated project.
+
+## Getting started
+
+| Method | Use it for | Result |
+| --- | --- | --- |
+| [npm project and Studio](#create-a-project-with-studio) | Author and preview TypeScript scenes, then render video | Source project, MP4 and snapshots |
+| [CDN modules](#use-retiam-from-a-cdn) | Add a live scene directly to a browser page | Interactive WebGPU canvas |
+| [Embedded export](#export-an-independent-web-embed) | Share a finished animation on another website | Hosted web component and bundled assets |
+
+### Create a project with Studio
+
+Use Node.js 20.19 or newer and a WebGPU-capable browser. The project generator
+creates a TypeScript application, installs its dependencies, and opens Retiam
+Studio with a **Write** animation of “Retiam”:
+
+```bash
+npx create-retiam@latest my-animation
+```
+
+The generated project declares
+`"retiam": "latest"`. Its initial install uses npm's `latest` engine release;
+the package manager's lockfile records the resolved version for later installs.
+
+The editor opens below the preview. Drag the divider to resize it, or use the
+layout control to dock it on the left or right. Studio remembers your choice.
+Single-scene projects show the preview and editor; scene navigation and search
+appear when more scenes are added and the page reloads.
+
+Press Ctrl+C to stop the server. To reopen Studio:
+
+```bash
+cd my-animation
+npm run dev
+```
+
+Edit `src/scenes/Retiam.ts` in your editor or Studio. The generated project also
+includes `config.js` for CLI rendering, `studio/` for the local editor, and the
+Vite and TypeScript configuration. In Studio, **Run** or **Ctrl/Command+Enter**
+applies and saves edits. Add default-exported Scene classes under `src/scenes/`
+to make them available in the scene browser after reloading.
+
+| Generator option | Behavior |
+| --- | --- |
+| `--no-start` | Install dependencies without starting Studio |
+| `--no-install` | Generate files without installing or starting |
+| `--no-open` | Start the server without opening a browser |
+| `--title "Hello"` | Change the starter animation text |
+| `--pm npm\|pnpm\|yarn\|bun` | Choose the package manager |
+
+The [`create-retiam` package](packages/create-retiam/README.md)
+is released separately from the engine. Publish the engine version required by
+its starter before publishing the generator. Generator updates apply to new
+projects; existing projects keep their own Studio and configuration files.
+
+### Manual setup
+
+Install Retiam in your own TypeScript application:
+
+```bash
+npm install retiam
+npm install --save-dev typescript "vite@^6.1.1" @webgpu/types
+```
+
+Follow the [installation guide](https://abhilasbiswas.github.io/retiam-docs/installation/) for the complete project structure, TypeScript configuration, and browser entry point. To use an unpublished checkout, run `npm pack` in this repository and install the generated `.tgz` file in your application.
+
+For Vite applications, preserve Retiam's packaged module and asset URLs by excluding it from dependency prebundling in `vite.config.ts`:
+
+```typescript
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  optimizeDeps: { exclude: ["retiam"] },
+});
+```
+
+Retiam requires a WebGPU-capable browser and compatible GPU. Serve browser applications over HTTPS or localhost.
+
+### Your first scene
+
+Save this as `scenes/FirstScene.ts`. Scenes define their animation in an asynchronous `run()` method; durations are in milliseconds.
+
+```typescript
+import { Scene, Circle, Create, FadeOut, CameraModel, hex } from "retiam";
+
+export default class FirstScene extends Scene {
+  async run() {
+    this.clearColor(hex("#090E1B"));
+    this.camera.model = CameraModel.ORTHOGRAPHIC;
+    this.camera.orthoScale = 12;
+    this.camera.position.set([0, 0, 20]);
+    this.camera.lookAt([0, 0, 0]);
+
+    const circle = new Circle(1, { fill: hex("#38BDF8") });
+    circle.move([-2, 0, 0]);
+    this.add(circle);
+
+    await this.play(new Create(circle, { duration: 1200 }));
+    await this.play(circle.animate.move([2, 0, 0]), { duration: 1000 });
+    await this.wait(800);
+    await this.play(new FadeOut(circle, { duration: 600 }));
+    await this.wait(400);
+  }
+}
+```
+
+Start the scene from your application's browser entry point, `src/main.ts`:
+
+```typescript
+import FirstScene from "../scenes/FirstScene";
+
+const canvas = document.querySelector<HTMLCanvasElement>("#canvas");
+if (!canvas) throw new Error("Missing scene canvas.");
+
+const scene = new FirstScene();
+await scene.start(canvas);
+window.addEventListener("pagehide", () => scene.destroy(), { once: true });
+```
+
+The host page needs a `<canvas id="canvas"></canvas>` with an explicit CSS display size. Continue with [your first scene](https://abhilasbiswas.github.io/retiam-docs/first-scene/) for animation, camera, and lifecycle guidance.
+
+## Use Retiam from a CDN
+
+Import Retiam directly in a browser page. The published module is available at
+**[jsDelivr](https://cdn.jsdelivr.net/npm/retiam@latest/dist/retiam.es.min.js)**.
+This example loads the core and charts entries through the latest release tag:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Retiam CDN animation</title>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      canvas { display: block; width: 100%; height: 100%; }
+    </style>
+    <script type="importmap">
+      {
+        "imports": {
+          "retiam": "https://cdn.jsdelivr.net/npm/retiam@latest/dist/retiam.es.min.js",
+          "retiam/charts": "https://cdn.jsdelivr.net/npm/retiam@latest/dist/libs/charts/index.js"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <canvas id="canvas"></canvas>
+    <script type="module">
+      import { Scene, Circle, Create, CameraModel, hex } from 'retiam';
+
+      class BrowserScene extends Scene {
+        async run() {
+          this.clearColor(hex('#080C14'));
+          this.camera.model = CameraModel.ORTHOGRAPHIC;
+          this.camera.orthoScale = 12;
+          this.camera.position.set([0, 0, 20]);
+          this.camera.lookAt([0, 0, 0]);
+          const circle = new Circle(1, { fill: hex('#38BDF8') });
+          this.add(circle);
+          await this.play(new Create(circle, { duration: 1200 }));
+          await this.wait(1000);
+        }
+      }
+
+      const scene = new BrowserScene();
+      scene.start(document.querySelector('#canvas')).catch(console.error);
+      window.addEventListener('pagehide', () => scene.destroy(), { once: true });
+    </script>
+  </body>
+</html>
+```
+
+Serve the page over HTTPS or localhost, with a WebGPU-capable browser. No Retiam
+npm installation is needed for this page. Add import-map entries for any other
+sublibraries you use, such as `retiam/shapes`, with the same release tag. jsDelivr
+serves the module's related chunks, fonts, workers and WASM assets. A CDN page
+runs the animation live; the [npm CLI workflow](#cli-and-video-rendering) produces
+video and snapshots.
+
+## Export an independent web embed
+
+Bundle a finished scene into a custom element for a blog, documentation page or
+another application. The exported files include the engine code and emitted
+assets needed by that scene. The receiving site needs WebGPU and those files.
+
+This recipe uses Vite 6, matching the generated project's toolchain. For a
+generated npm project, save the following as `src/embed.ts`. Each element
+owns its canvas and Scene, handles resizing, and cleans up when removed.
+
+<details>
+<summary>src/embed.ts</summary>
+
+```typescript
+import MyScene from './scenes/Retiam';
+
+// A separate name lets this bundle coexist with other scene components.
+class MyRetiamSceneElement extends HTMLElement {
+  private cleanup?: () => void;
+
+  connectedCallback() {
+    this.cleanup?.();
+    const canvas = document.createElement('canvas');
+    canvas.style.cssText = 'display:block;width:100%;height:100%';
+    this.replaceChildren(canvas);
+    const scene = new MyScene();
+    let cancelled = false, started = false, resizeFrame = 0;
+    let observer: ResizeObserver | undefined;
+
+    this.cleanup = () => {
+      cancelled = true;
+      observer?.disconnect();
+      cancelAnimationFrame(resizeFrame);
+      if (started) scene.destroy();
+      // A pending initialization cleans up in its continuation below.
+    };
+    void scene.start(canvas).then(() => {
+      started = true;
+      if (cancelled) { scene.destroy(); return; }
+      observer = new ResizeObserver(() => {
+        cancelAnimationFrame(resizeFrame);
+        resizeFrame = requestAnimationFrame(() => {
+          // Current composer resizing listens to the window resize event.
+          window.dispatchEvent(new Event('resize'));
+        });
+      });
+      observer.observe(this);
+      this.dispatchEvent(new CustomEvent('scene-ready', { bubbles: true }));
+    }).catch(error => {
+      scene.destroy();
+      if (!cancelled) {
+        const message = document.createElement('p');
+        message.setAttribute('role', 'alert');
+        message.textContent = String(error);
+        this.replaceChildren(message);
+      }
+    });
+  }
+
+  disconnectedCallback() {
+    this.cleanup?.();
+    this.cleanup = undefined;
+  }
+}
+
+if (!customElements.get('my-retiam-scene')) {
+  customElements.define('my-retiam-scene', MyRetiamSceneElement);
+}
+```
+
+</details>
+
+For a manual project, change the scene import to your scene module. The
+[npm embed recipe](https://abhilasbiswas.github.io/retiam-docs/export/#embed-from-npm)
+explains lifecycle handling, multiple instances and hosting.
+
+Save this as `vite.embed.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  base: './',
+  build: {
+    target: 'es2022',
+    outDir: 'outputs/embed',
+    lib: {
+      entry: 'src/embed.ts',
+      formats: ['es'],
+      fileName: 'my-scene',
+    },
+  },
+});
+```
+
+Build the component:
+
+```bash
+npx vite build --config vite.embed.config.ts
+```
+
+Copy the **whole** `outputs/embed` folder to your website, for example under
+`/embeds/my-scene/`, then mount the custom element:
+
+```html
+<script type="module" src="/embeds/my-scene/my-scene.js"></script>
+<my-retiam-scene style="display:block;width:100%;height:540px"></my-retiam-scene>
+```
+
+The receiving site needs no npm installation or separate Retiam CDN import.
+Preserve emitted files and their relative paths. Assets or services explicitly
+referenced by remote URLs still need hosting. Use a distinct custom-element name
+for each different scene bundle. An MP4 is the alternative when the receiving
+page only needs video playback.
+
+The engine repository also provides an export CLI:
+
+```bash
+npx retiam export scenes/MyScene.ts outputs/embed
+```
+
+Its current implementation expects the engine repository's `src/engine` layout.
+Use the package-based Vite recipe above for generated and other external npm
+projects. See [repository export](https://abhilasbiswas.github.io/retiam-docs/export/#standalone-embeds)
+for the CLI's script and `<retiam-scene>` usage.
+
+## CLI and video rendering
+
+Run these commands from the generated project folder containing `package.json`
+and `config.js`:
+
+```bash
+npx retiam lint src/scenes/Retiam.ts --json
+npx retiam snapshot src/scenes/Retiam.ts --times 1.0,2.5,4.0 --json
+npx retiam render src/scenes/Retiam.ts
+```
+
+Puppeteer is a required production dependency of Retiam and is installed automatically with the package. Render and snapshot commands need a working Chrome/WebGPU setup. Video rendering also requires FFmpeg on your `PATH`.
+
+### Render configuration
+
+The generated [config.js](packages/create-retiam/starter/config.js) contains CLI
+output and renderer quality settings with their defaults and comments. The default output
+is 1920×1080 at 60 fps, MP4 at `20M`, in `outputs/video`. `maxDuration: 0` renders
+until the scene finishes; set a limit for scenes that loop indefinitely.
+
+For a smaller draft, edit the output fields in `config.js`:
+
+```javascript
+export default {
+  width: 1280,
+  height: 720,
+  fps: 30,
+  videoBitrate: '8M',
+  outputFormat: 'mp4',
+  outputDir: './outputs/video',
+  maxDuration: 4000, // milliseconds
+};
+```
+
+The renderer starts with built-in defaults, loads `config.js` from the calling
+project, then applies CLI flags. If `retiam.config.js` exists, it is used instead
+of `config.js`. For example, this renders at 60 fps while retaining the other
+file settings:
+
+```bash
+npx retiam render src/scenes/Retiam.ts -f 60
+```
+
+The complete file also covers anti-aliasing, transparency layers, shadows,
+culling, raytracing, denoising, local server ports, and input replay.
+See the [configuration reference](https://abhilasbiswas.github.io/retiam-docs/export/#render-configuration).
+
+Choose surface appearance in scene code and materials:
+
+```typescript
+import { CelShading, GoochShading } from 'retiam';
+
+this.shading = new CelShading({ bands: 3 }); // Scene default
+sphere.material.shading = new GoochShading({ warm: 0.6, cool: 0.4 });
+```
+
+Each shading model supplies its own WGSL. Numeric parameters update through the
+material buffer without recompiling shaders. These styles apply to rasterized
+3D models; raytracing uses its own physically based lighting.
+
+For the manual setup above, use `scenes/FirstScene.ts` as the scene path. Rendering
+and snapshots serve the project's `index.html`; a host that supports selecting
+different scenes must load the CLI's `file` query parameter. The
+[manual installation guide](https://abhilasbiswas.github.io/retiam-docs/installation/#create-a-consumer-application)
+includes that bootstrap. Render duration (`-d`) is in milliseconds, snapshot
+times are in seconds, and output (`-o`) is a directory. Render filenames include
+a timestamp.
+
+See [rendering and export](https://abhilasbiswas.github.io/retiam-docs/export/) for project setup and encoding options, or follow [package-based embeds](https://abhilasbiswas.github.io/retiam-docs/export/#embed-from-npm) to bundle a scene for another website. Run `npx retiam help` for the command reference.
+
+## Libraries
+
+Import shared scene primitives from `retiam` and specialized functionality from its own entry point.
+
+| Import | Purpose |
+| --- | --- |
+| `retiam` | Scenes, entities, animations, cameras, geometry, text, and core math |
+| `retiam/shapes` | Procedural 2D paths and 3D meshes |
+| `retiam/charts` | Cartesian and polar charts, scales, themes, and tooltips |
+| `retiam/graphs` | Graphs, layouts, automata, and tapes |
+| `retiam/highlights` | Emphasis and attention animations |
+| `retiam/physics` | 2D and 3D physics integrations |
+| `retiam/rough` | RoughJS styling integration |
 | `retiam/tts` | Microsoft Edge speech synthesis, narration, and subtitles |
-
-See the [library guide](https://abhilasbiswas.github.io/retiam-docs/libraries/) for import boundaries and examples. The RoughJS integration requires the optional `roughjs` peer dependency.
-
+
+See the [library guide](https://abhilasbiswas.github.io/retiam-docs/libraries/) for import boundaries and examples. `roughjs` is a required production dependency and is installed automatically.
+
 Built-in fonts and imported engine assets are included in the library package. Application media is managed separately. Edge speech synthesis in the browser requires a compatible service. See [asset workflows](https://abhilasbiswas.github.io/retiam-docs/asset-workflows/) and [speech and subtitles](https://abhilasbiswas.github.io/retiam-docs/speech-subtitles/) for setup.
-
-## Repository development
-
-Use Node.js 24, matching the documentation CI configuration.
-
-```bash
-git clone https://github.com/abhilasbiswas/Retiam.git
-cd Retiam
-npm ci
-npm run dev
-```
-
-Open the URL printed by Vite. Retiam Studio is available at `/studio/` on the same server. See the [tooling guide](https://abhilasbiswas.github.io/retiam-docs/tooling/) for the editor, inspector, and playback controls.
-
-### Documentation development
-
-The viewer, authored guides, examples, assets, API reference data, and Pages workflow are maintained in the separate [retiam-docs repository](https://github.com/abhilasbiswas/retiam-docs). It installs, builds, and deploys independently of this engine checkout. See that repository's README and deployment guide for local development and publishing.
-
-## Documentation and source
-
-- [Handbook](https://abhilasbiswas.github.io/retiam-docs/): guides, tutorials, examples, and API references.
-- [Compatibility notes](https://abhilasbiswas.github.io/retiam-docs/limitations/): current implementation boundaries and known differences from historical examples.
-- [Architecture notes](docs/README.md): detailed subsystem documentation.
-- [Example sources](examples/): repository scenes and integrations.
-- [Agent skill](.agents/skills/retiam/SKILL.md): scene-authoring guidance for coding assistants.
-
+
+MSDF font generation runs in a browser worker using the WASM supplied by
+`@zappar/msdf-generator`, a production dependency. The repository's font-baking
+tools, including `msdf-bmfont-xml` and `msdf-atlas-gen`, remain development tools.
+
+## Repository development
+
+Use Node.js 24, matching the documentation CI configuration.
+
+```bash
+git clone https://github.com/abhilasbiswas/Retiam.git
+cd Retiam
+npm ci
+npm run dev
+```
+
+Open the URL printed by Vite. Retiam Studio is available at `/studio/` on the same server. See the [tooling guide](https://abhilasbiswas.github.io/retiam-docs/tooling/) for the editor, inspector, and playback controls.
+
+### Documentation development
+
+The viewer, authored guides, examples, assets, API reference data, and Pages workflow are maintained in the separate [retiam-docs repository](https://github.com/abhilasbiswas/retiam-docs). It installs, builds, and deploys independently of this engine checkout. See that repository's README and deployment guide for local development and publishing.
+
+## Documentation and source
+
+- [Handbook](https://abhilasbiswas.github.io/retiam-docs/): guides, tutorials, examples, and API references.
+- [Compatibility notes](https://abhilasbiswas.github.io/retiam-docs/limitations/): current implementation boundaries and known differences from historical examples.
+- [Architecture notes](docs/README.md): detailed subsystem documentation.
+- [Example sources](examples/): repository scenes and integrations.
+- [Agent skill](.agents/skills/retiam/SKILL.md): scene-authoring guidance for coding assistants.
+