@tangle-network/starter-foundry 0.5.4 → 0.7.2

package/registry/layers/framework/tauri-menubar/manifest.json

@@ -0,0 +1,92 @@
+{
+  "id": "tauri-menubar",
+  "description": "Tauri 2 menu-bar layer: tray icon + 320×400 popover panel with hide-on-blur, global-shortcut toggle, and macOS Accessory-policy dock hiding.",
+  "appliesTo": ["tauri-menubar"],
+  "files": [
+    { "source": "files/tsconfig.json",    "target": "tsconfig.json" },
+    { "source": "files/vite.config.ts",   "target": "vite.config.ts" },
+    { "source": "files/index.html",       "target": "index.html" },
+    { "source": "files/main.tsx",         "target": "src/main.tsx" },
+    { "source": "files/App.tsx",          "target": "src/App.tsx" },
+    { "source": "files/styles.css",       "target": "src/styles.css" },
+    { "source": "files/Cargo.toml",       "target": "src-tauri/Cargo.toml" },
+    { "source": "files/build.rs",         "target": "src-tauri/build.rs" },
+    { "source": "files/main.rs",          "target": "src-tauri/src/main.rs" },
+    { "source": "files/lib.rs",           "target": "src-tauri/src/lib.rs" },
+    { "source": "files/tauri.conf.json",  "target": "src-tauri/tauri.conf.json" }
+  ],
+  "packageDeps": {
+    "dependencies": {
+      "react": "^19.2.0",
+      "react-dom": "^19.2.0",
+      "@tauri-apps/api": "^2.0.0"
+    },
+    "devDependencies": {
+      "@tauri-apps/cli": "^2.0.0",
+      "@types/node": "^20.17.0",
+      "@types/react": "^19.2.0",
+      "@types/react-dom": "^19.2.0",
+      "@vitejs/plugin-react": "^4.7.0",
+      "typescript": "^5.9.0",
+      "vite": "^6.4.2"
+    }
+  },
+  "buildHints": {
+    "whenToUse": "Pick tauri-menubar when the app lives in the macOS menu bar or Windows system tray and opens a small floating popover on click (Raycast-style launcher, quick-access panel). NOT for full desktop windows — use tauri-desktop for that.",
+    "firstSteps": [
+      "Run `pnpm install` then `cargo tauri dev` — Vite serves on :1420, Tauri wraps it as a tray popover positioned under the menu-bar icon.",
+      "All Rust setup is in `src-tauri/src/lib.rs`: TrayIconBuilder, tauri-plugin-positioner wiring, and the hide-on-blur WindowEvent handler.",
+      "The React surface is `src/App.tsx` — a 320×400 fixed-size panel with a search input and scrollable action list.",
+      "Add Tauri IPC commands in `src-tauri/src/lib.rs` with `#[tauri::command]` and call them from the frontend with `import { invoke } from '@tauri-apps/api/core'`.",
+      "Run `cargo tauri icon path/to/icon.png` to generate the full icon set in `src-tauri/icons/` before building for distribution."
+    ],
+    "gotchas": [
+      "macOS: `ActivationPolicy::Accessory` is set in the lib.rs setup closure — this hides the dock icon. Comment it out during development if you need Xcode debugger attach.",
+      "Tray icon requires at least one valid icon file. Run `cargo tauri icon <1024x1024.png>` to generate the full set before `cargo tauri build`; the icons/ directory is not scaffolded here.",
+      "Hide-on-blur on Windows fires when the user clicks the tray icon itself, causing a show-then-immediately-hide loop. Add a ~100ms debounce if you extend the focus handler.",
+      "`src-tauri/build.rs` calls `tauri_build::build()` which must stay — removing it breaks Tauri's code-generation step that produces `tauri::generate_context!()`."
+    ],
+    "architectureNotes": [
+      "`src-tauri/src/lib.rs` owns the TrayIconBuilder and uses tauri-plugin-positioner's `Position::TrayCenter` to place the window under the icon on left-click.",
+      "`src-tauri/src/main.rs` is a thin shim forwarding to `lib::run()` so all setup logic is testable without spawning a window.",
+      "The popover window (tauri.conf.json) is decorations:false, alwaysOnTop:true, skipTaskbar:true, resizable:false, 320×400 — changing these dims requires matching CSS changes in `src/styles.css`."
+    ],
+    "placeholders": [
+      {
+        "path": "src/App.tsx",
+        "description": "{{headline}} and {{subheadline}} are substituted at compose time. Replace the SEED action list with real commands backed by #[tauri::command] handlers in lib.rs."
+      },
+      {
+        "path": "src-tauri/Cargo.toml",
+        "description": "{{crateName}} is substituted at compose time with the snake_case project name (used for both [package].name and the lib crate name)."
+      },
+      {
+        "path": "src-tauri/src/main.rs",
+        "description": "{{crateName}}_lib::run() is substituted at compose time to match the crate name declared in Cargo.toml."
+      },
+      {
+        "path": "src-tauri/tauri.conf.json",
+        "description": "{{projectName}} and {{packageName}} are substituted at compose time with the human-readable project name and npm package slug."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": [
+      "pnpm install",
+      "cargo tauri dev",
+      "pnpm build",
+      "node preview-server.mjs",
+      "node validate-types.mjs"
+    ],
+    "entrypoints": [
+      "src-tauri/src/lib.rs",
+      "src-tauri/tauri.conf.json",
+      "src/App.tsx"
+    ],
+    "preview": { "path": "/" },
+    "extensionPoints": [
+      "src-tauri/src/lib.rs",
+      "src/App.tsx"
+    ]
+  }
+}

package/registry/layers/framework/tauri-tray/files/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "{{crateName}}"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+name = "{{crateName}}_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+
+[dependencies]
+tauri = { version = "2", features = ["tray-icon"] }
+tauri-plugin-notification = "2"
+tauri-plugin-autostart = "2"
+tauri-plugin-log = "2"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"

package/registry/layers/framework/tauri-tray/files/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    tauri_build::build()
+}

package/registry/layers/framework/tauri-tray/files/lib.rs

@@ -0,0 +1,89 @@
+// Tray-only daemon: no window ships by default. The user interacts via
+// the tray menu and receives feedback through native OS notifications.
+//
+// Menu items are registered up-front with stable ids so the handler can
+// dispatch to Tauri commands (keeps business logic separable from the
+// menu wiring).
+
+use tauri::{
+    menu::{Menu, MenuItem, PredefinedMenuItem},
+    tray::TrayIconBuilder,
+    Manager,
+};
+use tauri_plugin_autostart::MacosLauncher;
+use tauri_plugin_notification::NotificationExt;
+
+#[tauri::command]
+fn sync_now(app: tauri::AppHandle) -> Result<(), String> {
+    // Replace with real sync work; this stub sends a confirmation
+    // notification so agents can smoke-test the tray → notification
+    // pipeline end-to-end on first run.
+    app.notification()
+        .builder()
+        .title("Sync complete")
+        .body("All local changes are up to date.")
+        .show()
+        .map_err(|e| e.to_string())
+}
+
+#[cfg_attr(mobile, tauri::mobile_entry_point)]
+pub fn run() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_log::Builder::new().build())
+        .plugin(tauri_plugin_notification::init())
+        .plugin(tauri_plugin_autostart::init(
+            MacosLauncher::LaunchAgent,
+            Some(vec!["--autostart"]),
+        ))
+        .invoke_handler(tauri::generate_handler![sync_now])
+        .setup(|app| {
+            #[cfg(target_os = "macos")]
+            app.set_activation_policy(tauri::ActivationPolicy::Accessory);
+
+            let status = MenuItem::with_id(app, "status", "● Idle", false, None::<&str>)?;
+            let sep1 = PredefinedMenuItem::separator(app)?;
+            let sync = MenuItem::with_id(app, "sync", "Sync now", true, None::<&str>)?;
+            let logs = MenuItem::with_id(app, "logs", "Open logs…", true, None::<&str>)?;
+            let prefs = MenuItem::with_id(app, "prefs", "Preferences…", true, None::<&str>)?;
+            let sep2 = PredefinedMenuItem::separator(app)?;
+            let quit = MenuItem::with_id(app, "quit", "Quit", true, None::<&str>)?;
+
+            let menu = Menu::with_items(
+                app,
+                &[&status, &sep1, &sync, &logs, &prefs, &sep2, &quit],
+            )?;
+
+            // Fallback to a transparent 16×16 placeholder when no icon files have been
+            // generated yet. Run `pnpm tauri icon <source.png>` to replace it.
+            let icon = app.default_window_icon()
+                .cloned()
+                .unwrap_or_else(|| tauri::image::Image::new_owned(vec![0u8; 16 * 16 * 4], 16, 16));
+            let _tray = TrayIconBuilder::with_id("main")
+                .icon(icon)
+                .menu(&menu)
+                .tooltip("{{projectName}}")
+                .on_menu_event(|app, event| match event.id.as_ref() {
+                    "sync" => {
+                        let _ = sync_now(app.clone());
+                    }
+                    "quit" => {
+                        app.exit(0);
+                    }
+                    "logs" | "prefs" => {
+                        // Lazy-create a hidden webview here if/when the
+                        // project needs a real settings pane. Left as a
+                        // no-op so the daemon stays windowless by default.
+                        let _ = app.notification()
+                            .builder()
+                            .title("{{projectName}}")
+                            .body("Settings pane not wired yet — extend in src-tauri/src/lib.rs.")
+                            .show();
+                    }
+                    _ => {}
+                })
+                .build(app)?;
+            Ok(())
+        })
+        .run(tauri::generate_context!())
+        .expect("error while running tauri tray daemon");
+}

package/registry/layers/framework/tauri-tray/files/main.rs

@@ -0,0 +1,5 @@
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+fn main() {
+    {{crateName}}_lib::run();
+}

package/registry/layers/framework/tauri-tray/files/src/main.ts

@@ -0,0 +1 @@
+export { syncNow } from "./tray";

package/registry/layers/framework/tauri-tray/files/src/tray.ts

@@ -0,0 +1,5 @@
+import { invoke } from "@tauri-apps/api/core";
+
+export async function syncNow(): Promise<void> {
+  await invoke<void>("sync_now");
+}

package/registry/layers/framework/tauri-tray/files/tauri.conf.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "../node_modules/@tauri-apps/cli/config.schema.json",
+  "productName": "{{projectName}}",
+  "version": "0.1.0",
+  "identifier": "com.starterfoundry.{{packageName}}",
+  "build": {
+    "frontendDist": "../dist"
+  },
+  "app": {
+    "windows": [],
+    "security": {
+      "csp": null
+    }
+  },
+  "bundle": {
+    "active": true,
+    "targets": "all",
+    "icon": [
+      "icons/32x32.png",
+      "icons/128x128.png",
+      "icons/icon.icns",
+      "icons/icon.ico"
+    ],
+    "macOS": {
+      "minimumSystemVersion": "10.15"
+    }
+  }
+}

package/registry/layers/framework/tauri-tray/files/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": false,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}

package/registry/layers/framework/tauri-tray/manifest.json

@@ -0,0 +1,80 @@
+{
+  "id": "tauri-tray",
+  "description": "Tauri system-tray daemon — tray icon, right-click context menu, and native OS notifications. No primary window ships by default.",
+  "appliesTo": ["tauri-tray"],
+  "files": [
+    { "source": "files/tsconfig.json", "target": "tsconfig.json" },
+    { "source": "files/src/main.ts", "target": "src/main.ts" },
+    { "source": "files/src/tray.ts", "target": "src/tray.ts" },
+    { "source": "files/build.rs", "target": "src-tauri/build.rs" },
+    { "source": "files/Cargo.toml", "target": "src-tauri/Cargo.toml" },
+    { "source": "files/main.rs", "target": "src-tauri/src/main.rs" },
+    { "source": "files/lib.rs", "target": "src-tauri/src/lib.rs" },
+    { "source": "files/tauri.conf.json", "target": "src-tauri/tauri.conf.json" }
+  ],
+  "packageDeps": {
+    "dependencies": {
+      "@tauri-apps/api": "^2.0.0"
+    },
+    "devDependencies": {
+      "@tauri-apps/cli": "^2.0.0",
+      "@types/node": "^20.17.0",
+      "typescript": "^5.9.0"
+    }
+  },
+  "buildHints": {
+    "whenToUse": "Pick tauri-tray when the app is a headless background daemon with no primary window — tray icon + context menu + OS notifications only. Classic: Dropbox sync, Slack notifier, build-status watcher. If the user needs a popover panel, use tauri-menubar. If they need a real window, use tauri-desktop.",
+    "firstSteps": [
+      "Run `pnpm install` then `cargo tauri dev` — the daemon registers a tray icon and the context menu is live.",
+      "Template variables ({{crateName}}, {{projectName}}, {{packageName}}) are substituted automatically at compose time.",
+      "Add real icons via `pnpm tauri icon <source.png>` — generates into src-tauri/icons/ and auto-wires them in tauri.conf.json. Until then the tray falls back to a transparent placeholder.",
+      "Extend `on_menu_event` in src-tauri/src/lib.rs with business logic; add `#[tauri::command]` functions for async work.",
+      "Run `node preview-server.mjs` (or `pnpm preview:instant`) for a static HTML preview of the tray menu without a Rust build."
+    ],
+    "gotchas": [
+      "macOS: ActivationPolicy::Accessory is set in .setup() — without it you get both a dock icon AND a tray icon.",
+      "macOS notifications require NSUserNotificationsUsageDescription in Info.plist (via bundle.macOS in tauri.conf.json) and explicit user permission on first send — handle the denial case.",
+      "Linux (GNOME 45+): tray icons require the AppIndicator GNOME extension; document this since Tauri silently fails on stock GNOME.",
+      "build.rs must call tauri_build::build() — without it the Rust compile fails even though the build-dep is listed in Cargo.toml.",
+      "Windows: tray-only apps without a window can trigger AV heuristics — sign the binary and submit to Microsoft SmartScreen via Partner Center."
+    ],
+    "architectureNotes": [
+      "No webview window ships by default — the app is pure Rust with a tray surface.",
+      "Business logic lives in Tauri commands (#[tauri::command]) invoked from the Rust menu handler — keeps dispatch testable.",
+      "Lazy webview: create a hidden webview window programmatically if a settings pane is needed later. Set visible:false in tauri.conf.json to avoid flash-on-start.",
+      "Plugin calls (notification, autostart, log) are made from Rust, so no Tauri capability JSON files are required for this default shape."
+    ],
+    "placeholders": [
+      {
+        "path": "src-tauri/Cargo.toml",
+        "description": "{{crateName}} — snake_case crate name (e.g. my_tray_app). Substituted at compose time."
+      },
+      {
+        "path": "src-tauri/src/lib.rs",
+        "description": "{{projectName}} — used as tray tooltip and notification sender. Substituted at compose time."
+      },
+      {
+        "path": "src-tauri/tauri.conf.json",
+        "description": "{{projectName}} and {{packageName}} — app display name and bundle identifier. Substituted at compose time."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": [
+      "pnpm install",
+      "pnpm preview:instant",
+      "cargo tauri dev",
+      "pnpm tauri icon <source.png>"
+    ],
+    "entrypoints": [
+      "src-tauri/src/lib.rs",
+      "src-tauri/tauri.conf.json"
+    ],
+    "preview": {
+      "path": "/"
+    },
+    "extensionPoints": [
+      "src-tauri/src/lib.rs"
+    ]
+  }
+}

package/registry/layers/framework/tgi-server/files/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "tgi-starter"
+version = "0.1.0"
+description = "HuggingFace TGI client starter"
+requires-python = ">=3.11"
+dependencies = [
+    "huggingface_hub>=0.24.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.9.0",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src"]
+
+[tool.pyright]
+pythonVersion = "3.11"
+typeCheckingMode = "basic"
+include = ["src"]

package/registry/layers/framework/tgi-server/files/src/__init__.py

@@ -0,0 +1 @@
+"""TGI client package. See src/client.py for the HTTP wrapper."""

package/registry/layers/framework/tgi-server/files/src/main.py

@@ -0,0 +1,50 @@
+"""TGI server entrypoint.
+
+Runs a /generate call (or token-streaming /generate_stream) against a
+running TGI server.  Start the server first:
+
+    cp .env.example .env   # set MODEL_ID + HUGGING_FACE_HUB_TOKEN
+    docker compose up -d
+
+Then run:
+
+    python -m src.main                          # blocking generate
+    python -m src.main --stream "Your prompt"   # streaming
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from .client import generate, generate_stream
+
+TGI_URL = os.environ.get("TGI_URL", "http://localhost:8080")
+DEFAULT_PROMPT = "Explain Flash Attention in one paragraph."
+
+
+def main() -> int:
+    args = sys.argv[1:]
+    stream = "--stream" in args
+    prompt_parts = [a for a in args if a != "--stream"]
+    prompt = " ".join(prompt_parts) if prompt_parts else DEFAULT_PROMPT
+
+    print(f"TGI_URL: {TGI_URL}")
+    print(f"> {prompt}\n")
+
+    try:
+        if stream:
+            for token in generate_stream(prompt):
+                print(token, end="", flush=True)
+            print()
+        else:
+            print(generate(prompt))
+    except Exception as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        print("Is TGI running?  docker compose up -d", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/registry/layers/framework/tgi-server/manifest.json

@@ -0,0 +1,41 @@
+{
+  "id": "tgi-server",
+  "description": "Python package scaffold for the TGI client — pyproject.toml for typecheck, typed src/__init__.py, and a src/main.py entrypoint that exercises /generate and /generate_stream against a local TGI server.",
+  "appliesTo": ["tgi-server"],
+  "files": [
+    { "source": "files/src/__init__.py", "target": "src/__init__.py" },
+    { "source": "files/src/main.py",   "target": "src/main.py" },
+    { "source": "files/pyproject.toml","target": "pyproject.toml" }
+  ],
+  "buildHints": {
+    "whenToUse": "Always applied to tgi-server projects — provides the Python package structure (src/__init__.py, src/main.py, pyproject.toml) that wraps the docker-compose + client files supplied by the tgi-server family.",
+    "firstSteps": [
+      "cp .env.example .env — fill in MODEL_ID and HUGGING_FACE_HUB_TOKEN",
+      "docker compose up -d — first boot pulls model weights (~15-60 GB) to ./data; watch `docker compose logs -f` until the health-check passes",
+      "pip install -r requirements.txt",
+      "python -m src.main                         # blocking /generate with default prompt",
+      "python -m src.main --stream 'Your prompt'  # token-streaming via /generate_stream"
+    ],
+    "gotchas": [
+      "Run as a module (`python -m src.main`), not a script (`python src/main.py`) — the relative import `from .client import …` requires the package context.",
+      "mypy runs in strict mode; all three deps (httpx, huggingface_hub, pydantic) ship py.typed markers so `mypy src/` passes clean after `pip install -r requirements.txt`.",
+      "TGI_URL defaults to http://localhost:8080 — if you changed the port mapping in docker-compose.yml, set TGI_URL in .env before running the client."
+    ],
+    "placeholders": [
+      {
+        "path": "src/main.py",
+        "description": "DEFAULT_PROMPT — replace with your actual test prompt before shipping."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": [
+      "pip install -r requirements.txt",
+      "mypy src/",
+      "python -m src.main",
+      "python -m src.main --stream 'Explain transformer attention'"
+    ],
+    "entrypoints": ["src/main.py", "src/client.py"],
+    "extensionPoints": ["src/main.py", "src/client.py"]
+  }
+}

package/registry/layers/framework/threejs-game/files/src/main.ts

@@ -0,0 +1,62 @@
+import {
+  AmbientLight,
+  BoxGeometry,
+  DirectionalLight,
+  Mesh,
+  MeshStandardMaterial,
+  PerspectiveCamera,
+  Scene,
+  WebGLRenderer,
+} from 'three'
+
+const canvas = document.getElementById('scene') as HTMLCanvasElement
+if (!canvas) throw new Error('#scene canvas missing from index.html')
+
+const renderer = new WebGLRenderer({ canvas, antialias: true })
+renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))
+renderer.setSize(window.innerWidth, window.innerHeight)
+
+const scene = new Scene()
+
+const camera = new PerspectiveCamera(60, window.innerWidth / window.innerHeight, 0.1, 100)
+camera.position.set(2, 2, 3)
+camera.lookAt(0, 0, 0)
+
+scene.add(new AmbientLight(0xffffff, 0.6))
+const key = new DirectionalLight(0xffffff, 0.9)
+key.position.set(3, 4, 5)
+scene.add(key)
+
+const cube = new Mesh(
+  new BoxGeometry(1, 1, 1),
+  new MeshStandardMaterial({ color: 0x6ea8ff, roughness: 0.35, metalness: 0.1 }),
+)
+scene.add(cube)
+
+let rafHandle = 0
+function tick(): void {
+  cube.rotation.x += 0.008
+  cube.rotation.y += 0.012
+  renderer.render(scene, camera)
+  rafHandle = requestAnimationFrame(tick)
+}
+tick()
+
+function onResize(): void {
+  const w = window.innerWidth
+  const h = window.innerHeight
+  renderer.setSize(w, h)
+  camera.aspect = w / h
+  camera.updateProjectionMatrix()
+}
+window.addEventListener('resize', onResize)
+
+if (import.meta.hot) {
+  import.meta.hot.dispose(() => {
+    cancelAnimationFrame(rafHandle)
+    window.removeEventListener('resize', onResize)
+    cube.geometry.dispose()
+    ;(cube.material as MeshStandardMaterial).dispose()
+    renderer.dispose()
+  })
+}

package/registry/layers/framework/threejs-game/files/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/registry/layers/framework/threejs-game/manifest.json

@@ -0,0 +1,50 @@
+{
+  "id": "threejs-game",
+  "description": "Three.js WebGL framework layer — renderer, camera, lit mesh, animation loop, resize + HMR dispose wired from first render.",
+  "appliesTo": ["threejs-game"],
+  "files": [
+    { "source": "files/src/main.ts", "target": "src/main.ts" },
+    { "source": "files/src/vite-env.d.ts", "target": "src/vite-env.d.ts" }
+  ],
+  "packageDeps": {
+    "dependencies": {
+      "three": "^0.170.0"
+    },
+    "devDependencies": {
+      "@types/three": "^0.170.0",
+      "typescript": "^5.9.0",
+      "vite": "^6.4.2"
+    }
+  },
+  "buildHints": {
+    "whenToUse": "3D scene viewers, WebGL games, shader playgrounds, gltf/fbx asset explorers, or any product archetype where the primary surface is a live 3D canvas.",
+    "firstSteps": [
+      "Run `pnpm install` then `pnpm dev` — Vite serves on 5173 with HMR; the rotating cube renders immediately.",
+      "All scene setup lives in `src/main.ts` — scene, camera, renderer, lights, mesh, and animation loop in one file; fork cleanly from there.",
+      "Add 3D models via `GLTFLoader` from `three/examples/jsm/loaders/GLTFLoader.js`; place assets in `public/` and load with `new GLTFLoader().load('/model.glb', ...)`.",
+      "Run `pnpm build` to emit static assets to `dist/` — no server required, deploy anywhere."
+    ],
+    "gotchas": [
+      "`import.meta.hot` requires Vite client types — `src/vite-env.d.ts` provides the reference directive; do not delete it or typecheck will fail on the HMR block.",
+      "Always cancel `requestAnimationFrame` in the HMR dispose callback; the handle is stored in `rafHandle`. Skipping this causes multiple parallel render loops and runaway CPU usage.",
+      "Call `renderer.setSize(w, h)` AND `camera.aspect = w/h; camera.updateProjectionMatrix()` on resize — CSS-only resize stretches the image without updating the projection matrix.",
+      "Dispose geometries, materials, and textures manually when swapping scenes — Three.js does not garbage-collect GPU memory. Use `geometry.dispose()`, `material.dispose()`, `texture.dispose()`."
+    ],
+    "architectureNotes": [
+      "Single renderer per page — do not construct a new `WebGLRenderer` per frame or per component; it leaks the GL context.",
+      "Keep render-loop work pure: mutate transforms in the loop, allocate meshes and materials outside it. Allocations inside the loop cause GC pauses visible as jank."
+    ],
+    "placeholders": [
+      {
+        "path": "src/main.ts",
+        "description": "Rotating cube bootstrap. Replace the BoxGeometry + MeshStandardMaterial with actual geometry or a GLTFLoader call. Keep the renderer, camera, resize handler, and HMR dispose block."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": ["pnpm install", "pnpm dev", "pnpm build", "pnpm run validate"],
+    "entrypoints": ["src/main.ts"],
+    "preview": { "path": "/" },
+    "extensionPoints": ["src/main.ts", "src/scene.ts", "src/loop.ts"]
+  }
+}

package/registry/layers/framework/triton-server/files/AGENTS.md

@@ -0,0 +1,71 @@
+# {{serviceName}} — NVIDIA Triton Inference Server
+
+## What this scaffold gives you
+
+| File | Purpose |
+|---|---|
+| `docker-compose.yml` | Triton container with GPU device reservation, model_repository mount, ports {{port}}/{{grpcPort}}/{{metricsPort}} |
+| `model_repository/identity/config.pbtxt` | Built-in echo model — passes smoke-test without any real weights |
+| `model_repository/identity/1/.gitkeep` | Integer version-dir placeholder (Triton ignores non-integer dirs like `v1/`) |
+| `src/client.py` | HTTP (KServe v2) client — infers against the identity model out of the box |
+| `src/__init__.py` | Package init so `python -m src.client` resolves without a separate `__main__.py` |
+| `requirements.txt` | Runtime pip deps: `tritonclient[http]`, `numpy` |
+| `pyproject.toml` | Python project metadata, deps, pyright (basic), ruff |
+| `Makefile` | Workflow shortcuts: `install`, `install-dev`, `typecheck`, `up`, `health`, `client` |
+| `docs/triton.md` | Extended reference: ONNX/TRT config, dynamic batching, ensemble setup |
+
+## Quick start
+
+```sh
+# 1. Install Python deps
+make install        # pip install -r requirements.txt
+make install-dev    # pip install -e '.[dev]'  (pyright + ruff)
+
+# 2. Start Triton (pulls ~15 GB on first run)
+make up             # docker compose up -d
+
+# 3. Wait for ready (Triton takes ~60 s on cold start)
+make health         # curl -f http://localhost:{{port}}/v2/health/ready
+
+# 4. Run inference smoke-test against the identity model
+make client         # python -m src.client  →  output: [1.0, 2.0, 3.0, 4.0]
+
+# 5. Typecheck
+make typecheck      # pyright src/  — zero errors out of the box
+```
+
+## Add a real model
+
+1. Drop weights under `model_repository/<name>/<version>/` — version **must** be an integer:
+   ```
+   model_repository/
+   └── my_model/
+       ├── config.pbtxt
+       └── 1/
+           └── model.onnx
+   ```
+2. Write `config.pbtxt` — use `backend` **or** `platform` (never both):
+   - ONNX: `backend: "onnxruntime"`
+   - TensorRT: `platform: "tensorrt_plan"`
+   - Python custom: `backend: "python"`
+3. Triton polls `model_repository/` every 30 s. Force an immediate reload:
+   ```sh
+   curl -X POST http://localhost:{{port}}/v2/repository/models/my_model/load
+   ```
+4. Edit `src/client.py` — update `MODEL_NAME`, input/output tensor names, and shape to match your model.
+
+## Key extension points
+
+- **New model** — add `model_repository/<name>/config.pbtxt` + integer version dir with weights
+- **Ensemble** — add `ensemble_scheduling` block in `config.pbtxt` to chain existing models
+- **Client code** — edit `src/client.py`; run `make client` to iterate
+- **Pin the image** — replace `nvcr.io/nvidia/tritonserver:latest` with a specific tag (e.g. `24.10-py3`) in `docker-compose.yml` to avoid surprise breaks on TRT engine rebuilds
+
+## Critical gotchas
+
+- **Integer version dirs only.** `1/`, `2/` work; `v1/`, `latest/` are silently skipped — no error, no warning.
+- **`platform` and `backend` are mutually exclusive.** Mixing them causes an opaque model-load failure.
+- **Dynamic dims** — use `-1` in `dims: [ -1 ]` for variable-size axes. Wrong dims → `inference failed` with no usable stack trace.
+- **TRT engines are GPU-specific.** A `.plan` built on A100 will not load on H100 — rebuild per deploy target.
+- **KServe v2 protocol** — endpoints are `/v2/models/<name>/infer`, not the legacy `/api/infer`.
+- **Image is ~15 GB.** First `docker compose up` takes 10–20 min. Pin the tag so you don't re-pull unexpectedly.