> 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/src/extensions/readme_extensions.md).

# Extensions

Compile-time extension platform for adding modular features to AI OS. Trend Finder and AI Rogue are the current registered extensions.

For a step-by-step guide to adding a new extension, see [docs/extensions/README\_docs-extensions.md](/ai-os-and-trend-finder-docs/docs/extensions/readme_docs-extensions.md).

## Architecture

Extensions are statically registered at build time. There is no dynamic code loading. Each extension declares client views, a sidebar entry, capabilities, and optionally a script-side collector. Multi-view extensions use the host's extension-local view navigation instead of adding every view to the global sidebar.

## Client Contracts

| File          | Purpose                                                 |
| ------------- | ------------------------------------------------------- |
| `types.ts`    | ClientExtension, ExtensionView, capability declarations |
| `registry.ts` | Static extension list, env-based enablement             |

Enablement is controlled by the static registry plus `VITE_CLAUDE_OS_ENABLED_EXTENSIONS` overrides in `.env.local`. AI Rogue is production-enabled by default and remains enabled for any non-`none` extension list. Trend Finder remains opt-in. After changing a `VITE_` value, restart Vite so the browser bundle sees the new list. Editing `.env.local.example` only updates the committed template.

## Data Access

| File                    | Purpose                                             |
| ----------------------- | --------------------------------------------------- |
| `use-extension-data.ts` | Selector hook over the `LiveData.extensions` branch |

### Runtime Data Modes

Every extension is registered in the browser registry, but not every enabled extension has a collector item in `liveData.extensions.items`.

Set `runtimeDataMode` on the `ClientExtension` when the default collector-item mode is not correct:

| Mode             | Use It When                                                                                     |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| `extension-item` | A script-side collector writes browser-safe data under `liveData.extensions.items[extensionId]` |
| `host-live-data` | A client-local extension reads the host LiveData payload and does not emit a collector item     |

`extension-item` is the default. An enabled extension in this mode remains pending or unknown until its collector item exists. `host-live-data` extensions can be enabled without a matching item under `liveData.extensions.items`; `use-extension-data.ts` passes the full host LiveData payload to the view.

## Registered Extensions

| ID             | Name         | Version | Views | Status                            |
| -------------- | ------------ | ------- | ----- | --------------------------------- |
| `trend-finder` | Trend Finder | 0.1.0   | 6     | Opt-in, collector-backed          |
| `ai-rogue`     | AI Rogue     | 0.1.0   | 4     | Production default, host LiveData |

## Trend Finder Extension

```
trend-finder/
|-- client.tsx                 # Extension registration (views, sidebar nav, capabilities)
|-- schema.ts                  # Zod schemas and parseTrendFinderData
|-- fixtures.ts                # Synthetic sample data
|-- view-model.ts              # Dashboard-facing derived state
|-- creator-lens-storage.ts    # Browser-local Creator Lens draft helpers
|-- run-control.ts             # Run status and refresh coordination helpers
|-- components/                # Trend cards, score/source breakdowns, run controls
|-- hooks/                     # Creator Lens and run-control hooks
`-- views/
    |-- trends-view.tsx
    |-- signal-workbench-view.tsx
    |-- hidden-gems-view.tsx
    |-- sources-view.tsx
    |-- watchlist-view.tsx
    `-- brief-view.tsx
```

The collector side lives in `scripts/extensions/trend-finder/`. See [Scripts README](/ai-os-and-trend-finder-docs/scripts/readme_scripts.md) for collector details.

## AI Rogue Extension

```
ai-rogue/
|-- capabilities.ts             # readGeneratedData and localStorage declarations
|-- client.tsx                  # Extension registration and lazy view wrappers
|-- economy.ts                  # Browser-safe Insight Shards derivation
|-- persistence.ts              # Browser-local localStorage and IndexedDB helpers
|-- progression.ts              # Capped local progression derivation
|-- save-schema.ts              # Versioned save, wallet, ledger, and history schemas
|-- runtime/                    # Pure simulation plus lazy PixiJS runtime boundary
`-- views/
    |-- play-view.tsx
    |-- ledger-view.tsx
    |-- loadout-view.tsx
    `-- settings-view.tsx
```

AI Rogue has no script-side collector. It reads browser-safe generated data through the normal extension host with `runtimeDataMode: "host-live-data"`, derives capped local economy/progression state, and stores wallet, ledger, preferences, run history, and save slots in browser-local storage only.

## Host Routes

| Route                              | Purpose                  |
| ---------------------------------- | ------------------------ |
| `/extensions`                      | Extension listing page   |
| `/extensions/$extensionId`         | Redirect to default view |
| `/extensions/$extensionId/$viewId` | Extension view host      |

Trend Finder Engine Replay is a dedicated utility route at `/extensions/trend-finder/engine`. It is Trend Finder-scoped, but it is not one of the six creator-facing extension views registered in `client.tsx`.

AI Rogue uses `/extensions/ai-rogue/play` as its primary route, with `ledger`, `loadout`, and `settings` as supporting extension-local views.

## Adding an Extension

1. Create a `ClientExtension` object in `src/extensions/<name>/client.tsx`.
2. Add it to the `extensions` array in `src/extensions/registry.ts`.
3. Choose `runtimeDataMode`: omit it for collector-backed `extension-item`, or set `"host-live-data"` for client-local host-data extensions.
4. Optionally create a `CollectorExtension` in `scripts/extensions/<name>/collector.ts` and register it in `scripts/extensions/registry.ts`.
5. Decide the visibility default. Add collector-backed or experimental extension IDs to `VITE_CLAUDE_OS_ENABLED_EXTENSIONS` in `.env.local`; add production-default client extensions through reviewed registry code and focused tests.
6. Restart Vite after changing `.env.local`.


---

# 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/src/extensions/readme_extensions.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.