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

# Onboarding

## Prerequisites

* Bun 1.3.14 installed. `.bun-version` and CI pin this exact release for hackathon certification parity.
* Git installed.
* Node-compatible shell environment.

## Setup Paths

Choose one setup path. The quick path is enough for normal UI development. The full telemetry path intentionally reads and writes local machine state.

### Quick Start UI Only

Use this path when you only need the app to run with safe fallback data.

1. Clone the repository.
2. Enter the project directory.
3. Install dependencies:

```bash
bun install
```

4. Start the app:

```bash
bun run dev
```

5. Open `http://127.0.0.1:5189` if the browser does not open automatically.

`bun install` may load `.env.local` before install-time scripts such as `postinstall` run. Keep secrets in ignored files and do not paste secret values into shell commands. The project `postinstall` script only wires this clone's local Git hook path when `.githooks/` is available.

`bun run dev` runs `seed:data` first. `seed:data` copies `src/data/live-data.example.json` to `src/data/live-data.json` only when `src/data/live-data.json` is missing; it does not overwrite an existing generated file. The dev server can also fall back to the example file if the generated file is absent.

The browser setup flow saves choices in `localStorage`. To preconfigure setup wizard fields from `.env.local`, use the public `VITE_CLAUDE_OS_*` values and restart `bun run dev`; see [Public Browser Configuration](/ai-os-and-trend-finder-docs/docs/environments.md#public-browser-configuration).

The local dashboard uses Vite middleware for current browser data and local actions: `GET /__live-data` serves generated or fallback data, `GET /__token` hands the local browser a same-run token, `POST /__refresh_data` refreshes generated data, and `POST /__run_dream` starts a manual Dream run. Refresh and Dream actions require loopback access and the same-run token.

Because the dev server always uses `http://127.0.0.1:5189`, browser `localStorage` and same-origin tokens can carry across disposable clones. For a clean first-run check, clear site data for `127.0.0.1:5189` or use a fresh browser profile before opening the app.

For certification runs where opening the default browser would pollute the test, use this no-open equivalent and open the URL manually in a clean profile:

```bash
bun run seed:data
bunx vite dev --host 127.0.0.1 --port 5189
```

### Full Local Telemetry Setup

Use this path when you want AI OS to scan local tool, memory, and integration signals and generate local dashboard data.

```bash
bun install
bun run setup
bun run dev
```

This is optional for developing AI OS. It is only needed if you want the inherited operator dashboard pages to show local machine data.

`bun run setup` may:

* Run the aggregate writer and update `src/data/live-data.json`.
* Write private aggregate traces under `logs/`.
* Copy `skills/dream/` to `~/.claude/skills/dream/`.
* Copy `skills/personas/` to `~/.hermes/skills/personas/` when absent.
* Install the AI OS Dream schedule on macOS or Windows, or print Linux cron guidance.
* Set `core.hooksPath` to `.githooks` in this Git checkout.
* Write `~/.ai-os/show-wizard` so the browser setup wizard opens once.
* Read optional local config and auth presence from locations such as `~/.claude/`, `~/.codex/`, Obsidian, Pinecone, and OpenRouter.

If a required setup step fails, `bun run setup` exits nonzero and prints a final failed summary. `bun run dev` can still load sample data after a setup failure, but that is not a successful full telemetry setup.

`bun run setup` output is terminal-only local diagnostics. It may print absolute local paths when a step needs to tell you what it read, copied, skipped, or could not find. Browser-bound generated data, Vite middleware responses, and scheduler status output must keep raw private home and repository paths out of the payload by using safe labels or redacted paths.

### Credential-Free Hackathon Demo

Use a disposable clone when you need a demo or recording that does not depend on private credentials. This path intentionally resets generated dashboard data to the committed fixture/demo payload.

See [Credential-Free Demo Path](/ai-os-and-trend-finder-docs/docs/hackathon/hackathon-submission.md#credential-free-demo-path) for the exact commands and the warning before removing `src/data/live-data.json`.

### Platform Limitations

The `bun run setup` command works on all platforms, but some signals remain platform-specific:

* **Dream schedule**: Uses macOS `launchd` or Windows Task Scheduler. Linux prints manual cron guidance instead of editing the user's crontab.
* **Local control plane**: Browser refresh and Dream controls are local Vite middleware actions, not public APIs; keep them on loopback.
* **Keychain detection**: macOS-only. Non-macOS environments report no keychain signals.
* **Terminal app detection**: Partially macOS-specific (iTerm, Terminal.app). Non-macOS environments detect generic terminal emulators where possible.

All other aggregator features (Claude/Codex session scanning, Obsidian vault scanning, Pinecone/OpenRouter API polling) work cross-platform.

## Optional Scheduled Aggregate

Scheduled aggregate is an AI OS host scheduler path for refreshing generated local data through the scheduler runner. Starter metadata marks it enabled by default, while timer installation remains local machine setup outside `bun run setup`.

Local timer intent lives in `data/ai-os.scheduler.json`, seeded from `data/ai-os.scheduler.example.json`. The private file may only select reviewed scheduler jobs, reviewed cadence IDs, booleans, and strict Dream `HH:MM` times. It does not install a timer; it only records local intent for `bun run scheduler:status`.

Run the command-first checks from the repository root:

```bash
bun run scheduler:status
bun run scheduler:run
bun run scheduler:status
```

On a fresh checkout, the first status command can report `Not run yet` because no private scheduler state exists. After `bun run scheduler:run`, status should show the latest aggregate scheduler state, warning count, duration, exit code, trigger source, and lock outcome without printing private log contents or local paths.

The default scheduled aggregate cadence is every 4 hours. To enable an actual Linux user timer, create a local systemd user unit from your checkout path; see [Scheduled Aggregate Runbook](/ai-os-and-trend-finder-docs/docs/runbooks/scheduled-aggregate.md). Keep any machine-specific unit files out of git.

`bun run scheduler:run` remains the compatibility full-aggregate writer. Use `bun run scheduler:agents:run` when you only want host/local AI OS data, and use `bun run scheduler:trend-finder:run` when you only want Trend Finder extension data. The matching status commands report safe labels and any local timer intent from the private config file without printing private paths or raw logs.

The direct refresh path remains available:

```bash
bun run aggregate
```

Both direct and scheduler-invoked aggregate refresh `src/data/live-data.json`. The scheduler path additionally writes private scheduler run state, lock, and log records. Generated data, `.env.local`, account auth files, caches, logs, coverage, test results, and browser reports must stay untracked.

## Verify Setup

* [ ] `bun install` completes.
* [ ] `bun run dev` starts on `http://127.0.0.1:5189`.
* [ ] The app renders with fallback data when no generated local data exists.
* [ ] Optional: `bun run scheduler:status` prints safe aggregate status.
* [ ] Optional: `bun run scheduler:agents:status` prints safe host/local status.
* [ ] Optional: `bun run scheduler:trend-finder:status` prints safe Trend Finder status.
* [ ] Optional: `bun run scheduler:run` completes or records a safe local failure state without exposing private data.
* [ ] `bun run typecheck` completes with no errors.
* [ ] `bun run test` completes with all tests passing.
* [ ] `bun run lint` completes before PRs.
* [ ] `bun run build` completes before PRs.

## Optional Extension Enablement

The Trend Finder extension is opt-in. To enable it, add this to `.env.local`:

```bash
VITE_CLAUDE_OS_ENABLED_EXTENSIONS=trend-finder
```

Then restart `bun run dev`. The Trend Finder views appear in the sidebar under Extensions. Direct Trend Finder URLs are still registered when the switch is unset, so fixture/demo routes can render from the committed fallback payload; that is route availability, not proof that the collector ran.

The same switch is read by script-side extension collection. Run `bun run scheduler:trend-finder:run` to refresh only Trend Finder data, or `bun run aggregate` when you intentionally want a full host/local and extension refresh. If the switch is unset for those commands, Trend Finder is disabled or skipped. Hacker News can collect without an API key when the collector runs. Apify source execution additionally requires `APIFY_TOKEN` and explicit reviewed source config.

## Local Data Safety

* `src/data/live-data.json` is generated and gitignored.
* `.env.local` is gitignored.
* Scheduled aggregate run state, locks, and logs are private local diagnostics.
* Keep generated local telemetry and API keys out of commits.


---

# 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/onboarding.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.