@telemetryos/cli 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @telemetryos/cli
 
+## 1.4.0
+
+### Minor Changes
+
+- This change updates the CLI package to properly host applications with
+  full support for all SDK features.
+
+### Patch Changes
+
+- Updated dependencies
+  - @telemetryos/development-application-host-ui@1.4.0
+
+## 1.3.0
+
+### Minor Changes
+
+- Add Weather API
+
+  Adds a weather API for applications that wish to use it. It can be found on
+  client instances under .weather.
+
+### Patch Changes
+
+- Updated dependencies
+  - @telemetryos/development-application-host-ui@1.3.0
+
 ## 1.2.0
 
 ### Minor Changes

package/dist/commands/init.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const initCommand: Command;

package/dist/commands/init.js

@@ -0,0 +1,79 @@
+import { Command } from 'commander';
+import { generateApplication } from '../generate-application.js';
+import inquirer from 'inquirer';
+import path from 'path';
+export const initCommand = new Command('init')
+    .description('Initializes a new telemetryOS application')
+    .option('-n, --name <string>', 'The name of the application', '')
+    .option('-d, --description <string>', 'The description of the application', 'A telemetryOS application')
+    .option('-a, --author <string>', 'The author of the application', '')
+    .option('-v, --version <string>', 'The version of the application', '0.1.0')
+    .option('-t, --template <string>', 'The template to use (vite-react-typescript)', '')
+    .argument('[project-path]', 'Path to create the new telemetry application project. Defaults to a folder current working directory with the same name as your project', '')
+    .action(handleInitCommand);
+async function handleInitCommand(projectPath, options) {
+    let name = options.name;
+    let description = options.description;
+    let author = options.author;
+    let version = options.version;
+    let template = options.template;
+    const questions = [];
+    if (!name)
+        questions.push({
+            type: 'input',
+            name: 'name',
+            message: 'What is the name of your application?',
+            validate: (input) => input.length > 0 || 'Application name cannot be empty'
+        });
+    if (!description)
+        questions.push({
+            type: 'input',
+            name: 'description',
+            message: 'What is the description of your application?',
+            default: ''
+        });
+    if (!author)
+        questions.push({
+            type: 'input',
+            name: 'author',
+            message: 'Who is the author of your application?',
+            default: ''
+        });
+    if (!version)
+        questions.push({
+            type: 'input',
+            name: 'version',
+            message: 'What is the version of your application?',
+            default: '0.1.0',
+            validate: (input) => /^\d+\.\d+\.\d+(-.+)?$/.test(input) || 'Version must be in semver format (e.g. 1.0.0)'
+        });
+    if (!template)
+        questions.push({
+            type: 'list',
+            name: 'template',
+            message: 'Which template would you like to use?',
+            choices: [
+                { name: 'Vite + React + TypeScript', value: 'vite-react-typescript' }
+            ]
+        });
+    if (questions.length !== 0) {
+        const answers = await inquirer.prompt(questions);
+        if (answers.name)
+            name = answers.name;
+        if (answers.template)
+            template = answers.template;
+    }
+    if (!projectPath)
+        projectPath = path.join(process.cwd(), name);
+    await generateApplication({
+        name,
+        description,
+        author,
+        version,
+        template,
+        projectPath,
+        progressFn: (createdFilePath) => {
+            console.log(`.${path.sep}${path.relative(process.cwd(), createdFilePath)}`);
+        }
+    });
+}

package/dist/commands/root.js

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
 import pkg from '../../package.json' with { type: 'json' };
-export const rootCommand = new Command('tx')
-    .description('TelemetryX Application CLI')
+export const rootCommand = new Command('tos')
+    .description('TelemetryOS Application CLI')
     .version(pkg.version);

package/dist/commands/serve.js

@@ -1,7 +1,7 @@
 import { Command } from 'commander';
 import { runServer } from '../run-server.js';
 export const serveCommand = new Command('serve')
-    .description('Serves a telemetryX application locally for development')
+    .description('Serves a telemetryOS application locally for development')
     .option('-p, --port <number>', 'Port to run the development ui on', '6969')
     .argument('[project-path]', 'Path to the telemetry application project. Defaults to current working directory', process.cwd())
     .action(runServer);

package/dist/generate-application.d.ts

@@ -0,0 +1,10 @@
+export type GenerateApplicationOptions = {
+    name: string;
+    description: string;
+    author: string;
+    version: string;
+    template: string;
+    projectPath: string;
+    progressFn: (createdFilePath: string) => void;
+};
+export declare function generateApplication(options: GenerateApplicationOptions): Promise<void>;

package/dist/generate-application.js

@@ -0,0 +1,45 @@
+import fs from "fs/promises";
+import path from "path";
+const ignoredTelemplateFiles = [
+    '.DS_Store',
+    'thumbs.db',
+    'node_modules',
+    '.git',
+    'dist'
+];
+const templatesDir = path.join(import.meta.dirname, '../templates');
+export async function generateApplication(options) {
+    const { name, description, author, version, template, projectPath, progressFn } = options;
+    await fs.mkdir(projectPath, { recursive: true });
+    await copyDir(path.join(templatesDir, template), projectPath, {
+        name,
+        description,
+        author,
+        version
+    }, progressFn);
+}
+async function copyDir(source, destination, replacements, progressFn) {
+    const dirListing = await fs.readdir(source);
+    for (const dirEntry of dirListing) {
+        if (ignoredTelemplateFiles.includes(dirEntry))
+            continue;
+        const sourcePath = path.join(source, dirEntry);
+        const destinationPath = path.join(destination, dirEntry);
+        const stats = await fs.stat(sourcePath);
+        if (stats.isDirectory()) {
+            await fs.mkdir(destinationPath, { recursive: true });
+            await copyDir(sourcePath, destinationPath, replacements, progressFn);
+        }
+        else if (stats.isFile()) {
+            await copyFile(sourcePath, destinationPath, replacements, progressFn);
+        }
+    }
+}
+async function copyFile(source, destination, replacements, progressFn) {
+    let contents = await fs.readFile(source, 'utf-8');
+    for (const [key, value] of Object.entries(replacements)) {
+        contents = contents.replace(new RegExp(`{{${key}}}`, 'g'), value);
+    }
+    await fs.writeFile(destination, contents, 'utf-8');
+    progressFn(destination);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { initCommand } from './commands/init.js';
+import { rootCommand } from './commands/root.js';
+import { serveCommand } from './commands/serve.js';
+rootCommand.addCommand(serveCommand);
+rootCommand.addCommand(initCommand);
+rootCommand.parse(process.argv);

package/dist/run-server.d.ts

@@ -0,0 +1,5 @@
+type Flags = {
+    port: number;
+};
+export declare function runServer(projectPath: string, flags: Flags): Promise<void>;
+export {};

package/dist/run-server.js

@@ -0,0 +1,100 @@
+import { spawn } from 'child_process';
+import { readFile } from 'fs/promises';
+import http from 'http';
+import path from 'path';
+import readable from 'readline/promises';
+import serveHandler from 'serve-handler';
+const ansiWhite = '\u001b[37m';
+const ansiYellow = '\u001b[33m';
+const ansiCyan = '\u001b[36m';
+const ansiBold = '\u001b[1m';
+const ansiReset = '\u001b[0m';
+export async function runServer(projectPath, flags) {
+    printSplashScreen();
+    projectPath = path.resolve(process.cwd(), projectPath);
+    const telemetryConfig = await loadConfigFile(projectPath);
+    if (!telemetryConfig) {
+        console.error('No telemetry configuration found. Are you in the right directory?');
+        process.exit(1);
+    }
+    await serveDevelopmentApplicationHostUI(flags.port, telemetryConfig);
+    await serveTelemetryApplication(projectPath, telemetryConfig);
+}
+async function serveDevelopmentApplicationHostUI(port, telemetryConfig) {
+    const hostUiPath = await import.meta.resolve('@telemetryos/development-application-host-ui/dist');
+    const serveConfig = { public: hostUiPath.replace('file://', '') };
+    const server = http.createServer();
+    server.on('request', (req, res) => {
+        const url = new URL(req.url, `http://${req.headers.origin}`);
+        if (url.pathname === '/__tos-config__') {
+            res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify(telemetryConfig));
+            return;
+        }
+        serveHandler(req, res, serveConfig).catch((err) => {
+            console.error('Error handling request:', err);
+            res.statusCode = 500;
+            res.end('Internal Server Error');
+        });
+    });
+    printServerInfo(port);
+    server.listen(port);
+}
+async function serveTelemetryApplication(rootPath, telemetryConfig) {
+    var _a;
+    if (!((_a = telemetryConfig === null || telemetryConfig === void 0 ? void 0 : telemetryConfig.devServer) === null || _a === void 0 ? void 0 : _a.runCommand))
+        return;
+    const runCommand = telemetryConfig.devServer.runCommand;
+    const binPath = path.join(rootPath, 'node_modules', '.bin');
+    const childProcess = spawn(runCommand, {
+        shell: true,
+        env: { ...process.env, FORCE_COLOR: '1', PATH: `${binPath}:${process.env.PATH}` },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        cwd: rootPath,
+    });
+    const stdoutReadline = readable.createInterface({
+        input: childProcess.stdout,
+        crlfDelay: Infinity,
+    });
+    const stderrReadline = readable.createInterface({
+        input: childProcess.stderr,
+        crlfDelay: Infinity,
+    });
+    stdoutReadline.on('line', (line) => {
+        console.log(`[application]: ${line}`);
+    });
+    stderrReadline.on('line', (line) => {
+        console.error(`[application]: ${line}`);
+    });
+    process.on('exit', () => {
+        childProcess.kill();
+    });
+}
+async function loadConfigFile(rootPath) {
+    const configFilePath = path.join(rootPath, 'telemetry.config.json');
+    try {
+        const fileContent = await readFile(configFilePath, 'utf-8');
+        const config = JSON.parse(fileContent);
+        return config;
+    }
+    catch {
+        return null;
+    }
+}
+function printSplashScreen() {
+    console.log(`
+
+     ${ansiWhite} █       █                  █          ${ansiYellow}▄▀▀▀▄ ▄▀▀▀▄
+     ${ansiWhite} █       █                  █          ${ansiYellow}█   █ █
+     ${ansiWhite}▀█▀ ▄▀▀▄ █ ▄▀▀▄ █▀▄▀▄ ▄▀▀▄ ▀█▀ █▄▀ █ █ ${ansiYellow}█   █  ▀▀▀▄
+     ${ansiWhite} █  █▀▀▀ █ █▀▀▀ █ █ █ █▀▀▀  █  █   █ █ ${ansiYellow}█   █     █
+     ${ansiWhite} ▀▄ ▀▄▄▀ █ ▀▄▄▀ █ █ █ ▀▄▄▀  ▀▄ █    █  ${ansiYellow}▀▄▄▄▀ ▀▄▄▄▀
+     ${ansiWhite}                                   ▄▀  ${ansiReset}`);
+}
+function printServerInfo(port) {
+    console.log(`
+╔═══════════════════════════════════════════════════════════╗
+║ ${ansiBold}Development environment running at: ${ansiCyan}http://localhost:${port}${ansiReset} ║
+╚═══════════════════════════════════════════════════════════╝
+`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetryos/cli",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "The official TelemetryOS application CLI package. Use it to build applications that run on the TelemetryOS platform",
   "type": "module",
   "bin": {
@@ -25,7 +25,7 @@
   "license": "",
   "repository": "github:TelemetryTV/Application-API",
   "dependencies": {
-    "@telemetryos/development-application-host-ui": "^1.2.0",
+    "@telemetryos/development-application-host-ui": "^1.4.0",
     "@types/serve-handler": "^6.1.4",
     "commander": "^14.0.0",
     "inquirer": "^12.9.6",

package/templates/vite-react-typescript/AGENTS.md

@@ -0,0 +1,7 @@
+# Agent Guidelines
+
+This document outlines guidelines for interacting with and developing for AI agents within this project.
+
+## Important Notes
+
+*   **Claude-specific Guidelines:** If you are working with Claude models, please refer to `CLAUDE.md` for specific guidelines and best practices.

package/templates/vite-react-typescript/CLAUDE.md

@@ -0,0 +1,625 @@
+# TelemetryOS SDK Reference
+
+**Application:** [Your App Name]
+**Purpose:** [What this application does]
+
+## Platform Architecture
+
+TelemetryOS applications are web apps that run on digital signage devices. Applications have up to 4 components:
+
+1. **Render** (`/render`) - Content displayed on devices (runs on device in Chrome/iframe)
+2. **Settings** (`/settings`) - Config UI in Studio admin portal (runs in Studio browser)
+3. **Workers** (optional) - Background JavaScript (runs on device, no DOM)
+4. **Containers** (optional) - Docker containers for backend services (runs on device)
+
+**Runtime Environment:**
+- Chrome browser (platform-controlled version)
+- Iframe sandbox execution
+- Client-side only (no SSR, no Node.js APIs)
+- Modern web APIs available (Fetch, WebSockets, WebGL, Canvas)
+- External APIs require CORS proxy
+
+**Communication:**
+- Settings and Render share instance storage
+- Settings saves config → Render subscribes to config
+- Device storage only available in Render (not Settings)
+
+## Project Structure
+
+```
+project-root/
+├── telemetry.config.json       # Platform configuration
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+├── index.html
+└── src/
+    ├── main.tsx                # Entry point (configure SDK here)
+    ├── App.tsx                 # Routing logic
+    ├── views/
+    │   ├── Settings.tsx        # /settings mount point
+    │   └── Render.tsx          # /render mount point
+    ├── components/             # Reusable components
+    ├── hooks/                  # Custom React hooks
+    ├── types/                  # TypeScript interfaces
+    └── utils/                  # Helper functions
+```
+
+## Configuration Files
+
+### telemetry.config.json (project root)
+```json
+{
+  "name": "app-name",
+  "version": "1.0.0",
+  "mountPoints": {
+    "render": "/render",
+    "settings": "/settings"
+  },
+  "devServer": {
+    "runCommand": "vite --port 3000",
+    "url": "http://localhost:3000"
+  }
+}
+```
+
+### package.json scripts
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@telemetryos/sdk": "latest",
+    "react": "latest",
+    "react-dom": "latest"
+  },
+  "devDependencies": {
+    "@types/react": "latest",
+    "@types/react-dom": "latest",
+    "@vitejs/plugin-react": "latest",
+    "typescript": "latest",
+    "vite": "latest"
+  }
+}
+```
+
+## Complete File Implementations
+
+### src/main.tsx (Entry Point)
+```typescript
+import { configure } from '@telemetryos/sdk';
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+import './index.css';
+
+// Configure SDK ONCE before React renders
+// Name must match telemetry.config.json
+configure('app-name');
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+```
+
+### src/App.tsx (Routing)
+```typescript
+import Settings from './views/Settings';
+import Render from './views/Render';
+
+export default function App() {
+  const path = window.location.pathname;
+
+  if (path === '/settings') return <Settings />;
+  if (path === '/render') return <Render />;
+
+  return <div>Invalid mount point: {path}</div>;
+}
+```
+
+### src/views/Settings.tsx (Complete Reference)
+```typescript
+import { useEffect, useState, FormEvent } from 'react';
+import { store } from '@telemetryos/sdk';
+
+interface Config {
+  city: string;
+  units: 'celsius' | 'fahrenheit';
+}
+
+export default function Settings() {
+  const [config, setConfig] = useState<Config>({ city: '', units: 'celsius' });
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Load existing config on mount
+  useEffect(() => {
+    store().instance.get<Config>('config')
+      .then(saved => { if (saved) setConfig(saved); })
+      .catch(err => setError(err.message));
+  }, []);
+
+  const handleSave = async (e: FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+    setError(null);
+
+    try {
+      const success = await store().instance.set('config', config);
+      if (!success) throw new Error('Storage operation failed');
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Unknown error');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div>
+      <h2>Settings</h2>
+      {error && <div style={{ color: 'red' }}>{error}</div>}
+      <form onSubmit={handleSave}>
+        <div>
+          <label htmlFor="city">City:</label>
+          <input
+            id="city"
+            value={config.city}
+            onChange={(e) => setConfig({ ...config, city: e.target.value })}
+            required
+          />
+        </div>
+        <div>
+          <label htmlFor="units">Units:</label>
+          <select
+            id="units"
+            value={config.units}
+            onChange={(e) => setConfig({ ...config, units: e.target.value as Config['units'] })}
+          >
+            <option value="celsius">Celsius</option>
+            <option value="fahrenheit">Fahrenheit</option>
+          </select>
+        </div>
+        <button type="submit" disabled={loading}>
+          {loading ? 'Saving...' : 'Save'}
+        </button>
+      </form>
+    </div>
+  );
+}
+```
+
+### src/views/Render.tsx (Complete Reference)
+```typescript
+import { useEffect, useState } from 'react';
+import { store, proxy } from '@telemetryos/sdk';
+
+interface Config {
+  city: string;
+  units: 'celsius' | 'fahrenheit';
+}
+
+interface WeatherData {
+  temperature: number;
+  conditions: string;
+}
+
+export default function Render() {
+  const [config, setConfig] = useState<Config | null>(null);
+  const [weather, setWeather] = useState<WeatherData | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Subscribe to config changes from Settings
+  useEffect(() => {
+    store().instance.get<Config>('config').then(setConfig);
+
+    const unsubscribe = store().instance.subscribe('config', (newConfig: Config) => {
+      setConfig(newConfig);
+    });
+
+    return () => unsubscribe();
+  }, []);
+
+  // Fetch weather when config changes
+  useEffect(() => {
+    if (!config?.city) return;
+
+    const fetchWeather = async () => {
+      setLoading(true);
+      setError(null);
+
+      try {
+        const response = await proxy().fetch(
+          `https://api.example.com/weather?city=${config.city}&units=${config.units}`
+        );
+
+        if (!response.ok) throw new Error(`API error: ${response.status}`);
+
+        const data = await response.json();
+        setWeather({ temperature: data.temp, conditions: data.conditions });
+
+        // Cache for offline
+        await store().device.set('cached', { data, timestamp: Date.now() });
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Unknown error');
+
+        // Try cached data
+        const cached = await store().device.get<any>('cached');
+        if (cached) setWeather(cached.data);
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    fetchWeather();
+  }, [config]);
+
+  // States
+  if (!config) return <div>Configure in Settings</div>;
+  if (loading && !weather) return <div>Loading...</div>;
+  if (error && !weather) return <div>Error: {error}</div>;
+
+  return (
+    <div>
+      <h1>{config.city}</h1>
+      <div>{weather?.temperature}°{config.units === 'celsius' ? 'C' : 'F'}</div>
+      <div>{weather?.conditions}</div>
+      {error && <div style={{ color: 'orange' }}>Showing cached data</div>}
+    </div>
+  );
+}
+```
+
+## SDK API Reference
+
+Import from `@telemetryos/sdk`.
+
+### Initialization
+
+```typescript
+configure(applicationName: string): void
+```
+- Call once in main.tsx before React renders
+- Name must match telemetry.config.json
+- Throws if called multiple times
+
+### Storage API
+
+**Type Signatures:**
+```typescript
+store().application.set(key: string, value: any): Promise<boolean>
+store().application.get<T>(key: string): Promise<T | null>
+store().application.subscribe(key: string, handler: (value: any) => void): () => void
+store().application.delete(key: string): Promise<boolean>
+store().application.keys(): Promise<string[]>
+
+// Same methods for instance, device, shared(namespace)
+```
+
+**Four Scopes:**
+
+1. **application** - Shared across all instances of app in account
+```typescript
+await store().application.set('companyLogo', 'https://...');
+const logo = await store().application.get<string>('companyLogo');
+```
+
+2. **instance** - This specific app instance (Settings ↔ Render communication)
+```typescript
+// Settings saves
+await store().instance.set('config', { city: 'NYC' });
+
+// Render subscribes
+const unsubscribe = store().instance.subscribe('config', (newConfig) => {
+  updateDisplay(newConfig);
+});
+// Later: unsubscribe();
+```
+
+3. **device** - This physical device only (NOT available in Settings)
+```typescript
+// Only in Render mount point
+await store().device.set('cache', data);
+const cached = await store().device.get<CacheType>('cache');
+```
+
+4. **shared(namespace)** - Inter-app communication
+```typescript
+// App A publishes
+await store().shared('weather').set('temp', '72°F');
+
+// App B subscribes
+store().shared('weather').subscribe('temp', (temp) => console.log(temp));
+```
+
+**Constraints:**
+- All operations timeout after 30 seconds (throws Error)
+- Returns Promise<boolean> for set/delete (true = success)
+- Returns Promise<T | null> for get
+- subscribe() returns unsubscribe function
+- Device scope throws Error in Settings mount point
+
+### Proxy API
+
+```typescript
+proxy().fetch(url: string, options?: RequestInit): Promise<Response>
+```
+
+- Same interface as standard fetch()
+- Use for ALL external API calls to avoid CORS errors
+- Returns standard Response object
+- Handles CORS server-side
+
+**Example:**
+```typescript
+import { proxy } from '@telemetryos/sdk';
+
+const response = await proxy().fetch('https://api.example.com/data');
+const json = await response.json();
+```
+
+### Media API
+
+```typescript
+media().getAllByTag(tag: string): Promise<MediaContent[]>
+media().getById(id: string): Promise<MediaContent | null>
+
+interface MediaContent {
+  id: string;
+  url: string;
+  type: 'image' | 'video';
+  tags: string[];
+  metadata: Record<string, any>;
+}
+```
+
+### Playlist API
+
+```typescript
+playlist().nextPage(): Promise<boolean>
+playlist().previousPage(): Promise<boolean>
+playlist().jumpToPage(index: number): Promise<boolean>
+```
+
+### Overrides API
+
+```typescript
+overrides().setOverride(id: string): Promise<boolean>
+overrides().clearOverride(): Promise<boolean>
+```
+
+Note: Override IDs must be pre-configured in Freeform Editor.
+
+### Platform Information
+
+```typescript
+accounts().getCurrent(): Promise<Account>
+users().getCurrent(): Promise<User>
+devices().getCurrent(): Promise<Device>  // Render only
+```
+
+## Hard Constraints
+
+**These cause runtime errors:**
+
+1. **Device storage in Settings**
+   - Settings runs in Studio browser, not on devices
+   - `store().device.*` throws Error in Settings
+   - Use `store().instance` or `store().application` instead
+
+2. **External API without proxy**
+   - Direct `fetch()` to external domains fails with CORS error
+   - Must use `proxy().fetch()` for all external requests
+
+3. **Missing configure()**
+   - SDK methods throw "SDK not configured" Error
+   - Call `configure()` once in main.tsx before React renders
+
+4. **Subscription memory leaks**
+   - `subscribe()` returns unsubscribe function
+   - Must call unsubscribe on component unmount
+   - Return unsubscribe from useEffect cleanup
+
+5. **Timeout errors**
+   - All SDK operations timeout after 30 seconds
+   - Throws Error with message containing 'timeout'
+   - Handle with try/catch
+
+## TypeScript Patterns
+
+**Define interfaces for all configs and data:**
+```typescript
+interface AppConfig {
+  city: string;
+  units: 'celsius' | 'fahrenheit';
+  refreshInterval: number;
+}
+
+const config = await store().instance.get<AppConfig>('config');
+if (config) {
+  console.log(config.city);  // TypeScript knows this exists
+}
+```
+
+**Component with proper types:**
+```typescript
+interface Props {
+  data: WeatherData;
+  onRefresh: () => void;
+}
+
+export default function WeatherCard({ data, onRefresh }: Props) {
+  return <div>{data.temperature}</div>;
+}
+```
+
+## React Patterns
+
+**Error handling:**
+```typescript
+const [error, setError] = useState<string | null>(null);
+
+try {
+  await store().instance.set('key', value);
+} catch (err) {
+  setError(err instanceof Error ? err.message : 'Unknown error');
+}
+```
+
+**Loading states:**
+```typescript
+const [loading, setLoading] = useState(false);
+
+const handleAction = async () => {
+  setLoading(true);
+  try {
+    await someAsyncOperation();
+  } finally {
+    setLoading(false);
+  }
+};
+```
+
+**Subscription cleanup:**
+```typescript
+useEffect(() => {
+  const unsubscribe = store().instance.subscribe('key', handler);
+  return () => unsubscribe();
+}, []);
+```
+
+**Empty deps for mount-only effects:**
+```typescript
+useEffect(() => {
+  // Runs once on mount
+  store().instance.get('config').then(setConfig);
+}, []); // Empty deps array
+```
+
+## Code Style
+
+**Naming:**
+- Components: PascalCase (`WeatherCard.tsx`)
+- Functions: camelCase (`fetchWeatherData`)
+- Constants: UPPER_SNAKE_CASE (`API_BASE_URL`)
+- Interfaces: PascalCase (`WeatherData`, `AppConfig`)
+
+**Imports order:**
+```typescript
+// 1. SDK imports
+import { configure, store, proxy } from '@telemetryos/sdk';
+
+// 2. React imports
+import { useEffect, useState } from 'react';
+
+// 3. Local imports
+import WeatherCard from '@/components/WeatherCard';
+import type { WeatherData } from '@/types';
+```
+
+**TypeScript:**
+- Use strict mode
+- Define interfaces for all configs and data
+- Use generics with storage: `get<Type>(key)`
+- Prefer `interface` over `type` for objects
+
+**React:**
+- Functional components only
+- Use hooks (useState, useEffect, useMemo, useCallback)
+- Implement loading, error, empty states
+- Clean up subscriptions in useEffect return
+
+## Development Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Start local dev server
+tos serve
+# Or: npm run dev
+
+# Build for production
+npm run build
+
+# Type check
+tsc --noEmit
+```
+
+**Local testing:**
+- Settings: http://localhost:3000/settings
+- Render: http://localhost:3000/render
+
+**Deployment:**
+```bash
+git add .
+git commit -m "Description"
+git push origin main
+# GitHub integration auto-deploys
+```
+
+## Common Errors
+
+**"SDK not configured"**
+→ Call `configure('app-name')` in main.tsx before React renders
+
+**"device storage not available"**
+→ Using `store().device` in Settings - use `store().instance` instead
+
+**CORS error**
+→ Using direct `fetch()` - use `proxy().fetch()` instead
+
+**"Request timeout"**
+→ SDK operation exceeded 30 seconds - handle with try/catch
+
+**Render not updating**
+→ Missing subscription - use `store().instance.subscribe()` in Render
+
+**Memory leak**
+→ Not returning unsubscribe from useEffect
+
+## Project-Specific Context
+
+[Add your project details here:]
+
+**Application Name:** [Your app name]
+**External APIs:**
+- [API name]: [endpoint]
+  - Authentication: [method]
+  - Rate limits: [limits]
+
+**Custom Components:**
+- [ComponentName]: [purpose]
+  - Location: [path]
+  - Props: [interface]
+
+**Business Logic:**
+- [Key algorithms or calculations]
+- [Data transformation rules]
+
+## Technical References
+
+**SDK API Documentation:**
+- [Storage API](https://docs.telemetryos.com/docs/storage-methods) - Complete storage scope reference
+- [Platform API](https://docs.telemetryos.com/docs/platform-methods) - Proxy, media, accounts, users, devices
+- [Playlist API](https://docs.telemetryos.com/docs/playlist-methods) - Page navigation methods
+- [Overrides API](https://docs.telemetryos.com/docs/overrides-methods) - Dynamic content control
+- [Client API](https://docs.telemetryos.com/docs/client-methods) - Device client interactions
+- [Media API](https://docs.telemetryos.com/docs/media-methods) - Media content queries
+
+**Critical Context:**
+- [CORS Guide](https://docs.telemetryos.com/docs/cors) - Why proxy().fetch() is required
+- [Mount Points](https://docs.telemetryos.com/docs/mount-points) - /render vs /settings execution
+- [Languages Supported](https://docs.telemetryos.com/docs/languages-supported) - Runtime environment constraints
+- [Configuration](https://docs.telemetryos.com/docs/configuration) - telemetry.config.json schema
+- [Workers](https://docs.telemetryos.com/docs/workers) - Background JavaScript patterns
+- [Containers](https://docs.telemetryos.com/docs/containers) - Docker integration patterns
+
+**Code Examples:**
+- [Code Examples](https://docs.telemetryos.com/docs/code-examples) - Real-world implementations
+- [LLMS.txt](https://docs.telemetryos.com/llms.txt) - Complete documentation index