> 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/readme.md). # AI OS **Version: 0.5.100** [Public Docs](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs) AI OS is a local-first AI operator cockpit with a compile-time extension platform. It has local tool telemetry, skills, memory, setup, and agent surfaces and a separate extension system. This repository began on an imported "Claude OS" dashboard foundation, then moved to a general "AI OS" identity due to adding Codex, Hermes Agent, and OpenClaw features. Trend Finder is a movement analysis extension for AI content creators. AI Rogue is a production-enabled local roguelike extension that turns browser-safe AI OS activity into capped local progression. [Project Identity](/ai-os-and-trend-finder-docs/docs/project-identity.md). [Original Claude OS](https://www.skool.com/aiautomationsbyjack/about?ref=708a50f55b4d4cb88025bb8d2cd5d652) ## Jack Robert's 'Trend Finder' Hackathon [Trend Finder Supplementals](https://drive.google.com/drive/folders/1NktVlv8AChE6qdkDiO0C_nsYQeR86GAg?usp=sharing) ## Quick Start Use Bun 1.3.14 for release and CI parity. The repository includes `.bun-version`, and GitHub Actions pins the same Bun version. ### Quick Start UI Only Use this path when you want the app running quickly and do not need local machine telemetry refreshed. After dependencies are installed, `bun run dev` is the one command that starts the local UI. ```bash bun install bun run dev ``` `bun install` may load `.env.local` before install-time scripts such as `postinstall` run. Keep secrets in ignored files and do not paste secret values into shell commands. `bun run dev` runs `seed:data`, which copies `src/data/live-data.example.json` to `src/data/live-data.json` only when the generated file is missing. It then starts the local Vite/TanStack app on `http://127.0.0.1:5189`. This path does not run the full local telemetry scan. For full local telemetry setup, including generated local data and home-directory compatibility assets, see [Onboarding](/ai-os-and-trend-finder-docs/docs/onboarding.md). For a disposable credential-free Trend Finder demo path, see [Hackathon Submission](/ai-os-and-trend-finder-docs/docs/hackathon/hackathon-submission.md#credential-free-demo-path). ### Windows And Platform Notes Windows development uses the same project commands from PowerShell after Bun is installed: ```powershell bun install bun run dev ``` The local app still runs on `http://127.0.0.1:5189`. Setup and scheduler scripts are platform-aware: macOS uses launchd where applicable, Windows uses Task Scheduler where applicable, and Linux prints manual timer guidance instead of editing system scheduler state. macOS Keychain-specific detection is skipped outside macOS. ### Public Demo The production public demo is available at `https://demo.aiagentsos.com`. It is served by the `ai-os-public-demo` Cloudflare Pages project from the static Pages output under `demo-website/dist`. The current production direct upload was deployed on 2026-06-25 from source commit `079d26316793`; Cloudflare returned deployment URL `https://032a8040.ai-os-public-demo.pages.dev`. ### Public Demo Static Preview Use this path to verify the Cloudflare Pages public demo from committed browser-safe fixtures instead of local runtime data: ```bash bun install bun run demo:preview:pages ``` `bun run demo:preview:pages` rebuilds the static Pages output under `demo-website/dist` and serves it with Wrangler Pages dev. It does not run the local telemetry aggregator, source collectors, local bridge endpoints, schedulers, account-auth flows, uploads, or hosted mutations. See [Public Demo Fixtures](/ai-os-and-trend-finder-docs/demo-website/readme_demo-website.md) and [Deployment](/ai-os-and-trend-finder-docs/docs/deployment.md#cloudflare-pages-public-demo). The current committed demo snapshot is a frozen public-safe projection of real local Trend Finder and Dream Review output from Phase 33. Snapshot metadata records source commit `7681a517980f`, 24 covered routes, scan status `pass`, and 0 scan issues. To enable the Trend Finder extension in a local checkout, add this to `.env.local` and restart the dev server: ```bash VITE_CLAUDE_OS_ENABLED_EXTENSIONS=trend-finder ``` AI Rogue is enabled by default in the browser registry. To enable both registered extensions for local development, keep the `trend-finder` value above; AI Rogue is merged in from the production default. Use `none` only when you need to hide all extension entries. The environment variable still carries the inherited `CLAUDE_OS` name for compatibility. Treat it as the current extension enablement switch until a deliberate migration renames it. Current Trend Finder switch behavior: * The extension routes are statically registered. Direct URLs such as `/extensions/trend-finder/trends` can render committed fixture/demo data even when the switch is unset. * The sidebar extension entry and browser enabled state appear only when the switch includes `trend-finder` or `all`. * `bun run aggregate` and `bun run scheduler:trend-finder:run` use the same switch to decide whether the Trend Finder collector executes. When it is unset, the collector is disabled or skipped instead of running sources. * Apify Actors still require `APIFY_TOKEN` plus explicit reviewed source config. The extension switch alone never runs Apify sources. Current AI Rogue switch behavior: * AI Rogue routes are statically registered under `/extensions/ai-rogue/*`. * The sidebar extension entry and browser enabled state appear by default unless the switch is exactly `none`. Explicit non-`none` lists such as `trend-finder` keep AI Rogue enabled through the production default. * Set `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` only when you need to hide all extension entries in a build. * AI Rogue remains client-local: no collector, remote content loading, WebGPU-only path, or private telemetry export is enabled by the switch. * The browser-local controls preference defaults to Auto. Coarse-pointer, no-hover browsers resolve Auto to Compact controls, desktop/fine-pointer browsers resolve Auto to Keyboard controls, and explicit Keyboard or Compact Settings choices override Auto. The PixiJS runtime still receives only concrete `keyboard | compact` modes. * Phase 30 Session 10 approved opt-in after typecheck, lint, formatting, focused Vitest, focused Playwright, production build, bundle budget, asset-size, and private-runtime checks passed. Phase 34 later closed the audited default-enable blockers and production-enabled AI Rogue in the browser registry. Phase 35 reran the final release gate on 2026-06-27 and kept the current posture at Production Go with tight bundle headroom and active-at-cap deterministic playthroughs recorded as non-blocking caveats. ## Current Platform * React 19, TanStack Router/Start, Vite, Tailwind CSS 4, and TypeScript app. * Compile-time extension platform with typed client and collector contracts. * AI OS scheduler foundation with full aggregate compatibility, scoped host/local and Trend Finder refresh jobs, and material-first Dream behavior; Dream activation remains explicit from the local dashboard, CLI, or scheduler process env. * AI OS host cockpit with local setup, skills, memory, activity, share, settings, and Hermes, Claude Code, and OpenClaw agent routes. * Knowledge Graph Shared Brain with `/knowledge-graph`, committed AI OS seed graph fallback, optional graphify-powered local/Git ingest, a home preview, and route-local Hermes grounded chat. * Trend Finder extension with Trends, Workbench, Hidden Gems, Sources, Watchlist, Brief, Engine Replay, movement analysis, predictions, and retro artifacts. * AI Rogue extension with Play, Ledger, Loadout, and Settings views; a lazy PixiJS v8 WebGL runtime; deterministic dungeon simulation; browser-local saves, wallet, ledger, run history, and preferences; and capped Insight Shards progression from browser-safe AI OS activity, with committed gameplay/UI visual atlases, Web Audio music, theme ambience, SFX, and adaptive stingers. * Trend Finder self-evaluation loop, historical backtest CLI, and retro artifacts are complete for the current release. The backtest path is script-only and keeps full archives private. * Engine Replay utility route for browser-safe inspection of Trend Finder collection and scoring state. * Script-only historical backtest CLI for reviewed windows, private archives, and bounded browser-safe summaries when explicitly published. * Local runtime data loading through Vite middleware and React Query. * Local control-plane endpoints for generated data refresh, Dream runs, token handoff, and Hermes bridge reads/writes. These are loopback-only or same-run-token gated according to their route, and they are development/local operator surfaces rather than public demo APIs. * Bun aggregation scripts for generated runtime data, source collection, scoring, snapshots, and diagnostics. * Optional local operator telemetry inherited from the starter, kept separate from Trend Finder trend evidence. * Optional Codex app-server readiness metadata from explicit loopback endpoints, emitted as health/status/counts only. * Antigravity usage and saved-equivalent summaries in the usage and home surfaces, derived from validated local metadata only. * Dream source-status strip for Claude Code, Antigravity, Memory, Skills, Integrations, Automations, and Hermes source readiness. ## Knowledge Graph Shared Brain The `/knowledge-graph` route maps local projects into graphify Knowledge Graph files and uses `src/data/graphs/index.json` as the shared registry for AI OS, Hermes, and graphify-enabled agents. Fresh clones render the committed `ai-os` seed graph. Local admin runs can ingest a local path or Git/GitHub URL through the dashboard, then use the active project graph to ground the route-local Hermes chat. Start with [Knowledge Graph](/ai-os-and-trend-finder-docs/docs/knowledge-graph/knowledge-graph.md). Maintainer architecture notes live in [Knowledge Graph Handover](/ai-os-and-trend-finder-docs/docs/knowledge-graph/knowledge-graph-handover.md), and future unlocks are tracked in [Knowledge Graph Unlocks](/ai-os-and-trend-finder-docs/docs/knowledge-graph/knowledge-graph-unlocks.md). ## Hermes Agent Surface The `/agents/hermes` route is the completed AI OS port of the local Hermes v2.3 surface. It keeps AI OS as the host cockpit and renders Hermes as one local-agent surface rather than replacing the product shell. Implemented Hermes areas: * Global header status pill for the coarse local Hermes status endpoint. * Host cockpit route with Overview, Sessions, Chat, Mission, Documents, Memory, Mnemosyne, Pantheon, Skills, and Admin tabs. * Overview sections for connections, derived stats, recent activity, role map, and CLI/terminal guidance. * Token-gated sensitive reads for sessions, session detail, memory, Pantheon personas, skills, and profile grids. * Public loopback reads for status, models, connections, Pantheon templates, missions, document summaries, document previews, and document trash. * Model catalog output preserves AI OS defaults (`openai` / `gpt-5.5`) while surfacing upstream Claude model names only as browser-safe catalog options. * Demo mode with committed fixtures so the whole Hermes page can render when no local bridge or Hermes install is running. Local Hermes data is read from `~/.hermes` unless `HERMES_HOME` overrides it. The bridge expects or creates only local files and directories: ``` ~/.hermes/ |-- config.yaml |-- .version |-- auth.json |-- .env |-- sessions/ |-- memories/ | |-- USER.md | `-- MEMORY.md |-- SOUL.md |-- pantheon/ | `-- personas/ |-- skills/ |-- image_cache/ `-- missions.json ``` Documents default to `~/Documents/Hermes/` and can be redirected with `HERMES_DOCUMENTS_DIR`. Pantheon sync uses a local mirror allow-list (`HERMES_MIRROR` or `~/.hermes/.mirror_path`). The mirror must be a git checkout that can push; it may start as an otherwise empty private repo. Obsidian linking requires an explicit `HERMES_OBSIDIAN_VAULTS` allow-list. Hermes writes are local development actions only. Chat, image upload, mission writes, Pantheon writes/sync, document delete/restore/purge, and Obsidian linking require loopback access, the same-run token, and `HERMES_DASHBOARD_ADMIN=1`. Destructive document and sync operations use confirmation payloads; document delete is soft-delete first. Demo mode never sends the token and cannot write. The local voice broker and Hermes Intelligence portal are shipped AI OS product surfaces for local operators. Current-state setup policy and verification limits live in [Local Voice Setup](/ai-os-and-trend-finder-docs/docs/local-voice-setup.md) and [Intelligence View](/ai-os-and-trend-finder-docs/docs/intelligence-view.md). Provider keys remain environment-only, public demo mode never starts live voice, and real spoken provider results should be claimed only after a safe local credential-backed run. ## Trend Finder Extension Trend Finder is designed to answer these questions quickly: * What AI topics are gaining momentum right now? * Which tools, repositories, workflows, papers, or debates are still under the radar? * What evidence supports each trend? * Is the signal broad enough to trust, or just a one-source spike? * What creator angle, hook, or experiment should come from it? Implemented dashboard areas include: * Ranked trending AI topics with visible score breakdowns. * Hidden gems for lower-volume early acceleration. * Source health, provenance labels, and degraded/blocked source states. * Evidence links and source metrics behind each topic. * Attention pattern, aggregate-only reception, corroboration, and bounded per-evidence rationale for browser-safe signal inspection. * Creator angles, suggested hooks, and audience questions. * Signal Workbench filters, browser-local watching state, demand centers, theme rollups, and outlier ideas. * Watchlist and movement artifacts generated from the current run. * Brief view, prediction calibration, Story Log, and opt-in static Brief export for compact creator handoff. * Industry-events, security-lens, One to Watch, source-death, and pre-run estimate projections over existing reviewed data and scheduler state. * Runtime readiness for AI provider status, credential presence, fallback state, and redacted warnings. ## Data Sources And Runtime Implemented or reviewed local source paths: * Hacker News posts and story metadata through the public HN adapter. * Direct public API/feed adapters for arXiv metadata, GitHub repository search, reviewed RSS/Atom feeds, and HN Algolia keyword story metadata. These run without Apify when their compliance docs and enable flags allow collection. * Reviewed Apify source declarations for GitHub public repository metadata, arXiv metadata, Product Hunt launch metadata, YouTube metadata, Reddit metadata, and approved RSS/news feeds when the operator configures matching reviewed Actors. * Reviewed Apify declarations remain fallbacks for matching direct adapters when direct collection is disabled, empty, rate-limited, timed out, or offline and the normal Apify credential/config gates are ready. * Disabled, blocked, or restricted declarations for sources that need credentials, explicit reviewed config, or more compliance work. AI analysis is optional. When a configured runtime is unavailable, Trend Finder surfaces warnings and uses deterministic fallback behavior instead of claiming live AI clustering. Local static Brief export is implemented through `bun run trend-finder:export-brief`; hosted runtime operation, dynamic marketplace loading, and unrestricted source collection remain deferred. ## Repository Structure ``` . |-- .githooks/ # Local git hooks, including secret scan |-- docs/ # Project docs, PRDs, conventions, audits, and runbooks |-- demo-website/ # Cloudflare Pages public demo fixtures and static output boundary |-- scripts/ | |-- lib/ # Shared script utilities and env loading | |-- lib/extensions/ # Extension collector runner, env, logger, validator | `-- extensions/ # Extension collector registries and adapters |-- skills/ # Imported starter skill assets |-- src/ | |-- assets/ # Images and logos | |-- components/ # Shared React components and UI primitives | |-- components/extensions/ # Extension host and error boundary | |-- data/ # Example runtime data shape | |-- extensions/ # Client extension contracts, registry, and extensions | |-- hooks/ # Shared React hooks | |-- lib/ # Utilities and runtime data helpers | `-- routes/ # TanStack Router route files |-- package.json # Bun scripts and dependencies |-- vite.config.ts # Vite/TanStack config and local middleware `-- wrangler.jsonc # Cloudflare Worker style entry config ``` ## Documentation Published docs: * [Public Docs](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs) Core docs: * [Documentation](/ai-os-and-trend-finder-docs/docs/readme_docs.md) * [Project Identity](/ai-os-and-trend-finder-docs/docs/project-identity.md) * [Onboarding](/ai-os-and-trend-finder-docs/docs/onboarding.md) * [Development Guide](/ai-os-and-trend-finder-docs/docs/development.md) * [Architecture](/ai-os-and-trend-finder-docs/docs/architecture.md) * [Data Contract](/ai-os-and-trend-finder-docs/docs/data-contract.md) * [Knowledge Graph](/ai-os-and-trend-finder-docs/docs/knowledge-graph/knowledge-graph.md) * [Knowledge Graph Handover](/ai-os-and-trend-finder-docs/docs/knowledge-graph/knowledge-graph-handover.md) * [Extension System](/ai-os-and-trend-finder-docs/docs/extensions/readme_docs-extensions.md) * [Extension Architecture](/ai-os-and-trend-finder-docs/src/extensions/readme_extensions.md) * [AI Rogue Docs](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/readme_ai-rogue.md) * [AI Rogue Enablement Decision](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/enablement-decision.md) * [Public Demo Fixtures](/ai-os-and-trend-finder-docs/demo-website/readme_demo-website.md) * [AI Runtime Setup](/ai-os-and-trend-finder-docs/docs/ai-runtime-setup.md) * [Apify Source Setup](/ai-os-and-trend-finder-docs/docs/apify.md) * [Environments](/ai-os-and-trend-finder-docs/docs/environments.md) * [Deployment](/ai-os-and-trend-finder-docs/docs/deployment.md) * [Testing](/ai-os-and-trend-finder-docs/docs/testing.md) * [Local API Notes](/ai-os-and-trend-finder-docs/docs/api/readme_api.md) * [Incident Response](/ai-os-and-trend-finder-docs/docs/runbooks/incident-response.md) * [Scheduled Aggregate Runbook](/ai-os-and-trend-finder-docs/docs/runbooks/scheduled-aggregate.md) * [AI OS Dream Runbook](/ai-os-and-trend-finder-docs/docs/runbooks/ai-os-dream.md) * [Local Voice Setup](/ai-os-and-trend-finder-docs/docs/local-voice-setup.md) * [Intelligence View](/ai-os-and-trend-finder-docs/docs/intelligence-view.md) * [Contributing](/ai-os-and-trend-finder-docs/contributing.md) Hackathon and demo records: * [Hackathon Project Brief](/ai-os-and-trend-finder-docs/docs/hackathon/hackathon-project-brief.md) * [Hackathon Submission](/ai-os-and-trend-finder-docs/docs/hackathon/hackathon-submission.md) * [Trend Finder Demo Workflow](/ai-os-and-trend-finder-docs/docs/hackathon/trend-finder-demo.md) * [Related Project Research](/ai-os-and-trend-finder-docs/docs/research/parallel-projects.md) ## Tech Stack * Bun - package manager and script runtime. * React 19 - UI framework. * TypeScript - application and script language. * TanStack Router / TanStack Start - routing and application shell. * Vite 8 - development server and build pipeline. * Tailwind CSS 4 - styling. * Radix UI - accessible component primitives. * React Query - local runtime data fetching. * Cloudflare Worker style server entry - deployment-compatible server wrapper. ## Useful Scripts | Command | Purpose | | ----------------------------------------- | ----------------------------------------------------------------------- | | `bun run dev` | Seed fallback data and start the local app | | `bun run build` | Seed fallback data and build production assets | | `bun run build:dev` | Build production assets in development mode | | `bun run preview` | Run Vite preview; see deployment docs for Worker preview caveat | | `bun run worker:preview` | Build and run the Worker locally with pinned Wrangler | | `bun run worker:deploy` | Build and deploy the Worker with pinned Wrangler | | `bun run demo:snapshot` | Regenerate browser-safe public demo fixtures locally | | `bun run demo:build:pages` | Build static Cloudflare Pages public demo output | | `bun run demo:scan:pages` | Scan committed fixtures and generated Pages output for private content | | `bun run demo:budget:pages` | Check the Pages static client bundle budget | | `bun run demo:preview:pages` | Build and serve the static Pages demo with Wrangler Pages dev | | `bun run demo:deploy:pages` | Print or execute a validated Cloudflare Pages direct-upload command | | `bun run typecheck` | Run TypeScript compiler in check-only mode | | `bun run typecheck:scripts` | Type-check scripts (`tsconfig.scripts.json`) | | `bun run test` | Run all tests once | | `bun run test:watch` | Run tests in watch mode | | `bun run test:coverage` | Run tests with coverage report | | `bun run test:e2e` | Run Playwright end-to-end browser tests | | `bun run lint` | Run ESLint | | `bun run lint:fix` | Run ESLint with auto-fix | | `bun run format` | Run Prettier | | `bun run format:check` | Check formatting without modifying files | | `bun run budget:check` | Verify bundle chunk sizes are within budget | | `bun run clean` | Remove build artifacts | | `bun run setup` | Run AI OS setup, aggregation, compatibility installs, and hook wiring | | `bun run aggregate` | Refresh local telemetry and extension data | | `bun run scheduler:run` | Run aggregate through the AI OS scheduler runner | | `bun run scheduler:status` | Print safe scheduled aggregate status | | `bun run scheduler:agents:run` | Refresh host/local AI OS data through the scoped scheduler job | | `bun run scheduler:agents:status` | Print safe host/local agent aggregate scheduler status | | `bun run scheduler:trend-finder:run` | Refresh only Trend Finder extension data through the scheduler | | `bun run scheduler:trend-finder:status` | Print safe Trend Finder scheduler status | | `bun run scheduler:dream:run` | Run material-first AI OS Dream through the scheduler | | `bun run scheduler:dream:status` | Print safe AI OS Dream scheduler status | | `bun run trend-finder:backtest` | Run the private Trend Finder historical backtest CLI | | `bun run trend-finder:export-brief` | Export the current Trend Finder Brief as a local standalone HTML report | | `bun run trend-finder:replay-backhistory` | Replay private Trend Finder backhistory artifacts | | `bun run apify:smoke` | Check Apify readiness with redacted output | | `bun run codex:smoke` | Check Codex account transport with redacted output | | `bun run agents:codex:smoke` | Print deferred AI OS Agents Codex smoke status | | `bun run runtime:check-private` | Verify private runtime artifacts are ignored and untracked | | `bun run auth:openai` | Manage script-only OpenAI account auth | | `bun run install-dream` | Install AI OS Dream schedule on macOS/Windows; print Linux guidance | | `bun run uninstall-dream` | Remove AI OS Dream schedule on managed platforms | ## Local Privacy Boundaries AI OS reads generated local telemetry only through explicit local scripts and the Vite dev middleware. `src/data/live-data.json`, `.env.local`, aggregate logs, account-auth files, coverage, and Playwright artifacts are private local state and stay out of git. Codex-account runtime consumers auto-refresh expired stored OpenAI account auth where possible. If OpenAI rejects the stored refresh token, run `bun run auth:openai -- reauth`. Scheduled aggregate uses the same generated-data boundary as direct `bun run aggregate`. The scheduler path adds private run state, lock, and log records under the local AI OS scheduler root and exposes only safe labels through `bun run scheduler:status`. AI OS Dream uses `bun run scheduler:dream:run` to evaluate current generated-data freshness, refresh stale or missing host/local material through `agent-aggregate`, and write private Dream output and continuity state under the local AI OS Dream root. Dream status exposes safe labels and counts only through `bun run scheduler:dream:status`. Local timer intent is recorded in `data/ai-os.scheduler.json`, seeded from `data/ai-os.scheduler.example.json`. The private file only selects reviewed jobs, reviewed cadence IDs, booleans, and strict Dream `HH:MM` values. It does not install a timer or change the compatibility aggregate command. Current local Vite middleware and bridge endpoints are scoped to local development: | Endpoint family | Boundary | | ---------------------- | ------------------------------------------------------------------------------------------- | | `GET /__live-data` | Serves generated live data or fallback data from disk. | | `GET /__token` | Returns the same-run token to the local browser. | | `POST /__refresh_data` | Runs aggregate refresh with loopback and token checks. | | `POST /__run_dream` | Runs AI OS Dream with loopback and token checks. | | `/__hermes_*` | Uses public read, token-gated read, or admin-gated write boundaries depending on the route. | Scheduler paths do not add a browser gateway, remote scheduler API, or daemon. Dream also has a local token-gated dashboard button for manual runs. The inherited `/dream` skill remains a compatibility asset; `install-dream` and `uninstall-dream` manage the OS-level AI OS Dream schedule and are not browser gateways or remote control-plane APIs. Codex app-server readiness is optional. When `CODEX_APP_SERVER_URL` is unset, CLI-only Codex setups remain normal. When it is set, AI OS accepts only loopback `http://` or `ws://` endpoints and emits readiness status, health status, warning codes, and bounded counts. It does not start Codex, execute commands, write config, install plugins, run OAuth flows, or render raw threads, turns, prompts, transcripts, command output, diffs, files, tokens, or private paths. Setup and aggregate terminal output is local operator diagnostics. It may print absolute local paths when explaining what it read, skipped, copied, or could not find. Browser-facing data, generated `src/data/live-data.json`, Vite middleware responses, and scheduler status output must use safe labels or redacted paths instead of raw private home or repository paths. ## Extension Runtime Run `bun run scheduler:trend-finder:run` after changing Trend Finder runtime env when you want to refresh only the Trend Finder extension payload. Run `bun run aggregate` when you intentionally want the full compatibility writer to refresh host/local and extension data together. Without private credentials, the dashboard still renders fixture/demo fallback data with visible provenance labels and readable warning states. The current Trend Finder runtime payload is delivered through `LiveData.extensions.items["trend-finder"]` and validated with Zod before the extension renders it. See [Extension System](/ai-os-and-trend-finder-docs/docs/extensions/readme_docs-extensions.md), [AI Runtime Setup](/ai-os-and-trend-finder-docs/docs/ai-runtime-setup.md), and [Apify Source Setup](/ai-os-and-trend-finder-docs/docs/apify.md) for the current contracts. AI Rogue is also registered in the extension host, but it has no script-side collector. It reads browser-safe generated data, derives capped local economy state, and stores only browser-local preferences, wallet, ledger, run history, and save slots. Its primary route is `/extensions/ai-rogue/play`. ## Data And Privacy Generated runtime data is written to `src/data/live-data.json`, which is gitignored. Each aggregate run also writes private diagnostic traces to `logs/aggregate-*.jsonl` and refreshes `logs/aggregate.latest.jsonl` with collector lifecycle, runtime readiness, and sanitized AI-analysis metadata. Scheduled aggregate may also write private scheduler run state, lock, and log records. Dream scheduler runs may also write private Dream output, continuity state, runtime state, scheduler state, locks, and scheduler logs. These are local diagnostics and should remain untracked. The inherited starter can scan local Claude/Codex/memory/integration signals when `bun run setup` or `bun run aggregate` is executed. Those local operator signals are private runtime data and should remain separate from Trend Finder public trend evidence. Do not commit `.env.local`, API keys, generated local data, account auth, cache snapshots, logs, coverage, test results, or browser reports. The committed `src/data/live-data.example.json` is the safe fallback shape used on fresh clones. Run `bun run runtime:check-private` before sharing a credentialed run. ## License This is a closed-source private project. It is not open source and is marked `SEE LICENSE IN LICENSE` in package metadata. The project was built on top of Jack Roberts' original [Claude OS](https://www.skool.com/aiautomationsbyjack/about?ref=708a50f55b4d4cb88025bb8d2cd5d652) project from AI Automations by Jack. The inherited Claude OS materials are licensed under the "Claude OS - Personal & Commercial Use License with Attribution" and remain subject to that license: they require visible attribution to **Claude OS by Jack Roberts** on any public deliverable they materially contribute to, and may not be redistributed, repackaged, sold, or offered as a hosted service or community-gated access. The closed-source terms above apply only to this project's own original contributions and authorized access. See [LICENSE](https://github.com/moshehbenavraham/ai-os/blob/main/LICENSE/README.md) for the binding terms and [NOTICE](https://github.com/moshehbenavraham/ai-os/blob/main/NOTICE/README.md) for the third-party/upstream scope (brand marks, agent integrations, AI-generated artwork). ## Project Status AI OS is the active local-first platform. Trend Finder is the active hackathon-born extension for public trend intelligence, and AI Rogue is the production-enabled local roguelike extension completed in Phase 30 and default-enabled after Phase 34 audit remediation and the Phase 35 final release gate. Product requirements live in [docs/PRD.md](/ai-os-and-trend-finder-docs/docs/prd.md), UX requirements live in [docs/PRD\_UX.md](/ai-os-and-trend-finder-docs/docs/prd_ux.md), conventions live in [docs/CONVENTIONS.md](/ai-os-and-trend-finder-docs/docs/conventions.md), and public-facing docs live under [docs](https://github.com/moshehbenavraham/ai-os/blob/main/docs/README.md). Keep root documentation focused on the platform; keep event-specific notes in [docs/hackathon](https://github.com/moshehbenavraham/ai-os/blob/main/docs/hackathon/README.md). --- # 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/readme.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.