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

# AGENTS.md

Guidance for AI coding agents working in this repository.

Use the user's prompt and the relevant source files for task-specific context; use the code as the source of truth where relevant.

## Reference Docs

* [Documentation](https://github.com/moshehbenavraham/ai-os/blob/main/docs/README.md)
* [Conventions](/ai-os-and-trend-finder-docs/docs/conventions.md)
* [Considerations](/ai-os-and-trend-finder-docs/docs/considerations.md)
* [Product Requirements](/ai-os-and-trend-finder-docs/docs/prd.md)
* [UX Requirements](/ai-os-and-trend-finder-docs/docs/prd_ux.md)
* [Project Identity](/ai-os-and-trend-finder-docs/docs/project-identity.md)
* [Onboarding](/ai-os-and-trend-finder-docs/docs/onboarding.md)
* [Development](/ai-os-and-trend-finder-docs/docs/development.md)
* [Local API Notes](/ai-os-and-trend-finder-docs/docs/api/readme_api.md)
* [AI OS Dream Runbook](/ai-os-and-trend-finder-docs/docs/runbooks/ai-os-dream.md)

## Common Commands

* `bun install` - install dependencies with the repo-pinned Bun version.
* `bun run dev` - seed fallback data and start the local app on `http://127.0.0.1:5189`.
* `bun run setup` - run local telemetry setup, compatibility installs, and hook wiring. This can read and write local machine state.
* `bun run aggregate` - refresh local host and extension generated data.
* `bun run scheduler:agents:run` - refresh host/local AI OS data only.
* `bun run scheduler:trend-finder:run` - refresh Trend Finder data only.
* `bun run scheduler:dream:run` - run AI OS Dream through the scheduler.
* `bun run test`, `bun run lint`, `bun run typecheck`, and `bun run typecheck:scripts` - primary validation commands.

## Access And Delivery Defaults

* Local AI OS product goals default to full local access, write access, and edit access. Do not define a new shipped local operator capability as observe-only, metadata-only, or manually admin-disabled unless the user explicitly asks for that exception or an external compliance boundary proves it is required.
* Read or metadata-only behavior is valid only as a named exception, a public demo/privacy boundary, a third-party source-compliance constraint, or a temporary implementation gap with an owner and recovery path. It is never the default product posture for local operator goals.
* Proper delivery means every shipped feature proves the intended user outcome end to end in the product: real execution, visible results, clear recovery paths, and focused tests. Do not count scaffolding, mock-only flows, labels, or disabled controls as complete delivery.

## Local Control Plane

* The local app uses Vite middleware for `GET /__live-data`, `GET /__token`, `POST /__refresh_data`, and `POST /__run_dream`.
* Hermes bridge routes live under `/__hermes_*`. Current public reads, token-gated reads, and write gates differ by route; check the bridge code and docs before documenting or changing a route.
* Do not add voice broker, Intelligence portal, or Dream engine-selection claims unless the matching code and tests exist in this repo. Current-state voice and Intelligence docs should identify Session 08 broker ownership, Session 09 portal ownership, and any unverified live-provider caveats.

## Privacy And Secrets

* Do not commit `.env`, `.env.local`, generated private data, account-auth files, API keys, bearer tokens, local logs, coverage, test results, browser reports, or raw operator data.
* `src/data/live-data.json` is generated and gitignored. The committed fallback is `src/data/live-data.example.json`.
* Browser-facing data, Vite middleware responses, public demo fixtures, and scheduler status output must use safe labels or redacted paths instead of raw home-directory paths, prompts, transcripts, auth JSON, tokens, or local usernames.
* Use placeholders shorter than real key patterns in docs.

## Naming Boundaries

* Use AI OS for the host app, shell, setup, local operator cockpit, scheduler, Dream host behavior, local-agent telemetry, and platform docs.
* Use Trend Finder only for the extension, public trend evidence, source collection, scoring, creator angles, watchlists, Brief, and Engine Replay.
* Use Claude OS only for inherited starter behavior, upstream attribution, or explicit compatibility contracts.
* `ai-os` is the canonical package/runtime/storage prefix for new global identifiers.
* Preserve existing `VITE_CLAUDE_OS_*`, `CLAUDE_OS_*`, and `FINDTREND_*` names as compatibility contracts unless a migration explicitly adds aliases, docs, and tests.
* Do not add new global `findtrend` identifiers.

## Implementation Rules

* Prefer existing project patterns over new abstractions.
* Document current shipped behavior before planned behavior.
* Keep public demo, local bridge, scheduler, Dream, Hermes, and Trend Finder data boundaries separate.
* Add focused tests when changing model recognition, bridge contracts, scheduler behavior, source parsing, scoring, or user-facing workflows.
* Keep documentation and fixtures free of secret-shaped strings and private generated data.


---

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