> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/architecture.md). # Architecture ## System Overview AI OS runs on an imported Claude OS application foundation. It is a single-package React/TanStack/Vite app with a local JSON data flow, a Cloudflare Worker style server entry, Bun scripts for setup and aggregation, optional Codex app-server readiness metadata, and a compile-time extension platform. The host dashboard uses AI OS product language while preserving inherited local-operator areas such as skills, memory, activity, workspaces, setup, share, settings, and agent pages. Trend Finder product language belongs to the Trend Finder extension. Internal `claude-os` and `findtrend` identifiers remain only where they are compatibility contracts rather than user-facing product copy. AI OS now also includes a typed scheduler foundation for local jobs. The scheduler registry, local scheduler config contract, runner, handler registry, status projection, and scoped generated-data writer live alongside the app code and expose browser-safe command summaries for `aggregate`, `agent-aggregate`, `trend-finder`, and `dream`. ## Local Access Contract Local AI OS operator goals default to full local access, write access, and edit access. Local product surfaces should move toward write-ready behavior by default while preserving loopback, Host-header, same-run token, schema, confirmation, timeout, safe-error, and redaction safeguards. Read or metadata-only behavior is an explicit exception, not the baseline. The valid exceptions are public demo safety, third-party source-compliance limits, secret/privacy boundaries, missing credentials, offline dependencies, or a temporary implementation gap recorded with a recovery path. A feature is not shipped until it proves real execution, visible results, recovery states, and focused tests. ## Dependency Graph ``` Browser | v TanStack Router routes in src/routes/ | v Shared React components in src/components/ | v useLiveData() in src/lib/use-live-data.ts | v Vite local middleware in vite.config.ts | v src/data/live-data.json or src/data/live-data.example.json Optional local refresh: Browser -> /__refresh_data -> bun run scripts/aggregate.ts -> src/data/live-data.json | v logs/aggregate.latest.jsonl Scoped Trend Finder refresh: Browser -> /__run_trend_finder -> bun run scripts/scheduler-runner.ts --job trend-finder | v src/data/live-data.json (extensions.items.trend-finder) Command scheduler: bun run scheduler:* -> scripts/scheduler-runner.ts -> scheduler handler | v scoped generated-data writer or private Dream output ``` ## Components ### Application Shell * Purpose: Provides the layout, sidebar, route outlet, metadata, error page, and React Query provider. * Tech: React, TanStack Router, React Query. * Location: `src/routes/__root.tsx`, `src/router.tsx`, `src/start.ts`, `src/server.ts`. ### Dashboard Routes * Purpose: Render the local operator dashboard plus extension host routes. * Tech: TanStack Router file routes. * Location: `src/routes/`. Current routes include home, skills, memory, activity, workspaces, setup, share, settings, three agent pages (`/agents/hermes`, `/agents/openclaw`, `/agents/claude-code`), `/extensions`, Trend Finder extension views hosted at `/extensions/trend-finder/`, the Trend Finder Engine Replay utility route at `/extensions/trend-finder/engine`, and AI Rogue extension views hosted at `/extensions/ai-rogue/`. ### UI Component Library * Purpose: Reusable components and local wrappers over Radix UI primitives. * Tech: React, Radix UI, Tailwind CSS, lucide-react icons. * Location: `src/components/` and `src/components/ui/`. ### Runtime Data Loader * Purpose: Fetches the latest local JSON data from the dev server without baking it into the bundle. * Tech: React Query and Vite middleware. * Location: `src/lib/use-live-data.ts`, `vite.config.ts`. ### Public Demo Snapshot Boundary * Purpose: Serves the Cloudflare Pages public demo from committed, browser-safe fixture files instead of local runtime middleware. The current Phase 33 fixture is a frozen projection of reviewed local Trend Finder and Dream Review output. * Tech: Vite demo-pages mode, TanStack static output, Bun snapshot/build/scan scripts, and Cloudflare Pages static hosting. * Fixture location: `demo-website/public/demo/`. * Generated output: `demo-website/dist/` (ignored). * Scripts: `bun run demo:snapshot`, `bun run demo:build:pages`, `bun run demo:scan:pages`, `bun run demo:budget:pages`, `bun run demo:preview:pages`, and `bun run demo:deploy:pages`. * Scope: Static-only public demo. It does not call local bridge endpoints, hosted collectors, scheduler jobs, account-auth flows, uploads, admin mutations, Pages Functions, `_worker.js`, analytics, or server storage. * Current fixture metadata: source commit `7681a517980f`, captured at `2026-06-25T05:03:40.752Z`, 24 covered routes, scan status `pass`, and 0 scan issues. ### Aggregator Script * Purpose: Imported Claude OS scanner that reads local Claude/Codex/memory/integration signals and emits dashboard data. * Tech: Bun, Node APIs, optional external APIs when keys are present. * Location: `scripts/aggregate.ts` (orchestrator), `scripts/lib/` (extracted sub-modules). * Diagnostics: Each run writes a private JSONL trace to `logs/aggregate-*.jsonl` and refreshes `logs/aggregate.latest.jsonl` with console output, collector lifecycle, runtime readiness, source counts, sanitized AI-analysis request/response metadata, validation issues, fallback reasons, and provider error causes. The aggregator was decomposed in Phase 01 into focused modules: | Module Area | Location | Purpose | | -------------- | ----------------------------------------------------------------------- | -------------------------------------------- | | Scan modules | `scripts/lib/` (`*-scanner.ts`, `scan-helpers.ts`) | Source-specific signal reading | | Output modules | `scripts/lib/` (`output-assembly.ts`, `sanitize.ts`, `memory-graph.ts`) | Data assembly, anonymization, graph building | | Environment | `scripts/lib/load-env.ts` | Centralized env parsing for all scripts | | Tool detection | `scripts/lib/tool-detection.ts` | Detect installed tools for setup | ### Setup Script * Purpose: Runs the imported local setup flow, installs the Dream skill, wires git hooks, and runs aggregation. * Tech: Bun and shell commands. * Location: `scripts/setup.ts`. ### Scheduler Foundation * Purpose: Provides the typed AI OS scheduler registry, job-id validation, handler dispatch, per-job locks, run state/logs, browser-safe status summaries, local scheduler config parsing, and scoped generated-data write contracts. * Tech: TypeScript modules and static registry helpers. * Primary locations: `scripts/lib/scheduler/types.ts`, `scripts/lib/scheduler/job-id.ts`, `scripts/lib/scheduler/registry.ts`, `scripts/lib/scheduler/config.ts`, `scripts/lib/scheduler/handlers.ts`, `scripts/scheduler-runner.ts`, `scripts/scheduler-status.ts`, `scripts/lib/scheduler/operator-status.ts`, `scripts/lib/aggregate-live-data-write.ts`, and `scripts/lib/aggregate-orchestration.ts`. * Scope: Command-first local scheduler behavior only. It does not expose raw commands, auth data, transcripts, prompts, source dumps, private logs, or private paths to browser data or status output. Current scheduler jobs: | Job | Package command | Owned output | Default stance | | ----------------- | ------------------------------------ | ---------------------------------------------------- | ------------------------------- | | `aggregate` | `bun run scheduler:run` | Full `src/data/live-data.json` compatibility writer | Manual compatibility job | | `agent-aggregate` | `bun run scheduler:agents:run` | Host/local live-data branches except `extensions` | Enabled metadata, every 4 hours | | `trend-finder` | `bun run scheduler:trend-finder:run` | `extensions.items.trend-finder` only | Enabled metadata, daily 06:00 | | `dream` | `bun run scheduler:dream:run` | Private Dream output after material freshness checks | Enabled metadata, daily 07:00 | The registry is the reviewed job, cadence, timeout, network-policy, and write target contract. Internal handlers are registered in `scripts/lib/scheduler/handlers.ts`; missing or unavailable handlers fail at the scheduler boundary before private writes occur. The generated-data writer owns three write scopes: | Scope | Writes | Preserves | | ---------------- | ---------------------------------------------- | ---------------------------------------------------- | | `full` | Complete validated `LiveData` object | Nothing; this is the compatibility writer | | `host-local` | Root browser-safe branches except `extensions` | Existing extension runtime data | | `extension-item` | `extensions.items[extensionId]` | Host/local branches and other extension runtime data | Per-job scheduler locks prevent overlapping runs of the same job. The shared generated-data lock serializes writes to `src/data/live-data.json` across different jobs. ### Brand and Storage Migration * Purpose: Centralized brand constants (app name, copy, storage prefix) and a localStorage/sessionStorage migration layer that reads old `claude-os`/`findtrend` keys and writes new `ai-os` keys transparently. * Tech: TypeScript modules. * Location: `src/lib/brand.ts`, `src/lib/storage-migration.ts`. ### Async Refresh * Purpose: Non-blocking local process model for the `/__refresh_data` endpoint. Replaces the former synchronous shell execution with spawn-based execution, timeout, and SIGKILL fallback. * Tech: Bun spawn, AbortController. * Location: `src/lib/async-refresh.ts`. ### Hermes Dev Bridge * Purpose: GET Vite middleware bridge for fresh local Hermes summaries during development. It serves status, models, public connections, Pantheon templates, missions, documents, document file/trash views, and token-gated profiles, skills, sessions, memory, and Pantheon persona summaries. Hermes mutations live in the local write bridge below. * Tech: Vite middleware plus Node filesystem reads with bounded traversal and sanitized JSON responses. * Location: `scripts/lib/hermes-dev-bridge.ts`, registered from `vite.config.ts`. * Access: Loopback-only for every route; profiles, skills, sessions, memory, and Pantheon reads also require `X-Claude-OS-Token`. * Scope: Local operator telemetry only. It does not feed Trend Finder trend evidence, scores, creator angles, reports, watchlists, or extension payloads. ### Hermes Admin Bridge * Purpose: Vite middleware bridge for local Hermes writes during development. It covers chat, image upload, mission create/optimize/tick/clear, persona validation/install/create/update/delete, Pantheon mirror sync, document delete/restore/purge, and Obsidian memory linking. The current Phase 40 implementation still checks `HERMES_DASHBOARD_ADMIN=1`; the product access contract treats that as a migration constraint, not the future default. * Tech: Vite middleware plus Node filesystem, child process, git, and SSE handling with bounded request bodies and sanitized command output. * Location: `scripts/lib/hermes-admin-bridge.ts`, registered from `vite.config.ts`. * Access: Loopback-only, per-run `X-Claude-OS-Token`, current `HERMES_DASHBOARD_ADMIN=1` implementation gate, and non-production `NODE_ENV`. * Scope: Local operator actions only. `HERMES_HOME`, `HERMES_BIN`, `HERMES_DOCUMENTS_DIR`, `HERMES_MIRROR`, `HERMES_OBSIDIAN_VAULTS`, `HERMES_OBSIDIAN_VAULT`, and `GIT_BIN` are read server-side from `.env.local`, `.env`, or the shell. Pantheon sync is confined to an allowed git mirror root and copies only persona YAML into `pantheon/personas/`. ### OpenClaw Scanner And Dev Bridge * Purpose: Scanner and Vite middleware bridge for local OpenClaw host-cockpit summaries. It serves status, dashboard, session, sub-agent, task, skill, and plugin metadata without reading transcript bodies, raw prompts, command output, credentials, logs, repo diffs, or workspace files. * Tech: Node filesystem reads, JSON5 config parsing, bounded SQLite task summaries through Bun-side script code, Vite middleware, React Query browser hooks, and typed parser functions. * Scanner location: `scripts/lib/openclaw-scanner.ts`, wired into `scripts/aggregate.ts` for the top-level `openclaw` live-data branch. * Bridge location: `scripts/lib/openclaw-dev-bridge.ts`, registered from `vite.config.ts`. * Browser boundary: `src/hooks/use-openclaw.ts` reads status first, then fetches `/__token` and token-gated summaries only when OpenClaw is ready. Responses are parsed in `src/lib/openclaw-types.ts` before route components consume them. * Access: Loopback-only for every route; dashboard, sessions, sub-agents, tasks, skills, and plugins also require `X-Claude-OS-Token`. * Scope: AI OS host-cockpit telemetry only. It does not feed Trend Finder trend evidence, scores, creator angles, reports, watchlists, source breakdowns, or extension payloads. ### OpenClaw Admin Bridge * Purpose: Local support checks for OpenClaw deploy/spawn actions. Current behavior reports unsupported and never starts an action; that is a known implementation gap for the all-access product contract, not complete shipped execution. * Tech: Vite middleware, loopback guard, per-run token guard, server-only `OPENCLAW_DASHBOARD_ADMIN=1` gate, bounded JSON request validation, and typed browser parser/hook state. * Location: `scripts/lib/openclaw-admin-bridge.ts`, `src/lib/openclaw-admin-types.ts`, `src/hooks/use-openclaw-admin.ts`, and `src/components/openclaw/openclaw-admin-panel.tsx`. * Access: Status is loopback-only. Action preflight currently requires loopback, token, and the implementation action gate. * Scope: Support preflight only. No deploy, spawn, shell, git, upload, delete, OpenClaw CLI, Gateway RPC, state write, or production admin behavior is implemented. ### Codex App-Server Readiness * Purpose: Optional aggregate-time scanner for local Codex app-server readiness. It records presence, health, and bounded count metadata when the operator has already started a loopback listener. See [Local Agent Contract](/ai-os-and-trend-finder-docs/docs/local-agent-contract.md#codex-app-server-readiness) for the detailed contract. * Tech: Bun script scanning and sanitized live-data emission. * Location: `scripts/lib/codex-app-server-readiness.ts`, the Codex-aware parts of `scripts/aggregate.ts`, and `docs/local-agent-contract.md`. * Scope: AI OS host-cockpit telemetry only. It does not start Codex, execute commands, write config, install plugins, run OAuth flows, or expose raw threads, prompts, transcripts, diffs, files, tokens, or private paths. ### Operator Photo Proxy * Purpose: Dev-only avatar proxy (`/__operator-photo`) with domain allowlist, private-IP blocking, redirect limits, timeout, and size cap. Falls back to a generated initials SVG on failure. * Tech: Vite middleware, fetch with abort. * Location: `vite.config.ts` (middleware), `src/lib/operator-profile.ts` (helpers). ### Structured Logger * Purpose: Application-wide structured logging and error file capture. * Tech: pino, pino-pretty (dev), pino-roll (dev log files). * Location: `src/lib/logger.ts`. * Log files: `logs/app.YYYY-MM-DD.log` (daily JSON rotation via pino-roll, dev only; the directory is gitignored). ### Extension Platform * Purpose: Typed compile-time extension system for adding modular features. Extensions declare client views, sidebar navigation, capabilities, and optional collector scripts. Host routes render extension views inside a shared error boundary. * Tech: React, TanStack Router, Zod. * Client contracts: `src/extensions/types.ts` (ClientExtension, ExtensionView, ExtensionCapabilityDeclaration). * Client registry: `src/extensions/registry.ts` (static list, env-based enablement via `VITE_CLAUDE_OS_ENABLED_EXTENSIONS`). * Host routes: `src/routes/extensions.index.tsx`, `src/routes/extensions.$extensionId.tsx`, `src/routes/extensions.$extensionId.$viewId.tsx`. * Utility route: `src/routes/extensions.trend-finder.engine.tsx` renders Trend Finder Engine Replay outside the registered creator-facing view list. * Host rendering: `src/components/extensions/extension-host.tsx`, `src/components/extensions/extension-error-boundary.tsx`. * Runtime data: `src/extensions/use-extension-data.ts` (selector hook over `LiveData.extensions` branch). * Collector contracts: `scripts/lib/extensions/types.ts` (CollectorExtension, ExtensionRuntimeItem). * Collector registry: `scripts/extensions/registry.ts`. * Collector runner: `scripts/lib/extensions/runner.ts` (timeout, payload size validation, per-extension failure isolation). * Settings UI: `src/routes/settings.tsx` (Extensions card showing status, capabilities, env-key presence as boolean badges). * Setup guide: `docs/extensions/README_docs-extensions.md`. ### Trend Finder Extension (v0.1.0) * Purpose: Opt-in collector-backed extension for discovering emerging AI topics from public sources and tracking the self-evaluation loop that links identity, movement, predictions, retros, comparison-derived signal lenses, and Engine Replay. * Client: `src/extensions/trend-finder/client.tsx` (6 creator-facing views: Trends, Workbench, Hidden Gems, Sources, Watchlist, Brief) plus `src/routes/extensions.trend-finder.engine.tsx` for the sanitized Engine Replay utility route. * Schema: `src/extensions/trend-finder/schema.ts` (Zod schemas with `parseTrendFinderData` fallback). * Fixtures: `src/extensions/trend-finder/fixtures.ts` (synthetic sample data for empty/demo states). * Views: `src/extensions/trend-finder/views/` (trends-view, signal-workbench-view, hidden-gems-view, sources-view, watchlist-view, brief-view). * Client helpers: `src/extensions/trend-finder/components/`, `hooks/`, `view-model.ts`, `creator-lens-storage.ts`, and `run-control.ts` provide score/source rendering, Creator Lens draft persistence, and aggregate refresh coordination. * Collector: `scripts/extensions/trend-finder/collector.ts` (functional pipeline with source adapters, AI runtime readiness, scoring, snapshots, and fallback behavior). * Source adapters: `scripts/extensions/trend-finder/sources/hn-adapter.ts`, `arxiv-adapter.ts`, `github-adapter.ts`, and `rss-adapter.ts` provide reviewed direct public API/feed paths. `scripts/extensions/trend-finder/sources/apify-adapter.ts` runs reviewed configured Apify Actor sources for GitHub, Reddit, arXiv, Product Hunt, YouTube, and RSS/news when `APIFY_TOKEN` and reviewed Actor config are present. * Compliance docs: HN plus GitHub, Reddit, arXiv, Product Hunt, YouTube, and RSS/news are documented in `docs/sources/source-compliance-*.md`. Direct arXiv, GitHub, RSS/feed, and HN Algolia collection is implemented; additional direct source adapters remain compliance-first future work. * Normalization and scoring: `scripts/extensions/trend-finder/normalize.ts`, `topics.ts`, `scripts/lib/ai-runtime/trend-analyst.ts`, `scoring.ts`, and `snapshots.ts` produce topic clusters, score breakdowns, creator angles, movement groups, demand centers, theme rollups, outlier ideas, watchlist artifacts, prediction/retro summaries, and deterministic fallback topics. * Comparison-derived projections: attention pattern, aggregate-only reception, corroboration, evidence rationale, run narratives, industry events, security relevance, One to Watch, source-death alarms, static Brief richness, and pre-run estimates are derived from existing normalized evidence, history, scheduler, and validation state. Podcast/audio and broad social sources stay deferred until a future source-specific compliance review approves them. * Historical backtest CLI: `scripts/trend-finder-backtest.ts` and `scripts/lib/ai-runtime/backtests.ts` provide script-only historical window replay, leakage protection, private archives, and bounded publish summaries. ### AI Rogue Extension (v0.1.0) * Purpose: Production-enabled client-local roguelike extension that turns browser-safe AI OS activity into capped local Insight Shards progression. * Client: `src/extensions/ai-rogue/client.tsx` (4 views: Play, Ledger, Loadout, Settings) with lazy view wrappers to keep game code out of the static entry chunk. * Runtime: `src/extensions/ai-rogue/runtime/` contains deterministic simulation modules, atlas mapping, input helpers, render descriptors, a local PixiJS v8 facade, and the route-scoped renderer. * Views: `src/extensions/ai-rogue/views/` renders the Play canvas, Ledger claims, Loadout upgrades, Settings preferences/reset, and shared shell states. * Persistence: `src/extensions/ai-rogue/persistence.ts`, `save-schema.ts`, and `use-save-state.ts` own browser-local preferences, wallet, ledger, run history, save slots, upgrades, and AI Rogue-only reset. * Input mode: `src/extensions/ai-rogue/input-mode.ts` owns raw `auto | keyboard | compact` preferences, the mounted pointer/hover resolver, and the user-facing raw/effective labels. Play, Loadout, and Settings resolve Auto at the mounted browser boundary; coarse pointer plus no hover resolves to Compact, while desktop/fine-pointer and unavailable capability paths resolve to Keyboard. Runtime Canvas and the PixiJS runtime receive only concrete `keyboard | compact` values. * Economy and progression: `src/extensions/ai-rogue/economy.ts` and `progression.ts` derive capped, browser-safe rewards and local progression from generated AI OS data. * Assets: `src/assets/ai-rogue/` contains committed gameplay and UI atlases with TexturePacker-style frame metadata. The current visual atlas contract includes 234 gameplay frames and 146 UI frames covering G3 sector identity, G4 status/equipment icons, G5 boss/final-defense art, G6 UI/cinematic panels, and the explicit G7 player-animation rejection. It also contains committed local Ogg audio: six primary music tracks, five theme ambience loops, and 64 SFX/stinger files. Asset provenance and size evidence live in `docs/extensions/ai-rogue/visual-assets.md`, `docs/extensions/ai-rogue/game-feel.md`, and `docs/media-policy.md`. * Enablement: AI Rogue is registered statically and production-enabled by default in the browser registry. `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` explicitly hides extension entries for a build; `all` continues to enable all registered extensions. * Boundary: No script-side collector, remote content loading, hosted storage, raw private telemetry export, WebGPU-only path, worker simulation, gamepad, or pointer-lock behavior is implemented in the current slice. ## Tech Stack Rationale | Technology | Purpose | Why Chosen | | ----------------------- | ---------------------------------- | -------------------------------------------------------- | | Bun | Package manager and script runtime | Existing starter uses Bun for scripts and app commands | | React | UI | Existing dashboard is React-based | | TypeScript | Static typing | Existing codebase is TypeScript | | TanStack Router / Start | Routing and app shell | Existing route files and server entry use TanStack | | Vite | Dev server and build pipeline | Existing local middleware and build setup are Vite-based | | Tailwind CSS | Styling | Existing components use Tailwind utility classes | | Radix UI | Component primitives | Existing UI wrappers are built on Radix | | React Query | Runtime data cache | Existing `useLiveData()` uses React Query | | PixiJS v8 | AI Rogue canvas runtime | Lazy route-scoped WebGL renderer for the game extension | | pino | Structured logging | Lightweight JSON logger for server and scripts | ## Data Layer * Database: None currently. * Committed fallback data: `src/data/live-data.example.json`. * Generated local data: `src/data/live-data.json` (gitignored). * Generated data writes pass a privacy gate before disk writes. The gate rejects private emails, tokens, raw macOS/Linux home paths, and the active current `HOME` path even when that home is a nonstandard isolated root such as `/tmp/...`. The safe `/home/operator` placeholder is allowed. * Private aggregate diagnostics: `logs/aggregate-*.jsonl` and `logs/aggregate.latest.jsonl` (gitignored). * Private scheduler diagnostics: AI OS scheduler run state, per-job locks, private scheduler logs, and the shared generated-data write lock under the local AI OS scheduler root. * Demo fixtures: `src/lib/demo-data.ts` contains narrow example-payload fixtures for production routes. The broader `src/lib/mock-data.ts` module is legacy sample data and is blocked from production imports by ESLint. * Public demo fixtures: `demo-website/public/demo/live-data.snapshot.json`, `snapshot-metadata.json`, and graph fixtures are committed browser-safe projections generated by `bun run demo:snapshot` and verified by `bun run demo:scan:pages`. * Extension data: `LiveData.extensions` branch holds per-extension runtime state (status, data payload, warnings, error, last-updated timestamp). Validated by `validateExtensions()` in `src/lib/validate-live-data.ts` with disabled-fallback defaults. * Extension data access: `useExtensionData(extensionId)` selector hook in `src/extensions/use-extension-data.ts`. ## Current Data Flow 1. `bun run dev` runs `bun run seed:data`. 2. `seed:data` copies `src/data/live-data.example.json` to `src/data/live-data.json` only if the generated file is missing. 3. The Vite dev server serves `/__live-data` from `src/data/live-data.json`, falling back to the example file. 4. React routes call `useLiveData()` to fetch the JSON. 5. The UI renders locally aggregated data, explicit demo fixtures for the committed example payload, or honest empty states. 6. Generic refresh buttons can call `/__refresh_data`, which reruns `scripts/aggregate.ts` after token checks. Trend Finder run controls call `/__run_trend_finder`, which runs the scoped Trend Finder scheduler job instead of the full aggregate. 7. Each aggregate run records a private structured trace in `logs/aggregate.latest.jsonl` for diagnosing collector and AI-analysis readiness issues. 8. Scheduler jobs run through `scripts/scheduler-runner.ts`. Full aggregate delegates to the compatibility aggregate path, `agent-aggregate` writes host/local data only, `trend-finder` writes only the Trend Finder extension item, and Dream refreshes stale or missing host/local material before writing private Dream output. 9. In local development only, Hermes UI calls the Hermes dev bridge for fresh local Hermes state without waiting for a full aggregate run. That includes public connections, Pantheon templates, missions, documents, and document file/trash views, plus token-gated profiles, sessions, memory, Pantheon, and skills. 10. In local development only, OpenClaw UI calls the OpenClaw dev bridge for fresh local OpenClaw state without waiting for a full aggregate run. Token-gated OpenClaw summaries stay separate from Trend Finder extension data. 11. In local development only, Codex readiness metadata is recorded from an explicit loopback `CODEX_APP_SERVER_URL` and surfaced as host telemetry only. It stays separate from Trend Finder extension data. 12. AI Rogue reads browser-safe generated data through the extension host, derives local economy/progression state in the browser, resolves the raw Auto input preference to a concrete runtime mode at the mounted Play boundary, and stores wallet, ledger, preferences, run history, upgrades, and saves in browser-local storage. It does not have a collector or Vite middleware endpoint. ## Public Demo Data Flow ``` Operator-local snapshot command | v Allowlisted exporter + privacy scan | v Committed fixtures under demo-website/public/demo/ | v demo-pages Vite build + Pages dist assembler | v Static Cloudflare Pages root under demo-website/dist/ | v Browser routes render frozen public demo state ``` Public demo mode reads `/demo/*` fixtures and uses route-level unavailable states for local-only actions. It must not request any local Vite middleware path beginning with `/__`. The Phase 33 public snapshot keeps only allowlisted product data: Trend Finder count summaries, public evidence, watchlist rows, movement artifacts, and a sanitized Engine Replay trace; Dream Review prescription titles, summaries, rationales, next actions, priority labels, and tags; and parsed Knowledge Graph fixtures. Provider metadata, raw prompts, runtime diagnostics, local paths, credentials, bridge URLs, scheduler endpoints, and private source artifacts are excluded before the fixture scan runs. ## API Endpoints ### Production (Worker-level) * `GET /health` returns `{"status":"healthy","timestamp":"..."}`. Handled by `src/server.ts` before SSR. ### Local Dev Only (Vite Middleware) * `GET /__live-data` returns current runtime JSON. * `GET /__just-installed` returns and clears a setup marker. * `GET /__token` returns a per-run token to loopback clients. * `POST /__refresh_data` reruns the aggregator when loopback and token checks pass. * `POST /__run_trend_finder` runs the scoped Trend Finder scheduler job when loopback and token checks pass. * `GET /__refresh_status` returns async refresh status when loopback and token checks pass. * `POST /__run_dream` runs the AI OS Dream scheduler job on demand when loopback and token checks pass. * `GET /__operator-photo` proxies a configured operator avatar with SSRF safeguards. * `GET /__time-saved-config` reads optional gitignored saved-time and hourly-rate config from `data/` when loopback checks pass. * `GET` and `POST /__trend_finder_creator_lens` read and persist the local Trend Finder Creator Lens config when loopback and token checks pass. * `GET /__trend-finder-visibility-config` reads optional gitignored Trend Finder visibility settings from `data/trend-finder.visibility.json` when loopback checks pass. * `GET /__hermes_status` returns fresh Hermes install/config/model status. * `GET /__hermes_models` returns the configured default model plus the provider catalog, MoA mixtures, and declared-versus-fallback context metadata. * `GET /__hermes_model_intelligence` returns Ministry model metrics, rankings, pricing provenance, and optional live OpenRouter pricing status. * `GET /__hermes_connections`, `/__hermes_pantheon_templates`, `/__hermes_missions`, `/__hermes_documents`, `/__hermes_documents/file`, and `/__hermes_documents/trash` return public local Hermes reads. * `GET /__hermes_profiles`, `/__hermes_skills`, `/__hermes_sessions`, `/__hermes_session`, `/__hermes_memory`, and `/__hermes_pantheon` return token-gated sanitized local Hermes reads. * `GET /__hermes_admin_status`, `POST /__hermes_chat`, `POST /__hermes_cmd`, `POST /__hermes_moa_save`, `POST /__hermes_image_upload`, `POST /__hermes_missions/create`, `POST /__hermes_missions/optimize`, `POST /__hermes_missions/commit`, `POST /__hermes_missions/tick`, `POST /__hermes_missions/clear`, `POST /__hermes_missions/set-active`, `POST /__hermes_pantheon_sync`, `POST /__hermes_pantheon/validate`, `POST /__hermes_pantheon/install`, `POST /__hermes_pantheon/create`, `PUT`/`DELETE /__hermes_pantheon/`, `DELETE /__hermes_documents?name=...`, `POST /__hermes_documents/restore`, `DELETE /__hermes_documents/trash`, and `POST /__hermes_obsidian` are current Hermes write bridge endpoints gated by loopback, token, and the Phase 40 `HERMES_DASHBOARD_ADMIN=1` implementation constraint. * `POST /__start_voice` starts or reuses the local voice broker for Hermes Intelligence after loopback and token checks; browser-supplied provider config is rejected. * `GET /__openclaw_status` returns coarse OpenClaw install/config/status counts. * `GET /__openclaw_dashboard`, `/__openclaw_sessions`, `/__openclaw_subagents`, `/__openclaw_tasks`, and `/__openclaw_skills` return token-gated sanitized local OpenClaw summaries. * `GET /__openclaw_admin_status` and `POST /__openclaw_admin_action` are current OpenClaw admin bridge endpoints. The action endpoint validates deploy/spawn preflight requests and returns unsupported without starting an OpenClaw action; that is a documented implementation gap, not delivered full-access execution. Local bridge endpoints are not included in the Cloudflare Worker production surface because they are registered only through Vite `configureServer`. ## Deployment Shape The app has a Cloudflare Worker style server wrapper: * `wrangler.jsonc` sets `main` to `src/server.ts`. * `src/server.ts` delegates to TanStack Start server entry and normalizes catastrophic SSR failures into a branded HTML error page. The Cloudflare Pages public demo is a separate static target under `demo-website/`. It uses `bun run demo:build:pages`, serves `demo-website/dist`, and keeps the Worker deployment path unchanged. A GitHub Actions code quality workflow exists at `.github/workflows/quality.yml` with nine independent jobs covering lint, format, typecheck (app + scripts), tests, coverage, E2E, build, and bundle budget. A dedicated `.github/workflows/security.yml` workflow covers dependency audit, secret scan, CodeQL SAST, and dependency review. See [Deployment](/ai-os-and-trend-finder-docs/docs/deployment.md) for the full job list. ## Trend Finder Data Flow ``` Public trend sources (reviewed direct adapters, optional reviewed Apify Actors) | v Extension collector runner (scripts/lib/extensions/runner.ts) | v Source adapters fetch + normalize evidence items | v AI analyst runtime when configured, deterministic fallback when unavailable | v Topic extraction, scoring, signal projections, snapshots, and watchlist artifacts | v Collector emits ExtensionRuntimeItem -> LiveData.extensions branch | +--> Aggregate run trace -> logs/aggregate.latest.jsonl | +--> Local snapshots -> .cache/extensions/trend-finder/ | v Browser reads via useExtensionData() -> Trend Finder views | +--> Creator Lens draft/config via /__trend_finder_creator_lens in dev ``` Direct Hacker News, arXiv, GitHub repository search, and reviewed RSS/feed source adapters are functional without Apify. GitHub direct collection can use an optional script-only `GITHUB_TOKEN` for rate-limit headroom. Reviewed Apify source declarations are implemented for GitHub, Reddit, arXiv, Product Hunt, YouTube, and RSS/news, but they run only when local credentials and reviewed Actor configuration are present. Matching Apify fallbacks are skipped when a reviewed direct source succeeds, and stay eligible when direct collection is disabled, empty, rate-limited, timed out, or offline. AI analysis is optional; disabled or unavailable runtimes degrade to warnings plus deterministic fallback topics. The dashboard Brief view, opt-in static Brief export, and script-only historical backtest CLI are the current shareable and offline verification surfaces. The backtest CLI replays reviewed historical windows, writes full output under `.cache/extensions/trend-finder/backtests/`, and publishes only bounded summaries to browser data when explicitly requested. The scoped Trend Finder scheduler command uses the same collector path but writes only `LiveData.extensions.items["trend-finder"]` through the generated-data merge writer's generic `extension-item` scope. Host/local live-data branches remain owned by `aggregate` or `agent-aggregate`. ## Testing Infrastructure The project uses [Vitest](https://vitest.dev/) for unit/integration testing and [Playwright](https://playwright.dev/) for browser-level E2E testing. | Component | Location | Purpose | | ----------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | Vitest config | `vitest.config.ts` | Test runner configuration with environment matching | | Unit tests | `src/lib/__tests__/` | Pure function tests (Node environment) | | Hook tests | `src/hooks/__tests__/` | React hook tests | | Component tests | `src/components/__tests__/` | App-specific component behavior tests | | Route smoke tests | `src/routes/__tests__/` | Component render verification (happy-dom environment) | | Script tests | `scripts/lib/__tests__/` | Build and script utility tests | | Extension tests | `scripts/extensions/trend-finder/**/__tests__/`, `src/extensions/ai-rogue/**/__tests__/` | Source adapter, collector, AI Rogue economy, persistence, simulation, runtime, and view tests | | Test utilities | `src/routes/__tests__/test-utils.tsx` | Shared `renderRoute` helper with QueryClientProvider | | Playwright config | `playwright.config.ts` | Browser E2E configuration (Chromium) | | E2E tests | `tests/e2e/` | Setup wizard, dashboard, skills, Hermes/OpenClaw agent pages, Trend Finder browser flows, and AI Rogue runtime/ledger/persistence/mobile flows | Environment matching in `vitest.config.ts` maps `.test.tsx` files to `happy-dom` for DOM APIs and keeps `.test.ts` files in the default Node environment. Coverage is provided by `@vitest/coverage-v8` with enforced thresholds maintained in `vitest.config.ts`. Run `bun run test:coverage` for the current coverage report and gate. ## Build Quality Scripts | Script | Purpose | | -------------------------------- | -------------------------------------------------------- | | `scripts/check-bundle-budget.sh` | Enforces per-chunk and total JS gzip size budgets | | `scripts/check-asset-sizes.sh` | Enforces configured per-file limits for committed assets | | `scripts/postinstall.sh` | Activates `.githooks/` on `bun install` | See [Media Policy](/ai-os-and-trend-finder-docs/docs/media-policy.md) for asset format and size rules. ## Key Decisions * Keep generated private runtime data out of git. * Treat imported Claude OS behavior as implementation history and compatibility surface, not as root product documentation. * Use the current dashboard shell as scaffolding for Trend Finder product surfaces. * Keep documentation explicit about what exists now versus what is planned. * Use the accepted static extension platform design in [ADR 0001](/ai-os-and-trend-finder-docs/docs/adr/0001-extension-platform-foundation.md) until a later ADR revisits dynamic extension loading. See [Architecture Decision Records](https://github.com/moshehbenavraham/ai-os/blob/main/docs/adr/README.md) for detailed decision history. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/architecture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.