@telemetryos/cli 1.9.0 → 1.11.0

package/templates/vite-react-typescript/_claude/skills/tos-requirements/SKILL.md

@@ -1,77 +1,251 @@
 ---
 name: tos-requirements
-description: Gather requirements for a new TelemetryOS app. Use at the START of any new app project to understand the developer's vision, render layout design, configuration fields, data sources, and implementation plan before writing code.
+description: Gather requirements for a new TelemetryOS app. Use at the START of any new app project to understand interaction model (display-only vs interactive), render layout, data sources, and implementation plan before writing code.
 ---
 
 # TelemetryOS App Requirements Gathering
 
-Use this skill at the START of any new TelemetryOS application project. Gather complete requirements before writing any code to ensure a successful "one-shot" implementation.
+Use this skill at the START of any new TelemetryOS application project. Gather complete requirements before writing any code to ensure a successful implementation.
 
 ## Requirements Interview
 
 **IMPORTANT: This is a conversation, not a survey.** Ask questions one phase at a time. Wait for answers before proceeding. Use earlier answers to skip irrelevant questions.
 
-### Phase 1: Start with Vision
+**All TelemetryOS apps use `@telemetryos/sdk`** with `render` and `settings` mount points. The key distinction is whether the render view is display-only or includes interactive elements.
+
+---
+
+## Phase 1: Start with Vision & Interaction Model
+
+### Starting Question
 
 Ask ONE question to start:
 
-> "What app do you want to build? Give me a quick description."
+> "What app do you want to build? Give me a quick description of what it should do and what users will see."
 
-That's it. Wait for their answer. Their response will tell you:
-- What data sources they need (weather? media? external API?)
+Wait for their answer. Their response will tell you:
+- Is this display-only or interactive?
 - What the layout probably looks like
+- What data sources they need
 - What settings make sense
 
-### Phase 2: Clarify Based on Their Answer
+### Listen For: Interaction Model
 
-Based on what they described, ask only the relevant follow-ups:
+**Digital Signage Indicators** (display-only):
+- "display", "show", "dashboard", "information board"
+- "menu board", "announcements", "slideshow"
+- Content that updates automatically
+- No mention of user interaction
+- **Implementation:** Render view with NO onClick handlers
 
-**If they mentioned specific data** (weather, stocks, social media, etc.):
-- "Do you have an API in mind, or should I suggest one?"
-- "How often should it refresh?"
+**Interactive Kiosk Indicators** (touch-enabled):
+- "touch screen", "interactive", "kiosk"
+- "users can click", "navigation", "buttons", "search"
+- "check-in", "directory", "wayfinding"
+- ANY mention of user input/interaction
+- **Implementation:** Render view WITH onClick handlers
 
-**If they mentioned media/images/video**:
-- "Will these come from the TelemetryOS media library, or external URLs?"
+**Multi-Mode Indicators** (same app, different views per device):
+- "one screen shows X while another shows Y"
+- "kiosk and display" or "control panel and viewer"
+- "different devices need different views of the same data"
+- data organized by location, department, topic, or similar grouping
 
-**If the layout isn't clear**:
-- "Quick layout check: fullscreen content, or split/grid layout?"
+### Confirm Interaction Model
 
-**If they gave a detailed description**: Skip to Phase 3 - you probably have enough.
+Before proceeding to Phase 2, explicitly state your understanding:
 
-### Phase 3: Fill Gaps
+**For Digital Signage:**
+> "Got it - we're building a digital signage display. Content is display-only - viewers watch it without interacting. We'll use @telemetryos/sdk with automatic updates driven by store subscriptions. Does that match what you have in mind?"
 
-Only ask about things that aren't obvious from their description:
+**For Interactive Kiosk:**
+> "Got it - we're building an interactive kiosk. Users will be able to touch/click elements on the screen. We'll use @telemetryos/sdk with onClick handlers in the render view. Does that match what you have in mind?"
 
-- Settings they'd want to configure (if not clear)
-- Any specific constraints (refresh rates, data limits)
-- Edge cases that matter for their use case
+**For Multi-Mode App:**
+> "Got it — this is a multi-mode app. Different devices will show different views: [Mode A description] and [Mode B description]. They'll share data scoped to a [entity]. Let me gather requirements for each mode."
 
-**Don't ask about:**
-- Categories that don't apply to their app
-- Settings with obvious defaults
-- Technical details you can infer
+Wait for confirmation before proceeding.
 
-### Reference: Layout Types
+---
 
-If you need to clarify layout:
-- **Single panel** - fullscreen content
-- **Split layout** - sidebar + main area
-- **Grid** - multiple items in rows/columns
-- **Fullscreen media** - image/video player
+## Phase 2: Render View First (What Users See)
+
+**Goal:** Understand the visual experience and interactions BEFORE diving into data sources.
+
+### Visual Experience Questions
+
+Ask conversationally, one at a time, based on what you already know:
+
+#### For ALL Apps:
+
+**Screen Layout:**
+- "What does the screen look like? Walk me through what someone sees."
+- Listen for: single panel, split layout, grid, fullscreen media
+
+**Content Elements:**
+- "What specific content appears on screen?"
+- Listen for: text, images, video, data displays, lists, charts
+
+**Visual Priority:**
+- "What's the most important thing viewers should see?"
+- Helps determine layout hierarchy
+
+#### For Interactive Apps ONLY:
+
+**Interaction Flow:**
+- "When someone touches the screen, what happens? Walk me through the interaction."
+- Listen for: button clicks, navigation flow, form inputs, search
+
+**User Journey:**
+- "What's a typical user flow? For example: User arrives → touches X → sees Y → does Z"
+
+**Idle State:**
+- "What happens when no one is interacting? Does it return to a home screen?"
+
+#### For Display-Only Apps ONLY:
+
+**Content Updates:**
+- "How often should the content update?"
+- Listen for: real-time, every X seconds/minutes, on schedule
+
+**Rotation/Playlist:**
+- "Does content rotate between different views, or stay on one view?"
+
+### Capture User Stories
+
+Based on their answers, document user stories:
+
+**For Display-Only Apps:**
+```
+User Story: Render View
+- As a viewer, I see [describe layout]
+- The screen displays [list content elements]
+- Content updates [frequency/trigger]
+- [Most important element] is prominently displayed
+```
+
+**For Interactive Apps:**
+```
+User Story: Render View
+- As a user approaching the kiosk, I see [idle/home screen]
+- When I touch [element], [what happens]
+- I can [describe interactions: navigate, search, input]
+- After [time], the screen returns to [idle state]
+- onClick handlers needed for: [list interactive elements]
+```
+
+### DO NOT Ask About Data Sources Yet
+
+At this phase:
+- ✅ DO focus on what's visible and interactions
+- ✅ DO ask about layout, content elements, visual hierarchy
+- ✅ DO understand user flows for interactive apps
+- ❌ DON'T ask "where does data come from?"
+- ❌ DON'T dive into APIs or data sources
+- ❌ DON'T ask about settings yet
+
+---
+
+## Phase 3: Data Source Discovery
+
+**Now** that you understand what users SEE, map content elements to data sources.
+
+### Data Mapping Questions
+
+For each content element identified in Phase 2:
+
+**Source Identification:**
+- "For [content element], where should that data come from?"
+- Listen for: TOS APIs, external APIs, user uploads, static content
+
+**External APIs** (if mentioned):
+- "Do you have a specific API in mind for [data source], or should I suggest one?"
+- "Will we need an API key for that?"
+
+**Media Content** (if images/video mentioned):
+- "Will media come from the TelemetryOS media library, or external URLs?"
+
+**Real-time vs Static:**
+- For dynamic content: "How often should [data] refresh?"
+- For static content: "Will admins update this in Settings, or is it hardcoded?"
+
+### Inference with Transparency
+
+**Show your thinking** when making important assumptions:
+
+✅ **Good examples:**
+- "I'm assuming the weather data comes from the TOS weather API since you mentioned current conditions and forecast - is that right?"
+- "Since you mentioned 'logo', I'm assuming that's uploaded to the TOS media library - correct?"
+- "You mentioned refreshing every 30 seconds - I'll use a timer-based refresh pattern for that."
+
+❌ **Don't assume without asking:**
+- Which external API to use
+- Authentication methods
+- Data formats or structures
+
+### Reference: Data Sources
+
+**TelemetryOS Platform APIs:**
+- `media()` - User-uploaded images/videos from media library
+- `weather()` - Weather data (current, hourly, daily forecasts)
+- `applications()` - Embedding other TOS apps
+- `store()` - Persistent configuration and state
+
+**External APIs:**
+- Use `proxy().fetch()` for external APIs (handles CORS)
+- Note: authentication method (API key, OAuth, none)
+- Note: rate limits if known
+
+**Refresh patterns:**
+- Timer-based (every N seconds/minutes)
+- Event-based (on user action, for interactive apps)
+- Most apps use 30-60 second refresh for live data
+
+---
 
-### Reference: Store Keys
+## Phase 4: Settings & Configuration
 
-Settings allow admins to configure the app. Use these categories to identify what settings make sense for their app (don't ask about every category).
+**Goal:** Identify what admins should be able to configure.
 
-#### Categories (consult as needed)
+### Configuration Questions
+
+**Admin Controls:**
+- "What should admins be able to configure in the Settings panel?"
+- Prompt with relevant categories if needed (see Reference below)
+
+**Sensible Defaults:**
+- "What are good default values? The app should work with minimal config."
+
+**Required vs Optional:**
+- "Which settings are required for the app to function?"
+
+**Validation:**
+- "Are there any constraints? For example, minimum/maximum values, specific formats?"
+
+### UI Scale Setting
+
+**For Digital Signage (Display-Only) Apps:**
+- **ALWAYS include UI Scale setting** (instance scope)
+- Default: 1, Range: 1-3 (step 0.01)
+- UI Component: Slider
+- Allows admins to adjust content size for different viewing distances and screen sizes
+
+**For Interactive Kiosk Apps:**
+- **DO NOT include UI Scale setting**
+- Kiosks have fixed interaction distance (user is right in front of screen)
+- Content sizing is optimized for touch interaction, not adjustable
+
+### Reference: Settings Categories
+
+Consult as needed - don't ask about every category:
 
 **Display Settings** - Visual appearance and layout
+- **UI Scale** (digital signage only - ALWAYS include)
 - Colors, fonts, background styles
 - Layout options (columns, alignment, spacing)
 - Show/hide toggles for UI elements
-- Animation preferences
 
-> Digital signage typically uses dark backgrounds (better contrast on TVs, reduces glare). Don't ask about light/dark "mode" unless the developer brings it up.
+> Digital signage typically uses dark backgrounds (better contrast on TVs). Don't ask about light/dark "mode" unless the developer brings it up.
 
 **Data Configuration** - How the app fetches and processes data
 - API keys and credentials
@@ -91,15 +265,14 @@ Settings allow admins to configure the app. Use these categories to identify wha
 - Date/time formats
 - Language/locale
 
-#### Store Scope Rules
+### Store Scope Rules
 
-**Default to `instance`** - most settings are instance-scoped. Only use other scopes when the setting clearly fits the patterns below.
+**Default to `instance`** - most settings are instance-scoped.
 
-**Use `application` scope for:**
+**Use `application` scope ONLY for:**
 - API keys and credentials (shared cost, single billing)
 - Account-wide branding (company logo URL, brand colors)
 - License keys or subscription identifiers
-- Shared service endpoints configured once per account
 
 **Use `instance` scope for everything else:**
 - Content selection (what to display)
@@ -107,15 +280,19 @@ Settings allow admins to configure the app. Use these categories to identify wha
 - Refresh intervals and timing
 - Localization (timezone, units, language)
 - Visual preferences (colors, fonts, backgrounds)
-- Filters, sort order, display limits
 
-**Quick Reference:**
-| Scope | Synced? | Shared Across | Common Use |
-|-------|---------|---------------|------------|
-| `instance` | Yes | Same instance on all devices | Per-widget config |
-| `application` | Yes | All instances in account | API keys, credentials |
+**Use `device` scope (Render only) for:**
+- Device-specific calibration settings
+- Local cache data
+- Interaction state that should persist on device
 
-#### Capture Each Store Key
+**Use `shared(namespace)` scope for:**
+- Inter-app communication
+- Broadcasting data between apps
+
+Scope is typically inferred - don't ask unless unclear.
+
+### Capture Store Keys
 
 For each setting identified, record:
 
@@ -126,127 +303,230 @@ For each setting identified, record:
 | units | Localization | instance | 'imperial' \| 'metric' | 'imperial' | enum | Yes |
 | refreshInterval | Data Config | instance | number | 30 | 10-300 | No |
 
-#### Questions to Ask (spread across conversation)
+---
 
-After understanding the core app, circle back to fill in settings details:
-- **What should admins be able to configure?** (prompt with relevant categories)
-- **What are sensible defaults?** (app should work with minimal config)
-- **Are there validation rules or constraints?** (min/max, patterns, enums)
-- **Which settings are required vs optional?**
+## Phase 5: Multi-Mode Design (If Applicable)
 
-Ask these as follow-ups in later turns, not all upfront. Scope is typically inferred from the rules above—only ask about scope if a setting doesn't clearly fit.
+**Only if Phase 1 identified a multi-mode app.**
 
-### Reference: Data Sources
+### Step 1: Identify the Modes
 
-Consult this when you need to understand their data needs (don't ask about all of these):
+Confirm the distinct Render views:
 
-**TelemetryOS Platform APIs:**
-- `media()` - User-uploaded images/videos from media library
-- `weather()` - Weather data (current, hourly, daily forecasts)
-- `applications()` - Embedding other TOS apps
+- "Let's name the modes. You mentioned [X] and [Y] — should we call them '[mode-a]' and '[mode-b]'?"
+- Each mode becomes a value in the mode union type (e.g., `'kiosk' | 'display'`)
+- Ask what each mode shows and whether it reads or writes shared data
 
-**External APIs:**
-- Use `proxy().fetch()` for external APIs (handles CORS)
-- Note: authentication method (API key, OAuth, none)
-- Note: rate limits if known
+### Step 2: Discover the Top-Level Entity
 
-**Refresh patterns:**
-- Timer-based (every N seconds/minutes)
-- Event-based (on user action)
-- Most apps use 30-60 second refresh for live data
+**The developer will almost never volunteer this on their own.** You MUST actively discover or propose the organizing entity that scopes all shared data.
 
-### Implementation Checklist
+Ask: "What organizes the data these modes share? For example, is this per-location, per-department, per-topic, per-event?"
 
-After gathering requirements, generate:
+If the developer doesn't have a clear answer, **propose one** based on the app domain:
 
-#### Store Hooks (hooks/store.ts)
+| App Domain | Likely Entity |
+|------------|---------------|
+| Queue / service | location, branch |
+| Content / editorial | topic, channel |
+| Event / scheduling | event, venue |
+| Organizational | department, team |
+| Retail / menu | store, menu |
 
-```typescript
-// Instance-scoped keys (most common - per-widget config)
-export const use[Key]State = createUseInstanceStoreState<Type>('key', default)
-// Usage: const [loading, value, setValue] = use[Key]State()
+Explain WHY: "This lets you run the same app at multiple [locations] — each with its own independent data — without creating separate app instances. An admin just selects which [location] each device belongs to."
 
-// Application-scoped keys (shared across all instances)
-export const use[Key]State = createUseApplicationStoreState<Type>('key', default)
-// Usage: const [loading, value, setValue] = use[Key]State()
+Confirm the entity name before proceeding.
 
-// Device-scoped keys (stays on device, Render only)
-export const use[Key]State = createUseDeviceStoreState<Type>('key', default)
-// Usage: const [loading, value, setValue] = use[Key]State()
-```
+### Step 3: Map Shared Data
 
-#### Settings UI Components
+For each content element from Phase 2, determine if it's:
+- **Per-device** (instance scope) — mode selection, entity selection, UI scale
+- **Account-wide** (application scope) — entity list, API keys
+- **Per-entity** (dynamic namespace scope) — the actual shared data between modes
 
-List each Settings control needed:
-- [ ] Text input for X
-- [ ] Dropdown for Y
-- [ ] Slider for Z
-- [ ] Toggle for W
+### Step 4: Mode-Specific Settings
 
-#### Render View Structure
+Ask: "Are there any settings that only apply to one mode? For example, audio chime only on the display, or touch feedback only on the kiosk?"
 
-Describe the component hierarchy:
-```
-Render
-├── Header (title, logo)
-├── MainContent
-│   └── DataDisplay
-└── Footer (timestamp, refresh indicator)
+### Reference: Multi-Mode Store Pattern
+
+```typescript
+// Instance scope — per device
+const useModeStoreState = createUseInstanceStoreState<'kiosk' | 'display'>('mode', 'kiosk')
+const useSelectedLocationStoreState = createUseInstanceStoreState<string>('selected-location', 'Location A')
+
+// Application scope — entity management
+const useLocationsStoreState = createUseApplicationStoreState<string[]>('locations', ['Location A'])
+
+// Dynamic namespace scope — shared between modes, scoped to entity
+const useQueuesStoreState = createUseDynamicNamespaceStoreState<Queue[]>('queues', [])
 ```
 
-#### SDK APIs Required
+See `tos-multi-mode` skill for the complete implementation pattern.
 
-- [ ] createUseInstanceStoreState - Settings ↔ Render sync
-- [ ] proxy().fetch() - External API calls
-- [ ] weather() - Weather data
-- [ ] media() - Media library
+---
 
-## Output Format
+## Phase 6: Summary & Validation
 
-After gathering requirements, provide a structured summary:
+After gathering all requirements, provide a structured summary:
 
 ```markdown
 # [App Name] Requirements
 
+## Interaction Model
+**[Display-Only | Interactive | Multi-Mode]**
+- SDK: `@telemetryos/sdk`
+- Mount Points: `render` (display), `settings` (config UI)
+- Interaction: [Display-only with subscriptions | Interactive with onClick handlers | Multi-mode with entity-scoped data]
+
 ## Vision
 [One sentence description]
 
-## Render View
-- Layout: [single/split/grid/fullscreen]
-- Content: [description]
-- Refresh: [interval or trigger]
+## Render View User Stories
 
-## Store Keys
-| Key | Category | Scope | Type | Default | UI Component |
-|-----|----------|-------|------|---------|--------------|
-| ... | ... | instance/application/device | ... | ... | ... |
+### Display-Only Apps:
+**As a viewer, I see:**
+- [Layout description]
+- [Content elements list]
+- [Visual hierarchy]
 
-## Data Sources
-- Internal: [list]
-- External: [list with endpoints]
+**Content updates:**
+- [Frequency/trigger]
+
+### Interactive Apps:
+**As a user approaching the kiosk:**
+- I see [idle state]
+- When I touch [element], [interaction flow]
+- I can [list interactions]
+- After [timeout], screen returns to [idle state]
+
+**onClick handlers needed:**
+- [List interactive elements]
+
+## Content → Data Source Mapping
+
+| Content Element | Data Source | API/Method | Refresh |
+|-----------------|-------------|------------|---------|
+| Current weather | TOS Weather API | weather().getConditions() | 60s |
+| Company logo | Media Library | media().getById() | Static |
+| Stock prices | External API | proxy().fetch('...') | 30s |
+
+## Multi-Mode Design (if applicable)
+
+**Modes:** [mode-a] (description), [mode-b] (description)
+**Top-Level Entity:** [entity name] (e.g., location, topic)
+**Entity-Scoped Data:** [list shared data keys that use dynamic namespace]
+**Mode-Specific Settings:** [list any settings that only apply to one mode]
+
+## Store Keys (Settings Configuration)
+
+| Key | Category | Scope | Type | Default | UI Component | Required? |
+|-----|----------|-------|------|---------|--------------|-----------|
+| uiScale | Display Settings | instance | number | 1 | Slider (1-3) | No (digital signage only) |
+| city | Localization | instance | string | '' | Text input | Yes |
+| apiKey | Data Config | application | string | '' | Password input | Yes |
+| units | Localization | instance | 'imperial' \| 'metric' | 'imperial' | Dropdown | Yes |
+| refreshInterval | Data Config | instance | number | 30 | Slider (10-300) | No |
+
+**Note:** UI Scale setting is ALWAYS included for digital signage apps, but NOT for interactive kiosk apps.
 
 ## Implementation Plan
-1. Create store hooks
-2. Build Settings UI
-3. Build Render view
-4. Add data fetching
-5. Test and polish
+
+1. **Store Hooks** (hooks/store.ts)
+   - Create instance-scoped hooks for [list keys]
+   - Create application-scoped hooks for [list keys]
+   - [If multi-mode] Create dynamic namespace hooks for entity-scoped data
+   - [If multi-mode] Create namespace helper function
+
+2. **Settings UI** (views/Settings.tsx)
+   - [For Digital Signage] UI Scale slider (instance scope, 1-3 range, 0.01 step)
+   - [List each setting with component type]
+   - Validation for required fields
+
+3. **Render View** (views/Render.tsx)
+   - [For Digital Signage] Use UI scale hooks (useUiScaleToSetRem with uiScale from store)
+   - [For Interactive Kiosk] Use UI scale hooks (useUiScaleToSetRem with fixed scale, typically 1)
+   - Layout structure: [describe layout]
+   - [For Interactive] Add onClick handlers for [list elements]
+   - [For Interactive] Add idle timeout logic
+
+4. **Data Fetching**
+   - [List each data source with method]
+   - Error handling
+   - Refresh logic
+
+5. **Polish**
+   - Responsive scaling (rem units)
+   - Loading states
+   - [For Interactive] Touch feedback animations
 ```
 
+### Validation Question
+
+After presenting the summary, ask:
+
+> "Does this capture everything correctly? Anything I missed or got wrong?"
+
+Wait for confirmation before proceeding to implementation.
+
+---
+
+## Reference: Layout Types
+
+If you need to clarify layout:
+- **Single panel** - fullscreen content
+- **Split layout** - sidebar + main area
+- **Grid** - multiple items in rows/columns
+- **Fullscreen media** - image/video player
+
+---
+
 ## Tips for Success
 
-1. **Don't skip requirements** - Incomplete requirements lead to rework
-2. **Validate early** - Confirm understanding before coding
-3. **Start simple** - MVP first, then add features
-4. **Use SDK hooks** - `createUseInstanceStoreState` for all store keys
-5. **Follow patterns** - Match existing Settings UI components exactly
+### For the Agent
+
+1. **One phase at a time** - Don't jump ahead to data sources before understanding render view
+2. **Show your thinking** - When inferring, explain your reasoning transparently
+3. **Validate assumptions** - Confirm important decisions before moving on
+4. **Be conversational** - This is a dialogue, not a form to fill out
+5. **Skip irrelevant questions** - If they already told you something, don't ask again
+6. **Recognize multi-mode patterns** — Watch for indicators of different views per device
+7. **Discover the top-level entity** — For multi-mode apps, the developer won't volunteer this. You must ask or propose one
+
+### Common Patterns to Recognize
+
+- **Weather Display** → Display-only, TOS weather API, location settings
+- **Menu Board** → Display-only, media library, scheduled updates
+- **Wayfinding Kiosk** → Interactive, touch navigation, search functionality
+- **Data Dashboard** → Display-only, external API, refresh interval
+- **Queue Manager** → Multi-mode (kiosk + display), entity: location, shared queue data
+
+### What to Infer vs What to Ask
+
+**Infer (with transparency):**
+- TOS weather API for weather data
+- Media library for logos/images
+- Timer-based refresh for live data
+- Instance scope for most settings
+
+**Ask (don't assume):**
+- Which external API to use
+- API authentication methods
+- Specific refresh intervals
+- Edge cases or constraints
+
+---
 
 ## Next Steps
 
 After gathering requirements, use these skills to implement:
 
+- **`tos-multi-mode`** - Multi-mode architecture patterns (if building multi-mode app — read first)
 - **`tos-store-sync`** - Create store hooks from the Store Keys table
 - **`tos-settings-ui`** - Build the Settings UI components
-- **`tos-proxy-fetch`** - Implement external API calls
+- **`tos-render-ui-design`** - Design the Render view layout (foundation - always read first)
+- **`tos-render-signage-design`** - Display-only render patterns (if building digital signage)
+- **`tos-render-kiosk-design`** - Interactive render patterns (if building kiosk)
+- **`tos-proxy-fetch`** - Implement external API calls (if needed)
 - **`tos-weather-api`** - Integrate weather data (if needed)
 - **`tos-media-api`** - Access media library (if needed)