> 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/scripts/readme_scripts.md).

# Scripts

Bun scripts for setup, data aggregation, image generation, extension collectors, Apify readiness checks, OpenAI account auth, Codex transport smoke checks, AI runtime analysis, scoring, snapshots, and deferred Agents provider command surfaces.

## Prerequisites

* **Bun** runtime and package manager (used for all script execution)
* **Node built-ins** only -- no extra dependencies beyond those in the project
* Optional: `KIE_API_KEY` in `.env.local` for image generation scripts
* Optional: `APIFY_TOKEN` in `.env.local` for Apify source readiness checks
* Optional: OpenAI account auth generated by `bun run auth:openai -- login` for Codex account transport smoke checks

## Script Inventory

| File                                 | Purpose                                                        | Requires API Key  |
| ------------------------------------ | -------------------------------------------------------------- | ----------------- |
| `setup.ts`                           | One-time setup: aggregator, skills, Dream schedule, hooks      | No                |
| `postinstall.sh`                     | Re-activate the repo-local git hooks path                      | No                |
| `dev.sh`                             | Start, reuse, or stop the tmux-managed dev server              | No                |
| `cleandev.sh`                        | Clean local build state and restart the dev server             | No                |
| `aggregate.ts`                       | Scan local signals and emit `src/data/live-data.json`          | Optional (\*)     |
| `scheduler-runner.ts`                | Run registered scheduler jobs such as aggregate and Dream      | No                |
| `scheduler-status.ts`                | Print browser-safe scheduler job status                        | No                |
| `dashboard-dream-run.ts`             | Token-gated local Dream run bridge target                      | No                |
| `install-dream-cron.ts`              | Manage Dream schedule: macOS launchd, Windows task, Linux copy | No                |
| `trend-finder-backtest.ts`           | Run script-only Trend Finder historical backtests              | Optional          |
| `trend-finder-replay-backhistory.ts` | Replay private backhistory input into backtest archives        | Optional          |
| `gen-image.ts`                       | Generate a single image via kie.ai API                         | KIE\_API\_KEY     |
| `batch-generate.ts`                  | Batch image generation for skills and logos                    | KIE\_API\_KEY     |
| `gen-dream-images.ts`                | Generate Dream feature card images                             | KIE\_API\_KEY     |
| `gen-cadence-images.ts`              | Generate Dream cadence step images                             | KIE\_API\_KEY     |
| `openai-account-auth.mjs`            | OpenAI account auth status, login, refresh, reauth, logout     | No                |
| `openai-codex-smoke.mjs`             | Codex account transport smoke check                            | Account auth      |
| `openai-agents-codex-smoke.mjs`      | Deferred future Agents SDK smoke check                         | No                |
| `test-openai-account-auth.mjs`       | Script-side account auth regression helper                     | Account auth      |
| `test-openai-codex-transport.mjs`    | Script-side Codex transport regression helper                  | Account auth      |
| `apify-smoke.ts`                     | Apify config/client readiness and optional Actor checks        | APIFY\_TOKEN (\*) |
| `playwright-webserver.sh`            | Playwright web-server wrapper                                  | No                |
| `check-asset-sizes.sh`               | Check public asset size budgets                                | No                |
| `check-bundle-budget.sh`             | Check generated client bundle budgets                          | No                |
| `check-private-runtime-artifacts.sh` | Git metadata check for ignored private runtime artifacts       | No                |

(\*) `aggregate.ts` optionally uses PINECONE\_API\_KEY and OPENROUTER\_API\_KEY for richer data, but runs fine without them. `apify-smoke.ts` warns when APIFY\_TOKEN is missing and exits cleanly without running source checks.

## Local Dev Helpers

`dev.sh` starts or reuses the tmux-managed Vite dev server. `cleandev.sh` is the full clean launch path: it stops the project dev process, removes ignored build state and dependencies, reinstalls from `bun.lock`, runs validation, hydrates host/local launch data, and starts the app in the `aios-dev` tmux session. Its default `all` launch profile enables extension surfaces for the Vite process, but it does not rerun paid Trend Finder collection or the daily Dream job. Private runtime state such as `.env.local` and `src/data/live-data.json` is preserved.

Use `scripts/cleandev.sh --validate-only` or `scripts/cleandev.sh --no-start` for the same clean, install, typecheck, test, and hydration checks without starting or leaving behind the tmux-managed dev server. This mode is intended for CI-like local validation.

Use `scripts/cleandev.sh --configured` or `CLEANDEV_LAUNCH_PROFILE=configured scripts/cleandev.sh` to launch only the features enabled by the current shell or `.env.local`. Individual launch jobs can be controlled with `CLEANDEV_RUN_HOST_AGGREGATE=0`, `CLEANDEV_RUN_TREND_FINDER=1`, or `CLEANDEV_RUN_DREAM=1`; extension startup can be overridden with `CLEANDEV_ENABLED_EXTENSIONS=<ids|all|none>`. Trend Finder and Dream remain opt-in from `cleandev.sh` because they can spend provider budget and have cadence-specific value.

At the end of restart and validation-only runs, `cleandev.sh` prints a phase summary for clean, install, typecheck, tests, hydration, start, and runtime hints. It also prints the raw aggregate log path when hydration writes one, plus `logs/aggregate.latest.jsonl` when available. Startup output reports UI extension state separately from extension collector state so enabled routes are not confused with skipped collector jobs.

`cleandev.sh` launches the Vite server with the Phase 41 local all-access startup contract. It derives `AI_OS_LOCAL_ALL_ACCESS=1` and the legacy Hermes and OpenClaw compatibility aliases when they are unset, then verifies the restarted server reports Hermes `ready`, local write readiness, and a working `/__token` handshake. If that check fails, the script exits nonzero instead of leaving a partly locked Hermes dashboard.

## Extension Collector System

The aggregator runs registered extension collectors after the core scan.

| Path                                                     | Purpose                                                                               |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `lib/extensions/types.ts`                                | CollectorExtension and runtime item types                                             |
| `lib/extensions/runner.ts`                               | Guarded collector runner (timeout, size, isolation)                                   |
| `lib/extensions/env.ts`                                  | Scoped env reader for extension secrets                                               |
| `lib/extensions/logger.ts`                               | Extension-scoped logger factory                                                       |
| `lib/extensions/validate.ts`                             | Payload size and result shape validation                                              |
| `extensions/registry.ts`                                 | Static collector registry                                                             |
| `extensions/trend-finder/collector.ts`                   | Trend Finder collector with source, runtime, scoring, snapshot, and fallback pipeline |
| `extensions/trend-finder/sources/hn-adapter.ts`          | Hacker News public API source adapter                                                 |
| `extensions/trend-finder/sources/apify-adapter.ts`       | Reviewed configured Apify Actor source adapter                                        |
| `extensions/trend-finder/sources/apify-source-config.ts` | Trend Finder source declarations, candidates, and compliance gates                    |
| `extensions/trend-finder/sources/apify-normalizers.ts`   | Source-specific Apify Dataset item normalizers                                        |
| `extensions/trend-finder/sources/types.ts`               | SourceAdapter interface                                                               |
| `extensions/trend-finder/normalize.ts`                   | Evidence normalization helpers                                                        |
| `extensions/trend-finder/topics.ts`                      | Keyword-frequency topic extraction                                                    |

Extension collectors are opt-in. Set `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=trend-finder` in `.env.local` and run `bun run aggregate` to execute enabled collectors. Direct browser routes can still render fixture/demo data without this switch; that is not collector execution. Apify-backed Trend Finder source execution also requires `APIFY_TOKEN` and explicit reviewed source config.

Every `bun run aggregate` execution writes a private structured JSONL trace to `logs/aggregate-*.jsonl` and refreshes `logs/aggregate.latest.jsonl`. The trace mirrors console output and includes extension lifecycle events, runtime config readiness, source counts, AI-analysis request shape, sanitized analyst request payloads, sanitized responses, validation issues, fallback reasons, and mapped provider error causes. The `logs/` directory is ignored by git except for `logs/README_logs.md`.

The Trend Finder collector now combines built-in public source adapters, reviewed configured Apify Actor sources, AI runtime readiness, analyst validation, deterministic fallback topics, score breakdowns, local snapshots, and dashboard payload validation. If credentials or one source are unavailable, the collector emits warning states and preserves valid evidence from other sources.

## Apify Runtime Foundation

The script-only Apify foundation lives under `scripts/lib/apify/`.

| Path                     | Purpose                                                |
| ------------------------ | ------------------------------------------------------ |
| `lib/apify/types.ts`     | Shared config, readiness, result, and provenance types |
| `lib/apify/config.ts`    | Env parsing, defaults, actor config, and warnings      |
| `lib/apify/client.ts`    | Safe client factory and redacted readiness helpers     |
| `lib/apify/actors.ts`    | Configured Actor runner with per-source degradation    |
| `lib/apify/datasets.ts`  | Bounded Dataset item reads                             |
| `lib/apify/normalize.ts` | Generic item normalization and provenance separation   |

Use `data/trend-finder.apify-actors.json` for the editable local Actor source list. `FINDTREND_APIFY_ACTORS_PATH` can point to another JSON file, and `FINDTREND_APIFY_ACTORS` remains available as an inline override for CI or one-off shell runs. JSON is required when a source needs Actor input, custom memory, custom timeout, custom item caps, or a per-run `maxTotalChargeUsd` cap for paid Apify Actors.

Missing `APIFY_TOKEN` is reported as setup-required readiness and exits cleanly. Source checks run only when `--check-sources` is supplied and a token is present. Actor inputs and Dataset items are not printed by smoke output.

## OpenAI Account Auth And Codex Transport

The script-only account auth modules live under `scripts/lib/openai-account-auth/`.

| Path                  | Purpose                                                         |
| --------------------- | --------------------------------------------------------------- |
| `common.mjs`          | AI OS auth constants, path resolution, PKCE/JWT helpers         |
| `storage.mjs`         | Credential normalization, status, locks, atomic writes, clear   |
| `oauth.mjs`           | PKCE login, callback server, manual code fallback, refresh      |
| `codex-transport.mjs` | Codex request construction, headers, SSE parsing, error mapping |
| `index.mjs`           | Script-side public exports                                      |

`data/openai-account-auth.json` is generated private local data and is ignored by git. Normal CLI output reports redacted readiness state and recovery commands; it does not print access tokens, refresh tokens, raw account IDs, raw account-auth paths, prompt payloads, raw response bodies, or transcripts. `AI_OS_OPENAI_ACCOUNT_AUTH_PATH` is the canonical host auth-path override; `FINDTREND_OPENAI_ACCOUNT_AUTH_PATH` and `FINDTREND_AI_RUNTIME_AUTH_PATH` remain compatibility fallbacks. Codex-account runtime consumers auto-refresh expired stored auth where possible; manual `refresh` remains useful for diagnostics, and rejected refresh tokens require `reauth`.

## AI Runtime, Analyst, Scoring, And Snapshots

The script-side AI runtime modules live under `scripts/lib/ai-runtime/`.

| Path               | Purpose                                                             |
| ------------------ | ------------------------------------------------------------------- |
| `config.ts`        | Provider/env parsing and script-only secret presence checks         |
| `host-config.ts`   | AI OS host env precedence and compatibility fallback loader         |
| `providers.ts`     | Disabled, mock, Codex-account, and placeholder OpenAI API providers |
| `trend-analyst.ts` | Structured analyst prompt, output parsing, validation, and fallback |
| `scoring.ts`       | Deterministic score breakdowns and fallback topic generation        |
| `snapshots.ts`     | Local trend snapshot read/write and movement comparison             |
| `contract.ts`      | Runtime provider and result interfaces                              |

Snapshots are written below the extension cache directory, normally `.cache/extensions/trend-finder/snapshots/`, and are ignored by git. Invalid or missing snapshots produce warnings rather than blocking collection.

## Shared Utilities

| File                             | Purpose                                         |
| -------------------------------- | ----------------------------------------------- |
| `lib/load-env.ts`                | Shared `.env.local` loader with quote stripping |
| `lib/__tests__/load-env.test.ts` | Unit tests for the shared env loader            |

### Environment Variable Loading

Scripts that need `.env.local` values import the shared loader:

```ts
import { loadEnv, requireEnv } from "./lib/load-env";

loadEnv();
const key = requireEnv("KIE_API_KEY");
```

The loader:

* Resolves `.env.local` from the **project root** (not a parent directory)
* Strips surrounding single and double quotes from values
* Skips comment lines (starting with `#`) and blank lines
* Does **not** override variables already set in the shell environment

`aggregate.ts` imports the same shared `loadEnv` helper, so aggregation and image scripts resolve `.env.local` consistently from the project root.

## Run Commands

This section lists package commands backed by files in `scripts/`. See [`docs/commands.md`](/ai-os-and-trend-finder-docs/docs/commands.md) for the complete package script catalog, including app build, lint, format, and test commands.

| Command                                   | Script                                       | Purpose                                                    |
| ----------------------------------------- | -------------------------------------------- | ---------------------------------------------------------- |
| `bun run setup`                           | `scripts/setup.ts`                           | Full one-time setup                                        |
| `bun run aggregate`                       | `scripts/aggregate.ts`                       | Re-scan and refresh data                                   |
| `bun run scheduler:run`                   | `scripts/scheduler-runner.ts`                | Run the aggregate scheduler job                            |
| `bun run scheduler:status`                | `scripts/scheduler-status.ts`                | Print safe aggregate scheduler status                      |
| `bun run scheduler:agents:run`            | `scripts/scheduler-runner.ts`                | Run the scoped host/local agent aggregate job              |
| `bun run scheduler:agents:status`         | `scripts/scheduler-status.ts`                | Print safe agent aggregate scheduler status                |
| `bun run scheduler:trend-finder:run`      | `scripts/scheduler-runner.ts`                | Run the scoped Trend Finder scheduler job                  |
| `bun run scheduler:trend-finder:status`   | `scripts/scheduler-status.ts`                | Print safe Trend Finder scheduler status                   |
| `bun run scheduler:dream:run`             | `scripts/scheduler-runner.ts`                | Run material-first AI OS Dream                             |
| `bun run scheduler:dream:status`          | `scripts/scheduler-status.ts`                | Print safe AI OS Dream scheduler status                    |
| `bun run trend-finder:backtest`           | `scripts/trend-finder-backtest.ts`           | Run Trend Finder historical backtests                      |
| `bun run trend-finder:replay-backhistory` | `scripts/trend-finder-replay-backhistory.ts` | Replay private backhistory into backtest archives          |
| `bun run auth:openai -- status`           | `scripts/openai-account-auth.mjs`            | OpenAI account auth readiness status                       |
| `bun run auth:openai -- login`            | `scripts/openai-account-auth.mjs`            | OpenAI account PKCE login                                  |
| `bun run auth:openai -- refresh`          | `scripts/openai-account-auth.mjs`            | Manually refresh stored OpenAI account auth                |
| `bun run auth:openai -- logout`           | `scripts/openai-account-auth.mjs`            | Clear stored OpenAI account auth                           |
| `bun run codex:smoke -- --json`           | `scripts/openai-codex-smoke.mjs`             | Codex account transport smoke check                        |
| `bun run agents:codex:smoke -- --json`    | `scripts/openai-agents-codex-smoke.mjs`      | Deferred Agents SDK smoke stub                             |
| `bun run apify:smoke -- --json`           | `scripts/apify-smoke.ts`                     | Apify config/client readiness check                        |
| `bun run apify:smoke -- --check-sources`  | `scripts/apify-smoke.ts`                     | Optional configured Actor checks                           |
| `bun run runtime:check-private`           | `scripts/check-private-runtime-artifacts.sh` | Verify private runtime artifacts are ignored and untracked |
| `bun run budget:check`                    | `scripts/check-bundle-budget.sh`             | Verify generated client bundle budgets                     |
| `bun run install-dream`                   | (install-dream-cron.ts)                      | Install AI OS Dream automation                             |
| `bun run uninstall-dream`                 | (install-dream-cron.ts)                      | Remove AI OS Dream automation                              |
| `bun run postinstall`                     | `scripts/postinstall.sh`                     | Re-activate `.githooks/` for this clone                    |

Image scripts are run directly: `bun run scripts/gen-dream-images.ts`

## AI OS Dream Schedule

`bun run install-dream` installs the daily Dream schedule on macOS through launchd and on Windows through Task Scheduler. Linux prints a manual crontab line because the script does not edit the user's crontab.

Scheduled runs use the AI OS runner sequence:

```sh
bun run scripts/aggregate.ts ; bun run scripts/dashboard-dream-run.ts
```

The first command refreshes browser-safe aggregate data for Dream input. The second command runs the AI OS Dream scheduler job and refreshes live data after new private Dream output is written. The installer does not schedule upstream `scripts/run-dream.ts` or raw `claude -p "/dream"`.

Windows-only maintenance actions are available through:

```sh
bun run scripts/install-dream-cron.ts --query
bun run scripts/install-dream-cron.ts --run
```

Image generation prompts use generic painterly, watercolor, and storybook animation wording. Avoid trademarked artist, studio, or franchise style names in script prompts and logs.

## Setup Skill Installation

`bun run setup` installs bundled local skills with different overwrite rules:

| Skill             | Destination                 | Overwrite behavior                       |
| ----------------- | --------------------------- | ---------------------------------------- |
| `skills/dream`    | `~/.claude/skills/dream`    | Existing inherited behavior              |
| `skills/personas` | `~/.hermes/skills/personas` | No-clobber; existing local skill is kept |

The personas skill supports the Hermes admin persona surface. Setup copies it only when the destination does not already exist, so user edits under `~/.hermes/skills/personas` are preserved across setup reruns.

## Env Var Reference

| Variable                                 | Used By                                                 | Required |
| ---------------------------------------- | ------------------------------------------------------- | -------- |
| `KIE_API_KEY`                            | gen-image, batch-generate, gen-dream/cadence            | Yes (\*) |
| `PINECONE_API_KEY`                       | aggregate.ts                                            | Optional |
| `OPENROUTER_API_KEY`                     | aggregate.ts                                            | Optional |
| `ANTHROPIC_API_KEY`                      | aggregate.ts                                            | Optional |
| `OPENAI_API_KEY`                         | OpenAI-backed local scripts and OpenAI API readiness    | Optional |
| `NOTION_TOKEN`                           | aggregate.ts Notion memory graph ingestion              | Optional |
| `NOTION_API_KEY`                         | Backwards-compatible Notion token alias                 | Optional |
| `APIFY_TOKEN`                            | Apify config/client readiness and optional Actor checks | Optional |
| `FINDTREND_APIFY_ACTORS_PATH`            | Optional path to reviewed Apify source JSON             | Optional |
| `AI_OS_AI_RUNTIME_ENABLED`               | Enable/disable script-side AI OS host runtime           | Optional |
| `AI_OS_AI_RUNTIME_PROVIDER`              | Select disabled, mock, codex-account, or openai-api     | Optional |
| `AI_OS_AI_RUNTIME_MODEL`                 | Requested AI OS host runtime model                      | Optional |
| `AI_OS_AI_RUNTIME_REASONING_EFFORT`      | Requested AI OS host runtime reasoning effort           | Optional |
| `AI_OS_AI_RUNTIME_BASE_URL`              | Host Codex account-auth backend base URL override       | Optional |
| `AI_OS_OPENAI_ACCOUNT_AUTH_PATH`         | Canonical host path for account-auth JSON               | Optional |
| `FINDTREND_APIFY_ACTORS`                 | Optional inline Apify source config override            | Optional |
| `FINDTREND_APIFY_DEFAULT_MEMORY_MB`      | Default Apify Actor memory in MB                        | Optional |
| `FINDTREND_APIFY_DEFAULT_TIMEOUT_SECS`   | Default Apify Actor timeout in seconds                  | Optional |
| `FINDTREND_APIFY_COLLECTION_BUDGET_SECS` | Total Apify collection budget per aggregate run         | Optional |
| `FINDTREND_APIFY_MAX_ITEMS_PER_SOURCE`   | Default Dataset item cap per source                     | Optional |
| `FINDTREND_AI_RUNTIME_ENABLED`           | Enable/disable script-side Trend Finder AI runtime      | Optional |
| `FINDTREND_AI_RUNTIME_PROVIDER`          | Select disabled, mock, codex-account, or openai-api     | Optional |
| `FINDTREND_AI_RUNTIME_MODEL`             | Requested analyst model                                 | Optional |
| `FINDTREND_AI_RUNTIME_REASONING_EFFORT`  | Requested reasoning effort                              | Optional |
| `FINDTREND_AI_RUNTIME_ORIGINATOR`        | Originator label included with runtime requests/logs    | Optional |
| `FINDTREND_AI_RUNTIME_BASE_URL`          | Codex account-auth backend base URL override            | Optional |
| `FINDTREND_AI_RUNTIME_AUTH_PATH`         | Compatibility path for account-auth JSON                | Optional |
| `FINDTREND_OPENAI_ACCOUNT_AUTH_PATH`     | Primary Codex account-auth runtime path                 | Optional |
| `FINDTREND_OPENAI_OAUTH_CALLBACK_HOST`   | OpenAI account OAuth callback bind host                 | Optional |
| `HERMES_HOME`                            | Hermes scanner and Vite dev bridges                     | Optional |
| `AI_OS_LOCAL_ALL_ACCESS`                 | Canonical local all-access startup switch               | Optional |
| `HERMES_DASHBOARD_ADMIN`                 | Legacy Hermes compatibility alias derived by local dev  | Optional |
| `HERMES_BIN`                             | Trusted local Hermes executable override                | Optional |
| `HERMES_DOCUMENTS_DIR`                   | Hermes document read/write directory override           | Optional |
| `HERMES_MIRROR`                          | Allowed git mirror root for Pantheon persona sync       | Optional |
| `HERMES_OBSIDIAN_VAULTS`                 | Obsidian vault allow-list for Hermes memory linking     | Optional |
| `HERMES_OBSIDIAN_VAULT`                  | Single-vault Obsidian allow-list compatibility value    | Optional |
| `GIT_BIN`                                | Git executable override for Pantheon mirror sync        | Optional |
| `CLAUDE_OS_PHOTO_ALLOWED_HOSTS`          | Operator photo proxy allowlist extension                | Optional |
| `VITE_CLAUDE_OS_ENABLED_EXTENSIONS`      | Browser-exposed extension enablement list               | Optional |
| `TREND_FINDER_HN_ITEMS`                  | HN story fetch count per collection run                 | Optional |

(\*) Required only for image generation scripts. Not needed for setup or aggregation.

## Failure Modes

| Script                      | Failure Behavior                                                                                |
| --------------------------- | ----------------------------------------------------------------------------------------------- |
| `setup.ts`                  | Logs per-step pass/fail, records failed setup steps, prints a failed summary, and exits nonzero |
| `aggregate.ts`              | Logs warnings for skipped optional signals; exits nonzero when generated data fails validation  |
| `gen-image.ts`              | Throws if KIE\_API\_KEY missing; throws on API or timeout error                                 |
| `batch-generate`            | Reports per-job pass/fail summary; does not exit early                                          |
| `gen-dream-images`          | Reports per-job pass/fail summary; does not exit early                                          |
| `gen-cadence`               | Reports per-job pass/fail summary; does not exit early                                          |
| `openai-account-auth`       | Reports status or performs login/refresh/logout with redacted output                            |
| `openai-codex-smoke`        | Runs Codex transport or reports redacted missing/invalid auth recovery                          |
| `openai-agents-codex-smoke` | Reports deferred Agents SDK behavior without importing `@openai/agents`                         |
| `apify-smoke`               | Reports Apify readiness; missing APIFY\_TOKEN is a warning; source checks are opt-in            |

`scripts/poll-existing.ts` was removed because it was an unsupported one-shot helper with hard-coded historical Kie task IDs and stale PNG output targets. Use the active generation scripts above for new Kie image jobs.

See [AI Runtime Setup](/ai-os-and-trend-finder-docs/docs/ai-runtime-setup.md) for credential paths, runtime env placeholders, AI OS host precedence, and the implemented/deferred boundary.

## Test Commands

Vitest test commands are defined in `package.json`, not as script files in this directory:

| Command                 | Purpose                        |
| ----------------------- | ------------------------------ |
| `bun run test`          | Run all tests once             |
| `bun run test:watch`    | Run tests in watch mode        |
| `bun run test:coverage` | Run tests with coverage report |

Test files live in colocated `__tests__/` directories under `src/`, `scripts/lib/`, and `scripts/extensions/`, with top-level browser and Bun runner suites under `tests/`. See [docs/testing.md](/ai-os-and-trend-finder-docs/docs/testing.md) for details.

Focused runtime certification uses:

```bash
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:e2e -- tests/e2e/trend-finder.spec.ts tests/e2e/trend-finder-engine-replay.spec.ts
bun run runtime:check-private
```

The final submission pass also runs app and script typechecks, the full Vitest suite, lint, format check, production build, and bundle budget check. See [`docs/hackathon/hackathon-submission.md`](/ai-os-and-trend-finder-docs/docs/hackathon/hackathon-submission.md) for the complete command list and Loom-safe claim boundaries.


---

# 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/scripts/readme_scripts.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.