diff --git a/CLAUDE.md b/CLAUDE.md index 0421310d..23987c88 100644 --- a/CLAUDE.md +++ b/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: diff --git a/docs/BATCHING.md b/docs/BATCHING.md index 8701b508..8737dc6c 100644 --- a/docs/BATCHING.md +++ b/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 diff --git a/docs/FIND_SYSTEM.md b/docs/FIND_SYSTEM.md index 0efee14c..a3c4fa21 100644 --- a/docs/FIND_SYSTEM.md +++ b/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 diff --git a/docs/PLUGINS.md b/docs/PLUGINS.md index 5e64afb0..8b82ce2e 100644 --- a/docs/PLUGINS.md +++ b/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. diff --git a/docs/api/README.md b/docs/api/README.md index f163fcd8..5035cba8 100644 --- a/docs/api/README.md +++ b/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** diff --git a/docs/architecture/noun-verb-taxonomy.md b/docs/architecture/noun-verb-taxonomy.md index 4b2983b7..7cb7c16d 100644 --- a/docs/architecture/noun-verb-taxonomy.md +++ b/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™** diff --git a/docs/architecture/triple-intelligence.md b/docs/architecture/triple-intelligence.md index fe6f8d19..96e6e2e6 100644 --- a/docs/architecture/triple-intelligence.md +++ b/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. diff --git a/docs/architecture/zero-config.md b/docs/architecture/zero-config.md index 363d9d7e..162ad391 100644 --- a/docs/architecture/zero-config.md +++ b/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. diff --git a/docs/guides/installation.md b/docs/guides/installation.md new file mode 100644 index 00000000..62d2690b --- /dev/null +++ b/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 diff --git a/docs/guides/quick-start.md b/docs/guides/quick-start.md new file mode 100644 index 00000000..7f871df2 --- /dev/null +++ b/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 diff --git a/docs/guides/storage-adapters.md b/docs/guides/storage-adapters.md index 22a9613f..9c81d7fc 100644 --- a/docs/guides/storage-adapters.md +++ b/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 diff --git a/package.json b/package.json index b07d9b18..19c66c09 100644 --- a/package.json +++ b/package.json @@ -151,6 +151,7 @@ "assets/models/all-MiniLM-L6-v2/**", "bin/", "brainy.png", + "docs/**/*.md", "LICENSE", "README.md", "CHANGELOG.md"