genoma-evolution 1.0.0

package/.brv/context-tree/docs/api/hermes_api_openapi_specification.overview.md

@@ -0,0 +1,44 @@
+## Hermes API OpenAPI Specification Overview
+
+### Key Points
+
+- **OpenAPI 3.1.0** specification for Hermes backend (FastAPI/Python)
+- Base server: `http://127.0.0.1:8000` (overridable via `NEXT_PUBLIC_API_BASE` environment variable)
+- Frontend (Next.js) consumes these endpoints with a defined response contract
+- **Evolution system** enables iterative skill improvement with scoring (baseline vs evolved scores)
+- **Jobs system** provides real-time tracking of evolution runs with status, logs, and progress
+- Standardized **ApiError schema** with typed error kinds for consistent frontend error handling
+- WebSocket endpoint (`/ws`) noted but streaming details not included in this spec excerpt
+
+---
+
+### Section Structure
+
+| Section | Path Prefix | Methods |
+|---|---|---|
+| Skills | `/api/skills` | GET (list, detail, evolution-history) |
+| Evolution | `/api/evolution` | GET (runs), POST (start) |
+| Jobs | `/api/jobs` | GET (list, detail), DELETE (cancel), GET logs |
+| Health | `/api/health` | GET |
+
+---
+
+### Notable Schemas
+
+| Schema | Purpose |
+|---|---|
+| `SkillInfo` | Basic skill metadata (name, path, providers, category, size) |
+| `SkillDetail` | Full skill content including parsed frontmatter, body, and raw content |
+| `EvolutionRun` | Historical record with baseline_score, evolved_score, improvement |
+| `EvolutionJob` | Active job with status enum and progress tracking |
+| `ApiError` | Typed error contract (network/timeout/server/client) |
+
+---
+
+### Notable Decisions / Patterns
+
+- **Job status enum** includes 11 states: `queued → loading_skill → building_dataset → validating → configuring → optimizing → evaluating → saving → completed/failed`
+- **Evolution constraints**: `iterations` (1-20, default 3), `eval_source` (default: "synthetic")
+- **503 handling**: All endpoints share a standardized `ServiceUnavailable` response; frontend shows "Desconectado" state with retry option
+- **Health endpoint** exposes system state including `hermes_repo_exists`, `skills_count`, and `categories` breakdown
+- **Job logs**: Streaming paginated logs via `?since=` query parameter

package/.brv/context-tree/frontend/_index.md

@@ -0,0 +1,48 @@
+---
+children_hash: 389c2df13933c66ce0fe0315d13164eb36710f49e971334300a4c3927b66c30b
+compression_ratio: 0.5270618556701031
+condensation_order: 2
+covers: [hermes_dashboard/_index.md, src/_index.md]
+covers_token_total: 776
+summary_level: d2
+token_count: 409
+type: summary
+---
+# Hermes Dashboard
+
+## Architecture
+
+Next.js 16 frontend ↔ FastAPI backend, communicating across ports 3000 and 8000 (env-configured as `NEXT_PUBLIC_API_BASE` → `http://127.0.0.1:9119`).
+
+**Stack:** Next.js 16 · React Query · Framer Motion · CSS gradients (Three.js removed for lighter footprint)
+
+## Frontend Structure
+
+**8 Navigation Sections** (sidebar.md): Overview · Skills · Evolution · Datasets · Memory · Metrics · Logs · Settings
+
+All pages lazy-loaded via `next/dynamic` with loading states.
+
+**Key Components:**
+- `Sidebar` — Collapsible (64px/240px), Framer Motion animations, cyan accent, dual light/dark mode
+- `SettingsPage` — System paths, env vars (`OPENAI_API_KEY`, `HERMES_AGENT_REPO`), health status
+
+**API Client** (`lib/api.ts`, `api_client_library.md`):
+- Auth: `X-Hermes-Session-Token` header, lazy-loaded session
+- Resilience: 15s AbortController timeouts, 401 retry with token refresh, WebSocket 3s auto-reconnect
+- Types: `SkillInfo`, `SkillDetail`, `EvolutionJob`, `EvolutionRun`, `MetricsData`, `DatasetInfo`
+
+## Source Files
+
+| Layer | Files |
+|-------|-------|
+| Pages | `src/app/page.tsx`, `src/app/layout.tsx` |
+| Components | `src/components/Sidebar.tsx`, `src/components/pages/*.tsx` |
+| API | `src/lib/api.ts` |
+| Backend | `backend/main.py` (FastAPI, ~20 endpoints + WebSocket) |
+
+## Drill-Down References
+
+- `hermes_dashboard/architecture_overview.md` — Full architecture details
+- `src/components/sidebar_navigation_component.md` — Sidebar implementation
+- `src/lib/api_client_library.md` — API client specification
+- `src/page.md` / `src/sidebar.md` / `src/settingspage.md` — Individual page docs

package/.brv/context-tree/frontend/hermes_dashboard/_index.md

@@ -0,0 +1,31 @@
+---
+children_hash: 05120e17ddf4ed76482037a8b67a15c5e41ea8a011162c03430a7d52723952f2
+compression_ratio: 0.6966292134831461
+condensation_order: 1
+covers: [architecture_overview.md]
+covers_token_total: 267
+summary_level: d1
+token_count: 186
+type: summary
+---
+# Hermes Dashboard Architecture
+
+## Overview
+Next.js 16 frontend paired with FastAPI backend, communicating across ports 3000 and 8000 respectively.
+
+## Frontend Stack
+- **Framework:** Next.js 16
+- **UI Optimization:** Three.js removed → CSS gradients for lighter footprint
+- **Config:** `next.config.ts` set to standalone mode
+- **Key Files:** `src/app/page.tsx`, `src/app/layout.tsx`
+
+## Dashboard Pages
+Overview · Skill Hub · Evolution · Datasets · Memory · Metrics · Logs · Settings
+
+## Backend
+- **Framework:** FastAPI
+- **Lazy-loaded:** Backend components loaded on-demand for faster initial frontend load
+- **Key File:** `backend/main.py`
+
+## Performance Decision
+CSS gradients replace Three.js → reduced bundle size, faster rendering.

package/.brv/context-tree/frontend/hermes_dashboard/architecture_overview.md

@@ -0,0 +1,41 @@
+---
+title: Architecture Overview
+summary: Next.js 16 + FastAPI dashboard with Three.js replaced by CSS gradients, lazy-loaded backend, standalone next.config
+tags: []
+related: []
+keywords: []
+createdAt: '2026-04-28T02:21:54.807Z'
+updatedAt: '2026-04-28T02:21:54.807Z'
+---
+## Reason
+Document Hermes Dashboard architecture from inline context
+
+## Raw Concept
+**Task:**
+Document Hermes Dashboard architecture
+
+**Changes:**
+- Replaced Three.js with CSS gradients
+- Backend lazy-loaded
+- next.config set to standalone
+
+**Files:**
+- src/app/page.tsx
+- src/app/layout.tsx
+- backend/main.py
+- next.config.ts
+
+**Flow:**
+Next.js frontend (port 3000) -> FastAPI backend (port 8000)
+
+**Timestamp:** 2026-04-28
+
+## Narrative
+### Structure
+Next.js 16 frontend with FastAPI backend. Dashboard pages: Overview, Skill Hub, Evolution, Datasets, Memory, Metrics, Logs, Settings.
+
+### Dependencies
+Backend requires FastAPI, frontend requires Next.js 16
+
+### Highlights
+Performance optimization: Three.js removed, CSS gradients used instead. Backend lazy-loaded for faster initial load.

package/.brv/context-tree/frontend/hermes_dashboard/architecture_overview.overview.md

@@ -0,0 +1,34 @@
+# Architecture Overview: Hermes Dashboard
+
+## Key Points
+
+- **Tech Stack**: Next.js 16 frontend with FastAPI backend
+- **Performance Optimization**: Three.js removed; CSS gradients now used for visual effects
+- **Backend Strategy**: Lazy-loaded backend for faster initial page load
+- **Deployment Config**: `next.config.ts` set to `standalone` mode
+- **Communication Flow**: Frontend (port 3000) ↔ Backend (port 8000)
+
+## Structure / Sections Summary
+
+### Raw Concept
+- Task: Document Hermes Dashboard architecture
+- Key changes: Three.js removal, CSS gradients, lazy backend, standalone config
+- Target files: `src/app/page.tsx`, `src/app/layout.tsx`, `backend/main.py`, `next.config.ts`
+
+### Narrative
+- **Structure**: Next.js 16 frontend + FastAPI backend with 8 dashboard pages (Overview, Skill Hub, Evolution, Datasets, Memory, Metrics, Logs, Settings)
+- **Dependencies**: FastAPI (backend), Next.js 16 (frontend)
+
+## Notable Entities & Decisions
+
+| Entity | Details |
+|--------|---------|
+| **Frontend** | Next.js 16, port 3000 |
+| **Backend** | FastAPI, port 8000, lazy-loaded |
+| **Build Config** | `standalone` mode enabled |
+| **Visual System** | CSS gradients (replaced Three.js) |
+
+### Decisions
+- **Three.js removal**: Reduces bundle size; CSS gradients sufficient for dashboard visuals
+- **Lazy backend loading**: Improves initial load time; backend services load on demand
+- **Standalone next.config**: Self-contained Next.js output for simplified deployment

package/.brv/context-tree/frontend/src/_index.md

@@ -0,0 +1,53 @@
+---
+children_hash: 90692b63a08a05d9811e0d3979c4a61bc3467fb2063e5c3b3eb75018971bdcc6
+compression_ratio: 0.09087154068566708
+condensation_order: 1
+covers: [components/_index.md, context.md, functioncallingpage.md, lib/_index.md, page.md, settingspage.md, sidebar.md]
+covers_token_total: 4842
+summary_level: d1
+token_count: 440
+type: summary
+---
+# Frontend Architecture (src)
+
+## Overview
+Next.js frontend with lazy-loaded page components, React Query for server state, and Framer Motion animations. Connects to FastAPI backend via typed API client.
+
+## Page Structure
+
+**8 Navigation Sections** (see `sidebar.md` for full nav):
+| Page | Component | Purpose |
+|------|-----------|---------|
+| Overview | `OverviewPage` | Dashboard home |
+| Skills | `SkillStudioPage` | Skill management |
+| Evolution | `EvolutionPage` | Evolution engine control |
+| Datasets | `DatasetPage` | Dataset analysis |
+| Memory | `MemoryPage` | Memory/intelligence |
+| Metrics | `MetricsPage` | Analytics & metrics |
+| Logs | `LogsPage` | Live log streaming |
+| Settings | `SettingsPage` | System paths & env vars |
+
+All pages lazy-loaded via `next/dynamic` with loading states.
+
+## Key Components
+
+- **`Sidebar`** — Collapsible (64px/240px), animated via Framer Motion, cyan accent theme, dual light/dark mode
+- **`SettingsPage`** — Displays system paths, env vars (OPENAI_API_KEY, HERMES_AGENT_REPO), health status via `fetchHealth()`
+
+## API Client (`lib/api.ts`)
+
+See `lib/_index.md` and `api_client_library.md` for full details.
+
+**Resilience:** 15s AbortController timeouts, retry on 401 with token refresh, WebSocket 3s auto-reconnect
+
+**Auth:** `X-Hermes-Session-Token` header, lazy-loaded session
+
+**Env:** `NEXT_PUBLIC_API_BASE` → `http://127.0.0.1:9119`
+
+**Key Types:** `SkillInfo`, `SkillDetail`, `EvolutionJob`, `EvolutionRun`, `MetricsData`, `DatasetInfo`, `ConstraintResult`, `ProviderSummary`
+
+## Source Files
+- `src/app/page.tsx` — Root page with page routing
+- `src/components/Sidebar.tsx` — Navigation sidebar
+- `src/components/pages/*.tsx` — Page components (lazy-loaded)
+- `src/lib/api.ts` — Typed API client

package/.brv/context-tree/frontend/src/components/_index.md

@@ -0,0 +1,52 @@
+---
+children_hash: b619fb96a0b08ac7bd129f1d7c125d830caeb4ba9111d31a8938bbf1868eb497
+compression_ratio: 0.21685082872928177
+condensation_order: 0
+covers: [sidebar_navigation_component.md]
+covers_token_total: 1448
+summary_level: d0
+token_count: 314
+type: summary
+---
+## Sidebar Navigation Component
+
+**Source:** `src/components/Sidebar.tsx`
+
+### Overview
+Collapsible sidebar providing navigation across 7 main sections with environment status, theme support, and animated transitions.
+
+### Navigation Structure
+7 navigation items with icons:
+- Overview (Layers)
+- Skill Hub (Sparkles)
+- Evolution (GitBranch)
+- Datasets (Database)
+- Metrics (BarChart3)
+- Live Logs (Terminal)
+- Settings (Settings)
+
+### Props Interface
+```
+activePage: Page
+onNavigate: (page: Page) => void
+```
+
+### Page Type Definition
+```typescript
+export type Page = "overview" | "skills" | "evolution" | "datasets" | "metrics" | "logs" | "settings";
+```
+
+### Visual Design
+- Collapsed width: 64px, Expanded: 240px
+- Animated width transition (0.2s easeOut) via Framer Motion
+- Logo with DNA icon and "Hermes Evolution Dashboard" branding
+- Active state: cyan highlight with text-[#0891B2] accent
+- Hover states with subtle cyan tint on both light/dark themes
+- Collapse toggle button at bottom
+
+### Key Features
+- AnimatePresence for label fade in/out on collapse
+- Sticky positioning (h-screen, top-0)
+- Scrollable nav area (flex-1, overflow-y-auto)
+- Dual theme support: light (bg-[#E8F9FA]) / dark (bg-[#061014])
+- Cyan border accents with 20% opacity

package/.brv/context-tree/frontend/src/components/sidebar_navigation_component.md

@@ -0,0 +1,161 @@
+---
+title: Sidebar Navigation Component
+summary: Navigation sidebar with environment status, skill toggles, and core loop controls
+tags: []
+related: []
+keywords: []
+createdAt: '2026-04-28T03:47:02.100Z'
+updatedAt: '2026-04-28T03:47:02.100Z'
+---
+## Reason
+Preserving complete Sidebar navigation component
+
+## Raw Concept
+**Task:**
+Document Sidebar navigation component
+
+**Files:**
+- src/components/Sidebar.tsx
+
+**Timestamp:** 2026-04-28
+
+## Narrative
+### Structure
+Sidebar navigation with sections: Environment, Core Loop, Skills, Theme
+
+---
+
+
+"use client";
+
+import { useState } from "react";
+import { motion, AnimatePresence } from "framer-motion";
+import {
+  Layers,
+  GitBranch,
+  Database,
+  BarChart3,
+  Terminal as TerminalIcon,
+  Settings,
+  Dna,
+  ChevronLeft,
+  ChevronRight,
+  Cpu,
+  BookOpen,
+  Bot,
+  Sparkles,
+} from "lucide-react";
+
+export type Page =
+  | "overview"
+  | "skills"
+  | "evolution"
+  | "datasets"
+  | "metrics"
+  | "logs"
+  | "settings"
+;
+
+interface NavItem {
+  id: Page;
+  label: string;
+  icon: React.ReactNode;
+}
+
+const navItems: NavItem[] = [
+  { id: "overview", label: "Overview", icon: <Layers className="w-4 h-4" /> },
+  { id: "skills", label: "Skill Hub", icon: <Sparkles className="w-4 h-4" /> },
+  { id: "evolution", label: "Evolution", icon: <GitBranch className="w-4 h-4" /> },
+  { id: "datasets", label: "Datasets", icon: <Database className="w-4 h-4" /> },
+  { id: "metrics", label: "Metrics", icon: <BarChart3 className="w-4 h-4" /> },
+  { id: "logs", label: "Live Logs", icon: <TerminalIcon className="w-4 h-4" /> },
+  { id: "settings", label: "Settings", icon: <Settings className="w-4 h-4" /> },
+];
+
+interface SidebarProps {
+  activePage: Page;
+  onNavigate: (page: Page) => void;
+}
+
+export default function Sidebar({ activePage, onNavigate }: SidebarProps) {
+  const [collapsed, setCollapsed] = useState(false);
+
+  return (
+    <motion.aside
+      animate={{ width: collapsed ? 64 : 240 }}
+      transition={{ duration: 0.2, ease: "easeOut" }}
+      className="h-screen sticky top-0 flex flex-col border-r border-[#B2FFFF]/20 bg-[#E8F9FA] dark:bg-[#061014] backdrop-blur-xl transition-colors duration-300"
+    >
+      {/* Logo */}
+      <div className="flex items-center gap-3 px-4 h-16 border-b border-[#B2FFFF]/15 dark:border-white/[0.06]">
+        <div className="w-8 h-8 rounded-lg bg-[#0891B2] dark:bg-[#06B6D4] flex items-center justify-center flex-shrink-0 shadow-sm shadow-[#0891B2]/20">
+          <Dna className="w-4 h-4 text-white" />
+        </div>
+        <AnimatePresence>
+          {!collapsed && (
+            <motion.div
+              initial={{ opacity: 0, x: -10 }}
+              animate={{ opacity: 1, x: 0 }}
+              exit={{ opacity: 0, x: -10 }}
+              className="overflow-hidden"
+            >
+              <span className="text-sm font-semibold tracking-tight text-[#0F172A] dark:text-white">Hermes</span>
+              <p className="text-[10px] text-[#475569] dark:text-slate-400">Evolution Dashboard</p>
+            </motion.div>
+          )}
+        </AnimatePresence>
+      </div>
+
+      {/* Nav items */}
+      <nav className="flex-1 py-4 px-2 space-y-1 overflow-y-auto">
+        {navItems.map((item) => (
+          <button
+            key={item.id}
+            onClick={() => onNavigate(item.id)}
+            className={`w-full flex items-center gap-3 px-3 py-2.5 rounded-xl text-sm transition-all duration-200 ${
+              activePage === item.id
+                ? "bg-[#B2FFFF]/40 text-[#0E7490] dark:bg-[#B2FFFF]/20 dark:text-[#E0FFFF] shadow-sm shadow-[#B2FFFF]/10"
+                : "text-[#475569] hover:text-[#0F172A] hover:bg-[#B2FFFF]/20 dark:text-[#B2FFFF] dark:hover:text-[#E0FFFF] dark:hover:bg-[#B2FFFF]/10"
+            }`}
+          >
+            <span
+              className={`flex-shrink-0 ${
+                activePage === item.id ? "text-[#0891B2] dark:text-[#67E8F9]" : ""
+              }`}
+            >
+              {item.icon}
+            </span>
+            <AnimatePresence>
+              {!collapsed && (
+                <motion.span
+                  initial={{ opacity: 0 }}
+                  animate={{ opacity: 1 }}
+                  exit={{ opacity: 0 }}
+                  className="truncate font-medium"
+                >
+                  {item.label}
+                </motion.span>
+              )}
+            </AnimatePresence>
+          </button>
+        ))}
+      </nav>
+
+      {/* Collapse toggle */}
+      <div className="p-2 border-t border-[#B2FFFF]/15 dark:border-[#B2FFFF]/10">
+        <button
+          onClick={() => setCollapsed(!collapsed)}
+          className="w-full flex items-center justify-center p-2 rounded-xl text-[#475569] hover:text-[#0F172A] hover:bg-[#B2FFFF]/20 dark:text-[#A5F3FC]/70 dark:hover:text-[#E0FFFF] dark:hover:bg-[#B2FFFF]/10 transition-colors"
+        >
+          {collapsed ? (
+            <ChevronRight className="w-4 h-4" />
+          ) : (
+            <ChevronLeft className="w-4 h-4" />
+          )}
+        </button>
+      </div>
+    </motion.aside>
+  );
+}
+
+    

package/.brv/context-tree/frontend/src/components/sidebar_navigation_component.overview.md

@@ -0,0 +1,32 @@
+# Sidebar Navigation Component Overview
+
+## Key Points
+
+- **React "use client" component** using Next.js with Framer Motion for smooth animations
+- **Collapsible sidebar** toggles between expanded (240px) and collapsed (64px) states with 0.2s ease-out transition
+- **7 navigation items**: Overview, Skills, Evolution, Datasets, Metrics, Live Logs, Settings — each with unique Lucide icon
+- **Dark mode support** with dual color token sets for light (`#E8F9FA`, `#B2FFFF`) and dark (`#061014`, `#06B6D4`) themes
+- **Active page highlighting** with distinct cyan-teal styling (`#0891B2`) and shadow effects
+- **Logo branding**: "Hermes/Evolution Dashboard" with DNA helix icon in rounded container
+- Props interface exposes `activePage` and `onNavigate` callback for parent-controlled routing
+
+## Structure / Sections
+
+| Section | Purpose |
+|---------|---------|
+| **Logo Header** | DNA icon + "Hermes/Evolution Dashboard" branding with border separator |
+| **Navigation** | 7 nav buttons with icons, labels, hover/active states |
+| **Collapse Toggle** | ChevronLeft/Right button to expand/collapse sidebar |
+
+## Notable Entities & Patterns
+
+- **Page type**: Union type literal (`"overview" | "skills" | "evolution" | ...`)
+- **NavItem interface**: `{ id: Page, label: string, icon: React.ReactNode }`
+- **Animation pattern**: `AnimatePresence` wrapping conditional labels with `initial`/`animate`/`exit` variants
+- **Color scheme**: Cyan-teal palette — `#B2FFFF` (accent), `#0891B2` (primary), `#67E8F9` (dark active)
+- **Hover states**: Semi-transparent cyan overlays (`/20`, `/10` opacity)
+- **Backdrop blur**: `backdrop-blur-xl` on sidebar background
+
+## File
+
+`src/components/Sidebar.tsx`

package/.brv/context-tree/frontend/src/context.md

@@ -0,0 +1,10 @@
+# Topic: src
+
+## Overview
+Frontend API client using React Query for server state management
+
+## Key Concepts
+- React Query integration
+- Typed API endpoints
+- WebSocket hooks
+- API configuration

package/.brv/context-tree/frontend/src/functioncallingpage.md

@@ -0,0 +1,34 @@
+---
+title: FunctionCallingPage
+summary: ''
+tags: []
+related: []
+keywords: []
+createdAt: '2026-04-28T01:33:30.536Z'
+updatedAt: '2026-04-28T01:33:30.536Z'
+---
+## Reason
+Preserving complete src/components/pages/FunctionCallingPage.tsx from hermes-dashboard project
+
+## Raw Concept
+**Task:**
+Preserve src/components/pages/FunctionCallingPage.tsx
+
+**Files:**
+- src/components/pages/FunctionCallingPage.tsx
+
+**Timestamp:** 2026-04-28
+
+## Narrative
+### Structure
+TSX file with 0 components/functions
+
+### Highlights
+Source: hermes-dashboard/src/components/pages/FunctionCallingPage.tsx
+
+---
+
+
+<!-- This page has been removed. See page.tsx for available pages. -->
+
+    

package/.brv/context-tree/frontend/src/functioncallingpage.overview.md

@@ -0,0 +1,26 @@
+# FunctionCallingPage - Document Overview
+
+## Key Points
+
+- **Preservation Record**: This document preserves metadata about a removed React page component from the hermes-dashboard project
+- **File Preserved**: `src/components/pages/FunctionCallingPage.tsx` — now deleted from the codebase
+- **Empty Component**: The TSX file contained **0 components/functions** — likely a placeholder or stub file that was never implemented
+- **Removal Status**: Explicitly marked as removed; references `page.tsx` for current available pages
+- **Project Context**: Belongs to the hermes-dashboard project
+- **Timestamps**: Created and updated on 2026-04-28 (identical — single preservation event)
+
+## Structure / Sections Summary
+
+| Section | Description |
+|---------|-------------|
+| **Reason** | States the preservation purpose: keeping the source reference for the removed file |
+| **Raw Concept** | Contains the task metadata: file path, timestamp, and preservation goal |
+| **Narrative** | Documents structure (0 components/functions) and highlights source location |
+
+## Notable Entities & Patterns
+
+- **Entity**: `FunctionCallingPage.tsx` — page component file
+- **Entity**: `hermes-dashboard` — parent project name
+- **Entity**: `page.tsx` — referenced as the source for available pages
+- **Pattern**: Removal notice comment `<!-- This page has been removed. See page.tsx for available pages. -->`
+- **Pattern**: Zero-state component (file existed but held no actual code)

package/.brv/context-tree/frontend/src/lib/_index.md

@@ -0,0 +1,48 @@
+---
+children_hash: 515c06ea24aed64bdce7f7f3687b2a2d29249f0c442224ad38bee6fc316193d0
+compression_ratio: 0.11090342679127727
+condensation_order: 0
+covers: [api_client_library.md]
+covers_token_total: 3210
+summary_level: d0
+token_count: 356
+type: summary
+---
+# API Client Library
+
+TypeScript API client (`src/lib/api.ts`) providing typed endpoints for jobs, skills, evolution, and WebSocket streaming. React Query-compatible design with resilient infrastructure.
+
+## Architecture
+
+**Resilience Features:**
+- AbortController timeouts (default 15s)
+- Typed `ApiError` with `ErrorKind`: `network | timeout | server | client`
+- Auto-refresh token on 401, retry once
+- WebSocket auto-reconnect after 3s
+
+**Auth:** Session token via `X-Hermes-Session-Token` header, lazy-loaded from `/`
+
+**Env:** `NEXT_PUBLIC_API_BASE` → fallback `http://127.0.0.1:9119`
+
+## Key Interfaces
+
+- `SkillInfo`, `SkillDetail` — skill metadata and content
+- `EvolutionJob`, `EvolutionRun` — job lifecycle and results
+- `MetricsData`, `DatasetInfo`, `ConstraintResult` — analysis data
+- `ProviderSummary` — skill provider groupings
+
+## Typed API Functions
+
+**Skills:** `fetchSkills`, `fetchSkill`, `fetchSkillHistory`, `fetchSkillProviders`, `toggleSkillEnabled`, `deleteProviderSkill`, `deleteGlobalSkill`, `refreshSkills`
+
+**Evolution:** `fetchEvolutionRuns`, `fetchSkillDiff`, `startEvolution`
+
+**Jobs:** `fetchJobs`, `fetchJob`, `fetchJobLogs`, `cancelJob`
+
+**Analysis:** `fetchMetrics`, `fetchDatasets`, `fetchDataset`, `validateSkill`
+
+**Infrastructure:** `fetchHealth`, `checkHealth`
+
+---
+
+See **api_client_library.md** for full source with session token logic, WebSocket helper, and typed fetch wrapper.

package/.brv/context-tree/frontend/src/lib/api_client_library.abstract.md

@@ -0,0 +1 @@
+A TypeScript API client library providing typed functions for jobs, skills, evolution, and WebSocket management with Hermes session-based auth, AbortController timeouts, categorized errors, and automatic token refresh on 401 responses.