@omiron33/omi-neuron-web 0.1.6 → 0.2.1

package/README.md

@@ -1,59 +1,819 @@
 # omi-neuron-web
 
-A drop-in Next.js library for data analysis and 3D visualization with OpenAI-powered insights.
+Agent Implementation Guide (exhaustive)
 
-## Features
+This README is written for AI agents and engineers who need a complete, precise view of the repo and how to implement or extend it. It enumerates every public entry point, type, class, configuration field, and runtime behavior that the library exposes today.
 
-- 🔮 **AI-powered analysis** - OpenAI integration for embeddings, clustering, and relationship inference
-- 🕸️ **Interactive visualization** - Three.js graph with customizable themes and interactions
-- 🐘 **Zero-config database** - Docker PostgreSQL with pgvector automatically provisioned
-- 📊 **Smart clustering** - K-means and DBSCAN algorithms for grouping similar nodes
-- 🎨 **Fully customizable** - Themes, colors, node types, and domains configurable per project
-- 🔌 **Simple React API** - Provider and hooks for seamless integration
+If you are working inside this repo, also read `AGENTS.md` for execution rules, plan order, and task tracking.
 
-## Quick Start
+## What this repo provides
 
-```bash
-# Install the package
-pnpm add @omiron33/omi-neuron-web
+- A TypeScript library for graph data analysis plus 3D visualization (Three.js) with a Next.js-friendly API.
+- A CLI that scaffolds configuration, Docker Postgres (pgvector), and Next.js route handlers.
+- A Node/Edge/Cluster data model, plus analysis and embeddings pipelines.
+- A React provider and hooks that wrap the API client.
+
+## Package entry points
+
+The published package exposes these entry points (see `package.json` exports):
+
+- `@omiron33/omi-neuron-web` (root) - types, schemas, analysis, storage, config helpers, visualization component, React hooks/provider.
+- `@omiron33/omi-neuron-web/api` - API route factory, repositories, query builder, middleware, API types.
+- `@omiron33/omi-neuron-web/visualization` - NeuronWeb component, theme, layout utilities, scene manager.
+- `@omiron33/omi-neuron-web/migration` - migration list and runner.
+- `@omiron33/omi-neuron-web/cli` - CLI entry (also exposed via the `omi-neuron` binary).
+
+## Repository map (what to edit)
+
+- `src/core/types/*` - Type system. If you add fields, update Zod schemas and migrations.
+- `src/core/schemas/*` - Zod runtime validation. Keep in sync with types.
+- `src/core/analysis/*` - Embeddings, clustering, relationship inference, scoring, pipeline.
+- `src/core/events/*` - Event bus and event types.
+- `src/storage/*` - Database, Docker manager, query helpers, migrations.
+- `src/api/*` - Route factory, repositories, query builder, middleware.
+- `src/visualization/*` - Three.js scene, renderers, interactions, animations, layout.
+- `src/react/*` - Provider, context, API client, hooks.
+- `src/cli/*` - CLI commands and templates.
+- `docs/*` - Additional docs (older, not as exhaustive as this README).
+
+## Root exports (from `src/index.ts`)
+
+```ts
+// Types and schemas
+export * from './core/types';
+export * from './core/schemas';
+export * from './core/events';
+
+// Analysis engines
+export { DataProcessor } from './core/analysis/data-processor';
+export { EmbeddingsService } from './core/analysis/embeddings-service';
+export { ClusteringEngine } from './core/analysis/clustering-engine';
+export { RelationshipEngine } from './core/analysis/relationship-engine';
+export { ScoringEngine } from './core/analysis/scoring-engine';
+export { AnalysisPipeline } from './core/analysis/pipeline';
+
+// Storage helpers
+export * from './storage';
+
+// Config helper
+export * from './config';
+
+// Visualization
+export { NeuronWeb } from './visualization';
+export type { NeuronWebProps, NeuronWebTheme, NeuronLayoutOptions, NeuronLayoutMode } from './visualization';
 
-# Initialize in your Next.js project
-npx @omiron33/omi-neuron-web init
+// React integration
+export * from './react/hooks';
+export { NeuronWebProvider } from './react/NeuronWebProvider';
 
-# Start the database
-npx @omiron33/omi-neuron-web db:up
+// Version constant
+export const VERSION = '0.1.1';
+```
+
+Note: `VERSION` is not currently auto-synced to `package.json`. Update it when releasing.
+
+## Configuration: NeuronConfig and NeuronSettings
+
+These types live in `src/core/types/settings.ts` and are validated by Zod schemas in `src/core/schemas/settings.ts`.
+
+### NeuronConfig (full configuration)
+
+```ts
+export interface NeuronConfig extends NeuronSettings {
+  openai: {
+    apiKey: string;
+    organization?: string;
+    requestsPerMinute?: number;
+    maxRetries?: number;
+  };
+  database: {
+    mode: 'docker' | 'external';
+    port: number;
+    containerName?: string;
+    image?: string;
+    user?: string;
+    password?: string;
+    database?: string;
+    url?: string;
+    pool?: {
+      min: number;
+      max: number;
+      idleTimeoutMs: number;
+      connectionTimeoutMs: number;
+    };
+    resources?: {
+      memoryLimit: string;
+      cpuLimit?: string;
+    };
+  };
+  api: {
+    basePath: string;
+    enableCors: boolean;
+    rateLimit?: {
+      windowMs: number;
+      max: number;
+    };
+  };
+  logging: {
+    level: 'debug' | 'info' | 'warn' | 'error';
+    prettyPrint: boolean;
+  };
+}
+```
+
+### NeuronSettings (runtime settings persisted in DB)
 
-# Run your Next.js app
-npm run dev
+```ts
+export interface NeuronSettings {
+  instance: {
+    name: string;
+    version: string;
+    repoName: string;
+  };
+  visualization: VisualizationSettings;
+  analysis: AnalysisSettings;
+  nodeTypes: NodeTypeConfig[];
+  domains: DomainConfig[];
+  relationshipTypes: RelationshipTypeConfig[];
+}
 ```
 
-## Documentation
+### Default settings (exact defaults)
+
+From `DEFAULT_VISUALIZATION_SETTINGS` and `DEFAULT_ANALYSIS_SETTINGS` in `src/core/types/settings.ts`:
+
+```ts
+export const DEFAULT_VISUALIZATION_SETTINGS = {
+  domainColors: {},
+  defaultDomainColor: '#c0c5ff',
+  edgeColor: '#4d4d55',
+  edgeActiveColor: '#c6d4ff',
+  backgroundColor: '#020314',
+  defaultCameraPosition: [4, 8, 20],
+  defaultCameraTarget: [0, 0, 0],
+  minZoomDistance: 4,
+  maxZoomDistance: 42,
+  enableStarfield: true,
+  starfieldCount: 1200,
+  labelDistance: 26,
+  maxVisibleLabels: 50,
+  performanceMode: 'auto',
+  nodeCountThreshold: 120,
+  pixelRatioCap: 2,
+  enableAnimations: true,
+  focusTweenDuration: 800,
+  filterTransitionDuration: 650,
+  enableHover: true,
+  enableClick: true,
+  enableDoubleClick: true,
+  enablePan: true,
+  enableZoom: true,
+  enableRotate: true,
+};
+
+export const DEFAULT_ANALYSIS_SETTINGS = {
+  embeddingModel: 'text-embedding-3-small',
+  embeddingDimensions: 1536,
+  embeddingBatchSize: 20,
+  embeddingCacheTTL: 86400,
+  clusteringAlgorithm: 'kmeans',
+  defaultClusterCount: 8,
+  minClusterSize: 3,
+  clusterSimilarityThreshold: 0.75,
+  relationshipInferenceModel: 'gpt-4o-mini',
+  relationshipMinConfidence: 0.7,
+  relationshipMaxPerNode: 10,
+  openaiRateLimit: 60,
+  maxConcurrentAnalysis: 5,
+};
+```
+
+### Full config example (neuron.config.ts)
+
+The CLI (`omi-neuron init`) writes a full config file. A complete config looks like:
+
+```ts
+import { defineNeuronConfig, DEFAULT_ANALYSIS_SETTINGS, DEFAULT_VISUALIZATION_SETTINGS } from '@omiron33/omi-neuron-web';
+
+export default defineNeuronConfig({
+  instance: {
+    name: 'my-instance',
+    version: '0.1.1',
+    repoName: 'my-repo',
+  },
+  visualization: DEFAULT_VISUALIZATION_SETTINGS,
+  analysis: DEFAULT_ANALYSIS_SETTINGS,
+  nodeTypes: [],
+  domains: [],
+  relationshipTypes: [],
+  openai: {
+    apiKey: process.env.OPENAI_API_KEY ?? '',
+    organization: undefined,
+    requestsPerMinute: undefined,
+    maxRetries: 3,
+  },
+  database: {
+    mode: 'docker',
+    port: 5433,
+    containerName: undefined,
+    image: 'pgvector/pgvector:pg16',
+    user: 'neuron',
+    password: 'neuron_dev',
+    database: 'neuron_web',
+    url: undefined,
+    pool: {
+      min: 0,
+      max: 10,
+      idleTimeoutMs: 30000,
+      connectionTimeoutMs: 5000,
+    },
+    resources: {
+      memoryLimit: '1g',
+      cpuLimit: undefined,
+    },
+  },
+  api: {
+    basePath: '/api/neuron',
+    enableCors: false,
+    rateLimit: undefined,
+  },
+  logging: {
+    level: 'info',
+    prettyPrint: true,
+  },
+});
+```
+
+### Environment variables
+
+- `OPENAI_API_KEY` - required for embeddings and relationship inference.
+- `DATABASE_URL` - optional; if set, the Database factory uses it.
+- `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME` - optional per `createDatabaseFromEnv()`.
+
+## Core data model (Types)
+
+### Nodes
+
+`NeuronNode` fields (see `src/core/types/node.ts`):
+
+- identity: `id`, `slug`, `label`, `nodeType`, `domain`, `createdAt`, `updatedAt`
+- content: `summary`, `description`, `content`
+- metadata: `metadata: Record<string, unknown>`
+- analysis fields: `embedding`, `embeddingModel`, `embeddingGeneratedAt`, `clusterId`, `clusterSimilarity`
+- relationship counts: `connectionCount`, `inboundCount`, `outboundCount`
+- status: `analysisStatus`, `analysisError`
+- visualization hints: `tier`, `visualPriority`, `positionOverride`
+
+Input types:
+
+- `NeuronNodeCreate` (minimal required fields: `label`; optional `slug`, `nodeType`, `domain`, `summary`, `description`, `content`, `metadata`, `tier`)
+- `NeuronNodeUpdate` (partial updates)
+- `NeuronNodeBatchCreate` (batch create with options)
+
+Visualization type:
+
+- `NeuronVisualNode` has `id`, `slug`, `label`, `domain`, `tier`, `metadata`, `ref`, `connectionCount`, `position`.
+
+### Edges
+
+`NeuronEdge` fields (see `src/core/types/edge.ts`):
+
+- identity: `id`, `fromNodeId`, `toNodeId`, `relationshipType`
+- strength/confidence: `strength`, `confidence`
+- evidence: `EdgeEvidence[]`
+- metadata: `label`, `description`, `metadata`, `source`, `sourceModel`, `bidirectional`, timestamps
+
+Input types: `NeuronEdgeCreate`, `NeuronEdgeUpdate`.
+
+Visualization type: `NeuronVisualEdge` uses `from` and `to` slugs.
+
+### Clusters
+
+`NeuronCluster` fields (see `src/core/types/cluster.ts`):
+
+- identity: `id`, `label`, `clusterType`
+- centroid: `centroid: number[]`
+- stats: `memberCount`, `avgSimilarity`, `cohesion`
+- metadata: `description`, `keywords`, `metadata`
 
-- [Getting Started](./docs/getting-started.md)
-- [Configuration](./docs/configuration.md)
-- [API Reference](./docs/api-reference.md)
-- [Hooks Reference](./docs/hooks-reference.md)
-- [Component Props](./docs/component-props.md)
-- [CLI Reference](./docs/cli-reference.md)
-- [Architecture](./docs/architecture.md)
-- [Troubleshooting](./docs/troubleshooting.md)
+### Analysis
 
-### Phase Overview
+`AnalysisRun`, `AnalysisRequest`, `AnalysisResponse`, `AnalysisPipelineConfig` are in `src/core/types/analysis.ts`.
 
-1. **Foundation** - Core types, Docker setup, migrations, CLI
-2. **Analysis Engine** - Embeddings, clustering, relationships, events
-3. **API Layer** - REST endpoints, repositories, query builder
-4. **Visualization** - Three.js component, themes, interactions
-5. **Integration** - Provider, hooks, examples
-6. **Validation** - Tests, documentation, npm publishing
+### Events
 
-## Development Status
+Event types and payloads are defined in `src/core/types/events.ts`.
+
+## Zod schemas
+
+All runtime validation lives in `src/core/schemas/*`.
+
+Key exports:
+
+- Nodes: `nodeTierSchema`, `nodeCreateSchema`, `nodeUpdateSchema`, `nodeBatchCreateSchema`, `nodeFilterSchema`
+- Edges: `edgeEvidenceSchema`, `edgeCreateSchema`, `edgeUpdateSchema`, `edgeFilterSchema`
+- Clusters: `clusteringConfigSchema`, `clusterCreateSchema`, `clusterUpdateSchema`
+- Analysis: `analysisOptionsSchema`, `analysisRequestSchema`
+- Settings: `nodeTypeConfigSchema`, `domainConfigSchema`, `relationshipTypeConfigSchema`, `visualizationSettingsSchema`, `analysisSettingsSchema`, `neuronSettingsSchema`, `neuronSettingsUpdateSchema`, `neuronConfigSchema`
+- API: `listNodesParamsSchema`, `listEdgesParamsSchema`, `getGraphParamsSchema`, `expandGraphRequestSchema`, `findPathRequestSchema`, `semanticSearchRequestSchema`, `findSimilarRequestSchema`
+
+## Storage layer
+
+### Database
+
+Class: `Database` in `src/storage/database.ts`.
+
+Constructor:
+
+```ts
+new Database({
+  connectionString?: string,
+  host?: string,
+  port?: number,
+  user?: string,
+  password?: string,
+  database?: string,
+  pool?: { min; max; idleTimeoutMs; connectionTimeoutMs },
+  ssl?: boolean | object,
+  slowQueryThresholdMs?: number,
+});
+```
+
+Methods:
+
+- `connect()` / `disconnect()`
+- `isConnected()`
+- `query<T>(sql, params)`
+- `queryOne<T>(sql, params)`
+- `execute(sql, params)`
+- `transaction(fn)`
+- `tableExists(tableName)`
+- `getPoolStats()`
+
+### DockerManager
+
+Class: `DockerManager` in `src/storage/docker-manager.ts`.
+
+Constructor config:
+
+```ts
+new DockerManager({
+  repoName: string,
+  port: number,
+  containerName?: string,
+  image?: string,
+  user?: string,
+  password?: string,
+  database?: string,
+  memoryLimit?: string,
+});
+```
+
+Methods:
+
+- `start({ forceRecreate?, waitForReady?, timeoutMs? })`
+- `stop({ removeVolumes?, timeoutMs? })`
+- `ensureRunning({ waitForReady? })`
+- `isRunning()`
+- `healthCheck()` -> `{ containerRunning, databaseReady, connectionString, details? }`
+- `getStats()` -> container stats
+- `getConnectionString()`
+- `getLogs({ tail?, since? })`
+- `execSql(sql)`
+- `updatePort(newPort)`
+
+### MigrationRunner
+
+Class: `MigrationRunner` in `src/storage/migrations/runner.ts`.
+
+Methods:
+
+- `getStatus()` -> applied/pending
+- `getPending()`
+- `getApplied()`
+- `up({ to? })`
+- `down({ to?, count? })`
+- `reset()`
+- `dryRun('up' | 'down')`
+
+### Database schema (migrations)
+
+Defined in `src/storage/migrations/*.ts`:
+
+- `nodes` table: `slug`, `label`, `node_type`, `domain`, `summary`, `description`, `content`, `metadata`, `tier`, `visual_priority`, `position_override`, `connection_count`, `inbound_count`, `outbound_count`, `analysis_status`, `analysis_error`, timestamps.
+- `edges` table: `from_node_id`, `to_node_id`, `relationship_type`, `strength`, `confidence`, `evidence`, `label`, `description`, `metadata`, `source`, `source_model`, `bidirectional`, timestamps.
+- `settings` table: JSONB settings for `visualization`, `analysis`, `node_types`, `domains`, `relationship_types`.
+- `clusters` table and `cluster_memberships` table.
+- `analysis_runs` table for pipeline jobs.
+- Extensions: `uuid-ossp`, `vector` (pgvector).
+
+## Analysis engines
+
+### DataProcessor
+
+File: `src/core/analysis/data-processor.ts`
+
+- Converts arbitrary input records to `NeuronNodeCreate`.
+- Options: `skipDuplicates`, `updateOnConflict`, `defaultNodeType`, `defaultDomain`, `contentFields`, `labelField`, `slugField`, `metadataFields`.
+- Key methods: `processItem`, `processBatch`, `processJSON`, `processCSV`, `generateSlug`, `extractContent`, `detectDuplicates`.
+
+### EmbeddingsService
+
+File: `src/core/analysis/embeddings-service.ts`
+
+Constructor:
+
+```ts
+new EmbeddingsService({
+  openaiApiKey: string,
+  model: 'text-embedding-ada-002' | 'text-embedding-3-small' | 'text-embedding-3-large',
+  dimensions?: number,
+  batchSize: number,
+  rateLimit: number,
+  cacheTTL: number,
+  maxRetries: number,
+}, db)
+```
+
+Methods:
+
+- `generateEmbedding(text)`
+- `generateBatchEmbeddings(texts)`
+- `embedNode(nodeId)`
+- `embedNodes(nodeIds)`
+- `getCachedEmbedding(nodeId)`
+- `cacheEmbedding(nodeId, embedding, model)`
+- `invalidateCache(nodeIds?)`
+- `countTokens(text)`
+- `estimateCost(nodeCount)`
+
+### ClusteringEngine
+
+File: `src/core/analysis/clustering-engine.ts`
+
+Methods:
+
+- `clusterNodes(config)` -> `{ clusters, unassigned }`
+- `recluster(config)`
+- `assignToCluster(nodeId)`
+- `findBestCluster(embedding)`
+- `recomputeCentroid(clusterId)` / `recomputeAllCentroids()`
+- `generateClusterLabel(clusterId)` / `generateAllLabels()`
+- `calculateSilhouetteScore(clusters)`
+- `calculateCohesion(cluster)`
+
+### RelationshipEngine
+
+File: `src/core/analysis/relationship-engine.ts`
+
+Constructor config:
+
+```ts
+{
+  model: string;
+  minConfidence: number;
+  maxPerNode: number;
+  similarityThreshold: number;
+  includeExisting: boolean;
+  batchSize: number;
+  rateLimit: number;
+}
+```
 
-🟥 **In Planning** - Implementation not yet started
+Methods:
 
-See [plans/master-plan-planner.md](./plans/master-plan-planner.md) for current status.
+- `inferForNode(nodeId)`
+- `inferForNodes(nodeIds)`
+- `inferAll()`
+- `findCandidates(nodeId)`
+- `validateRelationship(rel)`
+- `createEdgesFromInferences(inferences, autoApprove?)`
+
+### ScoringEngine
+
+File: `src/core/analysis/scoring-engine.ts`
+
+- Constructor accepts optional config `{ similarityWeight, connectionWeight, recencyWeight, domainBoost }`.
+- Key methods: `cosineSimilarity`, `semanticSimilarity`, `scoreForQuery`, `findSimilar`, `calculateNodeImportance`, `rankAllNodes`, `scoreRelevance`.
+
+### AnalysisPipeline
+
+File: `src/core/analysis/pipeline.ts`
+
+Constructor: `(db, embeddings, clustering, relationships, events)`.
+
+Methods:
+
+- `runFull(options)`
+- `runEmbeddings(options)`
+- `runClustering(options)`
+- `runRelationships(options)`
+- `getJob(jobId)` / `listJobs({ status?, limit? })`
+- `cancelJob(jobId)` / `isRunning()`
+
+`PipelineOptions` fields include `nodeIds`, `forceRecompute`, `skipEmbeddings`, `embeddingModel`, `skipClustering`, `clusterCount`, `clusteringAlgorithm`, `skipRelationships`, `relationshipThreshold`, `maxRelationshipsPerNode`, `onProgress`, `webhookUrl`.
+
+## API layer
+
+### createNeuronRoutes
+
+Entry point: `createNeuronRoutes(config)` from `@omiron33/omi-neuron-web/api`.
+
+Returns:
+
+```ts
+{
+  nodes: createNodesRoutes(config),
+  edges: createEdgesRoutes(config),
+  graph: createGraphRoutes(config),
+  analyze: createAnalyzeRoutes(config),
+  settings: createSettingsRoutes(config),
+  search: createSearchRoutes(config),
+  health: createHealthRoutes(config),
+}
+```
+
+### Route behaviors
+
+All handlers accept a Fetch API `Request` and return `Response` (Next.js route handlers are compatible).
+
+Nodes:
+
+- `GET /nodes` -> list nodes with pagination. Uses `listNodesParamsSchema`.
+- `POST /nodes` -> batch create. Uses `nodeBatchCreateSchema`.
+- `PATCH /nodes/:id` -> update. Uses `nodeUpdateSchema`.
+- `DELETE /nodes/:id` -> delete.
+
+Edges:
+
+- `GET /edges` -> list edges. Uses `listEdgesParamsSchema`.
+- `POST /edges` -> batch create. Uses `edgeCreateSchema`.
+- `PATCH /edges/:id` -> update.
+- `DELETE /edges/:id` -> delete.
+
+Graph:
+
+- `GET /graph` -> returns `NeuronVisualNode` and `NeuronVisualEdge` arrays.
+- `POST /graph/expand` -> expansion by depth.
+- `POST /graph/path` -> find paths.
+
+Analyze:
+
+- `POST /analyze` -> runs analysis pipeline (embeddings, clustering, relationships, or full).
+- `GET /analyze/:jobId` -> fetch job status.
+- `POST /analyze/:jobId/cancel` -> cancel job.
+- `GET /analyze/history` -> list recent jobs.
+
+Settings:
+
+- `GET /settings` -> fetch settings from DB.
+- `PATCH /settings` -> update settings.
+- `POST /settings/reset` -> reset entire or specific sections.
+
+Search:
+
+- `POST /search` -> semantic search.
+- `POST /search/similar` -> find similar to node.
+
+Health:
+
+- `GET /health` -> basic DB connectivity.
+
+### API client
+
+`NeuronApiClient` in `src/react/api-client.ts` wraps these endpoints; see that file for exact method names and payloads.
+
+### Middleware
+
+From `src/api/middleware/*` (exported in `@omiron33/omi-neuron-web/api`):
+
+- `withNeuronMiddleware(handler, { cors? })`
+- `withErrorHandler(handler)` and `handleError(error)`
+- `withLogging(handler)`
+- `withTiming(handler)`
+- `withCors({ origins? })`
+- `withValidation(schema, source)`
+
+## React integration
+
+### NeuronWebProvider
+
+Wrap your app and provide configuration. The provider loads settings from `/api/neuron/settings` via the API client.
+
+```tsx
+import { NeuronWebProvider } from '@omiron33/omi-neuron-web';
+
+export default function RootLayout({ children }) {
+  return (
+    <NeuronWebProvider
+      config={{
+        openaiApiKey: process.env.NEXT_PUBLIC_OPENAI_API_KEY,
+        databaseUrl: process.env.NEXT_PUBLIC_DATABASE_URL,
+        settings: {},
+        onEvent: (event) => {},
+        onError: (error) => {},
+      }}
+    >
+      {children}
+    </NeuronWebProvider>
+  );
+}
+```
+
+### Hooks
+
+- `useNeuronContext()` -> access provider context.
+- `useNeuronGraph({ domains?, nodeTypes?, minEdgeStrength?, autoRefresh?, refreshInterval? })` -> fetch and explore graph.
+- `useNeuronNodes({ initialFilters?, pageSize? })` -> CRUD nodes and pagination.
+- `useNeuronAnalysis()` -> start/cancel/check analysis jobs.
+- `useNeuronSettings()` -> update or reset settings.
+- `useNeuronSearch()` -> semantic search and find similar nodes.
+- `useNeuronEvents()` -> subscribe/emit events.
+
+Also available:
+
+- `useNodeEvents(handlers)`
+- `useAnalysisEvents(handlers)`
+
+## Visualization (NeuronWeb)
+
+### Component props (full list)
+
+`NeuronWebProps` from `src/visualization/types.ts`:
+
+```ts
+export interface NeuronWebProps {
+  graphData: {
+    nodes: NeuronVisualNode[];
+    edges: NeuronVisualEdge[];
+    storyBeats?: NeuronStoryBeat[];
+  };
+  fullHeight?: boolean;
+  isFullScreen?: boolean;
+  className?: string;
+  style?: React.CSSProperties;
+  isLoading?: boolean;
+  error?: string | null;
+  selectedNode?: NeuronNode | null;
+  focusNodeSlug?: string | null;
+  visibleNodeSlugs?: string[] | null;
+  onNodeClick?: (node: NeuronNode) => void;
+  onNodeDoubleClick?: (node: NeuronNode) => void;
+  onNodeHover?: (node: NeuronNode | null) => void;
+  onNodeFocused?: (node: NeuronNode) => void;
+  onEdgeClick?: (edge: NeuronEdge) => void;
+  onBackgroundClick?: () => void;
+  onCameraChange?: (position: [number, number, number]) => void;
+  studyPathRequest?: StudyPathRequest | null;
+  onStudyPathComplete?: () => void;
+  layout?: NeuronLayoutOptions;
+  cameraFit?: CameraFitOptions;
+  theme?: NeuronWebThemeOverride;
+  domainColors?: Record<string, string>;
+  renderNodeHover?: (node: NeuronVisualNode) => React.ReactNode;
+  hoverCard?: HoverCardOptions;
+  renderNodeDetail?: (node: NeuronNode) => React.ReactNode;
+  renderEmptyState?: () => React.ReactNode;
+  renderLoadingState?: () => React.ReactNode;
+  performanceMode?: 'auto' | 'normal' | 'degraded' | 'fallback';
+  ariaLabel?: string;
+}
+```
+
+Props currently used inside `NeuronWeb` (others are reserved for future use):
+
+- Used: `graphData`, `className`, `style`, `fullHeight`, `isFullScreen`, `isLoading`, `error`, `renderEmptyState`, `renderLoadingState`, `ariaLabel`, `theme`, `layout`, `renderNodeHover`, `hoverCard`, `onNodeHover`, `onNodeClick`, `onNodeDoubleClick`, `onNodeFocused`, `onBackgroundClick`, `performanceMode`.
+- Used: `cameraFit` (auto-fit bounds to a viewport fraction).
+- Reserved (declared but not used in the component yet): `selectedNode`, `focusNodeSlug`, `visibleNodeSlugs`, `onEdgeClick`, `onCameraChange`, `studyPathRequest`, `onStudyPathComplete`, `domainColors`, `renderNodeDetail`, `graphData.storyBeats`.
+
+### Layout modes
+
+`NeuronLayoutMode` = `'auto' | 'positioned' | 'fuzzy' | 'atlas'`.
+
+`applyFuzzyLayout()` behavior:
+
+- `positioned`: return nodes as-is (use positions from DB or API).
+- `auto`: if any node lacks a `position`, run `atlas` layout; otherwise return nodes as-is.
+- `atlas`: sphere layout with built-in override map (`ATLAS_POSITION_OVERRIDES` in `src/visualization/layouts/fuzzy-layout.ts`).
+- `fuzzy`: deterministic pseudo-random scatter based on `seed` and node key.
+
+Layout options:
+
+```ts
+{
+  mode?: NeuronLayoutMode;
+  radius?: number;       // base radius for layout
+  insightRadius?: number; // smaller radius for insight nodes
+  jitter?: number;       // random jitter
+  zSpread?: number;      // z-axis spread
+  seed?: string;         // deterministic seed
+  spread?: number;       // global scale factor
+  overrides?: Record<string, [number, number, number]>; // slug/id -> position
+}
+```
+
+### Camera auto-fit (center-third framing)
+
+Use `cameraFit` to center and zoom so all nodes sit inside a specific viewport fraction (default: 0.33 = center third).
+When `isFullScreen` is true and `cameraFit.enabled` is not specified, auto-fit is enabled by default.
+
+```tsx
+<NeuronWeb
+  graphData={graphData}
+  isFullScreen
+  cameraFit={{
+    enabled: true,
+    mode: 'once',          // or 'onChange' to refit when node positions change
+    viewportFraction: 0.33, // center-third framing
+    padding: 0.15,          // 15% padding around bounds
+  }}
+/>
+```
+
+To disable in fullscreen:
+
+```tsx
+<NeuronWeb graphData={graphData} isFullScreen cameraFit={{ enabled: false }} />
+```
+
+### Theme
+
+`NeuronWebTheme` defines colors, typography, effects, and animation. Defaults are in `src/visualization/constants.ts`.
+
+Key behavior in `NeuronWeb`:
+
+- Performance mode is auto-detected unless explicitly set.
+- Hover cards are disabled in `fallback` mode.
+- Labels and starfield density are reduced in `degraded`/`fallback`.
+
+### Fullscreen vs element rendering
+
+- `isFullScreen: true` makes the component `position: fixed` with `width: 100vw` and `height: 100vh`.
+- Default (not full screen) uses `width: 100%` and `height: 100%`. The parent element must define a height.
+- `fullHeight: true` sets `min-height: 100vh` when not full screen.
+
+## Visualization internals (agent map)
+
+Key internal modules:
+
+- `src/visualization/scene/scene-manager.ts` - sets up Three.js scene, camera, renderer, lights, starfield, labels.
+- `src/visualization/scene/node-renderer.ts` - renders nodes, labels, hover/selection states.
+- `src/visualization/scene/edge-renderer.ts` - renders edges, flow animations.
+- `src/visualization/interactions/interaction-manager.ts` - hover/click/double-click handling.
+- `src/visualization/animations/animation-controller.ts` - camera focus/transition animations.
+- `src/visualization/layouts/fuzzy-layout.ts` - layout generation.
+
+## Events
+
+Event system in `src/core/events/event-bus.ts` with types in `src/core/types/events.ts`.
+
+- Subscribe with `EventBus.subscribe(type, handler)` or `subscribeAll(handler)`.
+- Emit with `EventBus.emit(createEvent(type, payload, source))`.
+- `useNeuronEvents()` provides React helpers to subscribe/emit inside components.
+
+## API types (request/response)
+
+All API request/response types are defined in `src/core/types/api.ts`. If you need to implement a server or client manually, this file is the contract.
+
+## CLI reference (omi-neuron)
+
+The CLI is defined in `src/cli/index.ts` and subcommands in `src/cli/commands/*`.
+
+Commands:
+
+- `omi-neuron init` - scaffold config, docker compose, env file, and Next.js route.
+  - `--name`, `--port`, `--skip-docker`, `--skip-api`, `--skip-config`, `--app-dir`, `--force`
+- `omi-neuron db up|down|migrate|status|reset|seed`
+  - `up`: `--port`, `--force-recreate`, `--wait`
+  - `down`: `--remove-volumes`
+  - `migrate`: `--status`, `--rollback <n>`, `--to <version>`, `--dry-run`
+  - `status`: `--json`, `--verbose`
+  - `reset`: `--confirm`
+  - `seed`: `--file`, `--clear`, `--count`
+- `omi-neuron analyze embeddings|cluster|relationships|full`
+  - `embeddings`: `--node-ids`, `--force`
+  - `cluster`: `--count`, `--algorithm`
+  - `relationships`: `--threshold`, `--dry-run`
+  - `full`: `--force`
+- `omi-neuron validate` - checks config, docker, DB, and OpenAI env.
+- `omi-neuron config get|set|list|reset` - manage `neuron.config.ts` values.
+
+## Known gaps and reserved fields
+
+- Several `NeuronWebProps` are defined but not yet used internally (see list above).
+- `VisualizationSettings` vs `NeuronWebTheme`: the component uses theme overrides, not settings. If you want settings to drive visuals, wire them in `NeuronWeb`.
+- `VERSION` constant is not auto-updated.
+
+## Build and test
+
+```bash
+pnpm install
+pnpm build
+pnpm typecheck
+pnpm lint
+pnpm test
+```
 
 ## License
 
 MIT
-