> 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/hackathon-submission.md).

# Hackathon Submission

This page is the final local submission guide for Trend Finder. It is written for the May Competition submission package: GitHub repository, 60-second Loom walkthrough, and `May Comp` post.

## Submission Position

Trend Finder is a local dashboard that helps AI creators find emerging AI topics before they become mainstream. It collects public trend evidence through configured reviewed source paths, validates browser-safe evidence, ranks topics with explainable scores, and turns the strongest topics into creator angles.

The implemented MVP delivery surface is the dashboard, especially the Brief view. The Trends tab includes editable Creator Lens fields and a local run control that saves dirty lens drafts before rerunning aggregate. The Engine Replay route is an implemented local proof surface for the latest generated Trend Finder run: it replays sanitized source, evidence, runtime, scoring, movement, prediction, retro, and artifact summaries without reading raw logs or private runtime payloads. A generated HTML report, hosted platform, historical replay, generic host replay, dynamic source marketplace, and long-term feedback learning are deferred.

## Certification Status

Last recorded local install certification snapshot on 2026-06-01 passed with no live credentials required and no release blockers from the install audit:

* Disposable clone quick-start UI path passed with isolated `HOME`: `bun install`, `bun run dev`, HTTP 200 for `/`, `/__live-data`, and `/extensions/trend-finder/trends`, with first-run data seeded from `src/data/live-data.example.json`.
* Disposable clone full local telemetry path passed with isolated `HOME`: `bun run setup` wrote generated `src/data/live-data.json`, installed compatibility skills under the isolated home, wired hooks, skipped macOS launchd on Linux with guidance, and `bun run dev` served the same smoke routes with HTTP 200.
* Disposable clone credential-free no-open demo path passed: `bun install`, `rm -f src/data/live-data.json`, `bun run seed:data`, `bunx vite dev --host 127.0.0.1 --port 5189`, and HTTP 200 for the Trend Finder Trends, Engine Replay, Watchlist, Sources, and Brief routes.
* Scheduler checks passed: aggregate status started as first-run, `bun run scheduler:run` completed, follow-up aggregate status reported a safe `warning-only` latest run, and agent, Trend Finder, and Dream scheduler status commands reported safe first-run states.
* Credential-free Apify/OpenAI/Codex smoke statuses matched the expected redacted outputs documented below.
* Source and disposable-clone sanitizer/write-guard tests passed, including current `HOME` paths under nonstandard roots such as `/tmp`.
* Final quality commands passed: app typecheck, script typecheck, private artifact guard, lint, format check, build, bundle budget, and full Vitest. The recorded full Vitest run passed 213 files and 2756 tests.
* Targeted Trend Finder and Engine Replay Playwright suites passed with 12 Chromium tests. When certification uses a fresh isolated `HOME`, install the browser cache first with `bunx playwright install chromium`.
* Package-pinned Worker preview passed: `bun run worker:preview` built and served `/health`, `/`, and `/favicon.svg` with HTTP 200.

Re-run the final certification commands below before recording or sharing a new branch.

## 60-Second Loom Script

Use this script only when the dashboard labels match the run being recorded.

1. "Trend Finder finds emerging AI topics before they become mainstream."
2. "This local dashboard uses configured reviewed public sources when credentials are present, and it clearly labels fixture/demo data when I am using the credential-free path."
3. "Runtime readiness shows whether the current run was AI-analyzed, mock backed, disabled, or deterministic fallback."
4. "Engine Replay shows the latest run moving from sources to evidence, runtime, scoring, movement, predictions, retros, and artifacts using sanitized browser-safe trace labels."
5. "Here is a ranked topic. The score is broken down by momentum, novelty, evidence strength, source diversity, niche fit, and creator potential."
6. "The evidence links, source breakdown, movement labels, and public metric chips show where the signal came from, including degraded or blocked source labels instead of hiding them."
7. "The creator angle turns the trend into a practical hook or content idea."
8. "The generated Watchlist tracks topics selected for follow-up by analyst reasons, hidden-gem status, movement, novelty, creator fit, or weak evidence."
9. "The Brief view is the MVP handoff: top creator angles, evidence to verify, and source health."
10. "If the AI runtime or live sources are unavailable, Trend Finder falls back deterministically and says so."

## Proof Points To Show

* Runtime readiness and provenance labels.
* Engine Replay latest-run route with sanitized source, evidence, runtime, scoring, movement, prediction, retro, and artifact stages.
* Editable Creator Lens fields and the local Run Trend Finder or Save and run control, when demonstrating a local refresh.
* Ranked Trends with one strong example topic.
* Score breakdown for momentum, novelty, evidence strength, source diversity, niche fit, and creator potential.
* Public evidence links, source breakdown rows, and public evidence metric chips when present.
* Movement label, previous-score or score-delta copy, and movement analysis when present.
* Hidden Gems for lower-volume early signals.
* Watchlist entries with movement or reason labels.
* Sources view with active, degraded, blocked, fixture, or fallback states.
* Brief view as the creator-facing handoff.

## Claims To Avoid

* Do not claim unrestricted source collection.
* Do not claim all reviewed sources run live by default.
* Do not describe fixture/demo data as live collection.
* Do not describe deterministic fallback topics as live AI clustering.
* Do not claim hosted deployment or generated HTML report delivery.
* Do not claim historical replay, hosted observability, generic host replay, or raw trace playback.
* Do not claim official OpenAI API or Agents SDK analysis paths are implemented.
* Do not describe the Run Trend Finder button as a hosted job, scheduler, or source marketplace. It is a local dev-server aggregate refresh.
* Do not claim Creator Lens edits instantly rescore the current payload; they affect collector output after save and rerun.

## Credential-Free Demo Path

Use this path for a clean checkout or a recording that must not depend on private credentials.

Use a disposable clone for this path. The command block below removes `src/data/live-data.json` so the app reseeds from committed fixture/demo data. In a real operator checkout, stop here unless you have backed up that private generated file or intentionally accept losing it.

```bash
bun install
rm -f src/data/live-data.json
bun run seed:data
bun run dev
```

Before opening the dashboard for a certification recording, clear browser site data for `127.0.0.1:5189` or use a fresh browser profile. The app always uses that fixed local origin, so browser `localStorage` and same-origin tokens can carry across separate clones.

The Trend Finder routes are registered in the app even when `VITE_CLAUDE_OS_ENABLED_EXTENSIONS` is unset, so the direct URLs below can render fixture/demo data from the seeded payload. Set the env switch to `trend-finder` only when you also need sidebar navigation or when you are running the collector. Route availability is not proof that the collector, Apify Actors, or AI runtime executed.

If you need to avoid `bun run dev` auto-opening the default browser, run the same seed step and start Vite without `--open`:

```bash
bun install
rm -f src/data/live-data.json
bun run seed:data
bunx vite dev --host 127.0.0.1 --port 5189
```

Open:

```
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
```

Use this narration:

> This is the credential-free demo path. It uses committed safe fixture/demo data and deterministic fallback analysis, so I am not claiming live AI clustering or live source execution in this recording. Engine Replay is showing a fixture/demo or fallback latest-run proof, not historical replay.

If you show the run control in this path, describe it as a local refresh that will preserve the same fixture/demo or fallback labels unless credentials and reviewed source config are added.

## Credential-Free Smoke Statuses

Run these checks without private credentials when you need to prove that missing optional integrations fail or degrade predictably. The nonzero Codex statuses are expected and are not release blockers for the credential-free demo path.

```bash
APIFY_TOKEN= FINDTREND_APIFY_ACTORS= FINDTREND_APIFY_ACTORS_PATH= bun run apify:smoke -- --json
APIFY_TOKEN= FINDTREND_APIFY_ACTORS= FINDTREND_APIFY_ACTORS_PATH= bun run apify:smoke -- --tiny-validate --json
bun run auth:openai -- status --json --auth-path /tmp/ai-os-missing-openai-account-auth.json
bun run codex:smoke -- --json --auth-path /tmp/ai-os-missing-openai-account-auth.json
bun run agents:codex:smoke -- --json
```

Expected statuses:

| Command                                              | Expected credential-free result                                                                                           |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `apify:smoke -- --json`                              | Exits `0`; `ok: true`, `status: "setup-required"`, `readiness.status: "missing-token"`, and `secretValuesPrinted: false`. |
| `apify:smoke -- --tiny-validate --json`              | Exits `0`; `tinyValidation.ranLive: false`; reviewed sources are blocked with `reason: "missing-token"`.                  |
| `auth:openai -- status --json --auth-path <missing>` | Exits `0`; `authenticated: false`, `reason: "missing"`, and `secretValuesPrinted: false`.                                 |
| `codex:smoke -- --json --auth-path <missing>`        | Exits `1`; `error.code: "missing_auth"` with redacted recovery commands and `secretValuesPrinted: false`.                 |
| `agents:codex:smoke -- --json`                       | Exits `78`; `status: "deferred"`, `agentsSdkImported: false`, and `secretValuesPrinted: false`.                           |

## Credentialed Reviewed-Source Path

Use this path only when local ignored credentials are configured.

```bash
bun run apify:smoke -- --json
bun run apify:smoke -- --tiny-validate --json
bun run auth:openai -- status
bun run aggregate
bun run dev
```

Use this narration only when the dashboard labels match:

> This run used configured reviewed public sources. The dashboard labels show whether this payload was live generated data, AI-analyzed, mock-backed, deterministic fallback, degraded, or blocked. Engine Replay shows the latest sanitized local run only.

After the dashboard opens, you can also edit the Creator Lens and click Save and run. Use that only if the new payload labels still match the narration.

## Final Certification Commands

Run these before recording or sharing the branch:

```bash
bun run typecheck
bun run typecheck:scripts
bun run test -- scripts/lib/apify/__tests__ scripts/lib/ai-runtime/__tests__ scripts/extensions/trend-finder/__tests__ scripts/extensions/trend-finder/sources/__tests__ src/lib/__tests__/trend-finder-schema.test.ts src/lib/__tests__/trend-finder-dashboard.test.tsx src/lib/__tests__/trend-finder-engine-replay.test.tsx src/lib/__tests__/trend-finder-collector.test.ts
bun run test
bun run test:e2e -- tests/e2e/trend-finder.spec.ts tests/e2e/trend-finder-engine-replay.spec.ts
bun run lint
bun run format:check
bun run build
bun run budget:check
bun run runtime:check-private
```

When running those commands with a brand-new isolated `HOME`, install Playwright Chromium into that home before the e2e step:

```bash
bunx playwright install chromium
```

## Private Artifact Boundary

Do not commit private runtime files:

* `src/data/live-data.json`
* `data/openai-account-auth.json`
* `.cache/extensions/trend-finder/`
* `logs/`
* `coverage/`
* `test-results/`
* `playwright-report/`
* `.env`
* `.env.local`

`bun run runtime:check-private` verifies these with git metadata and does not read private file contents.

## Honest Deferrals

* Hosted deployment.
* Generated HTML report delivery.
* Historical run selection and durable run history.
* Hosted observability or production trace storage.
* Generic host replay outside Trend Finder.
* Raw JSONL, provider request/response, Actor/Dataset, prompt/response, or private telemetry playback.
* Dynamic source marketplace or source approval UI.
* Unrestricted source collection.
* Official OpenAI API provider analysis path.
* Agents SDK analysis path.
* Long-term preference memory, feedback learning, adaptive score tuning, or user-authored watchlist persistence.


---

# 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/hackathon-submission.md?ask=<question>&goal=<endgoal>
```

`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.