> 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/.spec_system/archive/prd/prd-backup-20260703-191154.md). # AI OS - Product Requirements Document ## Overview AI OS is a local-first AI operator cockpit with a compile-time extension platform. The current repository is a brownfield application built from an imported Claude OS local operator dashboard foundation and later extended with the Trend Finder hackathon extension. The product vision is platform consolidation around AI OS, not a README-level hackathon handoff. Imported local-operator surfaces may remain for AI tool telemetry, skills, memory, workspaces, setup, agents, and usage insight. Trend Finder owns the extension language: public AI trend discovery, evidence, scoring, creator angles, watchlists, and report export. The existing Claude OS foundation provides the UI shell, routing, component system, script structure, local data loading pattern, setup flows, graph concepts, dashboard patterns, and visual assets that AI OS can build on while preserving useful local operator areas. ## Product Vision AI OS should feel like a practical local operating layer for AI work. Its host surface should make local tools, memory, skills, usage, and agents legible without mixing private operator telemetry with extension data. Trend Finder should feel like a creator-facing market intelligence desk inside AI OS that turns public source activity into ranked, evidence-backed AI topic opportunities. The two systems should share infrastructure and visual language, but not blur their data models: * AI OS host data is local operator telemetry: skills, memory, activity, workspaces, agents, setup, subscription/usage, and local AI workflow state. * Trend Finder data is public trend intelligence: source items, evidence, topic clusters, scores, creator angles, watchlist state, and generated reports. The navigation, copy, data badges, and routes must make that separation clear. ## Goals 1. Bring the imported starter to a known-good, stable, tested, documented, and maintainable baseline before new feature work begins. 2. Document the current imported project accurately before changing core behavior. 3. Preserve the useful starter capabilities: React dashboard shell, local JSON data flow, setup scripts, and UI components. 4. Preserve useful imported operator areas while keeping Trend Finder as a clearly separated extension module. 5. Build a repeatable source collection, normalization, clustering, scoring, and reporting workflow for the Trend Finder hackathon submission. 6. Produce a clear GitHub repository, Trend Finder dashboard or HTML report, and 60-second Loom walkthrough by the hackathon deadline. 7. Default local AI OS operator goals to full local access, write access, and edit access unless a named public-demo, privacy, compliance, or external dependency boundary requires otherwise. 8. Treat proper delivery as end-to-end product proof: real execution, visible results, recovery paths, and focused tests. Scaffolding, labels, mock-only paths, and disabled controls are not complete delivery. ## Local Access Default The default local product posture is full access, full write, and full edit for the operator's local AI OS capabilities. Read or metadata-only behavior is allowed only as an explicit exception: public demo safety, third-party source compliance, secret/privacy protection, unavailable credentials, offline dependencies, or a temporary implementation gap with a named owner and recovery path. Historical phases may describe earlier limited-access foundations. Those records are superseded for future goals by this default. New docs, specs, and acceptance criteria must not present disabled controls or descriptive scaffolding as delivered features. ## Non-Goals For Initial Documentation 1. Do not claim that trend ingestion, clustering, or scoring is implemented yet. 2. Do not remove the imported operator routes, reference files, setup flows, or telemetry views as part of the initial Trend Finder work. 3. Do not document secrets, local private machine data, or generated `src/data/live-data.json` contents. 4. Do not mix AI OS local operator telemetry with Trend Finder public trend evidence in the same charts unless the data provenance is explicit. 5. Do not treat the whole application as Trend Finder while operator cockpit areas remain visible; represent Trend Finder as an extension inside AI OS. ## Phases | Phase | Name | Sessions | Status | | ----- | -------------------------------------------------- | -------- | ----------- | | 00 | Brownfield Stabilization Baseline | 12 | Certified | | 01 | Codebase Evaluation Remediation | 21 | Certified | | 02 | Plugin Extension System Foundation | 6 | Complete | | 03 | Hermes Local Telemetry Foundation | 4 | Complete | | 04 | Hermes Product Surface And Admin Gate | 4 | Complete | | 05 | AI Runtime Platform | 10 | Complete | | 06 | Hackathon Finish And Demo Readiness | 8 | Complete | | 07 | Engine Replay Visual Proof Surface | 5 | Complete | | 08 | OpenClaw Agent Page Implementation | 5 | Complete | | 09 | ChatGPT Codex Local-Agent Parity | 8 | Complete | | 10 | General Scheduler Foundation | 6 | Complete | | 11 | Scheduled Aggregate Path | 5 | Complete | | 12 | AI OS Dream Runtime Migration | 7 | Complete | | 13 | Trend Finder Self-Evaluation Loop | 4 | Complete | | 14 | Trend Finder Historical Backtest Harness | 2 | Complete | | 15 | Scheduler Config And Aggregate Split | 8 | Complete | | 16 | Hermes v2.3 Port Foundation | 3 | Complete | | 17 | Hermes Shell And Core Writes | 3 | Complete | | 18 | Hermes Memory And Visualization | 2 | Complete | | 19 | Hermes Orchestration And Documents | 2 | Complete | | 20 | Hermes Long-Tail And Parity Sign-off | 2 | Complete | | 21 | Non-Hermes v2.3 Usage Accuracy | 3 | Complete | | 22 | Non-Hermes Multi-Agent Detection And Home Surfaces | 3 | Complete | | 23 | Non-Hermes Routes, Polish And Closeout | 3 | Complete | | 24 | Trend Finder Outlier Signal Upgrade | 9 | Complete | | 25 | Hermes Mission Control Activation | 9 | Complete | | 26 | Knowledge Graph Shared Brain Port | 9 | Complete | | 27 | Trend Finder Alpha Radar Adoption | 12 | Complete | | 28 | Trend Finder Trends-Finderz Adoption | 15 | Complete | | 29 | Trend Finder TrendingAI Comparison Adoption | 18 | Complete | | 30 | AI Rogue Game Extension | 10 | Complete | | 31 | Cloudflare Pages Public Demo | 7 | Complete | | 32 | AI Rogue Mobile Input Auto-Detect | 5 | Complete | | 33 | Cloudflare Pages Real Product Fixtures | 6 | Complete | | 34 | AI Rogue Audit Remediation | 8 | Complete | | 35 | AI Rogue Audit Hardening And Refactor | 10 | Complete | | 36 | AI Rogue Audio Asset Finishing | 8 | Complete | | 37 | AI Rogue Visual Asset Finishing | 6 | Complete | | 38 | Claude OS v2.8.1 Semantic Port | 10 | Complete | | 39 | AI Rogue Level Authoring Infrastructure | 8 | Complete | | 40 | Claude OS v2.10.1 Semantic Port | 18 | Complete | | 41 | Hermes All-Access Remediation | 17 | Not Started | ## Phase 00: Brownfield Stabilization Baseline Phase 00 is a comprehensive audit and fix pass for the existing codebase. It must produce a known-good baseline before any new Trend Finder feature implementation begins. ### Objectives 1. Establish and verify the brownfield stabilization workflow for the repo. 2. Audit and fix local development tooling, linting, formatting, types, tests, and build reliability. 3. Audit and stabilize runtime data loading, local middleware, server entry points, scripts, and deployment configuration. 4. Audit and document security, privacy, dependency, and source-control safeguards. 5. Audit and fix user-facing reliability issues in the existing UI shell, routes, responsive behavior, loading states, and error states. 6. Document the current starter architecture, setup, scripts, environment expectations, and deployment shape accurately. 7. Call out which parts are imported operator behavior and which docs describe the Trend Finder extension direction. 8. Leave explicit acceptance gates proving the repo is stable enough for Phase 01 feature work. ### Sessions | Session | Name | Purpose | | ------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | 01 | Repo Inventory And Risk Map | Build the baseline inventory, risk register, and acceptance checklist for the brownfield starter. | | 02 | Toolchain And Command Baseline | Make install, dev, format, lint, typecheck, build, and preview commands deterministic and documented. | | 03 | TypeScript And Lint Debt Pass | Remove or explicitly contain existing TypeScript, ESLint, and Prettier debt across app code. | | 04 | Runtime Data Contract Stabilization | Stabilize runtime JSON contracts, fallback data, data loading, and local refresh middleware. | | 05 | Test Harness And Unit Coverage | Add or repair a practical test harness and cover core utilities, data transforms, and hooks. | | 06 | Route Smoke And Regression Coverage | Add route-level smoke checks for current pages, error states, and build output. | | 07 | UI Shell Responsiveness And Accessibility | Audit and fix the existing shell, navigation, focus behavior, reduced motion, and responsive layout. | | 08 | Security Privacy And Dependency Audit | Verify secret handling, generated data boundaries, dependency posture, and privacy documentation. | | 09 | Scripts And Automation Hardening | Audit and fix setup, aggregation, image, cron, and polling scripts for maintainability and safe failure. | | 10 | Documentation And Onboarding Sync | Reconcile README, docs, ADRs, runbooks, source docs, and documentation artifacts with implemented behavior. | | 11 | Deployment And Environment Readiness | Validate deployment configuration, Cloudflare Worker shape, environment docs, and production build assumptions. | | 12 | Final Baseline Certification | Run the full quality gate, close residual findings, and publish the Phase 00 known-good baseline record. | No new Trend Finder feature work should begin until all Phase 00 sessions are validated or explicitly deferred with documented owner approval. ## Phase 01: Codebase Evaluation Remediation Phase 01 resolves the 2026-05-14 codebase evaluation findings folded into the archived Phase 01 planning record. It is a remediation phase focused on moving the codebase from the current B-grade baseline toward an A-grade maintainable project before deeper Trend Finder feature implementation. ### Objectives 1. Decompose large route and script modules into focused, typed boundaries. 2. Repair quality gates through coverage, script typechecking, typed fixtures, and explicit `any` reduction. 3. Expand browser coverage for setup, home dashboard, memory graph, and skills workflows. 4. Align source branding, setup copy, docs, and storage migration with the AI OS host / Trend Finder extension boundary. 5. Harden local privileged endpoints and add CI, secret scanning, asset, and chunk budget controls. ### Sessions | Session | Name | Purpose | | ------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 01 | Home Route Section Extraction | Extract focused home dashboard sections from `src/routes/index.tsx` while preserving behavior. | | 02 | Home Data And State Boundaries | Move home data derivation and mutable state into typed hooks or pure helpers. | | 03 | Setup Wizard Shell Extraction | Extract setup wizard shell and step components from `src/routes/setup.tsx`. | | 04 | Setup Detection And Activation Modules | Extract setup persistence, detection adapters, activation flow, and modal boundary. | | 05 | Shared Route Boundary And Live Data Cleanup | Remove module-level live-data mutation from remaining routes. | | 06 | Typed Transforms And Nested Validation | Strengthen typed transforms and nested live-data validation. | | 07 | Aggregate Scan Module Extraction | Split scan-side responsibilities out of `scripts/aggregate.ts`. | | 08 | Aggregate Output Module Extraction | Split output, anonymization, graph, Dream, and file-writing responsibilities out of the aggregator. | | 09 | Script Typecheck Env And Logging | Add script typechecking, consolidate environment parsing, and add client-safe logging. | | 10 | Source Any Reduction Pass | Reduce explicit `any` usage in hand-authored source files. | | 11 | Test Fixture Type Safety Pass | Add typed fixtures and reduce loose route and component test mocks. | | 12 | Coverage Gate Repair | Add focused tests until configured global coverage thresholds pass. | | 13 | Setup Wizard E2E Coverage | Add Playwright coverage for setup wizard configuration, persistence, and activation. | | 14 | Dashboard And Skills E2E Coverage | Add Playwright coverage for home dashboard and skills workflows. | | 15 | Hackathon Identity Alignment | Historical session that aligned route metadata, visible copy, sidebar branding, share text, setup copy, and storage keys for the then-current Trend Finder direction. Superseded by the AI OS host / Trend Finder extension boundary. | | 16 | Docs And Setup Guidance Sync | Reconcile docs, setup guidance, secret lifecycle notes, and docs formatting drift. | | 17 | Operator Photo Proxy Hardening | Add allowlist, timeout, redirect, private-IP, and size safeguards to `/__operator-photo`. | | 18 | Refresh Endpoint Async Execution | Replace synchronous refresh shell execution with a non-blocking local process model. | | 19 | CI Build Audit And Secret Gates | Add build, dependency audit, secret scanning, and route warning cleanup to CI. | | 20 | Asset Compression And Media Policy | Compress or externalize oversized image assets and document a media policy. | | 21 | Chunk Budget And Final Certification | Add budget checks and publish final Phase 01 remediation certification. | Public trend source collection, clustering, scoring, and generated report implementation remain deferred until source terms, rate limits, retention, and privacy requirements are reviewed. ## Phase 02: Plugin Extension System Foundation Phase 02 implements the repo-local extension platform. It turns the Trend Finder module direction into explicit extension contracts, static host routes, runtime data isolation, collector guardrails, settings visibility, and a disabled-first Trend Finder scaffold. This phase deliberately starts with local compile-time registered extensions. It does not load remote code, run third-party packages dynamically, or implement broad public source ingestion until source terms, rate limits, retention, and privacy requirements are reviewed. ### Objectives 1. Add typed client and collector extension contracts with static registries. 2. Add `/extensions` host routes and sidebar navigation contributions without changing existing routes when no extensions are enabled. 3. Add an explicit `extensions` branch to `LiveData`, validation defaults, fallback data, and a `useExtensionData()` selector hook. 4. Add a guarded script-side collector runner that contains disabled, missing-env, timeout, warning, and error states per extension. 5. Surface extension enablement, capabilities, data status, and env-key presence in setup/settings without exposing private values. 6. Scaffold the Trend Finder extension with empty or fixture-backed views and prepare the first public source adapter only after compliance preconditions are documented. ### Sessions | Session | Name | Purpose | | ------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | 01 | Extension Platform Skeleton | Add shared extension contracts, client registries, static host routes, sidebar contributions, host rendering, and contained UI error handling. | | 02 | Runtime Data Contract | Add the `LiveData.extensions` branch, validator backfills, example fallback data, and `useExtensionData()` selector behavior. | | 03 | Collector Runner Guardrails | Add script-side extension collector types, registry, runner, aggregation wiring, and per-extension failure isolation. | | 04 | Settings And Setup Surface | Add extension enablement config, settings/status display, env-key presence wiring, and secret exposure tests. | | 05 | Trend Finder Extension Scaffold | Add the disabled-first Trend Finder client views, Zod schema, fixture-backed empty states, collector skeleton, and primary route coverage. | | 06 | Source Readiness And First Adapter | Document source compliance, add first-source adapter scaffolding behind capabilities, and verify partial-failure source health behavior. | Trend Finder source collection remains opt-in and staged. Session 06 may stop at compliance documentation and adapter scaffolding if source terms, rate limits, retention, or API key requirements are not resolved. ## Phase 03: Hermes Local Telemetry Foundation Phase 03 is complete. It ported the safe foundation from the Claude OS v2 porting plan before the project adopted the current all-access local default. It covered low-risk script and skill fixes, the validated `liveData.hermes` branch, script-side Hermes scanning, setup detection, and GET local dev middleware. The old limited-access posture is historical only. Future Hermes and local-agent goals must follow the project-wide full local access, write, and edit default while keeping Hermes state separate from Trend Finder public trend evidence, scores, creator angles, watchlists, and report data. The Claude OS v2 porting context for these sessions is folded into the archived Phase 03 planning record and session stubs. ### Objectives 1. Port upstream script and Dream skill hygiene fixes that do not require Hermes runtime UI. 2. Add a typed and validated `hermes` branch to generated live data. 3. Scan Hermes data through project scripts using bounded filesystem access and sanitized output. 4. Surface Hermes installation/configuration state through aggregation and setup without requiring Hermes on `PATH`. 5. Add GET local dev bridge endpoints with loopback and token protections for sensitive data. ### Sessions | Session | Name | Purpose | | ------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | 01 | Low-Risk Fixes And Script Hygiene | Port Dream skill, cron, prompt wording, and polling-script disposition fixes that do not require Hermes runtime UI. | | 02 | Hermes Data Contract And Scanner | Add the Hermes scanner, `liveData.hermes` contract, validator defaults, fallback data, aggregate wiring, and tests. | | 03 | Hermes Detection In Setup | Surface Hermes as an installed local tool through aggregation detection and setup wizard status. | | 04 | Hermes Dev Middleware | Add GET local Hermes status, model, skill, session, memory, and pantheon endpoints with loopback and token protections. | Write, delete, upload, spawn, git, chat, persona install, and memory edit capability were outside Phase 03. That old scope must not be reused as the default for future local operator goals. ## Phase 04: Hermes Product Surface And Admin Gate Phase 04 builds on the Phase 03 Hermes telemetry foundation to add the user-facing Hermes product surface, then introduces privileged local behavior behind the then-current explicit local write gate. It also brings over useful v2 visual polish while preserving the current media policy and Trend Finder product boundaries. The explicit write gate is current Phase 40 implementation history, not the product default for future goals. Future access work must move local operator features toward full local write/edit readiness by default while retaining loopback, token, confirmation, and recovery safeguards. The Claude OS v2 porting context for these sessions is folded into the archived Phase 04 planning record and session stubs. ### Objectives 1. Add compact Hermes status affordances without promoting Hermes data as Trend Finder public evidence. 2. Replace the static `/agents/hermes` concept page with a modular local-agent page. 3. Add write/chat/admin capabilities only behind explicit local opt-in, token auth, and security tests. 4. Integrate selected Hermes visuals and brand styling without violating asset or bundle budgets. 5. Keep documentation accurate about implemented local behavior versus planned or gated admin behavior. ### Sessions | Session | Name | Purpose | | ------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | 01 | Hermes Status Pill And Source-Aware Dashboard | Add compact Hermes status affordances and optional source-aware home copy without treating Hermes as public trend evidence. | | 02 | Modular Hermes Page MVP | Replace the static concept page with modular Hermes status, sessions, memory, pantheon, and skills UI. | | 03 | Opt-In Hermes Admin Bridge | Add chat and persona write capabilities only behind explicit local admin opt-in, token auth, and security tests. | | 04 | Asset And Brand Integration | Import only used, compressed Hermes visuals, scope route styling, update notices if needed, and run final asset and build gates. | GitHub sync and any broader public trend source expansion remain outside this two-phase port unless a later session explicitly scopes them. ## Phase 05: AI Runtime Platform Phase 05 implemented the AI Runtime Platform as one cohesive phase. It built the Apify-backed, Codex-powered Trend Finder runtime needed for the platform while keeping the delivery surface inside the existing dashboard and extension data pipeline. This phase was vertical-first. It did not port the full Job-Hunt API service, orchestration database, prompt bootstrap system, autonomous desktop control, or generated HTML report workflow. It added only the runtime primitives needed for Trend Finder: Apify collection, account-auth/Codex transport, AI provider readiness, structured analyst output, deterministic scoring, local snapshots, collector fallbacks, source breadth, and dashboard presentation. ### Objectives 1. Add runtime dependencies, package scripts, credential placeholders, Trend Finder runtime env vars, and secret guardrails. 2. Build a script-only Apify collection layer for configured Actors, Dataset reads, item caps, timeouts, provenance, and degraded source results. 3. Port the narrow OpenAI account auth and Codex transport pieces from Job-Hunt without importing broad orchestration or API service code. 4. Add an AI runtime provider boundary with `codex-account`, `mock`, `disabled`, and a narrow future `openai-api` slot. 5. Add structured analyst input/output contracts, Zod validation, evidence citation checks, retry-on-invalid behavior, and deterministic fallback. 6. Upgrade Trend Finder schemas with Creator Lens, runtime readiness, score breakdowns, AI-enriched fields, and snapshots while preserving backwards-compatible parsing. 7. Wire the collector to Apify, AI analysis, deterministic scoring, source warnings, runtime state, and local snapshots. 8. Configure multiple role-aware Apify-backed sources with implementation-time compliance checks and per-source normalizers. 9. Update the dashboard to show Creator Lens controls, runtime readiness, warnings, score breakdowns, evidence links, why-now explanations, hooks, and audience questions. 10. Certify the runtime with focused tests, typechecks, fallback checks, docs, and dashboard-centered demo notes. ### Sessions | Session | Name | Purpose | | ------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | 01 | Runtime Dependency And Secret Guardrails | Add runtime dependencies, scripts, env placeholders, credential examples, gitignore coverage, and secret guard checks. | | 02 | Apify Collection Foundation | Add Apify config, client, Actor run, Dataset read, item cap, timeout, and smoke-test foundation. | | 03 | OpenAI Account Auth And Codex Transport | Port the narrow Job-Hunt account auth and Codex transport pieces into the Trend Finder runtime with redaction and smoke scripts. | | 04 | AI Runtime Provider Boundary | Add script-only runtime contracts, config, readiness, disabled/mock providers, Codex-account provider, and OpenAI API slot. | | 05 | Analyst Contracts And Validation | Add structured analyst input/output contracts, evidence grounding, retry-on-invalid behavior, and validation tests. | | 06 | Trend Schema Scoring And Snapshots | Add Creator Lens, runtime state, score breakdowns, snapshot helpers, deterministic scoring, and backwards-compatible parsing. | | 07 | Collector AI Integration And Fallbacks | Wire Trend Finder collection to Apify, AI readiness, analyst output, deterministic fallback, warnings, and snapshots. | | 08 | Apify Source Breadth And Compliance | Configure multiple Apify-backed source roles with source-specific normalizers, compliance updates, and source weighting. | | 09 | Dashboard Runtime Delivery | Render runtime readiness, source warnings, Creator Lens controls, score breakdowns, evidence, why-now copy, hooks, and Brief/report cleanup. | | 10 | Runtime Validation And Demo Certification | Run quality gates, verify fallback states, update docs/security records, and record dashboard-centered demo proof points. | ## Phase 06: Hackathon Finish And Demo Readiness Phase 06 finishes the unfinished hackathon MVP work identified in `docs/hackathon/brainstorm-hackathon.md` after the completed AI Runtime Platform. It should make Trend Finder demo-ready as a dashboard-centered, permissioned AI trend analyst without broadening the scope into a hosted AI OS, dynamic marketplace, generated HTML report workflow, or long-term preference engine. The phase is built around the final brainstorm finish path: make Creator Lens edits affect the next run, add a Trend Finder-specific run control, validate a small reviewed Apify source set, generate watchlist and movement artifacts, show per-topic source breakdown and evidence metrics, prepare a labeled demo data path, and certify the final Loom/submission package. ### Objectives 1. Replace unresolved or placeholder Apify source declarations with concrete reviewed actor candidates and compliance-aligned source IDs. 2. Validate tiny capped Apify source outputs, update normalizers and fixtures, and record blocked sources honestly. 3. Make editable Creator Lens values persist and feed the next Trend Finder collection run. 4. Add a Trend Finder-specific run control that uses the current lens and existing local refresh guardrails. 5. Generate watchlist entries and clearer movement artifacts from analyst output, deterministic thresholds, and snapshots. 6. Add per-topic source breakdowns and evidence metric chips to make scores more explainable. 7. Prepare a repeatable local demo data path with exact fallback and AI-runtime labeling. 8. Complete the final validation gates, documentation, 60-second Loom script, and honest deferral list. ### Sessions | Session | Name | Purpose | | ------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | 01 | Apify Actor Declarations And Compliance Alignment | Replace unresolved actor placeholders with concrete reviewed source declarations and compliance-gate tests. | | 02 | Tiny Source Validation And Normalizer Fixtures | Validate tiny capped Actor outputs and update normalizers, fixtures, and tests for browser-safe evidence. | | 03 | Creator Lens Persistence And Collector Wiring | Make editable Creator Lens values persist locally and feed analyst, fallback, scoring, and creator-angle generation. | | 04 | Lens-Aware Run Control And Refresh UX | Add a Trend Finder-specific run control that persists the current lens and invokes the existing refresh path. | | 05 | Watchlist And Movement Artifacts | Generate watchlist entries, previous scores, score deltas, and movement labels from snapshots and trend output. | | 06 | Source Breakdown And Evidence Metrics UI | Show per-topic source-role breakdowns and source-aware evidence metric chips in the dashboard. | | 07 | Demo Data Path And Fallback Semantics | Prepare live-or-fixture demo data workflow and label AI, mock, disabled, fallback, degraded, and blocked states clearly. | | 08 | Hackathon Submission Certification | Run final checks, update docs/security notes, prepare Loom script, and record any post-hackathon deferrals. | ## Phase 07: Engine Replay Visual Proof Surface Phase 07 built the Engine Replay experience now folded into the archived Phase 07 planning record. It gives the hackathon demo a separate proof surface for the Trend Finder backend while keeping the main product tabs focused on creator-facing outcomes: ranked trends, hidden gems, source health, watchlist, and Brief. The phase adds a sidebar-promoted route at `/extensions/trend-finder/engine`, derives or generates a sanitized `EngineTrace`, visualizes the source-to-brief pipeline, and validates that the page never becomes a raw log viewer or privacy-risking debug dump. Historical replay across prior runs remains deferred until the SQLite observation store plan provides durable local run history. Session 05, Demo Validation And Documentation Closeout, is complete and validated. The phase is complete and archived. ### Objectives 1. Add a Trend Finder-scoped Engine Replay route and a distinct sidebar entry above Settings. 2. Define a browser-safe `EngineTrace` contract with fixture, missing-trace, fallback, and stale-data states. 3. Render the latest run as a visual source-to-artifact story using source health, evidence filtering, runtime state, scoring, watchlist, and Brief data. 4. Generate sanitized trace summaries from existing structured aggregate events without exposing raw logs, credentials, auth paths, prompts, responses, or private local telemetry. 5. Add timeline replay controls, reduced-motion behavior, desktop/mobile visual coverage, documentation, and demo script language. ### Sessions | Session | Name | Purpose | | ------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | | 01 | Engine Replay Route And Navigation Shell | Add the scoped route, sidebar placement, safe `EngineTrace` contract, and initial empty or fixture states. | | 02 | Source To Artifact Story Surface | Render the first complete visual story from current Trend Finder payload data and safe trace summaries. | | 03 | Sanitized Engine Trace Generation | Build and test script-side trace generation from structured Trend Finder aggregate events. | | 04 | Replay Controls And Motion Polish | Add timeline controls, explanatory motion, reduced-motion fallback, and responsive visual verification. | | 05 | Demo Validation And Documentation Closeout | Certify privacy, quality gates, docs, Loom language, and deferred historical replay scope. | ## Phase 08: OpenClaw Agent Page Implementation Phase 08 replaced the static `/agents/openclaw` concept preview with a real AI OS host-cockpit page for local OpenClaw state while preserving the current OpenClaw visual design. The planning details are folded into the archived Phase 08 planning record and session stubs. The phase mirrors the proven Hermes scanner, bridge, page, and admin-gate sequencing. Session 05, Documentation E2E And Polish, is complete and validated. Phase 08 is complete and archived. OpenClaw belongs to the AI OS host cockpit, not Trend Finder. OpenClaw data must not feed Trend Finder public evidence, scores, creator angles, watchlists, source breakdowns, hackathon docs, or reports. The historical Phase 08 slice shipped local OpenClaw metadata and explicit setup, loading, error, offline, live-local, and demo-only states. Future OpenClaw goals inherit the all-access local default. Deploy, spawn, shell, git, upload, delete, Gateway control, and state write behavior must not be claimed as shipped until a session proves supported execution with loopback, token auth, strict validation, visible results, recovery states, and tests. ### Objectives 1. Add a validated OpenClaw snapshot contract and scanner for config, agents, sessions, sub-agents, tasks, skills, plugins, and native metrics. 2. Add local-dev-only bridge endpoints with loopback checks, token-gated sensitive reads, no-store responses, and structured errors. 3. Replace the static `/agents/openclaw` route with modular components backed by real state or visibly labeled setup/error/demo states. 4. Preserve the current OpenClaw red-black hero, logo treatment, grid texture, metric tiles, swarm mode cards, active swarm list, role bars, and skills cards. 5. Keep deploy/spawn/admin behavior labeled as a gap unless proven safe and executable in its own session. 6. Update docs, route coverage, E2E coverage, and validation records so OpenClaw is documented as implemented behavior rather than a concept preview. ### Sessions | Session | Name | Purpose | | ------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | 01 | OpenClaw Contract And Scanner | Add the OpenClaw live-data contract, scanner, validators, fallback, fixtures, and tests. | | 02 | OpenClaw Dev Bridge | Add GET local bridge endpoints for status, dashboard, sessions, sub-agents, tasks, skills, and plugins. | | 03 | Modular OpenClaw Page | Replace the static route with modular components, real state, demo fixtures, and honest unavailable states. | | 04 | Deploy Action Proof | Define deploy/spawn actions only after a safe execution path is proven with local safeguards, recovery states, and tests. | | 05 | Documentation E2E And Polish | Update docs and route coverage, verify desktop/mobile layouts, and run final validation gates. | ## Phase 09: ChatGPT Codex Local-Agent Parity Phase 09 brings OpenAI ChatGPT/Codex coverage up to the same product depth that AI OS currently gives Claude Code. The 2026-05-19 source audit is folded into the archived phase planning record and session stubs. Phase 09 is now complete and archived. The phase is centered on the configured `CODEX_HOME` value from `.env.local`. `~/.codex` remains only the portable fallback. The historical Phase 09 slice emits safe metadata only and keeps ChatGPT/Codex host telemetry separate from Trend Finder extension data. Future Codex product actions inherit the all-access local default and must prove real write/edit/turn execution before being documented as shipped. ### Objectives 1. Make `CODEX_HOME` the single source of truth for Codex local discovery. 2. Add provider-neutral local-agent contracts that preserve existing Claude compatibility while supporting Codex activity, workspace, usage, config, memory, skill, automation, and integration summaries. 3. Parse Codex local sessions/history as safe metadata and feed activity and workspace projections. 4. Split ChatGPT plan, OpenAI API key, Codex CLI auth, configured model, and Codex usage into distinct facts. 5. Inventory Codex config, apps/connectors, MCP, plugins, skills, hooks, memories, model providers, permissions, sandbox, web search, and multi-agent settings without exposing secrets. 6. Update setup, settings, activity, workspaces, and spend UI with provider-neutral copy and Codex readiness details. 7. Add optional Codex app-server readiness metadata and close the phase with privacy documentation and validation. ### Sessions | Session | Name | Purpose | | ------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 01 | Codex Home Path And Safe Inventory | Make `CODEX_HOME` the canonical Codex root and add safe metadata inventory. | | 02 | Provider-Neutral Local-Agent Contract | Add contracts, validator defaults, fallback data, and compatibility mappings for provider-aware local-agent summaries. | | 03 | Codex Session History Scanner | Parse Codex sessions/history into safe activity, workspace, and tool metadata. | | 04 | OpenAI Auth Usage And Model Normalization | Separate ChatGPT plan, OpenAI API key, Codex auth, model, usage, and unknown-cost states. | | 05 | Codex Config Integrations And Apps Inventory | Parse Codex config with TOML and inventory MCP, apps/connectors, plugins, model providers, permissions, hooks, and related settings. | | 06 | Codex Memory Skills And Automation Parity | Add Codex memory/instruction metadata plus `CODEX_HOME`-aware skills and automations. | | 07 | Local-Agent UI And Setup Parity | Update activity, workspaces, setup, settings, and spend surfaces with provider-neutral copy and Codex readiness. | | 08 | App-Server Readiness Documentation And Validation | Add optional app-server readiness, update docs/security records, and validate the phase. | ## Phase 10: General Scheduler Foundation Phase 10 maps the first high-level phase from `docs/ongoing-projects/linux-scheduler-and-dream-runtime-plan.md` into the implementation roadmap. It builds the AI OS host scheduler foundation for Linux `systemd --user` timers so AI OS can install, run, inspect, and uninstall local scheduled jobs through a general scheduler subsystem. Phase 10 is marked complete in project docs as of 2026-05-21. Current checked-in Phase 10 artifacts cover the scheduler inventory/decision record and typed registry foundation. Phase 11 adds the aggregate-specific runner, state/log/lock, handler, status, docs, and certification path. General systemd unit rendering and lifecycle install/uninstall commands remain outside the Phase 11 shipped surface; scheduled aggregate timer installation is local machine setup. This is AI OS host work, not Trend Finder extension work. Phase 11 now owns the scheduled aggregate production path. Dream runtime migration remains deferred to Phase 12. ### Objectives 1. Reconcile inherited Dream-only launchd/crontab behavior with the target AI OS scheduler model. 2. Add typed scheduler job contracts and a static AI OS scheduler registry. 3. Add a scheduler runner foundation with strict job IDs, timeouts, PID locks, sanitized run state, and private logs. 4. Add Linux `systemd --user` unit rendering, availability checks, linger reporting, WSL/degraded-state reporting, and tests. 5. Add install, status, manual run, and uninstall command paths that do not silently change login policy. 6. Update setup, docs, security notes, and validation records while preserving aggregate and Dream deferrals. ### Sessions | Session | Name | Purpose | | ------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | 01 | Scheduler Inventory And Decisions | Document current scheduler-related behavior, settle names and boundaries, and capture deferrals before implementation. | | 02 | Scheduler Registry And Job Contract | Add typed scheduler job metadata, a static registry, strict job ID validation, and registry tests. | | 03 | Runner State Locks And Logs | Add the scheduler runner core with timeouts, PID locks, sanitized run state, private logs, and runner tests. | | 04 | Systemd User Timer Rendering | Add systemd user service/timer rendering, absolute path resolution, linger/WSL detection, and rendering tests. | | 05 | Scheduler Lifecycle Commands | Add install, status, manual run, and uninstall command paths for Linux user timers with mocked lifecycle tests. | | 06 | Setup Docs And Foundation Certification | Update setup/docs/security notes and validate the scheduler foundation while keeping later aggregate and Dream work explicit. | ## Phase 11: Scheduled Aggregate Path Phase 11 maps the second high-level phase from `docs/ongoing-projects/linux-scheduler-and-dream-runtime-plan.md` into the spec workflow. It builds on the Phase 10 scheduler foundation and makes `aggregate` the first production AI OS scheduler job. This phase preserves the existing manual `bun run aggregate` path while adding a scheduled path through the Phase 10 registry, runner, locks, logs, and run state. Scheduled aggregate uses the same private environment loading, redaction, source guardrails, warnings, and generated data boundaries as manual aggregate. Phase 11 is complete and certified with command-first status, private scheduler diagnostics, and no gateway. Dream runtime migration remains deferred to Phase 12. ### Objectives 1. Inventory manual aggregate behavior and finalize the production scheduler cadence and install stance. 2. Register `aggregate` as the first production scheduler job using the Phase 10 scheduler registry and runner. 3. Preserve manual/scheduled aggregate parity for environment loading, redaction, source guardrails, warnings, and generated output. 4. Record aggregate success, failure, duration, exit code, and sanitized warnings in private scheduler state and logs. 5. Surface aggregate scheduler status only through browser-safe metadata when needed. 6. Update setup, docs, security notes, and validation records while keeping Dream runtime migration explicit and deferred. ### Sessions | Session | Name | Purpose | | ------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | 01 | Aggregate Inventory And Cadence | Document manual aggregate behavior, decide cadence/install stance, and define parity requirements before implementation. | | 02 | Aggregate Job Registration And Handler | Register `aggregate` as the first production scheduler job and wire a scheduler-safe handler to existing aggregate behavior. | | 03 | Scheduled Aggregate State And Redaction | Record aggregate run state, logs, warnings, failures, and redaction through the scheduler state model. | | 04 | Status Projection And Setup Surface | Surface aggregate status and setup guidance through command output or browser-safe metadata while keeping Dream deferred to Phase 12. | | 05 | Docs And Aggregate Certification | Update docs/security records and certify scheduled aggregate with focused validation and Dream deferrals. | ## Phase 12: AI OS Dream Runtime Migration Phase 12 is complete. The detailed phase PRD and session artifacts were captured in the archived Phase 12 planning record and session notes. Phase 12 fully folds the remaining Dream runtime migration work originally captured in the deleted `docs/ongoing-projects/dream-runtime-plan.md` source plan into the implementation roadmap. It builds on the Phase 10 scheduler foundation and Phase 11 scheduled aggregate path so Dream becomes an AI OS host scheduler job instead of depending on the inherited Claude slash-command skill as the primary runtime. This is AI OS host runtime work, not Trend Finder extension work. Dream should consume fresh browser-safe generated material, refresh stale or missing host/local data through the scoped agent aggregate path, call the script-side AI runtime provider boundary, write private output under `~/.ai-os/dreams`, preserve a legacy `~/.claude-os/dreams` read bridge, and record sanitized lifecycle state. Gateway or service work remains deferred unless Dream runtime migration proves a concrete live-control need. As of 2026-05-24, Home and Settings include local token-gated manual Dream triggers that run the same scheduler path and return only browser-safe live-data projection. ### Objectives 1. Inventory inherited Dream behavior and finalize migration decisions for cadence, material readiness, lock/backoff semantics, prescription count, and compatibility aliases. 2. Add Dream output, continuity state, validation, and atomic write contracts under `~/.ai-os/dreams`. 3. Add canonical AI OS host runtime provider configuration while preserving Trend Finder compatibility env names. 4. Implement Dream activation gates, private lifecycle statuses, lock recovery, backoff, and bounded timeouts. 5. Register and execute Dream as an AI OS scheduler/manual job that ensures fresh browser-safe input before analysis. 6. Migrate Dream loading to prefer `~/.ai-os/dreams` with legacy `~/.claude-os/dreams` fallback and stable prescription continuity. 7. Update setup, docs, security notes, and validation proof while separating implemented Dream behavior from legacy skill compatibility and deferred gateway work. ### Sessions | Session | Name | Purpose | | ------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | 01 | Dream Inventory And Migration Decisions | Inventory inherited Dream behavior, settle migration decisions, and capture scheduler/aggregate/runtime dependencies. | | 02 | Dream Contract State And Output Paths | Add validated Dream output/state contracts, primary and legacy paths, atomic writes, and safety tests. | | 03 | Host AI Runtime Provider Boundary | Make script-side AI runtime providers usable by AI OS host jobs with additive AI OS env names and preserved compatibility aliases. | | 04 | Activation Gates Locks And Observability | Add Dream gate evaluation, private lifecycle statuses, scheduler lock usage, stale recovery, timeouts, and sanitized observability. | | 05 | Dream Job Registration And Execution | Register Dream as a scheduler/manual job and execute material-first analysis through the host runtime provider. | | 06 | Prescription Continuity And Loader Migration | Prefer `~/.ai-os/dreams`, keep legacy fallback reads, and preserve stable prescription continuity across runs. | | 07 | Setup Docs And Dream Certification | Update setup/docs/security records and certify Dream runtime migration with focused validation and explicit deferrals. | ## Phase 13: Trend Finder Self-Evaluation Loop Phase 13 lands items 1-4 of the `docs/ongoing-projects/last-sprint.md` plan so Trend Finder feels self-evaluating, not just ranked. The detailed phase PRD and session stubs were captured in the archived Phase 13 planning record. This is Trend Finder extension work, not AI OS host work. The phase replaces exact id/slug/name topic matching with a canonical identity resolver, adds an AI movement analyst with deterministic fallback, adds a prediction/retro lite loop backed by a private extension cache archive, and extends Engine Replay with a sanitized decision timeline that reflects the real intelligence loop. Item 5 of the source plan (Historical Backfill And Backtest Harness) is owned by Phase 14 and depends on the Phase 13 identity resolver and retro evaluator contracts. ### Objectives 1. Replace exact id/slug/name topic matching with a canonical topic identity resolver that combines deterministic matches, evidence overlap, and validated AI continuity hints, then propagate canonical IDs through scoring, snapshots, watchlist, and the browser schema with backwards-compatible Zod defaults. 2. Add an AI movement analyst that explains why a topic is new, rising, cooling, or noisy using validated current and previous canonical topic IDs and cited evidence IDs only, with deterministic fallback summaries and Watchlist/Brief integration. 3. Add a prediction and retro lite loop that writes cited predictions to a private archive, scores prior predictions on later runs, and surfaces capped "prediction / observed / lesson learned" dashboard copy without claiming historical backtest coverage. 4. Extend Engine Replay with a sanitized decision timeline that reflects the real intelligence loop (planner, source run, normalization, AI analysis, scoring critic, movement analyst, prediction writer, retro evaluator, artifact writer) without exposing prompts, Actor inputs, Dataset IDs, raw logs, private paths, or request IDs. ### Sessions | Session | Name | Purpose | | ------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 01 | Stable Topic Identity | Add the canonical topic identity resolver, propagate canonical IDs and aliases through scoring/snapshots/schema with Zod defaults, and wire the resolver into the collector before scoring. | | 02 | AI Movement Analyst | Add the script-side movement analyst with citation validation and deterministic fallback, persist capped browser-safe movement records, and project AI-vs-fallback explanations into Watchlist and Brief. | | 03 | Prediction And Retro Lite | Add prediction and retro modules, a private archive under `.cache/extensions/trend-finder/predictions/`, retro labeling using canonical identity continuity, and capped dashboard copy that does not overclaim backtest coverage. | | 04 | Engine Replay Intelligence Loop | Add a sanitized decision timeline to Engine Replay covering each intelligence-loop stage while preserving existing section and artifact IDs and rejecting unsafe keys/values. | Historical backfill, backtest CLI, source historical-window contracts, and new sources remain outside Phase 13 scope and are owned by Phase 14. ## Phase 14: Trend Finder Historical Backtest Harness Phase 14 landed item 5 of the `docs/ongoing-projects/last-sprint.md` plan. The detailed phase PRD and session stubs were captured in the archived Phase 14 planning record. This is Trend Finder extension work, not AI OS host work. The phase introduces a typed historical-window contract on Trend Finder source adapters, lands reviewed date-window overrides only where per-source compliance docs allow, and builds a script-only backtest CLI that generates synthetic snapshots with explicit leakage protection, reuses the Phase 13 retro evaluator as the single scoring path, and stores full results privately under `.cache/extensions/trend-finder/backtests/`. Browser data receives only bounded aggregate summaries, and only when the CLI is invoked with an explicit publish flag. Phase 14 depended on Phase 13. Phase scope was revalidated against the real Phase 13 prediction archive and retro evaluator contracts before the session work ran. ### Objectives 1. Add an explicit typed historical-window contract to source adapter types and configurations so each source declares whether it supports historical windows and which Actor input fields are safe to override. 2. Land reviewed date-window overrides only where the source compliance doc explicitly supports them; keep all other sources current-only with an explicit unsupported reason. 3. Build a script-only backtest CLI with fixed window start/end timestamps, source allowlists, max-window count, max-items caps, and dry-run output. 4. Generate synthetic snapshots by running collection and scoring as-of each window end, with leakage protection that excludes any evidence published after the window end from that window's score. 5. Reuse the Phase 13 prediction/retro evaluator to compare earlier predictions against later windows; do not invent a parallel scoring definition. 6. Store full backtest output under private extension cache paths and emit only bounded aggregate results to browser data when explicitly requested. 7. Update demo documentation so future-run retro language and historical backtest language are clearly distinguished. ### Sessions | Session | Name | Purpose | | ------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 01 | Historical Window Contract And Reviewed Sources | Add a typed historical-window contract on source types and Apify source declarations, attach safe-override fields and compliance-doc references where supported, keep all other sources current-only with explicit reasons, and update compliance docs accordingly. | | 02 | Backtest CLI And Leakage Guarantees | Build the script-only backtest CLI, generate synthetic snapshots with explicit leakage protection, reuse the Phase 13 retro evaluator, store full output privately, and emit only bounded aggregate summaries when the explicit publish flag is set; update demo docs. | HN remains current-only unless a separate reviewed historical source ships in its own future session. New AI tasks are not in Phase 14 scope. ## Phase 15: Scheduler Config And Aggregate Split Phase 15 is archived at `.spec_system/archive/phases/phase_15/PRD_phase_15.md` after completing all eight sessions. It split the current broad aggregate foundation into reviewed scheduler config, safe generated-data merge boundaries, reusable aggregate orchestration, scoped host/local and Trend Finder scheduler jobs, cross-job freshness behavior, timer guidance, and final docs validation while keeping `bun run aggregate` as the full compatibility command. This is AI OS host scheduler and generated-data infrastructure work. It must preserve the existing scheduler registry as the reviewed job contract, keep secrets and private runtime details out of status/log surfaces, and prevent separate jobs from overwriting each other's live-data branches. ### Objectives 1. Add repo-local scheduler settings under `data/` with sanitized examples, validation, status fallback behavior, and docs. 2. Define live-data ownership boundaries and a shared generated-data write lock so scoped jobs can preserve each other's branches. 3. Refactor aggregate orchestration into reusable host/local and extension paths without changing `bun run aggregate` output. 4. Add an `agent-aggregate` scheduler job for host/local data refresh. 5. Add a Trend Finder scoped scheduler job with lower default cadence and safe readiness/status reporting. 6. Verify cross-job ordering, Dream freshness behavior, merge safety, and generated-data freshness semantics. 7. Optionally add timer unit rendering and reconciliation after scoped jobs are stable. 8. Complete documentation, compatibility, and validation sweep. ### Closeout Note Phase 15 completed the config contract, live-data merge boundary, aggregate orchestration extraction, scoped `agent-aggregate` job, scoped Trend Finder job, cross-job Dream freshness validation, timer guidance, and final documentation sweep. Timer installation remains operator-managed; browser control surfaces remain out of scope. ### Original Session Plan | Session | Name | Purpose | | ------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | 01 | Scheduler Config Contract And Status Read Path | Add scheduler config templates, parser/validator, status projection, docs, and focused tests. | | 02 | Live Data Merge Boundary And Shared Write Lock | Add safe live-data branch ownership, shared write locking, merge writer behavior, and tests. | | 03 | Aggregate Orchestration Refactor | Extract reusable host/local and extension orchestration paths while preserving full aggregate compatibility. | | 04 | Agent Aggregate Scheduler Job | Add the scoped local-agent refresh job, scripts, status copy, locks, and tests. | | 05 | Trend Finder Scheduler Job | Add the scoped Trend Finder refresh job, scripts, readiness warnings, merge behavior, and tests. | | 06 | Cross-Job Integration And Dream Freshness Boundary | Prove scoped jobs can run independently and Dream can use recent agent data without forcing Trend Finder. | | 07 | Timer Unit Rendering And Reconciliation | Optional systemd user timer dry-run, inspect, install/uninstall, and drift reporting pass. | | 08 | Documentation Compatibility And Validation Sweep | Synchronize runbooks, env examples, data docs, command hints, and final validation gates. | ## Phase 16: Hermes v2.3 Port Foundation Phase 16 starts the five-phase Hermes v2.3 feature port. The cross-phase master reference lives in `.spec_system/PRD/phase_16/PRD_phase_16.md` and points directly to the source repositories: `V23/` at `/home/operator/projects/claudeos/claude-os-v2.3/`, `AIOS/` at `/home/operator/projects/aios/`, and diff artifacts under `/home/operator/projects/claudeos/diff-v1-v2.3/`. It includes the source-code legend, component inventory, endpoint inventory, Write-Path Safety Contract, write-operation inventory, dependencies, assets, validation strategy, non-goals, resolved decisions, open questions, and whole port completion criteria. ### Objectives 1. Confirm the architecture decision: port v2.3 features into aios modules, not the v2.3 monolith. 2. Land backend endpoint parity and the write-safety foundation before any new UI consumes it. 3. Extend hooks, types, validators, and demo data so every later surface uses the aios data layer. ### Sessions | Session | Name | Purpose | | ------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------ | | 01 | Guardrails, Architecture Decision And Parity Baseline | Record the architecture/IA decisions and current Hermes parity baseline. | | 02 | Backend Endpoint Parity And Write-Safety Foundation | Add the missing read/write endpoints behind loopback/token/admin/path-safety gates. | | 03 | Data Layer And Demo Fixtures | Add hooks, payload types, validators, and demo fixtures for every new Hermes domain. | ## Phase 17: Hermes Shell And Core Writes Phase 17 builds the visual shell and first core write surfaces on top of the Phase 16 foundation: v2.3 cinematic styling, the global status pill, the Chat tab, and the Pantheon upgrade with GitHub sync. ### Objectives 1. Apply the v2.3 Hermes visual vocabulary and mount the global status pill. 2. Add the Chat tab with current-gated send and image upload. 3. Upgrade Pantheon with templates, rich persona UI, and current-gated GitHub sync. ### Sessions | Session | Name | Purpose | | ------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | 01 | Visual System, Cinematic Shell And Global Status Pill | Port the v2.3 visual shell and status pill. | | 02 | Chat Tab (Write: Send + Image Upload) | Add modular Chat UI with write affordances routed through `useHermesAdmin`. | | 03 | Pantheon Upgrade (Write: Edit/Delete/Templates/GitHub Sync) | Add templates, rich persona UI, and GitHub sync while preserving existing persona writes. | Phase 17 is 3/3 complete as of 2026-06-02. Sessions 01 through 03 are validated and complete. ## Phase 18: Hermes Memory And Visualization Phase 18 upgrades Memory and adds Mnemosyne. It keeps sensitive reads token-gated and keeps Mnemosyne code-split so the 3D surface does not inflate the base bundle. Phase 18 is complete as of 2026-06-02. ### Objectives 1. Upgrade the Memory tab with three-layer memory, profile grids, and the allow-listed Obsidian write. 2. Add the Mnemosyne 3D constellation as a lazy-loaded tab. ### Sessions | Session | Name | Purpose | | ------- | ------------------------------------------------- | ---------------------------------------------------------------- | | 01 | Memory Upgrade (Sensitive Reads + Obsidian Write) | Port v2.3 memory sections and the current-gated Obsidian bridge. | | 02 | Mnemosyne 3D Constellation (Code-Split) | Port the 3D constellation with a recorded bloom/bundle decision. | Phase 18 is fully complete and archived. ## Phase 19: Hermes Orchestration And Documents Phase 19 adds the two heaviest write surfaces: Mission Control and Documents Gallery. Both use the current write gate and must satisfy the Phase 16 Write-Path Safety Contract. Phase 19 is complete and archived as of 2026-06-02. ### Objectives 1. Add Mission Control with mission view and create/optimize/tick/clear writes. 2. Add Documents Gallery with list/preview and soft-delete/restore/purge writes. ### Sessions | Session | Name | Purpose | | ------- | --------------------------------------------------- | ----------------------------------------------------------------------- | | 01 | Mission Control (Write: Create/Optimize/Tick/Clear) | Add mission orchestration with spawn-safe optimize and confined writes. | | 02 | Documents Gallery (Write: Delete/Restore/Purge) | Add artifact list/preview/trash with current-gated document mutations. | ## Phase 20: Hermes Long-Tail And Parity Sign-off Phase 20 completes v2.3 Hermes feature parity by porting the remaining long-tail sections and running final cleanup, docs, and side-by-side validation. Phase 20 is complete and archived as of 2026-06-02 after Session 02 completed. ### Objectives 1. Port Connections, stats, skills, sessions, roles, activity, CLI, and run-in-terminal sections into modular aios components. 2. Remove dead scaffolding, prove there are no hook/admin bypasses, update docs, and certify side-by-side parity with v2.3. ### Sessions | Session | Name | Purpose | | ------- | --------------------------------------------------- | -------------------------------------------------------------------- | | 01 | Connections, Stats And Long-Tail Sections | Port the remaining lower-risk Hermes sections. | | 02 | Cleanup, Dead-Code Removal And Full Parity Sign-off | Remove dead code, update docs, and validate full Hermes v2.3 parity. | ## Phase 21: Non-Hermes v2.3 Usage Accuracy Phase 21 starts the final non-Hermes v2.3 migration tranche. The detailed phase PRD and session stubs live under `.spec_system/archive/phases/phase_21/` and preserve the source-code anchors, already-done audit, caveats, resolved decisions, and validation requirements from `docs/ongoing-projects/v2_3-port-remaining.md`. This phase owns usage, spend, ROI, daily activity, project-window, and authoritative Claude usage accuracy work. It ports mechanisms from v2.3 while preserving aios's current pricing table, modular `scripts/lib/` aggregate architecture, validators, and privacy posture. ### Objectives 1. Add robust Claude model pricing lookup with exact, family fallback, old 3.x, and unknown-uncounted semantics while keeping current aios prices. 2. Emit real per-day unique-session counts and keep message-count fallback only for old data. 3. Make `recentProjects` a true seven-day window and add long-tail `allProjects`. 4. Restore per-skill default minutes so ROI rows have defensible saved-time estimates. 5. Add authoritative Claude OAuth `/usage` with redaction, timeout, and silent fallback to local estimates. ### Sessions | Session | Name | Purpose | | ------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | 01 | Pricing And Daily Activity Accuracy | Port pricing fallback/null semantics and real per-day session counts with live-data and home-transform support. | | 02 | Project Windows And Skill ROI Defaults | Correct recent/all project windows and port the per-skill minutes default table. | | 03 | Authoritative Claude Usage OAuth | Add a safe OAuth usage reader, aggregate wiring, source labels, redaction, and fallback tests. | ## Phase 22: Non-Hermes Multi-Agent Detection And Home Surfaces Phase 22 completes the multi-agent detection and home-dashboard surfaces from the non-Hermes v2.3 backlog. The detailed phase PRD and session stubs live under `.spec_system/archive/phases/phase_22/` and preserve the Antigravity, setup wizard, and Dream source-strip source anchors from the old ongoing-project document. This phase builds on Phase 21's usage and ROI contracts. It adds Antigravity as a dual-surface local agent signal, wires its usage into existing consumers, adds the Hermes Agent setup wizard card, and ports the home source-status strip for Dream inputs. ### Objectives 1. Detect Antigravity IDE and CLI surfaces independently and emit browser-safe conversation usage plus saved-equivalent value. 2. Add Antigravity usage-panel and home ROI consumers gated on validated data. 3. Add the Hermes Agent card to the setup wizard using existing aios detection. 4. Port `DreamSourcesStrip` as a focused aios home component and selector. ### Sessions | Session | Name | Purpose | | ------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | 01 | Antigravity Detection Data Contract | Extend app detection, live-data types, validators, example data, and tests for Antigravity surfaces and usage. | | 02 | Antigravity Usage Consumers | Add the Antigravity usage-panel row and home ROI saved-equivalent chip. | | 03 | Setup Wizard And Dream Sources Strip | Add the Hermes setup card and Dream source-status strip for Claude Code, Antigravity, Memory, Skills, Integrations, Automations, and Hermes. | ## Phase 23: Non-Hermes Routes, Polish And Closeout Phase 23 completes the non-Hermes v2.3 migration. The detailed phase PRD and session stubs have been archived under `.spec_system/archive/phases/phase_23/` and preserve the remaining Claude Code route, UI polish, optional housekeeping, validation strategy, non-goals, resolved decisions, and no-action audit items from the old ongoing-project document. This phase depends on Phase 19 for the reusable Hermes Mission Control component before adding the Claude Code route. It also applies small UI polish, records optional tooling decisions, and leaves a final validation record proving the old ongoing-project document is no longer required as a source of truth. ### Objectives 1. Add the Claude Code agent route after Hermes Mission Control is available. 2. Apply skill-card hover sheen and sticky sidebar polish. 3. Decide optional `.claude/launch.json` and Hermes file-type art regeneration tooling without re-porting already-present outputs. 4. Preserve skip/no-action decisions and validate final non-Hermes parity. ### Sessions | Session | Name | Purpose | | ------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | 01 | Claude Code Agent Route | Add `/agents/claude-code` by reusing Mission Control and wiring sidebar navigation. | | 02 | UI Polish And Optional Local Tooling | Apply hover sheen and sticky sidebar polish, and record optional tooling decisions. | | 03 | Non-Hermes Parity Documentation Closeout | Validate Phases 21-23, preserve no-action items, update docs, and confirm the old backlog document can be deleted. | ## Phase 24: Trend Finder Outlier Signal Upgrade Phase 24 completed the folded Outlier Lab review preserved in `.spec_system/archive/phases/phase_24/PRD_phase_24.md` into Trend Finder-native capabilities. The detailed phase PRD and session stubs were archived under `.spec_system/archive/phases/phase_24/` and preserve the ordered sessions-based implementation plan, compliance boundaries, source references, and acceptance checks from the old ongoing-project document. This phase improves signal quality, enrichment cost control, operator setup, dense triage, media-safe evidence review, recurring run visibility, and static Brief delivery without copying Instagram/Reels behavior or weakening existing reviewed-source, browser-safety, local bridge, and provenance rules. ### Objectives 1. Add source-local baseline and actionability signals that reduce popularity bias while keeping the existing six-factor score authoritative. 2. Add delta-aware enrichment, retention, pruning, and spend visibility so costly source work is bounded and observable. 3. Add browser-safe evidence asset and file-serving contracts before media preview or static export paths ship. 4. Make reviewed source setup, target lists, scheduler state, first-run status, and live run progress operable from local UI surfaces. 5. Add a dense Signal Workbench with local-only triage state that stays separate from generated Watchlist semantics. 6. Add an opt-in static Brief export, then align docs, in-app Reference mode, tests, and security validation. ### Sessions | Session | Name | Purpose | | ------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | 01 | Source-local Scoring Signals | Add browser-safe relative engagement, promoted/pinned exclusion, actionability bands, and bounded score support. | | 02 | Delta-aware Enrichment And Spend Accounting | Cache and prune costly enrichment, report saved work, and surface bounded spend estimates. | | 03 | Browser-safe Evidence Assets And File Hardening | Add reviewed evidence asset metadata, retention, safe file serving, and asset failure states. | | 04 | Source Setup And Target Configuration | Add local reviewed-source setup and target management without weakening compliance gates. | | 05 | Scheduler First-run And Live Progress Controls | Add scheduler/first-run controls and sanitized live run progress. | | 06 | Signal Workbench And Local Triage | Add dense topic/evidence triage with local-only acted-on, ignored, revisit, and notes state. | | 07 | Static Brief Export | Add an opt-in browser-safe static report export command and docs. | | 08 | Cross-surface Documentation And Reference Mode | Align manuals, in-app Reference mode, and docs tests after feature sessions land. | | 09 | End-to-end Validation And Release Hardening | Validate the full workflow, privacy boundary, generated artifacts, docs, and release readiness. | ## Phase 25: Hermes Mission Control Activation Phase 25 implements the source-verified follow-up plan folded into `.spec_system/PRD/phase_25/PRD_phase_25.md`. The detailed phase PRD and session stubs live under `.spec_system/PRD/phase_25/`. This phase keeps the AI OS Hermes architecture authoritative: thin routes, typed hooks, parser-validated contracts, split read/admin bridge modules, query invalidation, explicit UI states, demo/live parity, and current-gated writes. It restores the product-critical Mission Control affordances from the v2.3 reference without copying the monolith or weakening the local write gate. ### Objectives 1. Fix optimize semantics with explicit preview-to-commit writes. 2. Version mission storage and normalize legacy/v2.3-shaped mission files. 3. Restore safe long-form planning prompts and authorized agent-authored mission creation. 4. Add multi-goal authoring, per-goal `full_prompt` drawers, copy actions, human briefings, active mission rail/progress, archive actions, and Hermes/Claude Code parity. 5. Document the final contract and certify tests, responsive behavior, accessibility, and security posture. ### Sessions | Session | Name | Purpose | | ------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | 01 | Mission Write Contract Preview Commit | Split optimize preview from explicit current-gated commit and fix silent-success behavior. | | 02 | Mission Schema Version Legacy Compatibility | Version mission documents and normalize legacy/v2.3-shaped stores safely. | | 03 | Safe Planning Prompt Authorized Write | Restore long-form planning prompts and an authorized write mechanism without weakening the write gate. | | 04 | Multi-goal Authoring Preview UI | Replace one-goal creation with multi-goal authoring and optimized preview commit/discard. | | 05 | Full Prompt Drawer Copy Briefings | Surface `full_prompt`, copy `/goal` prompts, and render structured human briefings. | | 06 | Active Mission Rail Progress | Add one-goal rail focus, milestone-aligned progress, and stronger execution hierarchy. | | 07 | Mission Archive Actions | Let operators reactivate archived missions through a current-gated set-active path. | | 08 | Claude Code Parity Responsive E2E | Prove feature parity and overflow-safe copied prompt/drawer behavior across Hermes and Claude Code. | | 09 | Documentation Validation Release | Update docs, considerations, security posture, and certify the complete Mission Control activation phase. | ## Phase 26: Knowledge Graph Shared Brain Port Phase 26 ports the Claude OS v2.4 Knowledge Graph line of work (which also includes the later V2.5 "Shared Brain" changelog entry) into the AI OS architecture. AI OS currently reflects the v2.3 baseline. The audited source diff lives at `/home/operator/projects/claudeos/DIFF_V2.3_V2.4.md` and the full new reference tree at `/home/operator/projects/claudeos/claude-os-v2.4/`. The detailed phase PRD and session stubs live under `.spec_system/archive/phases/phase_26/`. The upstream feature wires the external `graphify` tool into the dashboard as a per-project code graph. Upstream concentrates it in three large files (`vite.config.ts`, `src/routes/codegraph.tsx`, `src/components/graphify-graph-3d.tsx`). AI OS keeps its typed, modular, current-gated architecture: thin route, dedicated page adapter, modular components, typed read/admin contracts, registered dev/admin bridge modules under `scripts/lib/`, demo fixtures, and broad tests. AI OS also already ships the 3D force-graph stack (`react-force-graph-3d`, `three`, `memory-graph-3d.tsx`, `graph-types.ts`) from the Phase 18 Mnemosyne constellation, which the new renderer reuses. Confirmed scope: comprehensive (V2.4 + V2.5) live ingest behind the full AI OS write gate plus Shared Brain scripts; AI OS-native `/knowledge-graph` naming with `/__graphify_*` wire paths preserved; and the upstream dormant KG hero CSS/asset wired into a real header. ### Objectives 1. Land typed graph contracts, demo fixtures, and a checked-in AI OS self-graph seed and registry. 2. Add a loopback-only read bridge (registry list with auto-prune, streamed graph reads with path confinement and seed fallback). 3. Add a current-gated ingest/removal bridge that shells graphify/git via argv arrays only, with vendored-deps and node-cap guards and absolute graphPath registry writes. 4. Build the reusable 3D code graph renderer, the `/knowledge-graph` route, the read hook, the wired hero, the gallery, the side rail, the ingest UI, and the connect prompt. 5. Ground Hermes chat against the active graph, port the homepage section, Shared Brain scripts, and the Hermes OAuth-provider setup false-positive fix, then document, validate, and release with parity sign-off. ### Sessions | Session | Name | Purpose | | ------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | 01 | Graph Data Contracts And Seed Fixtures | Typed graph/registry/god-node/savings contracts, demo fixtures, and the AI OS self-graph seed. | | 02 | Graph Read Bridge And Registry Endpoints | Loopback-only registry list (auto-prune) and streamed graph reads with path confinement and fallback. | | 03 | Graph Ingest And Removal Bridge | Current-gated graphify/git ingest and removal with argv-only spawning, guards, and absolute paths. | | 04 | Reusable 3D Code Graph Renderer | Reusable renderer (god nodes, clusters, density, bloom, fly-to, legend) reusing the Mnemosyne stack. | | 05 | Read Hook Route Shell And Project Gallery | Read hook, thin route + page adapter, wired hero header, gallery, 3D panel, side rail, sidebar nav. | | 06 | Ingest UI Connect Prompt And Starter Chips | Current-gated ingest card, copyable connect prompt, and chat-prefill starter chips. | | 07 | Hermes Chat Grounding And Graph Toolset | Ground Hermes chat on the active graph with seed context, chip, and toolsets/yolo forwarding. | | 08 | Homepage Surface Shared Brain Scripts OAuth | Homepage section, setup/ingest scripts, Hermes OAuth-provider setup fix, and graphify-out ignore. | | 09 | Documentation Validation And Release | Docs, full validation (tests, a11y, security, e2e), parity sign-off, and release. | ## Phase 27: Trend Finder Alpha Radar Adoption Phase 27 adopts the objective improvements mapped from the AI Alpha Radar hackathon submission at `/home/operator/projects/aios/EXAMPLES/ai-alpha-radar-submission/` (static judge-facing demo: `public/data.json` data contract, `public/dashboard.html` single-file dashboard, `technical-appendix/` backend notes; its backend pipeline is not included in that repo). The complete improvement map was captured from `docs/ongoing-projects/alpha-radar.md` on 2026-06-12, folded into `.spec_system/archive/phases/phase_27/`, and the ongoing-projects file was deleted in the final session. The phase follows the map's three tiers: Tier 1 exposes already-generated payload data (movement-grouped Brief, hit-rate and Brier calibration, deterministic derived signals and risk flags, data-driven Signal Radar, watching state, cross-source outlier preset); Tier 2 adds snapshot-backed time-series capability (daily sparklines, velocity acceleration/significance, burst, lifecycle stages, convergence detection, dated predictions, Story Log); Tier 3 extends analysis (competitor lens, creator angle pack, demand centers with strictly labeled estimates, theme rollups, per-outlier ideas). New source adapters (Semantic Scholar, Bluesky, Replicate, newsletters) stay deferred on the compliance-first path, and explicit non-goals (X/Twitter, invented point estimates such as `tbts`/`peak_estimate_days`, hotlinked thumbnails, single-creator hardcoding) are recorded in the phase PRD. Trend Finder invariants hold throughout: browser-safe payload boundary, deterministic fallback for every AI stage, compliance-gated sources, and validators that reject invented metrics. ### Objectives 1. Expose movement and retro data already generated each run: movement-grouped Brief, today's pick, confidence bands, hit-rate and Brier calibration. 2. Add deterministic derived signals: saturation, continuous hidden-gem score, consensus ratio, builder/role-share signal, and per-topic risk flags. 3. Make Signal Radar positions data-driven, render topic aliases, add a browser-local watching state, and ship a cross-source outlier preset. 4. Persist daily evidence counts and Hugging Face download counts; publish bounded sparklines and deltas. 5. Upgrade velocity math with acceleration, significance, and burst, each with explicit low-sample unavailable states. 6. Classify absolute lifecycle stages deterministically and wire them into cards, Workbench, and the radar. 7. Detect time-windowed cross-source convergence with per-source first-seen timestamps; render lead-lag and trajectory visuals. 8. Add dated, lifecycle-targeted predictions and a Story Log archive surface with verdict filtering. 9. Extend the Creator Lens with a public competitor list and the analyst with contrarian/plain-language/title angle fields plus per-outlier ideas. 10. Aggregate question-shaped evidence into demand clusters with observed counts and labeled estimates only, plus theme rollups above topics. 11. Document, validate, security-review, release, and delete the migrated `docs/ongoing-projects/alpha-radar.md`. ### Sessions | Session | Name | Purpose | | ------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | 01 | Brief Movement Groups And Calibration Metrics | Movement-grouped Brief, today's pick, confidence bands, hit-rate and Brier calibration from retro archives. | | 02 | Deterministic Derived Signals And Risk Flags | Saturation, continuous gem score, consensus ratio, builder signal, and deterministic risk flag chips. | | 03 | Data-Driven Radar Aliases And Watching State | Meaningful radar axes, alias rendering, browser-local watching state, cross-source outlier preset. | | 04 | Daily Time-Series Persistence And Sparklines | Snapshot-backed daily evidence counts, HF download deltas, bounded 14-day sparklines. | | 05 | Velocity Dynamics Upgrade | Acceleration, statistical significance, and capped burst signal with low-sample guards. | | 06 | Lifecycle Stage Taxonomy | Deterministic absolute stage classifier wired into cards, Workbench, and radar coloring. | | 07 | Convergence Detection And Trajectory Visuals | Time-windowed multi-source convergence, lead-lag timeline, labeled score trajectory. | | 08 | Dated Predictions And Story Log | Target-date lifecycle predictions, target-date retro grading, bounded prediction-history surface. | | 09 | Competitor Lens And Creator Angle Pack | Lens competitor list with collect-time matching; contrarian, plain-language, and title angle fields. | | 10 | Demand Centers | Question-cluster surface from collected discussion evidence with strictly labeled estimates. | | 11 | Theme Rollups And Outlier Ideas | Theme labels with deterministic fallback grouping, per-outlier ideas with enrichment caching. | | 12 | Documentation Validation And Release | Manual updates, full validation, security review, durable deferred decisions, source-file deletion. | ## Phase 28: Trend Finder Trends-Finderz Adoption Phase 28 adopts the objective improvements mapped from the Trends-Finderz reference project at `/home/operator/projects/aios/EXAMPLES/trends-finderz/` (a runnable Next.js/PostgreSQL product with deterministic scoring, real source connectors, scheduled scans, and QA/admin surfaces -- not a static demo). The complete improvement map was captured from `docs/ongoing-projects/trends-finderz.md` on 2026-06-12, folded with full source URLs into `.spec_system/archive/phases/phase_28/`, and the ongoing-projects file was deleted in the final session. Because the mapping was captured before Phase 27 Sessions 05-12 completed, this phase first reconciles against shipped Phase 27 work: it does not re-implement the lifecycle taxonomy, deterministic saturation, risk-flag set, watching state, theme rollups, or sparklines (all shipped in Phase 27), and it resolves the Phase 27 investigate-only embedding-clustering ADR. Its companion file `docs/ongoing-projects/alpha-radar.md` was deleted in Phase 27, so every `alpha-radar.md` cross-reference in the mapping is translated to the Phase 27 session that shipped it. The phase follows the map's four tiers: Tier 1 fixes scoring integrity in already-collected data (cross-source fingerprint dedup, per-signal quality and collection-health counters, scoring calibration version stamp, small-sample confidence dampener); Tier 2 adds derived layers (topic noise gate and visibility bands, per-role aging half-lives and saturation refinement, bounded lifecycle score multiplier and named-contribution breakdown, research-only flag, private-cache retention pruning); Tier 3 adds the decision layer and operator features (action verdicts and consistency QA, Action Queue Brief section, watchlist pin baselines/notes/tags, search palette and dependency-free embeddings, Brief export QA/Markdown/KPI strip); Tier 4 is compliance-gated collection work (reviewed keyword packs with rotation and coverage QA, direct first-party source adapters). Closeout documents, validates, security-reviews, releases, and deletes the migrated source file. Trend Finder invariants hold throughout: browser-safe payload boundary, deterministic fallback for every AI stage, compliance-gated sources, and validators that reject invented metrics. Numeric constants from trends-finderz are starting points requiring recalibration, never portable truths, and persistence/hosting shape is not ported (durable-store direction is owned by `docs/ongoing-projects/sqlite-observation-store-transition-plan.md`). ### Objectives 1. Add cross-source signal identity (URL normalization, content hashes, per-source fingerprints) so syndicated stories stop inflating evidence volume, diversity, and momentum. 2. Compute one cross-source per-signal quality score and publish per-run duplicate-rate and source-coverage counters. 3. Stamp a scoring calibration version into snapshots/predictions, flag cross-version comparisons, and apply a bounded small-sample confidence dampener. 4. Add a deterministic topic noise gate and visibility bands with reason codes and a suppressed-noise summary, keeping the early-hidden-gem rescue. 5. Add per-role aging half-lives and refine the Phase 27 saturation estimate. 6. Feed lifecycle into ranking via a bounded multiplier and surface every post-factor adjustment as a named contribution in the score breakdown. 7. Add a research-only role-composition risk flag and a retention pruning pass over private snapshot and prediction caches. 8. Add per-topic action verdicts with reason codes and an evidence-to-action consistency QA gate, surfaced as an Action Queue Brief section. 9. Extend the browser-local watching pin with a baseline snapshot, drift status, notes, tags, and bounded quality/lifecycle/last-seen metadata where already present. 10. Add a search command palette and dependency-free feature-hash embeddings (resolving the Phase 27 ADR) for ranking, theme clustering, and fallback clustering. 11. Add static Brief export QA with a leak scan, a copy-as-Markdown flow, and a KPI run-summary strip. 12. Introduce compliance-gated keyword packs with scan modes, rotation, and coverage QA, and scope compliance-first direct first-party source adapters. 13. Document, validate, security-review, release, and delete the migrated `docs/ongoing-projects/trends-finderz.md`. ### Sessions | Session | Name | Purpose | | ------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | 01 | Cross-Source Signal Identity And Dedup | URL/content/fingerprint identity, within-source dedup, cross-source syndication awareness; highest-leverage item. | | 02 | Signal Quality Score And Collection Health | One cross-source per-signal quality score; per-run duplicate-rate and "N of M sources" coverage rollups. | | 03 | Calibration Version Stamp And Confidence Dampener | `SCORING_VERSION` stamped into snapshots/predictions with cross-version flags; bounded small-sample dampener. | | 04 | Topic Noise Gate And Visibility Bands | Deterministic genericness/noise gate, visibility bands with reason codes, suppressed-noise summary, gem rescue. | | 05 | Signal Aging Half-Lives And Saturation Refinement | Per-role half-life recency weighting, lifecycle calibration fixtures, and saturation refinement. | | 06 | Lifecycle Multiplier And Named Contributions | Bounded lifecycle score multiplier; `{label, delta, kind}` named-contribution breakdown convention. | | 07 | Research-Only Calibration And Cache Retention | Research-only role-composition risk flag; retention pruning over snapshot and prediction caches. | | 08 | Per-Topic Action Verdicts And Consistency QA | Deterministic act/monitor/review/ignore verdicts with reasons; evidence-to-action consistency gate. | | 09 | Action Queue Surface | Decisions Brief section grouped by verdict with counts/reasons; static export projection; optional preset. | | 10 | Watchlist Pin Baselines, Notes, And Tags | Browser-local pin baseline snapshot with drift, notes, tags, and available quality/lifecycle/last-seen metadata. | | 11 | Search Palette And Deterministic Embeddings | Extension-local command palette; stdlib feature-hash embeddings for ranking, theme and fallback clustering. | | 12 | Brief QA, Markdown Export, And KPI Strip | Static Brief structural/leak QA; copy-as-Markdown flow; compact KPI run-summary strip. | | 13 | Keyword Packs, Rotation, And Coverage QA | Compliance-gated reviewed keyword packs, scan modes, seeded core+tail rotation, per-category coverage QA. | | 14 | Direct First-Party Source Adapters | Compliance-gated direct arXiv/GitHub/RSS/HN paths with readiness checks; Apify declarations kept as fallbacks. | | 15 | Documentation Validation And Release | Manual/Reference updates, full validation, security review, durable deferred decisions, source-file deletion. | ## Phase 29: Trend Finder TrendingAI Comparison Adoption Phase 29 adopts the objective improvements mapped from the TrendingAI vs. Trend Finder feature/capability comparison into Trend Finder. The consolidated comparison plan was captured on 2026-06-18 with every Trend Finder claim re-verified against actual source, not extension docs, and is now folded into the archived phase itself: `.spec_system/archive/phases/phase_29/PRD_phase_29.md` (its "Folded Comparison Plan (Reference)" appendix) plus the per-session stubs are the single source of truth. The comparison found Trend Finder already leads on history, calibration, provenance, scoring rigor, operational surfaces, and privacy, while TrendingAI leads on editorial synthesis quality, reception/sentiment analysis, and single-artifact presentation polish. This phase borrows editorial sharpness and aggregate-safe reception analysis without borrowing TrendingAI's source risk or statelessness. Most sessions add a deterministic derived field that walks the established shape (derive, validate/default, score/cap, sanitize, surface, prove, document), always with a deterministic fallback and validators that reject invented IDs, URLs, dates, source names, and metrics. Two boundaries are explicit. Broader social reach (X/TikTok/Instagram/Bluesky) is a documented non-goal under the current ToS/PII posture, not a collector session; it gets a known-coverage-gap paragraph in Session 01. Podcast media work is split: Session 16 is a compliance/documentation gate only, and Session 17 (podcast-themes implementation) must not start unless Session 16 explicitly approves the source/media boundary. The plan's 17 work sessions (A-Q) map onto Sessions 01-17 in their dependency-respecting order; Session 18 is the documentation/validation/release closeout. ### Objectives 1. Raise editorial copy quality with an anti-AI-trope voice guard, fold a reviewed engagement-farm hype-pattern set into existing noise scoring, and document the social-reach non-goal. 2. Add a deterministic `attentionPattern` axis and a compact polarity/attention grid across the run. 3. Add an aggregate-only `receptionSignal` with a `contested-reception` flag and act-now caps, never reading comment bodies. 4. Add a `corroboration` gate that quarantines single-origin signals distinct from `single-source-signal`, reusing reviewed identity sources. 5. Add bounded per-evidence `evidenceRationale` with weak-evidence omission, and bounded cross-topic substrate narratives validated against real IDs. 6. Add reliability guardrails: retry-once-then-degrade enrichment narration, a required-derived-field closeout gate, and a private source-death baseline alarm. 7. Add current-source Tier 2 lenses: a private seed-candidate review artifact, an industry-events rollup, and a security lens with severity and action items. 8. Add Tier 3 operator polish: static Brief run archival and richness, a One-to-Watch surface, and a pre-run spend/cadence/wall-clock estimate. 9. Gate podcast media work behind a compliance package; Session 16 deferred the boundary, so Session 17 is skipped in Phase 29 pending future source-specific approval. 10. Document, validate, security-review, and release the phase, then mark the consolidated comparison plan's status and keep the social-reach non-goal recorded. ### Sessions | Session | Name | Purpose | | ------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | 01 | Editorial Quick Wins | Anti-AI-trope prompt/fallback/validator guard; reviewed engagement-farm hype patterns; documented social non-goal. | | 02 | Attention Pattern And Polarity Grid | Deterministic `attentionPattern` states and a compact per-topic polarity/attention grid in Trends and Brief. | | 03 | Reception Signal Aggregate-Only | `receptionSignal` from aggregate metrics only; `contested-reception` flag; act-now caps; no comment-body reads. | | 04 | Corroboration Gate | `corroboration` object and `originator-only` caution; score/verdict caps reusing reviewed identity sources. | | 05 | Per-Evidence Rationale | Bounded validator-checked `evidenceRationale` with deterministic fallback and weak-evidence omission. | | 06 | Cross-Topic Substrate Narratives | Bounded run/theme narratives citing >=2 valid topic IDs; deterministic low-confidence fallback. | | 07 | Per-Stage Validation Narration | Retry-once-then-degrade enrichment narration recorded safely in Engine Replay. | | 08 | Required-Derived-Field Closeout Gate | Closeout assertion that ranked topics carry required derived fields before browser/static export. | | 09 | Source-Death Baseline Alarm | Private last-good per-source baseline distinguishing silent source death from a quiet run. | | 10 | Seed-Candidate Review Artifact | Private seed-candidate rows from reviewed evidence only, with collision checks and no auto-mutation. | | 11 | Industry-Events Rollup | Bounded `industry-events` over news adapters requiring two independent publishers, reusing corroboration. | | 12 | Security Lens | `securityRelevance` with severity and action items over existing evidence; Workbench filter and Brief callout. | | 13 | Static Brief Archival And Richness | Optional run-numbered Brief export plus `latest` pointer and denser Brief, media-embed gap intact. | | 14 | One-To-Watch Surface | Forward-looking watch surface over existing prediction/retro/calibration records, no mock accuracy. | | 15 | Pre-Run Estimate | Bounded pre-run spend/cadence/wall-clock estimate in scheduler and run control, no implied hard cap. | | 16 | Podcast Compliance Package | Compliance gate only: explicit approve/defer/reject decision for podcast transcription and retention. | | 17 | Podcast Themes Enrichment | Deferred by Session 16; no Phase 29 implementation deliverable remains. | | 18 | Documentation Validation And Release | Complete closeout: docs/Reference updates, bundled release validation, backlog/session-map status, and carryforward. | Session 18 validation accepted the recorded Reference mode, static Brief, private-artifact, payload/budget, dependency audit, typecheck, test, formatting, e2e, and security/GDPR evidence together. Phase 29 is complete. Phase 30 (AI Rogue Game Extension) is complete and archived. ## Phase 30: AI Rogue Game Extension Phase 30 builds `AI Rogue`, a repo-local AI OS extension that is a real playable roguelike rather than a demo wrapper around old example projects. The game mounts a modern PixiJS v8 runtime inside the existing React/TanStack extension host and connects back to AI OS by turning browser-safe agent telemetry into an in-game currency (`Insight Shards`) and progression system. The durable plan and locked decisions live in `docs/extensions/ai-rogue/plan-2026-06-21.md`, and the first-batch art decisions live in `docs/extensions/ai-rogue/visual-assets.md`. The core loop is: use AI OS and local agents, aggregate browser-safe usage, spend, token, skill, and tool metadata, convert bounded daily activity into currency via a manual claim, spend currency on roguelike upgrades and relics, and play short dungeon runs on `/extensions/ai-rogue/play`. Raw spend stays a capped signal, not the dominant reward source, so the game makes AI OS feel alive without incentivizing wasteful token burn. The locked source weights are 40% completed agent runs and sessions, 25% skill usage diversity, 20% tool-class diversity, 10% capped token or spend signal, and 5% provider readiness and streaks. The phase stays inside current platform constraints: a static compile-time extension registry (no dynamic or remote loading), React 19 / TanStack / Vite 8, a lazily loaded PixiJS chunk kept out of shared app and registry chunks within the 350 KB app / 450 KB watched-vendor / 1250 KB total client JS budgets, the 200 KB per-file media policy, and a local-first privacy boundary where browser saves stay local and no raw prompts, transcripts, commands, private paths, credentials, or logs enter game data. Session 10 recorded the initial release as gate-clean after all required quality checks passed. Phase 34 later fixed the audited default-enable blockers and production-enabled AI Rogue in the browser registry. PixiJS is pinned to the WebGL renderer with `preserveDrawingBuffer: true` so the memory-graph `readPixels` canvas check is reusable; WebGPU and its screenshot-based verification are deferred. Audio, worker simulation, gamepad, pointer lock, collectors, and generated content packs stay deferred until profiling or UX evidence justifies them. ### Objectives 1. Lock product naming, capability declarations, economy weights, renderer constraints, and pixel-art acceptance before runtime work begins. 2. Ship an `ai-rogue` extension whose first screen is a playable roguelike, with Ledger, Loadout, and Settings as supporting surfaces and honest `readGeneratedData` plus `localStorage` capabilities. 3. Prove a lazy PixiJS v8 (WebGL) runtime boundary that mounts, paints, resizes, and disposes cleanly without leaking the engine into shared app or registry chunks. 4. Derive a bounded, explainable `Insight Shards` economy from browser-safe `LiveData`, with manual claims, daily caps, idempotent redemption, and a "why did I earn this?" breakdown. 5. Persist preferences, wallet, ledger, run history, and saves locally with versioned Zod schemas and safe migration that tolerates stale or malformed records. 6. Build a deterministic, renderer-independent dungeon simulation with seeded RNG, FOV/fog, two enemy types, turn-based combat, and a win condition. 7. Integrate simulation, renderer, committed pixel art, controls, and one spendable upgrade into a complete playable run with accessibility controls. 8. Add AI OS-flavored progression depth (skill-linked classes/relics, capped model-flavored resources, expanded content) without changing the privacy boundary. 9. Polish presentation, controls, compact assets, optional audio, and mobile usability while preserving build and media constraints. 10. Validate end to end against all quality gates and make a clear enablement decision, capturing follow-up work for future content, collectors, WebGPU verification, a worker protocol, or expanded progression. ### Sessions | Session | Name | Purpose | | ------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------- | | 01 | Direction And Asset Readiness | Lock naming, economy weights, capability reasons, renderer constraints, and the first pixel-art acceptance checklist. | | 02 | Extension Shell And Routes | `ai-rogue` registration, Play/Ledger/Loadout/Settings surfaces, gated states, and honest capabilities. | | 03 | PixiJS Runtime Boundary | Lazy WebGL runtime mount, ticker loop, disposal, throttling, reduced motion, and bundle-budget evidence. | | 04 | Economy And Ledger | Pure `deriveAiRogueEconomy` transform, weighted/capped blend, manual claim, idempotent redemption, and provenance. | | 05 | Persistence And Save Contracts | Versioned Zod schemas for preferences, wallet, ledger, run history, and saves in localStorage/IndexedDB with reset. | | 06 | Dungeon Simulation Core | Deterministic seeded RNG, world generation, movement, FOV/fog, two enemies, combat, and a win condition. | | 07 | Play Runtime Integration | Wire committed art, render the run, connect lifecycle events, and add one wallet-backed upgrade plus accessibility. | | 08 | Progression Depth | Skill-linked classes/relics, capped model-flavored resources, expanded content, and local run history/achievements. | | 09 | Content Polish And Mobile | Reviewed atlases, optional Web Audio, seed sharing, mobile/pointer-first layout, and asset/readability validation. | | 10 | Quality Gates And Enablement | Full gate run, docs/privacy/provenance verification, enablement decision, and recorded follow-up work. | Phase 30 is gated: enable-by-default is blocked until `bun run typecheck`, `bun run lint`, `bun run format:check`, focused Vitest and Playwright suites, `bun run build`, `bun run budget:check`, `bash scripts/check-asset-sizes.sh`, and `bun run runtime:check-private` all pass, and no non-goal (remote loading, unbounded token-burn rewards, unreviewed large media, or raw private telemetry exposure) has slipped into the slice. Session 10 validation passed all required gates for the first release. Phase 30 is complete and archived as of 2026-06-22. Phase 34 later completed the default-enablement decision and made AI Rogue production-enabled by default. ## Phase 31: Cloudflare Pages Public Demo Phase 31 creates a public-safe Cloudflare Pages demo for AI OS. The demo reuses the real React/TanStack Start route tree and extension surfaces while replacing local runtime reads with curated, committed, browser-safe snapshot assets. The canonical planning source is archived under `.spec_system/archive/phases/phase_31/PRD_phase_31.md`, with session-specific details in `.spec_system/archive/phases/phase_31/session_*.md`. The phase keeps the existing Cloudflare Workers deployment path intact. The Pages demo is a separate static build under `demo-website/`, not a forked React application and not a migration of root `wrangler.jsonc`. Demo-pages mode must emit static HTML, copy or serve committed `/demo/*` snapshot assets, include Pages `_redirects` and `_headers`, and document Cloudflare Pages settings such as `BUN_VERSION=1.3.14`. The hosted behavior is read-only. Public demo mode must not call `/__live-data`, `/__time-saved-config`, `/__token`, refresh/run endpoints, Trend Finder source setup or asset bridge endpoints, Knowledge Graph ingest/remove endpoints, Hermes/OpenClaw admin endpoints, setup write flows, local schedulers, hosted collectors, chat uploads, or any local bridge beginning with `/__`. Trend Finder, Knowledge Graph, Hermes, Claude Code, OpenClaw, and AI Rogue remain visible, but unsafe behavior renders as read-only, unavailable, or browser-local only. ### Objectives 1. Add a public demo build mode that emits static Pages-compatible output without weakening the normal Worker build. 2. Create a deterministic, allowlist-first snapshot exporter and committed public-safe fixtures. 3. Make AI OS host routes, agent routes, Trend Finder, Knowledge Graph, and AI Rogue render from frozen demo state without local bridge requests. 4. Produce `demo-website/dist` with static routing, headers, snapshot assets, and Cloudflare Pages setup documentation. 5. Prove the demo route matrix, privacy scans, no-bridge network behavior, and release documentation before public use. ### Sessions | Session | Name | Purpose | | ------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 01 | Demo Mode Foundation | Add shared public demo mode detection, keep it distinct from `isExample`, skip the Worker plugin in demo-pages mode, enable static TanStack output, and force all registered extensions visible in demo mode. | | 02 | Snapshot Exporter And Fixtures | Create `demo-website/`, add a local-only allowlist-first snapshot exporter, commit public demo fixtures and metadata, and test redaction of private runtime fields. | | 03 | App Data And Mutation Boundary | Fetch frozen `/demo/*` data in public demo mode, suppress setup auto-open, use snapshot/default overlays, and disable local refresh, scheduler, setup, source, ingest, chat, upload, and admin mutations. | | 04 | Extensions And Agent Routes | Force agent and Knowledge Graph demo/read-only routes, make Trend Finder read from snapshots or fixtures, replace asset bridge URLs, and verify AI Rogue remains browser-local. | | 05 | Pages Build And Deployment Scaffold | Add Pages build/preview scripts, static `_redirects` and `_headers`, generated-only `demo-website/dist`, and Cloudflare Pages setup documentation. | | 06 | Demo QA And Privacy Verification | Add Pages route smoke tests, assert no `/__*` requests, run build/preview/typecheck/focused tests, and scan committed fixtures plus generated output. | | 07 | Release Polish And Documentation | Add frozen-snapshot provenance, tune demo content, polish unavailable states and mobile routes, review bundle budget, and update deployment docs. | Phase 31 succeeds when `bun run demo:build:pages` creates `demo-website/dist/index.html`, the output contains `_redirects`, `_headers`, and `/demo/*` assets, all planned public routes render from static preview, no route requests `/__*`, and scans find no local paths, secrets, credential labels, auth material, token/key-shaped strings, raw prompts, transcripts, command output, private memory text, or local bridge URLs. Session 07 validation passed all required release gates and documented the final Pages demo posture as static-only, public-safe, and separate from the existing Worker deployment path. Phase 31 is complete and archived as of 2026-06-24. ## Phase 32: AI Rogue Mobile Input Auto-Detect Phase 32 fixes the AI Rogue first-run mobile gameplay failure reproduced during Session 01 baseline validation. Before the fix, fresh mobile sessions could start a run, but the saved preference default was keyboard-first, compact controls were disabled, and canvas pointer movement was ignored outside compact mode. The phase adds a durable `auto` input preference, resolves it at the mounted browser UI boundary, and passes only a concrete effective mode into the runtime. Explicit user choices remain authoritative. At the time of Phase 32, AI Rogue remained opt-in; Phase 34 later production-enabled it after the closeout gates. This phase did not add hosted writes, collectors, or weaken the static public-demo boundary. Detailed phase artifacts live under `.spec_system/archive/phases/phase_32/`. ### Objectives 1. Validate the reported mobile failure and the pointer/hover capability signal. 2. Add durable `auto` preferences while preserving explicit Keyboard and Compact choices. 3. Wire an effective `keyboard | compact` mode through Play and Runtime Canvas. 4. Align Settings, Loadout, Play, compact controls, and HUD copy. 5. Add fresh-state mobile and public-demo gameplay coverage proving first-run movement. ### Sessions | Session | Name | Purpose | | ------- | ---------------------- | ---------------------------------------------------------------------------------------------------- | | 01 | Baseline Validation | Reproduce the fresh mobile failure and validate capability signals before code implementation. | | 02 | Preference Contract | Add durable Auto preferences, effective-mode types, resolver/hook, and schema/migration tests. | | 03 | Effective Mode Wiring | Route effective mode through Play, Runtime Canvas mount/update calls, compact controls, and tests. | | 04 | Settings And Copy | Add Auto controls UI and make Settings, Loadout, Play, and HUD copy match raw/effective mode. | | 05 | Gameplay Test Coverage | Add fresh-state mobile, desktop, runtime, and public-demo gameplay coverage for Start plus movement. | Phase 32 succeeds when fresh mobile/coarse-pointer sessions with no preferences can press Start and move on the first run, fresh desktop sessions remain keyboard-first, explicit Keyboard and Compact choices override Auto, runtime APIs never receive raw `auto`, and public-demo mobile smoke covers `/extensions/ai-rogue/play` gameplay without local bridge requests. Phase 32 is complete and archived as of 2026-06-25. Session 05 closed the phase with fresh mobile/touch, desktop/fine-pointer, Runtime Canvas, and public-demo gameplay coverage for raw Auto defaults, concrete runtime input modes, explicit overrides, Start plus movement, and no local bridge requests in hosted-demo smoke. ## Phase 33: Cloudflare Pages Real Product Fixtures Phase 33 refreshes the static Cloudflare Pages demo with frozen, public-safe copies of real local Trend Finder and Dream Review output. It builds on the Phase 31 static demo boundary and the self-contained Phase 33 PRD/session artifacts. The phase keeps Pages static-only: committed fixtures power the hosted site, while collectors, schedulers, account auth, local bridge reads, Dream runtime, source setup writes, uploads, analytics, and admin mutations stay local-only. The work focuses on better product proof, not on hosted runtime behavior. Detailed phase artifacts live under `.spec_system/archive/phases/phase_33/`. ### Objectives 1. Capture reviewed local Trend Finder and Dream Review output for demo use. 2. Freeze the selected output into committed public fixtures. 3. Preserve useful Trend Finder run artifacts while keeping references coherent. 4. Add a small public-safe Dream Review projection. 5. Polish hosted demo copy and disabled-runtime states. 6. Scan, build, smoke-test, and deploy the updated Pages demo. ### Sessions | Session | Name | Purpose | | ------- | ------------------------------ | --------------------------------------------------------------------------------------------------------- | | 01 | Capture Local Demo Runs | Produce and review the local Trend Finder and Dream Review payloads selected for the public demo. | | 02 | Freeze Public Fixtures | Convert the reviewed local payloads into deterministic committed Pages fixtures and metadata. | | 03 | Harden Trend Finder Projection | Preserve useful Trend Finder demo artifacts with schema-valid provenance and coherent bounded references. | | 04 | Harden Dream Projection | Add an allowlisted Dream Review projection with positive and negative privacy coverage. | | 05 | Polish Public Demo UI States | Make public demo UI states read as frozen real product output with hosted runtime disabled. | | 06 | Scan Build And Deploy | Run fixture, scan, budget, build, route-smoke, and Cloudflare deployment verification gates. | Phase 33 succeeds when the hosted Pages demo shows realistic frozen Trend Finder and Dream Review output, no private data or local paths leak into fixtures or dist, public routes make no `/__*` bridge or mutation requests, and deployment verification records the final Pages URL, branch, source commit, and route HTTP status results. Phase 33 is complete and archived as of 2026-06-25. Session 06 closed the phase by refreshing the public demo snapshot from source commit `7681a517980f`, rebuilding and scanning static Pages output, passing budget, type, lint, format, unit, desktop, and mobile route-smoke gates, deploying to Cloudflare Pages, and verifying hosted routes, metadata, source commit, and no local bridge requests. ## Phase 34: AI Rogue Audit Remediation Phase 34 resolves the default-enablement blockers and refactor prerequisites from the completed AI Rogue comprehensive audit. The historical audit findings were later folded into `.spec_system/archive/phases/phase_35/PRD_phase_35.md` and the Phase 35 session stubs, backed by the migrated audit execution record in `.spec_system/archive/phases/phase_34/PRD_phase_34.md`. The phase fixes the blockers required to flip AI Rogue to production default-enabled status: accessibility, simulation correctness, debug-scenario exposure, renderer lifecycle, runtime ownership, persistence/schema contracts, performance pressure, audio/doc drift, and validation evidence while preserving the local-only state and static public demo boundaries. Detailed phase artifacts live under `.spec_system/archive/phases/phase_34/`. ### Objectives 1. Add characterization coverage before changing high-risk AI Rogue runtime, simulation, renderer, persistence, accessibility, and compact-input paths. 2. Fix the audit's default-enablement blockers: dynamic accessible runtime summary, lethal turn-start status handling, production combat scenario gate, and transient Pixi sprite retention. 3. Narrow runtime ownership so run-state transitions flow through simulation APIs and durable save/claim contracts flow through schema-owned helpers. 4. Reduce renderer hot-loop, resize, media-query, platform-fallback, and audio/doc drift risk without adding remote loading or hosted game state. 5. Re-run the complete AI Rogue, Pages demo, privacy, budget, and release gates and record the production default-enablement decision. ### Sessions | Session | Name | Purpose | | ------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | 01 | Characterization Test Harness | Add pre-fix regression coverage for lethal DOT, assistive summaries, sprite bounds, claim normalization, and saves. | | 02 | Accessibility And Compact Input | Surface dynamic runtime summaries and complete compact Inspect/Next target and Large HUD behavior or removal. | | 03 | Simulation Correctness And Scenario Gate | Centralize lethal turn-start status handling and remove or gate the production combat fixture scenario. | | 04 | Renderer Lifecycle And Robustness | Bound transient Pixi resources and harden resize, reduced-motion media-query, setup-failure, and audio fallbacks. | | 05 | Runtime API Ownership | Move pre-run upgrade/loadout mutation into simulation APIs and narrow runtime barrel entrypoints. | | 06 | Persistence Schema Contracts | Normalize direct claim writes and rename/hydrate durable runtime snapshot contracts through schema helpers. | | 07 | Render Performance And Audio Docs | Cache or bound render-model hot-loop work and reconcile audio ducking/media-policy documentation. | | 08 | Default Enablement Evidence Closeout | Run full quality gates, update docs/security notes, and publish the renewed AI Rogue enablement recommendation. | Phase 34 succeeds when every high-priority audit blocker has either been fixed with focused coverage or explicitly carried as a documented non-go condition, all changed paths preserve AI Rogue browser-local state and static Pages demo safety, and the full closeout gate set is recorded before production default enablement. Phase 34 is complete and archived as of 2026-06-26. Session 08 closed the phase by rerunning the full AI Rogue and public-demo gate matrix, recording targeted privacy and boundary scans, and publishing the Production Go recommendation that now backs browser-registry default enablement. ## Phase 35: AI Rogue Audit Hardening And Refactor Phase 35 uses the folded AI Rogue audit source embedded in `.spec_system/archive/phases/phase_35/PRD_phase_35.md` and routed through the Phase 35 session stubs as the source plan for post-audit hardening. Phase 34 closed the original production default-enable blockers and made AI Rogue visible by default; Phase 35 turns the remaining audit backlog into a structured implementation/refactor phase that keeps the production default, local-only game state, static Pages demo boundary, and D3 privacy posture intact. The phase starts by rebaselining which findings are live versus historical, then locks fixed blocker contracts with regression evidence, finishes any remaining accessibility/control coverage, hardens renderer and storage failure paths, narrows runtime and simulation ownership, splits broad renderer and world/type modules, syncs current audio/media docs, and ends with the full AI Rogue and Pages release gate matrix. Detailed phase artifacts live under `.spec_system/archive/phases/phase_35/`. ### Objectives 1. Reconcile the production-enabled closeout with the historical finding register and identify stale versus live follow-up items. 2. Preserve direct regression coverage for the original default-enable blockers and fixed schema/runtime ownership contracts. 3. Finish accessible runtime summary, compact/touch controls, Large HUD, mobile, renderer fallback, audio fallback, resize, and storage failure coverage. 4. Refactor AI Rogue simulation, renderer, persistence, world, and type ownership boundaries only after the relevant contracts are protected. 5. Sync AI Rogue docs with current Web Audio/media policy and final release evidence, preserving no-new-D3 privacy boundaries. ### Sessions | Session | Name | Purpose | | ------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | 01 | Rebaseline Audit Evidence | Reconcile live and historical findings, default enablement evidence, D3 boundaries, stale gaps, and active caveats. | | 02 | Fixed Blocker Regression Coverage | Verify or add direct guards for original blockers, schema-owned claims/hydration, and simulation-owned pre-run state. | | 03 | Runtime Accessibility Controls | Finish screen-reader, compact/touch Inspect/Next target, Large HUD, and mobile accessibility behavior or removals. | | 04 | Renderer Robustness And Scheduling | Coalesce resize work and harden matchMedia, WebGL/Pixi, asset-load, AudioContext, decode, and dispose fallbacks. | | 05 | Persistence Schema Contracts | Stabilize wallet, ledger, save-slot, migration, reset, idempotency, and storage-failure contracts. | | 06 | Simulation Ownership Refactor | Narrow runtime public APIs, isolate fixtures, and move run-state mutation fully behind simulation transitions. | | 07 | Renderer And React Bridge Refactor | Split renderer, effects, render-model, audio adapter, runtime hooks, controls, and assistive summary ownership. | | 08 | World Types And Fixture Cleanup | Split broad world/type modules and protect deterministic generation, fixture parser, barrel, and compile boundaries. | | 09 | Documentation And Media Policy Sync | Align AI Rogue docs with current Web Audio, media caps, no-ducking reality, production default, and local state. | | 10 | Final Release Gate | Run the full app, AI Rogue, Pages, privacy, budget, asset, playthrough, and release evidence gate matrix. | Phase 35 succeeds when the live audit backlog is unambiguous, each retained blocker contract has direct coverage or documented evidence, refactors preserve AI Rogue behavior and boundaries, current docs match source, and the final gate matrix either passes or records a concrete No-Go blocker. ## Phase 36: AI Rogue Audio Asset Finishing Phase 36 folds the former AI Rogue media-finishing audio plan into executable spec-system session stubs. The phase validates the current 45-cue AI Rogue audio baseline, adds typed metadata for enemy-family audio routing, generates and wires enemy and boss identity cues, defines and implements sector theme audio, optionally adds adaptive stingers after the runtime contract is clear, and closes with provenance, media-policy, browser, and validation evidence. The phase preserves the Phase 35 Production Go posture, browser-local AI Rogue state, static Pages public-demo boundary, no remote game-content loading, autoplay unlock behavior, mute and volume preferences, deterministic simulation behavior, and silent fallback behavior. Detailed phase artifacts live under `.spec_system/archive/phases/phase_36/`. ### Objectives 1. Validate the current title, music, SFX, unlock, mute, volume, and silent fallback behavior in desktop and mobile browser review. 2. Add typed audio-routing metadata for enemy-family and boss cues without making audio selection affect simulation state or replay behavior. 3. Generate, optimize, document, and wire enemy-family and boss SFX within media policy and provenance requirements. 4. Define theme-aware audio routing and add sector identity assets keyed by `snapshot.theme`. 5. Add adaptive stingers only after the engine contract is explicit, tested, and accepted by playtesting. 6. Reconcile AI Rogue audio docs, media policy, provenance, and final validation evidence. ### Sessions | Session | Name | Purpose | | ------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------- | | 01 | Current Audio Balance Audit | Validate the current 45-cue audio pack in browser and record cue balance, fatigue, unlock, or routing gaps. | | 02 | Enemy Audio Metadata | Add typed runtime metadata needed for enemy-family audio routing while preserving deterministic state. | | 03 | Enemy And Boss SFX Pack | Generate, optimize, document, and wire family-specific enemy and boss cues. | | 04 | Theme Audio Routing Contract | Define and implement theme-aware music or ambience routing keyed by sector theme. | | 05 | Sector Theme Audio Pack | Generate, optimize, document, and wire the selected sector theme ambience or music assets. | | 06 | Adaptive Music Engine Expansion | Add the minimal runtime support needed for adaptive stingers without destabilizing existing audio behavior. | | 07 | Adaptive Stinger Pack | Generate, document, and wire adaptive stingers after the engine contract is in place. | | 08 | Final Audio Validation And Docs | Run the full audio validation matrix and reconcile documentation after asset and engine work. | Phase 36 succeeds when the audio baseline has browser-reviewed balance notes, enemy and theme audio identities are typed, routed, tested, optimized, and documented, adaptive stingers are either implemented through a tested contract or explicitly deferred with evidence, all committed audio files have provenance, asset-size checks pass, and no hosted runtime, public-demo, privacy, remote-loading, or deterministic-simulation boundary is widened. Phase 36 is complete and archived as of 2026-06-28. Session 08 closed the phase by rerunning the full audio validation matrix, recording operator-approved desktop and mobile manual listening, confirming provenance for all 11 music/ambience files and all 64 SFX/stinger files, passing focused runtime tests and Playwright route checks, syncing game-feel and media-policy docs, and preserving local-only AI Rogue safety boundaries. Phase 38 has since been created from the Claude OS v2.7 to v2.8.1 manual port plan. ## Phase 38: Claude OS v2.8.1 Semantic Port Phase 38 ports every relevant Claude OS v2.7 to v2.8.1 upstream change into the diverged AI OS codebase as a semantic feature port rather than a file replacement. The canonical folded implementation plan now lives in `.spec_system/archive/phases/phase_38/PRD_phase_38.md` and its ten session stubs. The phase keeps AI OS architecture as the base: script helpers remain under `scripts/lib/**`, Dream execution remains owned by AI OS runners, setup and engine settings use AI OS config/path conventions, Hermes chat continues through the existing bridge and SSE backend, and local control-plane endpoints preserve loopback, token, Host-header, body-size, and path-safety guards. Resolved policy for this phase is fixed: adopt upstream v2.8.1 license terms; use upstream OpenAI Realtime as the default voice path while honoring `OPENAI_BASE_URL`; adapt storage to current AI OS settings and paths; use AI OS Dream config and runners as the base while porting upstream controls; keep AI OS model defaults while adding upstream model names as optional selections where provider readiness supports them. ### Objectives 1. Port Tier 0 correctness fixes for Memory counts, seed data, and Hermes graph/yolo chat semantics. 2. Add shared platform helpers and Windows-aware aggregate, Dream scheduling, setup, and runtime bridge behavior through AI OS modules. 3. Align license, docs, changelog, executable modes, and model catalogs with shipped behavior and resolved policy. 4. Add Dream engine selection, the OpenAI Realtime voice broker, and the Hermes Intelligence portal through existing AI OS product surfaces. 5. Close the phase with hunk-by-hunk reconciliation for every upstream changed path and full release-gate verification. ### Sessions | Session | Name | Purpose | | ------- | ------------------------------------ | ---------------------------------------------------------------------------------------------- | | 01 | Tier 0 Parity Fixes | Ship low-risk Memory, seed-data, and Hermes graph/yolo correctness fixes. | | 02 | Platform Foundation | Establish shared cross-platform path, app-data, CLI, and venv helper logic. | | 03 | Aggregate and Dream Health | Add Windows-aware aggregation and surface Dream health metadata through live data. | | 04 | Dream Scheduling and Setup | Add Windows Dream scheduling and readiness-aware setup guidance. | | 05 | Runtime Bridge Hardening | Make Hermes, Graphify, Dream, and Vite local endpoints platform-safe and Host-header hardened. | | 06 | Policy, Docs, and Catalogs | Adopt resolved license/docs/model/catalog policy and align docs with shipped endpoints. | | 07 | Dream Engine Product Integration | Add durable Dream engine selection and health-aware dashboard generation. | | 08 | Voice Broker | Add the local OpenAI Realtime token broker path with `OPENAI_BASE_URL` support. | | 09 | Intelligence Portal | Wire the Hermes Intelligence portal and voice loop to the existing Hermes chat backend. | | 10 | Hunk Reconciliation and Release Gate | Prove every upstream changed path and hunk has a disposition and run final release gates. | Phase 38 succeeds when all 10 sessions are validated, no open-decision markers remain in docs, every shipped feature proves the user's intended outcome end to end with real execution, visible results, recovery paths, and tests, voice and Intelligence features use real configured backends, every upstream changed path has a recorded disposition, and lint, build, targeted tests, docs sweeps, and security checks pass or document exact non-port blockers. Phase 38 is complete and archived as of 2026-06-30. Session 10 closed the phase by recording dispositions for all 39 upstream changed paths, reconciling 99 modified-file hunks, correcting stale release-copy claims, preserving Phase 38 policy metadata, passing the full static, test, browser, privacy, and security gates, and documenting Linux-local limitations for unavailable real Windows and provider-credential proof. ## Phase 37: AI Rogue Visual Asset Finishing Phase 37 folds the remaining AI Rogue visual asset plan into executable spec-system PRD and session stubs. It uses the generated G3-G8 visual source sheets to select, crop, clean, pack, wire, test, document, and browser-validate the remaining runtime visual improvements: combat/status/fog/accessibility FX, status and equipment icons, Kernel Sentinel and final-defense presentation, sector theme decals, UI/cinematic icons, and the player animation ship-or-redraw decision. The phase preserves the Phase 35 Production Go posture, browser-local AI Rogue state, static Pages public-demo boundary, no remote game-content loading, deterministic simulation behavior, reduced-motion and high-contrast equivalence, committed asset-size policy, and the existing two-atlas model unless size evidence requires a later reviewed expansion. Proper delivery for this phase means every shipped visual feature proves the user's intended outcome end to end in the product, with real runtime execution, visible results, preference or fallback recovery paths where applicable, and tests. Scaffolding, typed frame names, atlas JSON, or docs that look complete are not enough unless the visuals render in AI Rogue and the acceptance evidence shows the user-facing outcome. Detailed phase artifacts live under `.spec_system/archive/phases/phase_37/`. ### Objectives 1. Pack and wire G8 combat, status, fog, high-contrast, and reduced-motion visual frames that materially improve runtime readability. 2. Finish the remaining G4 status, equipment, reward, loadout, ledger, and settings icon opportunities without disturbing already-wired system-object frames. 3. Upgrade Kernel Sentinel and final-defense presentation while keeping boss logic, footprint, pathing, and win conditions unchanged. 4. Add sector theme identity through additive G3 decals and a small number of tile variants while preserving world-generation rules. 5. Use G6 UI and cinematic icons only where they improve domain-specific readability over standard controls. 6. Review G7 player animation at 16x16 and either wire it with evidence or record it as redraw reference. ### Sessions | Session | Name | Purpose | | ------- | -------------------- | ---------------------------------------------------------------------------------------------------------- | | 01 | G8 Runtime FX | Pack and wire combat, status, fog, high-contrast, and reduced-motion visuals with runtime proof. | | 02 | G4 Status Equipment | Finish status/equipment/reward/loadout icon visuals without disturbing wired system-object frames. | | 03 | G5 Boss Presentation | Upgrade Kernel Sentinel and final-defense visuals while preserving gameplay logic and footprint. | | 04 | G3 Theme Decals | Add additive sector decals and tile variants while preserving world-generation rules. | | 05 | G6 UI Cinematics | Add generated UI and cinematic visuals only where they improve domain-specific readability. | | 06 | G7 Player Animation | Decide whether generated player animation ships at 16x16 and wire it only if runtime evidence supports it. | Phase 37 succeeds when each accepted visual batch has crop-manifest decisions, refreshed atlas outputs, typed required frame names, runtime or React mappings, focused tests, updated visual asset docs, passing asset-size validation, and desktop/mobile browser evidence that the visual outcome is actually visible in AI Rogue without widening simulation, privacy, public-demo, remote-loading, or accessibility boundaries. Phase 37 is complete and archived as of 2026-06-29. Session 06 closed the phase by generating the 16x16 G7 player downscale review, rejecting direct runtime use of the generated G7 player sheet as redraw reference, recording 32 rejected G7 player manifest entries with zero accepted G7 player frames, preserving the existing stable player frame contract and atlas outputs, passing full Vitest, focused Vitest, desktop/mobile Playwright, typecheck, lint, asset-size, JSON, manifest-invariant, security, behavioral, and UI product-surface checks, and preserving local-only AI Rogue safety boundaries. The next workflow step is `audit` because the workflow is entering Phase Transition. ## Phase 39: AI Rogue Level Authoring Infrastructure Phase 39 turns AI Rogue level expansion from a cross-cutting set of depth branches into a typed, registry-backed authoring workflow. The canonical planning source and executable phase artifacts live under `.spec_system/archive/phases/phase_39/`. The phase starts by locking the current three-floor run with baseline and golden determinism tests, then adds a level registry, routes depth resolvers through level specs, adds registry and save-schema parity gates, proves the workflow with a reused-media fourth floor, and hardens enemy metadata, asset validation, audio routing, boss/finale contracts, documentation, and final validation. The phase preserves browser-local AI Rogue state, static public-demo safety, no remote game-content loading, route-lazy PixiJS ownership, deterministic simulation behavior, asset-size policy, and schema-backed save boundaries. ### Objectives 1. Add behavior-preserving baseline and golden determinism coverage for depth 1-3. 2. Add a typed `runtime/content/` level registry and validation layer. 3. Route depth helpers and world generation through level specs without changing shipped behavior. 4. Add registry and save-schema parity checks before expanding content. 5. Prove the workflow with a reused-media fourth floor. 6. Move enemy audio/frame requirements and boss/finale behavior into metadata. 7. Close with validation evidence, documentation, privacy, asset, audio, and bundle-budget hardening. ### Sessions | Session | Name | Purpose | | ------- | --------------------------------------- | ------------------------------------------------------------------------------------ | | 01 | Baseline And Registry Skeleton | Add behavior-preserving tests and the dead-but-tested level registry. | | 02 | Depth Resolver Migration | Route current depth-based runtime decisions through level specs. | | 03 | Registry Validation And Save Parity | Make malformed specs and save-schema ID drift fail fast. | | 04 | Existing-Media Floor Four | Prove authoring by adding a fourth floor that reuses existing media and IDs. | | 05 | Enemy Metadata And Derived Asset Checks | Move enemy audio and frame requirements into data-backed validation. | | 06 | Boss And Finale Contracts | Generalize Kernel Sentinel into a reusable boss/finale contract. | | 07 | Real Content Expansion Path | Add one real content path through catalogs, specs, and focused tests. | | 08 | Validation And Documentation Hardening | Run gates, update docs, and confirm privacy, save, asset, audio, and bundle posture. | Phase 39 succeeds when all 8 sessions are validated, current depth 1-3 behavior remains covered and unchanged, authored floors are driven by level specs, malformed registry or save IDs fail tests, a reused-media fourth floor proves the workflow, enemy and boss content requirements are metadata-backed, and documentation plus validation evidence match shipped behavior. ## Phase 40: Claude OS v2.10.1 Semantic Port Phase 40 ports the actionable Claude OS 2.9, 2.10, and 2.10.1 Hermes changes into AI OS without copying upstream monolithic route or Vite middleware files. The canonical planning source is now folded into the Phase 40 PRD and session stubs under `.spec_system/PRD/phase_40/`. The phase is a semantic port: model contracts, command execution, MoA saving, connection probes, model catalog data, chat UI, Ministry, voice parity, assets, docs, and validation are translated into the current split Hermes bridges, hooks, schemas, and components while preserving AI OS product identity and local-only privacy boundaries. The phase preserves loopback, Host-header, same-run token, admin, body-size, schema, timeout, safe-error, public-demo, media-policy, graph-storage, environment-only secret, and no-raw-private-output constraints. ### Objectives 1. Rebaseline upstream 2.9 through 2.10.1 deltas and lock AI OS port invariants before implementation. 2. Expand Hermes model, provider, chat, command, MoA, and connection bridge contracts with parser and redaction coverage. 3. Port model catalog, context metadata, Ministry model intelligence, pricing provenance, and compliant visual assets. 4. Add the chat model selector, context meter, command menu, compact flow, copy replies, thinking state, and narrowed warning filter. 5. Integrate Ministry into Pantheon with valid MoA config generation, analytics, and current-gated save UX. 6. Verify voice no-reprompt parity through AI OS environment-backed broker behavior without browser key persistence. 7. Close with honest docs, metadata/gitignore decisions, full validation, and not-ported rationale. ### Sessions | Session | Name | Purpose | | ------- | --------------------------------------- | ------------------------------------------------------------------------------------ | | 01 | Baseline And Port Invariants | Confirm upstream delta, local state, and non-negotiable AI OS port boundaries. | | 02 | Models And Provider Readiness | Expand model response parsing and configured-provider readiness safely. | | 03 | Shared Redaction Foundation | Establish reusable bridge-output redaction before new browser-visible output paths. | | 04 | Chat Overrides And Runtime | Add per-chat model/provider overrides and upstream-inspired streaming safeguards. | | 05 | Command Endpoint | Add token/current-gated deterministic Hermes command execution. | | 06 | MoA Save Endpoint | Add safe local persistence for Ministry MoA presets. | | 07 | Connection Probe Parity | Port useful safe Hermes connection probes with bounded no-output execution. | | 08 | Catalog And Context Metadata | Refresh Hermes catalog and context metadata while preserving AI OS aliases. | | 09 | Model Intelligence And Pricing | Add Hermes-scoped Ministry model rows and local-live pricing provenance. | | 10 | Assets And Media Compliance | Rehome required vendor visuals and create compliant Ministry visual assets. | | 11 | Chat Model Selector And Context Meter | Add split chat selector and context meter components. | | 12 | Compact And Chat Polish | Add compact flow, reply copy, thinking timer, and narrowed startup-warning handling. | | 13 | Command UX And Slash Actions | Add command menu and slash actions on top of the command endpoint. | | 14 | Ministry Builder And Pantheon | Integrate Ministry builder into Pantheon without regressing persona workflows. | | 15 | Ministry Config, Analytics, And Save UX | Complete MoA config generation, analytics, and direct save UX. | | 16 | Voice Parity And Broker Respawn | Verify no-unnecessary-reprompt behavior while preserving environment-backed secrets. | | 17 | Docs, Metadata, And Gitignore Closeout | Update docs and repository metadata only after matching behavior ships. | | 18 | Full Validation And Handoff | Run focused and broad validation, smoke key paths, and record final handoff. | Phase 40 succeeds when all 18 sessions are validated, actionable upstream Hermes changes are implemented or explicitly marked not ported with rationale, bridge contracts and UI behavior are tested, model/pricing/asset provenance is clear, voice parity preserves secret handling, docs describe shipped AI OS behavior only, and no private generated data or secret-shaped strings are committed. ## Phase 41: Hermes All-Access Remediation Phase 41 implements the current local access default across AI OS local operator surfaces. The canonical planning source is the folded Phase 41 PRD and executable session stubs under `.spec_system/PRD/phase_41/`. This phase removes legacy limited-access and manual admin opt-in posture from normal local execution. `AI_OS_LOCAL_ALL_ACCESS=1` is the canonical positive contract for local startup. Legacy `HERMES_DASHBOARD_ADMIN` and `OPENCLAW_DASHBOARD_ADMIN` keys may remain only as compatibility aliases whose absence does not block shipped local writes, edits, process actions, deploy or spawn actions, voice actions, Intelligence actions, or local-agent execution. The phase preserves local control-plane security controls: loopback, Host-header, same-run token, schema, body-size, timeout, safe-error, redaction, no-shell argv, and path confinement remain automatic defenses. Those controls must produce visible recovery paths when they fail; they must not become the normal local product posture. ### Objectives 1. Make normal local startup paths establish all-access readiness before Vite middleware and product routes evaluate capability. 2. Convert Hermes bridge, route, hook, shell, mutation, Voice, and Intelligence behavior to local all-access execution with real recovery paths and tests. 3. Convert Knowledge Graph, OpenClaw, Claude Code, and local-agent behavior to real write/edit/action execution wherever capabilities are shipped. 4. Separate public demo, hosted privacy, source-compliance, credential-probe, offline, and dependency failures as named exceptions rather than local product posture. 5. Update active docs, spec memory, archive supersession guidance, validation tests, and generated data through supported commands. ### Sessions | Session | Name | Purpose | | ------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | 01 | Local Access Startup Contract | Default `AI_OS_LOCAL_ALL_ACCESS=1` across `bun run dev`, Vite, `scripts/dev.sh`, and `scripts/cleandev.sh`. | | 02 | Hermes Bridge Status | Convert Hermes bridge status and browser parsing to all-access readiness while preserving real security failures. | | 03 | Hermes Route Modes And Hooks | Rename ready local Hermes mode to `live-local` and align hooks with bridge readiness. | | 04 | Knowledge Graph Write Path | Make ingest, remove, and grounded chat write-ready by default when Graphify and tokens are available. | | 05 | Voice Token Bootstrap | Make Start Voice and direct `bun run voice` token-ready without manual token setup. | | 06 | Intelligence Action Access | Make typed Ask Hermes and Intelligence actions use all-access readiness and named recovery states. | | 07 | Hermes Shell Identity | Replace legacy limited route identity with all-access local route language and component names. | | 08 | Hermes Mutation Controls | Make retained chat, mission, document, Pantheon, Ministry, and Obsidian controls execute or show real blockers. | | 09 | OpenClaw Action Execution | Implement deploy, spawn, and action execution with visible results or specific recovery states. | | 10 | Claude Code Execution | Provide real workspace, shell, git, process, and file/write execution wherever exposed. | | 11 | Local Agent Contract Parity | Bring shipped local-agent capabilities into full execution parity with visible results and tests. | | 12 | Public Demo Setup And Dream Modes | Separate hosted-demo/privacy and setup/Dream constraints from normal local all-access behavior. | | 13 | Extension And Compliance Boundaries | Keep source-compliance and credential-probe constraints as named exceptions, not local posture. | | 14 | End-To-End Test Matrix | Sweep tests, fixtures, e2e paths, and validation commands for all-access regression coverage. | | 15 | Active Docs And Runbooks | Update active docs to describe implemented behavior without claiming unimplemented capability. | | 16 | Spec Memory And Archive Supersession | Update spec-system memory and archive guidance so old gates stay historical. | | 17 | Generated Data Closeout | Regenerate and verify ignored local data after source, tests, docs, and archive updates. | Phase 41 succeeds when all 17 sessions are validated, normal local startup is all-access by default, retained shipped local capabilities execute for real with visible results and recovery paths, active docs and spec memory match the implemented behavior, and generated private data remains uncommitted. ## Current Technical Stack * Bun package manager and runtime for scripts. * React 19 application. * TypeScript. * TanStack Router and TanStack Start. * Vite 8 with local Vite/TanStack configuration. * Tailwind CSS 4 styles through `src/styles.css`. * Radix UI primitives and local `src/components/ui/` wrappers. * React Query for runtime JSON data loading. * Cloudflare Worker style server entry via `src/server.ts` and `wrangler.jsonc`. ## Current Brownfield Assets * Imported upstream README details have been removed from the root docs; current starter-foundation notes live in `README.md`, `docs/ARCHITECTURE.md`, `docs/development.md`, and `docs/onboarding.md`. * `AGENTS.md` contains current AI coding-agent instructions and project identity rules. * `src/routes/` contains AI OS dashboard routes for home, skills, memory, activity, workspaces, setup, share, settings, agents, and extensions. * `scripts/aggregate.ts` scans local Claude/Codex/memory/integration signals and writes `src/data/live-data.json`. * `src/data/live-data.example.json` is the committed sanitized fallback data shape. * `skills/dream/SKILL.md` is the imported daily Dream review skill. ## Target Information Architecture Trend Finder is a repo-local extension inside the AI OS application shell rather than the top-level product identity. AI Rogue (Phase 30, complete) is a second repo-local extension that joins the same Extensions area. ``` AI OS |-- Home |-- Skills |-- Memory |-- Activity |-- Workspaces |-- Agents |-- Extensions | |-- Trend Finder | | |-- Trends | | |-- Hidden Gems | | |-- Sources | | |-- Watchlist | | `-- Brief | `-- AI Rogue (Phase 30, complete) | |-- Play | |-- Ledger | |-- Loadout | `-- Settings |-- Engine Replay `-- Settings ``` Trend Finder routes live under `/extensions/trend-finder/*`; the extension ID stays stable even as the AI OS host identity changes. Engine Replay is a Trend Finder-scoped sidebar utility route at `/extensions/trend-finder/engine`, not a separate extension or creator-facing product tab. AI Rogue routes live under `/extensions/ai-rogue/*`, with `/extensions/ai-rogue/play` as the primary canvas-first surface and Ledger, Loadout, and Settings as supporting panels. Phase 30 is complete, Phase 34 closed the audited blockers, and AI Rogue is production-enabled by default in the browser registry. ## Target Hackathon Outcome Trend Finder should remain a working extension inside AI OS, with dashboard surfaces that help AI creators, automators, and builders discover early AI topic signals. The planned report sections include top trends, hidden gems, evidence, source breakdown, trend score, creator angle, and watchlist items. The hackathon demo should make the boundary clear: AI OS is the host cockpit, and Trend Finder is the public trend-intelligence extension being demonstrated. ## Success Criteria * [x] New contributors can understand and run the current starter app from docs alone. * [x] Documentation clearly separates AI OS host behavior from Trend Finder extension behavior. * [x] Baseline architecture, development, deployment, environment, and runbook docs exist. * [x] Product implementation can start from a documented source of truth. * [x] Final hackathon submission includes repo setup instructions, Trend Finder dashboard or report output, and Loom walkthrough notes. * [x] Existing imported operator surfaces remain available unless an implementation session explicitly scopes hiding, replacing, or reorganizing them. --- # 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/.spec_system/archive/prd/prd-backup-20260703-191154.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.