# ⛔ ARCHIVED — DO NOT USE

> **This repository is ARCHIVED as of 2026-07-23.**
>
> Per operator directive 2026-07-23 ("ai shell repo needs deleting these shell modules need to belong to Oscar"), all shell modules have been moved to `avidtech6/oscar-platform/app/src/modules/<m>/` and the gallery has been re-mirrored to source from Oscar.
>
> **Status**: DEPRECATED — do not consume `@freshvibe/ai-shell` in any new code.
> **Migration**: Update imports from `@freshvibe/ai-shell/{voice,components,ui,engine,styles}` to:
>   - `@oscar/ai-mic`, `@oscar/ai-toast`, `@oscar/ai-stt`, `@oscar/ai-workspaces-chip` (chrome modules, now in Oscar)
>   - Local imports for engine code (was a re-export of Oscar's `app/src/assistant/`)
>   - `./styles/ai-shell.css` (CSS moved to Oscar)
>
> **The repository will remain on GitHub for historical reference but is read-only.**

---

# Original README follows

# ai-shell

The constitutional AI shell for the FreshVibe ecosystem. Used by FreshVibe Studio (Windows app), the 3 standalones (FreshCards, VibeCoder, VibeScope), and Oscar Platform.

## Three modes

- **`local`** — Windows app. Encrypted IndexedDB. Offline-capable.
- **`hosted`** — VPS standalone. PocketBase. Multi-user.
- **`studio`** — Studio connected to VPS. PocketBase. Shared conversations.

## Usage

```tsx
import {
  AiShellProvider,
  AskUnit,
  ToastHost,
  WorkspacesChip,
  useCredentials,
  useChat,
  registerDefaultProviders,
} from '@freshvibe/ai-shell';
import '@freshvibe/ai-shell/styles';

function App() {
  return (
    <AiShellProvider
      config={{
        mode: 'local',
        appId: 'freshcards-standalone',
        defaultWorkspaceId: 'freshcards',
        encryptionPassphrase: 'user-chosen-passphrase',
      }}
    >
      <YourApp />
      <ToastHost />
      <WorkspacesChip position="top-right" />
    </AiShellProvider>
  );
}

function YourApp() {
  return (
    <main>
      <h1>FreshCards</h1>
      <AskUnit placeholder="Ask about your cards…" />
    </main>
  );
}
```

## Exports

- `AiShellProvider`, `useAiShell`, `useAiShellOptional` — context
- `AskUnit` — input bar + answer surface
- `ToastHost`, `pushToast`, `dismissToast`, `dismissAllToasts` — toasts
- `WorkspacesChip` — cross-app nav
- `useThreads`, `useCredentials`, `useProviders`, `useChat` — hooks
- `IndexedDBStorage`, `PocketBaseStorage` — storage adapters
- `migrateLocalToPB`, `getLocalMigrationSize`, `validateMigration` — migration
- `eventBus`, `bridgeWindowToBus` — cross-surface events
- `registerProvider`, `listProviders`, `OpenAICompatibleProvider`, `registerDefaultProviders` — provider registry
- Types

## Mode-specific configuration

### Local mode

```tsx
<AiShellProvider
  config={{
    mode: 'local',
    appId: 'studio',
    defaultWorkspaceId: 'origin',
    encryptionPassphrase: 'user-chosen',
    indexedDB: { name: 'studio-ai' },
  }}
>
```

### Hosted mode (VPS standalone)

```tsx
<AiShellProvider
  config={{
    mode: 'hosted',
    appId: 'vibecoder-standalone',
    defaultWorkspaceId: 'vibecoder',
    pocketbaseUrl: 'https://pb.freshvibeapps.com',
    pocketbaseToken: '<jwt-from-panel>',
  }}
>
```

### Studio mode

```tsx
<AiShellProvider
  config={{
    mode: 'studio',
    appId: 'studio',
    defaultWorkspaceId: 'origin',
    pocketbaseUrl: 'https://pb.freshvibeapps.com',
    pocketbaseToken: '<jwt-from-panel>',
    systemPromptBuilder: createOriginContextBuilder(),
  }}
>
```

## Context builders

```tsx
// VibeCoder: inject active file + cursor
import { createVibeCoderContextBuilder } from '@freshvibe/ai-shell/context-builders/vibecoder';

const builder = createVibeCoderContextBuilder({
  getActiveFile: () => ({ path, content, cursor }),
});
```

```tsx
// VibeScope: inject active layer + properties
import { createVibeScopeContextBuilder } from '@freshvibe/ai-shell/context-builders/vibescope';

const builder = createVibeScopeContextBuilder({
  getActiveLayer: () => ({ id, type, properties }),
});
```

## Migration

When switching from `local` to `hosted`/`studio`, flush local data to PB:

```tsx
import { migrateLocalToPB, getLocalMigrationSize } from '@freshvibe/ai-shell';

const size = await getLocalMigrationSize(localStorage);
if (size.threads > 0 || size.credentials > 0) {
  if (confirm(`Migrate ${size.threads} threads and ${size.credentials} credentials?`)) {
    const report = await migrateLocalToPB({ source: localStorage, target: pbStorage });
    console.log(report);
  }
}
```

## Pact

See `pact/ai-shell.md` for the constitutional rules. Major version bumps for breaking changes.

## License

UNLICENSED. © FreshVibe. Private repo.