> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/hackathon/trend-finder-demo.md). # Trend Finder Demo Workflow This runbook describes the local demo paths for Trend Finder. It separates a credentialed reviewed-source run from the credential-free fixture/demo fallback so the dashboard and Loom narration do not overclaim live source breadth or AI analysis state. Use [Hackathon Submission](/ai-os-and-trend-finder-docs/docs/hackathon/hackathon-submission.md) as the final 60-second Loom script, proof-point checklist, certification command list, and deferral record. ## What The Demo Can Claim Use this wording when the dashboard shows matching provenance labels: * Live generated data: generated locally from configured reviewed public sources. * AI-analyzed run: a configured AI runtime returned validated analyst output. * Mock runtime analysis: deterministic local runtime output for tests or demos. * Deterministic fallback analysis: topic grouping and scoring ran without live AI clustering. * Fixture/demo data: committed safe fallback data for credential-free demos. * Degraded source: a source returned partial public metadata or warnings. * Blocked source: local credentials or reviewed source config are missing. * Engine Replay: the latest generated Trend Finder run is shown as sanitized source, evidence, runtime, scoring, movement, prediction, retro, and artifact stages. * Decision timeline: Engine Replay may show sanitized planner, source run, normalization, AI analysis, scoring critic, movement analyst, prediction writer, retro evaluator, and artifact writer decisions. Treat these as latest-run intelligence-loop summaries only. * Creator Lens run control: the Trends tab can save unsaved Creator Lens edits and request a local aggregate refresh. Treat this as a local dev-server run, not a hosted job or scheduler. * Source context and metric chips: topic cards can show source role, quality, status, evidence counts, and browser-safe public metrics when the generated payload includes them. * Generated watchlist: the Watchlist tab is read-only generated output from analyst reasons, hidden-gem status, movement, novelty, creator fit, or weak evidence signals. * Historical backtest: a script-only Trend Finder CLI replay of reviewed historical source windows. It writes full output privately and only publishes bounded counts when explicitly requested. Avoid these claims unless the dashboard labels prove them in the current run: * Do not say all reviewed sources ran live by default. * Do not say fallback topics were live AI-clustered. * Do not say a generated HTML report exists; the implemented handoff is the dashboard Brief view. * Do not describe unrestricted source collection. Use configured reviewed public sources. * Do not describe Engine Replay as historical replay, hosted observability, generic host replay, or raw trace playback. * Do not describe the decision timeline as a backtest, historical audit, raw AI transcript, raw prompt log, or provider trace. * Do not describe future-run retros as historical backtests. Future-run retros grade predictions from normal generated runs; historical backtests use the separate `trend-finder:backtest` CLI. * Do not say historical backtests run from the browser or scheduler. Phase 14 backtests are script-only. * Do not say the Run Trend Finder button starts a hosted job, source marketplace, or remote scheduler. * Do not say Creator Lens edits rescore the current payload immediately. They affect collector output only after save and rerun. ## Credential-Free Fixture Demo This path requires no private tokens and is the safest baseline for a clean checkout. 1. Install dependencies. ```bash bun install ``` 2. Optionally enable the extension sidebar entry by ensuring `.env.local` contains: ``` VITE_CLAUDE_OS_ENABLED_EXTENSIONS=trend-finder ``` Direct Trend Finder routes are statically registered and can render fixture/demo data without this switch. The switch is required for sidebar visibility and for script-side collector execution. 3. Seed the safe committed fallback payload. ```bash rm -f src/data/live-data.json bun run seed:data ``` 4. Start the dashboard. ```bash bun run dev ``` 5. Open the Trend Finder views. ``` http://127.0.0.1:5189/extensions/trend-finder/trends http://127.0.0.1:5189/extensions/trend-finder/engine http://127.0.0.1:5189/extensions/trend-finder/watchlist http://127.0.0.1:5189/extensions/trend-finder/sources http://127.0.0.1:5189/extensions/trend-finder/brief ``` Expected labels: * `Fixture/demo data` * `Deterministic fallback analysis` * `Fixture/demo sources` * Runtime status `Disabled` * Engine Replay state `Fixture/demo trace`, `Sanitized trace missing`, or explicit empty/fallback labels depending on the seeded payload Use this narration: > This is the credential-free demo path. The dashboard is using committed safe fixture/demo data and deterministic fallback analysis. It shows the product surface and fallback semantics without claiming a live AI-analyzed run. Engine Replay is showing sanitized fixture/demo or fallback latest-run proof, not historical replay. If you demonstrate the run control here, say it is a local refresh path. Unless credentials and reviewed source config are added, the expected result remains fixture/demo data or deterministic fallback labels. The fixture/demo route path does not run reviewed source collectors by itself. For a collector run, set `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=trend-finder` and run `bun run aggregate` or `bun run scheduler:trend-finder:run`. Apify sources still require `APIFY_TOKEN` and reviewed source config. ## Credentialed Reviewed-Source Run This path is optional. It requires local-only credentials and explicit reviewed source configuration. 1. Put local values in `.env.local` or export them in the shell. Keep runtime secrets script-only; do not use `VITE_` prefixes for tokens or account auth. ``` VITE_CLAUDE_OS_ENABLED_EXTENSIONS=trend-finder APIFY_TOKEN= FINDTREND_APIFY_ACTORS_PATH=data/trend-finder.apify-actors.json FINDTREND_AI_RUNTIME_PROVIDER=codex-account FINDTREND_AI_RUNTIME_MODEL=gpt-5.5 FINDTREND_AI_RUNTIME_AUTH_PATH=data/openai-account-auth.json FINDTREND_OPENAI_ACCOUNT_AUTH_PATH=data/openai-account-auth.json ``` 2. Check Apify readiness without running Actors. ```bash bun run apify:smoke -- --json ``` 3. Optionally run tiny capped validation. This is credential-gated and can consume Apify credits. ```bash bun run apify:smoke -- --tiny-validate --json ``` 4. Check or refresh account auth when using Codex-account analysis. ```bash bun run auth:openai -- status bun run auth:openai -- login ``` 5. Generate local dashboard data. ```bash bun run aggregate ``` 6. Start or refresh the dashboard. ```bash bun run dev ``` Expected labels depend on the configured runtime and source outcome: * `Live generated data` when aggregation produced a new Trend Finder payload. * `AI-analyzed run` when configured AI analysis succeeded. * `Deterministic fallback analysis` when the runtime was unavailable or analyst output failed validation. * `Reviewed public sources`, `Degraded source path`, or `Blocked source path` depending on source results. * Engine Replay `Sanitized trace`, `Stale sanitized trace`, `Trace unavailable`, or explicit empty/offline labels depending on the latest generated payload. * Decision timeline rows when the latest sanitized trace includes intelligence-loop decisions. Empty timeline states mean the payload is older or fallback-only, not that historical backtest coverage exists. Use this narration: > This run used configured reviewed public sources. The dashboard labels show whether the current payload was AI-analyzed, mock-backed, deterministic fallback, degraded, or blocked. Engine Replay shows the latest sanitized local run only. ## Historical Backtest CLI This path is optional and script-only. It is for testing reviewed historical windows without claiming that the browser runs backtests. Dry-run a reviewed Product Hunt historical window plan: ```bash bun run trend-finder:backtest -- --sources producthunt-ai-launches --window-start 2026-01-01 --window-end 2026-01-07 --windows 4 --dry-run ``` Run the backtest and keep all output private: ```bash bun run trend-finder:backtest -- --sources producthunt-ai-launches --window-start 2026-01-01 --window-end 2026-01-07 --windows 4 ``` Publish only the bounded browser-safe aggregate after a run: ```bash bun run trend-finder:backtest -- --sources producthunt-ai-launches --window-start 2026-01-01 --window-end 2026-01-07 --windows 4 --publish-aggregate ``` Expected behavior: * The CLI rejects unknown, current-only, or unsupported historical sources before collection. * Full archives stay under `.cache/extensions/trend-finder/backtests/`. * Browser data receives only `backtestAggregateSummary` counts, labels, generated timestamp, and `mode: "backtest"` when `--publish-aggregate` is set. * Backtest retro records are tagged `mode: "backtest"`. Existing future-run retros default to `mode: "future-run"`. * Engine Replay remains a latest-run surface. It is not the backtest UI. ## Loom Path Keep the walkthrough under 60 seconds: 1. Open Trends and point to the top-bar freshness, source, and provenance state. 2. Show the Creator Lens and run control only if the recording benefits from proving local repeatability. Read the current button/status label aloud and avoid implying hosted execution. 3. Open Engine Replay for 10 to 15 seconds. Pause or scrub the replay to show sources, evidence, runtime, scoring, movement, predictions, retros, and artifacts, then read the trace label aloud. Use the visible label: `Fixture/demo trace`, `Sanitized trace`, `Stale sanitized trace`, `Sanitized trace missing`, `Trace unavailable`, or an empty/offline state. If the decision timeline is visible, describe it as sanitized latest-run intelligence-loop decisions only. 4. Show the Signal Radar, ranked trend count, and one selected trend with its score, movement, source context, evidence, public metric chips when present, and creator angle. 5. Open Hidden Gems or Watchlist only if the recording needs a second example of low-volume opportunity or movement tracking. 6. Open Sources and show live, degraded, blocked, fixture, or fallback source labels. 7. Open Brief and read the provenance line before showing top creator angles. 8. Mention that generated HTML report delivery, historical replay, hosted observability, and raw trace playback are deferred; the Brief view and Engine Replay route are dashboard-native surfaces. Use the exact script in [Hackathon Submission](/ai-os-and-trend-finder-docs/docs/hackathon/hackathon-submission.md) after checking that the dashboard labels match the current run path. ## Private Artifact Check Before sharing a branch or recording a credentialed run, verify private runtime artifacts are ignored and untracked: ```bash bun run runtime:check-private ``` The command checks git metadata for generated live data, account auth, Trend Finder snapshots, backtest archives, raw cache output, aggregate logs, coverage, test results, and browser reports. It does not read private file contents. ## Validation Checklist * Final certification commands in [Hackathon Submission](/ai-os-and-trend-finder-docs/docs/hackathon/hackathon-submission.md#final-certification-commands) have passed for the branch being recorded. * Dashboard labels match the run path before recording. * No `.env.local`, account auth JSON, generated live data, cache snapshots, logs, coverage, test results, or browser reports are tracked. * Fixture/demo output is described as fixture/demo output. * Deterministic fallback output is not described as live AI clustering. * Source language says configured reviewed public sources. * Watchlist and Brief views are shown as dashboard surfaces, not generated HTML report output. * Engine Replay is described as latest-run sanitized proof, not historical replay or hosted observability. * Historical backtests are described as script-only, and only the optional bounded aggregate is described as browser-visible. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/hackathon/trend-finder-demo.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.