@kinqs/brainrouter-mcp-server 0.3.4

package/docs/design/themes/realty-open-house.md

@@ -0,0 +1,101 @@
+---
+version: alpha
+name: Realty Open House
+description: Open-house listing: linen warm, brass accents.
+colors:
+  primary: "#1E1914"
+  secondary: "#8A7E6C"
+  tertiary: "#A57D46"
+  neutral: "#F2ECDE"
+  surface: "#FBF5E6"
+  on-primary: "#FBF5E6"
+typography:
+  display:
+    fontFamily: Cormorant Garamond
+    fontSize: 5rem
+    fontWeight: 400
+    letterSpacing: "-0.015em"
+  h1:
+    fontFamily: Cormorant Garamond
+    fontSize: 2.6rem
+    fontWeight: 400
+  body:
+    fontFamily: Inter
+    fontSize: 1rem
+    lineHeight: 1.65
+  label:
+    fontFamily: Inter
+    fontSize: 0.72rem
+    fontWeight: 500
+    letterSpacing: "0.2em"
+rounded:
+  sm: 2px
+  md: 4px
+  lg: 6px
+spacing:
+  sm: 8px
+  md: 16px
+  lg: 32px
+components:
+  button-primary:
+    backgroundColor: "{colors.tertiary}"
+    textColor: "{colors.on-primary}"
+    rounded: "{rounded.md}"
+    padding: 12px 20px
+  card:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.primary}"
+    rounded: "{rounded.lg}"
+    padding: 24px
+---
+## Overview
+
+A premium real-estate palette: linen warmth, brass accent, tall serif display.
+
+## Colors
+
+The palette is built around high-contrast neutrals and a single accent that drives interaction.
+
+- **Primary (`#1E1914`):** Headlines and core text.
+- **Secondary (`#8A7E6C`):** Borders, captions, and metadata.
+- **Tertiary (`#A57D46`):** The sole driver for interaction. Reserve it.
+- **Neutral (`#F2ECDE`):** The page foundation.
+
+## Typography
+
+- **display:** Cormorant Garamond 5rem
+- **h1:** Cormorant Garamond 2.6rem
+- **body:** Inter 1rem
+- **label:** Inter 0.72rem
+
+## Do's and Don'ts
+
+- **Do** use Tertiary for exactly one action per screen.
+- **Do** let Neutral carry the composition — negative space is a feature.
+- **Don't** introduce gradients. This system is flat on purpose.
+- **Don't** mix Tertiary with alternate accents; the single-accent rule is load-bearing.
+
+## AI Agent Instructions: Taste Skill Integration
+
+When generating code or designing interfaces based on this system, the AI Agent **MUST** also apply the advanced frontend engineering principles defined in the Taste Skill framework.
+
+1. **Apply the Skill:** Read and follow the directives outlined in `../../skills/design/taste-skill/SKILL.md` (or the equivalent `design-taste-frontend` skill).
+2. **Merge Logic:**
+   - Use the **Colors**, **Typography**, and **Spacing** defined in this `Design.md` document as your absolute source of truth for all design tokens.
+   - Use the **Taste Skill** directives for layout engineering, motion (e.g., Framer Motion), anti-slop bias correction, and modern component architecture.
+3. **Active Baseline Configuration for this Design:**
+   - `DESIGN_VARIANCE`: 3 (Traditional, elegant grids and structured property layouts).
+   - `MOTION_INTENSITY`: 4 (Warm, soft transitions and high-quality image reveals).
+   - `VISUAL_DENSITY`: 3 (Spacious, high-quality feel with balanced linen/brass tones).
+
+### Available Taste Skill Modules
+The following modules are available in `../../skills/design/`. The AI should refer to the corresponding `SKILL.md` files when specific stylistic variations or task optimizations are needed:
+- **`taste-skill`**: The main design skill for premium frontend code. Covers layout, typography, colors, spacing, and motion.
+- **`gpt-taste`**: Elite Awwwards-level frontend design and GSAP motion skill for premium, deterministic, anti-slop UI generation.
+- **`soft-skill`**: Focuses on an expensive, soft UI look with premium fonts, whitespace, depth, and smooth animations.
+- **`minimalist-skill`**: Enforces clean, editorial-style interfaces (Notion/Linear style) with strict monochrome palettes.
+- **`brutalist-skill`**: Raw mechanical interfaces, Swiss typography, extreme scale contrast.
+- **`redesign-skill`**: For upgrading existing projects by auditing and fixing design problems.
+- **`output-skill`**: Prevents AI from being lazy, skipping code blocks, or using placeholder comments.
+- **`stitch-skill`**: Google Stitch-compatible semantic design rules for premium AI UI generation.
+- **`concept-diagrams`**: Unified visual language for creating minimal, SVG-based architecture and concept diagrams.

package/docs/design/themes/vodafone.md

@@ -0,0 +1,101 @@
+---
+version: alpha
+name: Vodafone
+description: Monumental uppercase display. Vodafone-red chapter bands.
+colors:
+  primary: "#0D0D0D"
+  secondary: "#6D6D6D"
+  tertiary: "#E60000"
+  neutral: "#F4F4F4"
+  surface: "#FFFFFF"
+  on-primary: "#FFFFFF"
+typography:
+  display:
+    fontFamily: Archivo Black
+    fontSize: 6rem
+    fontWeight: 900
+    letterSpacing: "-0.025em"
+  h1:
+    fontFamily: Archivo Black
+    fontSize: 2.8rem
+    fontWeight: 900
+  body:
+    fontFamily: Inter
+    fontSize: 1rem
+    lineHeight: 1.6
+  label:
+    fontFamily: Inter
+    fontSize: 0.74rem
+    fontWeight: 700
+    letterSpacing: "0.1em"
+rounded:
+  sm: 2px
+  md: 4px
+  lg: 6px
+spacing:
+  sm: 8px
+  md: 16px
+  lg: 32px
+components:
+  button-primary:
+    backgroundColor: "{colors.tertiary}"
+    textColor: "{colors.on-primary}"
+    rounded: "{rounded.md}"
+    padding: 12px 20px
+  card:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.primary}"
+    rounded: "{rounded.lg}"
+    padding: 24px
+---
+## Overview
+
+Vodafone: monumental all-caps display, saturated red chapter bands on white, uncompromising sans.
+
+## Colors
+
+The palette is built around high-contrast neutrals and a single accent that drives interaction.
+
+- **Primary (`#0D0D0D`):** Headlines and core text.
+- **Secondary (`#6D6D6D`):** Borders, captions, and metadata.
+- **Tertiary (`#E60000`):** The sole driver for interaction. Reserve it.
+- **Neutral (`#F4F4F4`):** The page foundation.
+
+## Typography
+
+- **display:** Archivo Black 6rem
+- **h1:** Archivo Black 2.8rem
+- **body:** Inter 1rem
+- **label:** Inter 0.74rem
+
+## Do's and Don'ts
+
+- **Do** use Tertiary for exactly one action per screen.
+- **Do** let Neutral carry the composition — negative space is a feature.
+- **Don't** introduce gradients. This system is flat on purpose.
+- **Don't** mix Tertiary with alternate accents; the single-accent rule is load-bearing.
+
+## AI Agent Instructions: Taste Skill Integration
+
+When generating code or designing interfaces based on this system, the AI Agent **MUST** also apply the advanced frontend engineering principles defined in the Taste Skill framework.
+
+1. **Apply the Skill:** Read and follow the directives outlined in `../../skills/design/taste-skill/SKILL.md` (or the equivalent `design-taste-frontend` skill).
+2. **Merge Logic:**
+   - Use the **Colors**, **Typography**, and **Spacing** defined in this `Design.md` document as your absolute source of truth for all design tokens.
+   - Use the **Taste Skill** directives for layout engineering, motion (e.g., Framer Motion), anti-slop bias correction, and modern component architecture.
+3. **Active Baseline Configuration for this Design:**
+   - `DESIGN_VARIANCE`: 4 (Structured, monumental layouts with bold chapter bands).
+   - `MOTION_INTENSITY`: 7 (Snappy, fast transitions to match the bold, high-energy brand).
+   - `VISUAL_DENSITY`: 6 (High impact, large typography, and moderate information density).
+
+### Available Taste Skill Modules
+The following modules are available in `../../skills/design/`. The AI should refer to the corresponding `SKILL.md` files when specific stylistic variations or task optimizations are needed:
+- **`taste-skill`**: The main design skill for premium frontend code. Covers layout, typography, colors, spacing, and motion.
+- **`gpt-taste`**: Elite Awwwards-level frontend design and GSAP motion skill for premium, deterministic, anti-slop UI generation.
+- **`soft-skill`**: Focuses on an expensive, soft UI look with premium fonts, whitespace, depth, and smooth animations.
+- **`minimalist-skill`**: Enforces clean, editorial-style interfaces (Notion/Linear style) with strict monochrome palettes.
+- **`brutalist-skill`**: Raw mechanical interfaces, Swiss typography, extreme scale contrast.
+- **`redesign-skill`**: For upgrading existing projects by auditing and fixing design problems.
+- **`output-skill`**: Prevents AI from being lazy, skipping code blocks, or using placeholder comments.
+- **`stitch-skill`**: Google Stitch-compatible semantic design rules for premium AI UI generation.
+- **`concept-diagrams`**: Unified visual language for creating minimal, SVG-based architecture and concept diagrams.

package/docs/hooks/Hooks.md

@@ -0,0 +1,30 @@
+# Custom Hooks
+
+This document provides an overview of all the custom React hooks available in the `@the project/hooks` package. These hooks encapsulate the core business logic, API interactions, and state management used across both the Web and Mobile clients.
+
+---
+
+## 🏗️ Architecture
+
+The hook layer sits between the UI components and the `@the project/sdk` services. Hooks are designed to be:
+- **Composable**: Build complex logic from simpler hooks.
+- **Reusable**: Share logic between different platforms (Web/Mobile).
+- **Testable**: Easily mockable for unit testing.
+
+---
+
+## 🛠️ Core Hooks
+
+### Auth
+- `useAuth`: Handles login, logout, and current user state.
+- `useSession`: Manages JWT refresh and session persistence.
+
+### Data Fetching
+- `useResource`: Generic hook for fetching and caching resources.
+- `useMutation`: Wrapper for creating/updating/deleting data.
+
+---
+
+## 📦 SDK Integration
+
+For modules like **Storage** and **Analytics**, the logic is handled via the `@the project/sdk` services. Hooks provide a reactive interface to these services.

package/docs/schema/Schema.md

@@ -0,0 +1,35 @@
+# Database Schema
+
+This document describes the data models and relationships for the project.
+
+## 🗄️ Database Type
+- Primary: [e.g., PostgreSQL, MongoDB, Appwrite]
+
+---
+
+## 🗺️ Entity Relationship Diagram
+(Link to diagram or describe relationships here)
+
+---
+
+## 📑 Collections / Tables
+
+### `users`
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `id` | UUID | Primary Key |
+| `email` | String | Unique email |
+| `name` | String | Display name |
+| `createdAt` | DateTime | Creation timestamp |
+
+### `resources`
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `id` | UUID | Primary Key |
+| `ownerId` | UUID | FK to users.id |
+| `status` | Enum | [DRAFT, PUBLISHED] |
+
+---
+
+## 🛡️ Security Rules
+- [Describe RLS or ACL policies here]

package/docs/strategy/ScalingStrategy.md

@@ -0,0 +1,19 @@
+# Scaling Strategy
+
+Roadmap for handling growth and ensuring system performance at scale.
+
+## 📈 Phase 1: MVP (0 - 1k Users)
+- **Architecture**: Monolithic / Single Cluster.
+- **Database**: Single instance.
+- **Caching**: Local memory.
+
+## 🚀 Phase 2: Growth (1k - 100k Users)
+- **Load Balancing**: Traefik / Nginx.
+- **Database**: Read replicas.
+- **Caching**: Redis / Distributed cache.
+- **Storage**: S3 / CDN.
+
+## 🌎 Phase 3: Global Scale (100k+ Users)
+- **Infrastructure**: Multi-region deployment.
+- **Database**: Horizontal sharding.
+- **Messaging**: RabbitMQ / Kafka for async tasks.

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@kinqs/brainrouter-mcp-server",
+  "version": "0.3.4",
+  "description": "BrainRouter MCP server — the cognitive memory engine. Exposes recall, capture, focus scenes, persona, contradictions, skills, and graph queries as MCP tools for any MCP-speaking agent.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "brainrouter-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "agents",
+    "references",
+    "docs",
+    "README.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "prepack": "node scripts/prepack.mjs",
+    "postpack": "node scripts/postpack.mjs",
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "dev:http": "tsx watch src/index.ts -- --http --port 3747",
+    "start": "node dist/index.js",
+    "start:http": "node dist/index.js --http --port 3747",
+    "test": "vitest run",
+    "setup:mcp": "node scripts/setup-mcp.js",
+    "bench:longmemeval": "npx tsx benchmark/longmemeval-bench.ts fts",
+    "bench:longmemeval:hybrid": "npx tsx benchmark/longmemeval-bench.ts hybrid",
+    "bench:quality": "npx tsx benchmark/quality-eval.ts",
+    "bench:scale": "npx tsx benchmark/scale-eval.ts",
+    "bench:load": "npx tsx benchmark/load-100k-bench.ts",
+    "bench:real-embeddings": "npx tsx benchmark/real-embeddings-eval.ts",
+    "bench:e2e": "npx tsx benchmark/end-to-end-bench.ts",
+    "bench:download": "npx tsx benchmark/lib/dataset-loader.ts",
+    "bench:overnight": "npx tsx benchmark/run-overnight.ts",
+    "setup:admin": "node scripts/setup-admin.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.0",
+    "dotenv": "^16.4.5",
+    "express": "^5.2.1",
+    "glob": "^11.0.0",
+    "gray-matter": "^4.0.3",
+    "sqlite-vec": "^0.1.9",
+    "zod": "^3.22.4",
+    "@kinqs/brainrouter-types": "^0.3.4"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.0.0",
+    "@xenova/transformers": "^2.17.2",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.4.0"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "mcp",
+    "model-context-protocol",
+    "memory",
+    "cognitive-memory",
+    "llm",
+    "rag",
+    "embeddings",
+    "graphrag",
+    "brainrouter"
+  ],
+  "license": "MIT",
+  "author": "BrainRouter contributors",
+  "homepage": "https://github.com/kinqsradiollc/BrainRouter#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kinqsradiollc/BrainRouter.git",
+    "directory": "brainrouter"
+  },
+  "bugs": {
+    "url": "https://github.com/kinqsradiollc/BrainRouter/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/references/accessibility-checklist.md

@@ -0,0 +1,160 @@
+# Accessibility Checklist
+
+Quick reference for WCAG 2.1 AA compliance. Use alongside the `frontend-ui-engineering` skill.
+
+## Table of Contents
+
+- [Essential Checks](#essential-checks)
+- [Common HTML Patterns](#common-html-patterns)
+- [Testing Tools](#testing-tools)
+- [Quick Reference: ARIA Live Regions](#quick-reference-aria-live-regions)
+- [Common Anti-Patterns](#common-anti-patterns)
+
+## Essential Checks
+
+### Keyboard Navigation
+- [ ] All interactive elements focusable via Tab key
+- [ ] Focus order follows visual/logical order
+- [ ] Focus is visible (outline/ring on focused elements)
+- [ ] Custom widgets have keyboard support (Enter to activate, Escape to close)
+- [ ] No keyboard traps (user can always Tab away from a component)
+- [ ] Skip-to-content link at top of page - visible (at least) on keyboard focus
+- [ ] Modals trap focus while open, return focus on close
+
+### Screen Readers
+- [ ] All images have `alt` text (or `alt=""` for decorative images)
+- [ ] All form inputs have associated labels (`<label>` or `aria-label`)
+- [ ] Buttons and links have descriptive text (not "Click here")
+- [ ] Icon-only buttons have `aria-label`
+- [ ] Page has one `<h1>` and headings don't skip levels
+- [ ] Dynamic content changes announced (`aria-live` regions)
+- [ ] Tables have `<th>` headers with scope
+
+### Visual
+- [ ] Text contrast ≥ 4.5:1 (normal text) or ≥ 3:1 (large text, 18px+)
+- [ ] UI components contrast ≥ 3:1 against background
+- [ ] Color is not the only way to convey information
+- [ ] Text resizable to 200% without breaking layout
+- [ ] No content that flashes more than 3 times per second
+
+### Forms
+- [ ] Every input has a visible label
+- [ ] Required fields indicated (not by color alone)
+- [ ] Error messages specific and associated with the field
+- [ ] Error state visible by more than color (icon, text, border)
+- [ ] Form submission errors summarized and focusable
+- [ ] Known fields use autocomplete (for example `type="email" autocomplete="email"`)
+
+### Content
+- [ ] Language declared (`<html lang="en">`)
+- [ ] Page has a descriptive `<title>`
+- [ ] Links distinguish from surrounding text (not by color alone)
+- [ ] Touch targets ≥ 44x44px on mobile
+- [ ] Meaningful empty states (not blank screens)
+
+## Common HTML Patterns
+
+### Buttons vs. Links
+
+```html
+<!-- Use <button> for actions -->
+<button onClick={handleDelete}>Delete Task</button>
+
+<!-- Use <a> for navigation -->
+<a href="/tasks/123">View Task</a>
+
+<!-- NEVER use div/span as buttons -->
+<div onClick={handleDelete}>Delete</div>  <!-- BAD -->
+```
+
+### Form Labels
+
+```html
+<!-- Explicit label association -->
+<label htmlFor="email">Email address</label>
+<input id="email" type="email" required />
+
+<!-- Implicit wrapping -->
+<label>
+  Email address
+  <input type="email" required />
+</label>
+
+<!-- Hidden label (visible label preferred) -->
+<input type="search" aria-label="Search tasks" />
+```
+
+### ARIA Roles
+
+```html
+<!-- Navigation -->
+<nav aria-label="Main navigation">...</nav>
+<nav aria-label="Footer links">...</nav>
+
+<!-- Status messages -->
+<div role="status" aria-live="polite">Task saved</div>
+
+<!-- Alert messages -->
+<div role="alert">Error: Title is required</div>
+
+<!-- Modal dialogs -->
+<dialog aria-modal="true" aria-labelledby="dialog-title">
+  <h2 id="dialog-title">Confirm Delete</h2>
+  ...
+</dialog>
+
+<!-- Loading states -->
+<div aria-busy="true" aria-label="Loading tasks">
+  <Spinner />
+</div>
+```
+
+### Accessible Lists
+
+```html
+<ul role="list" aria-label="Tasks">
+  <li>
+    <input type="checkbox" id="task-1" aria-label="Complete: Buy groceries" />
+    <label htmlFor="task-1">Buy groceries</label>
+  </li>
+</ul>
+```
+
+## Testing Tools
+
+```bash
+# Automated audit
+npx axe-core          # Programmatic accessibility testing
+npx pa11y             # CLI accessibility checker
+
+# In browser
+# Chrome DevTools → Lighthouse → Accessibility
+# Chrome DevTools → Elements → Accessibility tree
+
+# Screen reader testing
+# macOS: VoiceOver (Cmd + F5)
+# Windows: NVDA (free) or JAWS
+# Linux: Orca
+```
+
+## Quick Reference: ARIA Live Regions
+
+| Value | Behavior | Use For |
+|-------|----------|---------|
+| `aria-live="polite"` | Announced at next pause | Status updates, saved confirmations |
+| `aria-live="assertive"` | Announced immediately | Errors, time-sensitive alerts |
+| `role="status"` | Same as `polite` | Status messages |
+| `role="alert"` | Same as `assertive` | Error messages |
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| `div` as button | Not focusable, no keyboard support | Use `<button>` |
+| Missing `alt` text | Images invisible to screen readers | Add descriptive `alt` |
+| Color-only states | Invisible to color-blind users | Add icons, text, or patterns |
+| Autoplaying media | Disorienting, can't be stopped | Add controls, don't autoplay |
+| Custom dropdown with no ARIA | Unusable by keyboard/screen reader | Use native `<select>` or proper ARIA listbox |
+| Removing focus outlines | Users can't see where they are | Style outlines, don't remove them |
+| Empty links/buttons | "Link" announced with no description | Add text or `aria-label` |
+| `tabindex > 0` | Breaks natural tab order | Use `tabindex="0"` or `-1` only |