docs: add public frontmatter to docs for soulcraft.com/docs pipeline

Add YAML frontmatter (slug, public, category, template, order) to 8
existing docs and 2 new getting-started guides (installation, quick-start).
Include docs/**/*.md in npm package files so the portal sync-docs script
can read them from node_modules after publish.

Update CLAUDE.md with docs pipeline trigger phrases and release checklist.

CLAUDE.md

@@ -75,6 +75,64 @@ test: add/update tests       (patch version bump)
 
 **Important:** Never use `BREAKING CHANGE` in commit messages. Major version bumps are manual decisions only (`npm run release:major`).
 
+## Docs Pipeline — soulcraft.com/docs
+
+Docs in `docs/**/*.md` are published with the npm package (included in `files`) and synced to soulcraft.com/docs on every portal deploy. Frontmatter controls what appears publicly.
+
+### Docs check triggers
+
+Run the docs check whenever the user says ANY of:
+- "commit, publish, release" / "release" / "publish"
+- "update the docs" / "make sure docs are accurate" / "check the docs"
+- "review docs" / "clean up docs"
+
+### Pre-release docs check (MANDATORY before every release)
+
+When the user says "commit, publish, release" or any variation, **before committing**:
+
+1. **Scan all files changed in this session** (and any recently added `docs/*.md` files)
+2. For each changed/new doc, decide: is this useful to external users?
+   - **Yes** → ensure it has complete frontmatter (add or update it)
+   - **No** (internal, migration, dev-only) → ensure it has no frontmatter or `public: false`
+3. For docs that already have frontmatter, verify:
+   - `description` still matches the actual content
+   - `next` links still exist and are still the right follow-up pages
+   - `title` matches the doc's h1
+4. Include frontmatter changes in the commit
+
+### Frontmatter format
+
+```yaml
+---
+title: Human-readable title
+slug: category/page-name          # URL: soulcraft.com/docs/category/page-name
+public: true                      # false or absent = not published
+category: getting-started | concepts | guides | api
+template: guide | concept | api   # controls layout on soulcraft.com
+order: 1                          # sidebar position within category (lower = first)
+description: One sentence. What this doc covers and why it matters.
+next:                             # "Next steps" links shown at bottom of page
+  - category/other-slug
+---
+```
+
+### Category guide
+
+| category | use for |
+|----------|---------|
+| `getting-started` | installation, quick start, first steps |
+| `concepts` | how the system works, mental models |
+| `guides` | how to do specific things, recipes |
+| `api` | method reference, signatures, parameters |
+
+### What stays internal (no frontmatter / `public: false`)
+
+- Release guides, developer learning paths
+- Migration guides for old versions (v3→v4, v5.11)
+- Architecture analysis docs (clustering algorithms, etc.)
+- Anything in `docs/internal/`
+- Deployment/ops/cost docs (cloud-run, kubernetes, cost-optimization)
+
 ## Release Process
 
 Fully automated via `scripts/release.sh`:
@@ -88,6 +146,11 @@ npm run release:major        # Breaking changes (rare, manual decision)
 
 The script: verifies clean git state, builds, tests, bumps version, updates CHANGELOG.md, commits, tags, pushes, publishes to npm, and creates a GitHub release.
 
+After a successful release, remind the user:
+> "Published. Deploy portal to pick up the new docs → go to the portal project and deploy."
+
+Do NOT deploy portal from here. Portal is always deployed separately from within the portal project.
+
 ## Performance Claims
 
 When documenting performance characteristics:

docs/BATCHING.md

@@ -1,3 +1,16 @@
+---
+title: Batch Operations
+slug: guides/batching
+public: true
+category: guides
+template: guide
+order: 5
+description: Eliminate N+1 query patterns with batchGet() and storage-level batch APIs. Achieve 90%+ faster cloud storage access — from 12.7 seconds down to under 1 second.
+next:
+  - api/reference
+  - guides/find-system
+---
+
 # Batch Operations API
 > **Enterprise Production-Ready** | Zero N+1 Query Patterns | 90%+ Performance Improvement
 

docs/FIND_SYSTEM.md

@@ -1,3 +1,16 @@
+---
+title: The Find System
+slug: guides/find-system
+public: true
+category: guides
+template: guide
+order: 3
+description: Complete guide to Brainy's find() method — four intelligence systems, query execution phases, NLP patterns, and performance from 1K to 10M entities.
+next:
+  - concepts/triple-intelligence
+  - api/reference
+---
+
 # Brainy's Find System - Complete Guide
 
 ## Overview

docs/PLUGINS.md

@@ -1,3 +1,16 @@
+---
+title: Plugin System
+slug: guides/plugins
+public: true
+category: guides
+template: guide
+order: 4
+description: Replace any Brainy subsystem — distance functions, embeddings, HNSW index, metadata index, aggregation — with a custom implementation or native Rust via Cortex.
+next:
+  - cortex/comparison
+  - guides/storage-adapters
+---
+
 # Plugin Development Guide
 
 Brainy has a plugin system that allows third-party packages to replace internal subsystems with custom implementations. This is how `@soulcraft/cortex` provides native Rust acceleration, and it's the same system available to any developer.

docs/api/README.md

@@ -1,3 +1,16 @@
+---
+title: API Reference
+slug: api/reference
+public: true
+category: api
+template: api
+order: 1
+description: Complete API reference for all Brainy methods — add, find, relate, update, delete, batch operations, branching, entity versioning, VFS, neural API, and more.
+next:
+  - getting-started/quick-start
+  - guides/find-system
+---
+
 # 🧠 Brainy API Reference
 
 > **Complete API documentation for Brainy**

docs/architecture/noun-verb-taxonomy.md

@@ -1,3 +1,16 @@
+---
+title: Noun & Verb Types
+slug: concepts/noun-types
+public: true
+category: concepts
+template: concept
+order: 2
+description: 42 NounTypes and 127 VerbTypes cover 96-97% of all human knowledge. The universal vocabulary for structuring anything from people and documents to events and relationships.
+next:
+  - concepts/triple-intelligence
+  - api/reference
+---
+
 # The Universal Knowledge Protocol: Noun-Verb Taxonomy
 
 > **Brainy is the Universal Knowledge Protocol™ powered by Triple Intelligence™**

docs/architecture/triple-intelligence.md

@@ -1,3 +1,16 @@
+---
+title: Triple Intelligence
+slug: concepts/triple-intelligence
+public: true
+category: concepts
+template: concept
+order: 1
+description: Unified vector similarity, graph traversal, and metadata filtering in one query. Auto-optimizes between parallel execution and progressive filtering.
+next:
+  - concepts/noun-types
+  - api/reference
+---
+
 # Triple Intelligence System
 
 The Triple Intelligence System is Brainy's revolutionary query engine that unifies vector similarity, graph relationships, and metadata filtering into a single, optimized query interface.

docs/architecture/zero-config.md

@@ -1,3 +1,16 @@
+---
+title: Zero Configuration
+slug: concepts/zero-config
+public: true
+category: concepts
+template: concept
+order: 3
+description: Brainy auto-detects storage, initializes embeddings, and builds indexes — no configuration required. Works in Node.js, Bun, OPFS, and cloud environments.
+next:
+  - getting-started/installation
+  - guides/storage-adapters
+---
+
 # Zero Configuration & Auto-Adaptation
 
 > **Current Status**: Basic zero-config is fully functional. Advanced auto-adaptation features are in development.

docs/guides/installation.md

@@ -0,0 +1,100 @@
+---
+title: Installation
+slug: getting-started/installation
+public: true
+category: getting-started
+template: guide
+order: 1
+description: Install Brainy with npm, bun, yarn, or pnpm. Works in Node.js 22+, Bun 1.0+, and browser (OPFS). TypeScript included.
+next:
+  - getting-started/quick-start
+  - concepts/zero-config
+---
+
+# Installation
+
+## Requirements
+
+- **Node.js 22+** or **Bun 1.0+**
+- TypeScript is optional — Brainy ships with full type definitions
+
+## Install
+
+```bash
+npm install @soulcraft/brainy
+```
+
+Or with your preferred package manager:
+
+```bash
+bun add @soulcraft/brainy
+yarn add @soulcraft/brainy
+pnpm add @soulcraft/brainy
+```
+
+## Verify
+
+```javascript
+import { Brainy } from '@soulcraft/brainy'
+
+const brain = new Brainy()
+await brain.init()
+
+console.log('Brainy ready.')
+```
+
+## Native Acceleration (Optional)
+
+For production workloads, add Cortex for Rust-accelerated SIMD distance calculations, vector quantization, and native embeddings:
+
+```bash
+npm install @soulcraft/cortex
+```
+
+```javascript
+import { Brainy } from '@soulcraft/brainy'
+import { registerCortex } from '@soulcraft/cortex'
+
+registerCortex()  // activates native acceleration globally
+
+const brain = new Brainy()
+await brain.init()
+```
+
+Cortex delivers a **5.2x geometric mean speedup** — see [Brainy vs Cortex](/docs/cortex/comparison) for measured benchmarks.
+
+## Browser (OPFS)
+
+Brainy works in the browser using the Origin Private File System:
+
+```javascript
+import { Brainy } from '@soulcraft/brainy'
+
+const brain = new Brainy({ storage: 'opfs' })
+await brain.init()
+```
+
+No server required. Data persists across page refreshes in the browser's private storage.
+
+## TypeScript
+
+Brainy ships with full TypeScript types. No `@types/` package needed:
+
+```typescript
+import { Brainy, NounType, VerbType } from '@soulcraft/brainy'
+
+const brain = new Brainy()
+await brain.init()
+
+const id = await brain.add({
+  data: 'Hello, Brainy',
+  type: NounType.Concept,
+  metadata: { created: Date.now() }
+})
+```
+
+## Next Steps
+
+- [Quick Start](/docs/getting-started/quick-start) — build your first knowledge graph in 60 seconds
+- [Zero Configuration](/docs/concepts/zero-config) — understand what Brainy auto-detects
+- [Storage Adapters](/docs/guides/storage-adapters) — choose the right storage for your deployment

docs/guides/quick-start.md

@@ -0,0 +1,105 @@
+---
+title: Quick Start
+slug: getting-started/quick-start
+public: true
+category: getting-started
+template: guide
+order: 2
+description: Build your first knowledge graph in 60 seconds. Add entities, create relationships, and query with Triple Intelligence — vector + graph + metadata in one call.
+next:
+  - concepts/triple-intelligence
+  - api/reference
+---
+
+# Quick Start
+
+Get Brainy running in under a minute.
+
+## 1. Install
+
+```bash
+npm install @soulcraft/brainy
+```
+
+## 2. Initialize
+
+```javascript
+import { Brainy, NounType, VerbType } from '@soulcraft/brainy'
+
+const brain = new Brainy()
+await brain.init()
+```
+
+That's it. Brainy auto-configures storage, loads the embedding model, and builds the indexes.
+
+## 3. Add Knowledge
+
+```javascript
+// Text is automatically embedded into 384-dim vectors
+const reactId = await brain.add({
+  data: 'React is a JavaScript library for building user interfaces',
+  type: NounType.Concept,
+  metadata: { category: 'frontend', year: 2013 }
+})
+
+const nextId = await brain.add({
+  data: 'Next.js framework for React with server-side rendering',
+  type: NounType.Concept,
+  metadata: { category: 'framework', year: 2016 }
+})
+```
+
+## 4. Create Relationships
+
+```javascript
+// Typed graph relationships
+await brain.relate({
+  from: nextId,
+  to: reactId,
+  type: VerbType.BuiltOn
+})
+```
+
+## 5. Query with Triple Intelligence
+
+```javascript
+// All three search paradigms in one call
+const results = await brain.find({
+  query: 'modern frontend frameworks',    // Vector similarity search
+  where: { year: { greaterThan: 2015 } }, // Metadata filtering
+  connected: { to: reactId, depth: 2 }   // Graph traversal
+})
+
+console.log(results.items)
+// [{ id: nextId, data: 'Next.js...', score: 0.94, ... }]
+```
+
+## What Just Happened
+
+Every entity you `add()` lives in three indexes simultaneously:
+
+| Index | What it stores | Query with |
+|-------|---------------|------------|
+| Vector | 384-dim embedding of `data` | `find({ query: '...' })` |
+| Metadata | All `metadata` fields | `find({ where: { ... } })` |
+| Graph | Typed relationships from `relate()` | `find({ connected: { ... } })` |
+
+`find()` queries all three in parallel and fuses the results.
+
+## Natural Language Queries
+
+Brainy understands 220+ natural language patterns:
+
+```javascript
+// These all work without any configuration
+await brain.find({ query: 'recent documents about machine learning' })
+await brain.find({ query: 'articles created this week' })
+await brain.find({ query: 'people who work at Anthropic' })
+```
+
+## Next Steps
+
+- [Triple Intelligence](/docs/concepts/triple-intelligence) — understand how the query engine works
+- [The Find System](/docs/guides/find-system) — advanced queries, operators, and graph traversal
+- [API Reference](/docs/api/reference) — complete method documentation
+- [Storage Adapters](/docs/guides/storage-adapters) — S3, GCS, Azure, filesystem, OPFS

docs/guides/storage-adapters.md

@@ -1,3 +1,16 @@
+---
+title: Storage Adapters
+slug: guides/storage-adapters
+public: true
+category: guides
+template: guide
+order: 2
+description: "Six adapters for every deployment: in-memory, OPFS (browser), filesystem, S3, Google Cloud Storage, Azure Blob, and Cloudflare R2. All support copy-on-write branching."
+next:
+  - guides/plugins
+  - concepts/zero-config
+---
+
 # Storage Adapters Guide
 
 ## Overview

package.json

@@ -151,6 +151,7 @@
     "assets/models/all-MiniLM-L6-v2/**",
     "bin/",
     "brainy.png",
+    "docs/**/*.md",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"