> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.forboc.ai/npm/installation/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.forboc.ai/_mcp/server.

# Installation

## Choose Packages

```bash
# Node runtime + CLI
npm install @forbocai/node

# Browser runtime slices/thunks
npm install @forbocai/browser

# Core protocol/state/thunks only
npm install @forbocai/core
```

The legacy unscoped `forbocai` package is a thin redirect to `@forbocai/core`. New consumers should use the scoped packages directly.

## Export Matrix

| Export                                                     | `@forbocai/core` | `@forbocai/node` | `@forbocai/browser` |
| :--------------------------------------------------------- | :--------------: | :--------------: | :-----------------: |
| `createSDKStore`                                           |        Yes       |  Yes (extended)  |    Yes (extended)   |
| `setNPCInfo`, `processNPC`, `updateNPCState`               |        Yes       |         —        |          —          |
| Protocol thunks (directive, context, verdict)              |        Yes       |         —        |          —          |
| Remote memory thunks                                       |        Yes       |         —        |          —          |
| Bridge / Soul / Ghost thunks                               |        Yes       |         —        |          —          |
| RTK Query API slice (`sdkApi`)                             |        Yes       |         —        |          —          |
| Functional core (`Maybe`, `Either`, `pipe`, `curry`)       |        Yes       |         —        |          —          |
| `createNodeCortex` + Node cortex slice                     |         —        |        Yes       |          —          |
| Node memory slice (LanceDB)                                |         —        |        Yes       |          —          |
| Node vector slice                                          |         —        |        Yes       |          —          |
| CLI binary (`forbocai`)                                    |         —        |        Yes       |          —          |
| Native deps tooling (`checkNativeDeps`, `setupNativeDeps`) |         —        |        Yes       |          —          |
| Browser cortex thunks (WebLLM)                             |         —        |         —        |         Yes         |
| Browser memory slice (Orama)                               |         —        |         —        |         Yes         |
| Browser vector slice                                       |         —        |         —        |         Yes         |

`@forbocai/node` and `@forbocai/browser` both depend on `@forbocai/core`. Install the environment-specific package and you get core automatically.

## Requirements

* Node.js `20+`
* For `@forbocai/node`: native build toolchain for `node-llama-cpp` (C++ compiler, CMake)
* For `@forbocai/browser`: WebGPU-capable browser for WebLLM

## Environment-Specific Gotchas

| Concern                | `@forbocai/node`                            | `@forbocai/browser`                      |
| :--------------------- | :------------------------------------------ | :--------------------------------------- |
| **Vector DB**          | LanceDB (file-based, persists to disk)      | Orama (in-memory, ephemeral per session) |
| **Cortex engine**      | `node-llama-cpp` (GGUF models, CPU/GPU)     | WebLLM (WebGPU, browser tab)             |
| **Model download**     | Automatic on first use via HTTP             | Automatic on first use via WebLLM cache  |
| **Memory persistence** | Survives process restarts (LanceDB on disk) | Lost on tab close (Orama in-memory)      |
| **CLI**                | `npx forbocai <command>`                    | N/A                                      |
| **Native deps**        | Requires C++ toolchain for `node-llama-cpp` | No native deps                           |

## API Configuration

Node runtime config resolution:

1. `FORBOCAI_API_URL`
2. `~/.forbocai.json` (`apiUrl`)
3. fallback default: `http://localhost:8080`

API key resolution:

1. `FORBOCAI_API_KEY`
2. `~/.forbocai.json` (`apiKey`)

Recommended for hosted API usage:

```bash
export FORBOCAI_API_URL=https://api.forboc.ai
export FORBOCAI_API_KEY=fb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Minimal Integration (Node)

```typescript
import { createSDKStore, setNPCInfo, processNPC } from '@forbocai/core';
import { createNodeCortex } from '@forbocai/node';

const store = createSDKStore();
const cortex = createNodeCortex('smollm2-135m');
await cortex.init();

store.dispatch(setNPCInfo({ id: 'npc_demo', persona: 'A helpful guide' }));

await store.dispatch(processNPC({
  npcId: 'npc_demo',
  text: 'Hello there',
  apiUrl: process.env.FORBOCAI_API_URL || 'https://api.forboc.ai',
  apiKey: process.env.FORBOCAI_API_KEY,
  cortex
})).unwrap();
```

## Verify via CLI

```bash
npx forbocai doctor
npx forbocai status
```

> Package selection and runtime setup