docs: align usage contracts and discovery surfaces

.changeset/bright-urls-redirect.md

@@ -0,0 +1,5 @@
+---
+'@agentskit/integrations': patch
+---
+
+Point the package homepage and README at the canonical integration guide and preserve the legacy docs URL with a direct redirect.

.changeset/quiet-errors-guide.md

@@ -0,0 +1,6 @@
+---
+'@agentskit/core': patch
+'@agentskit/rag': patch
+---
+
+Point built-in and RAG errors at canonical documentation routes, and align the package and site usage guides with the current public contracts.

.changeset/tidy-vectra-peer.md

@@ -0,0 +1,5 @@
+---
+'@agentskit/memory': patch
+---
+
+Declare Vectra as an optional peer dependency for the on-disk vector memory backend.

.doc-bridge/capabilities.json

@@ -7,7 +7,7 @@
     "name": "AgentsKit",
     "root": "."
   },
-  "contentHash": "4b8372dc800cc78266ddc77be7184f5451bcfa6a91c36f3ef631f6119733c5e6",
+  "contentHash": "cfa57ad9da1ec022f65144e749091be3fc89d27a360a3c580ab4f3c0658145b2",
   "artifacts": {
     "index": ".doc-bridge/index.json",
     "llmsTxt": "llms.txt"

.doc-bridge/index.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
-  "contentHash": "4b8372dc800cc78266ddc77be7184f5451bcfa6a91c36f3ef631f6119733c5e6",
+  "contentHash": "cfa57ad9da1ec022f65144e749091be3fc89d27a360a3c580ab4f3c0658145b2",
   "contentHashAlgo": "sha256-normalized-v1",
-  "generatedAt": "2026-08-13T01:23:01.529Z",
+  "generatedAt": "2026-08-13T02:11:22.456Z",
   "project": {
     "name": "AgentsKit",
     "root": "."
@@ -89,7 +89,7 @@
       "type": "agent-doc",
       "title": "memory",
       "path": "apps/docs-next/content/docs/for-agents/memory.mdx",
-      "body": "Install Primary exports Chat memory (ordered history) - fileChatMemory({ path }) — JSON file. - sqliteChatMemory — SQLite-backed. - redisChatMemory — Redis-backed. - tursoChatMemory — Turso / libSQL. - createWebStorageMemory from @agentskit/memory/web-storage — injected, SSR-safe localStorage / sessionStorage with runtime validation, byte/message bounds, cancellation, and host-owned legacy migration. Vector memory - fileVectorMemory({ path }) — JSON file. - redisVectorMemory — Redis Vector. - pgvector , pinecone , qdrant , chroma , upstashVector — BYO-client / HTTP vector adapters. See . - supabaseVectorStore , weaviateVectorStore , milvusVectorStore , mongoAtlasVectorStore — managed / cluster backends. - matchesFilter(record, filter) — utility for evaluating vector-store filter predicates outside an adapter. Higher-order memory - createVirtualizedMemory (from @agentskit/core ) — hot window + cold retriever. - createHierarchicalMemory — MemGPT tiers (working / recall / archival). - createAutoSummarizingMemory (from @agentskit/core/auto-summarize ) — fold oldest into a summary. - createEncryptedMemory — AES-GCM over any ChatMemory . See . - createInMemoryGraph — knowledge graph (nodes + edges + BFS). See . - createInMemoryPersonalization + renderProfileContext — per-subject profile. See . - wrapChatMemoryWithRedaction(mem, { rules, mode?, vault?, allowedRoles? }) — redact (or tokenize) PII at save() time on any ChatMemory . Pairs with @agentskit/core/security tokenize / reveal for role-gated read. - wrapVectorMemoryWithRedaction(mem, { rules, mode?, vault?, allowedRoles? }) — same for VectorMemory.store() . Embeddings pass through verbatim; redact the input to your embedder separately if it is a hosted provider. - forgetSubject(memory, subjectId) / makeForgettable(memory) — GDPR-style right-to-erasure helpers that purge all records for a subject across ChatMemory and VectorMemory . Key-value store ( AgentskitMemoryStore ) A generic get(key) / set(key,value) store with TTL + max-key eviction, complementing the conversation ChatMemory model — for agent scratchpad, pipeline state, and arbitrary JSON keyed by string. - createInMemoryStore(config) / createFileStore(config) / createLocalStorageStore({ config, storage? }) — zero-dependency backends. - createSqliteStore({ config, open }) — open is a better-sqlite3-style opener; tryDefaultSqliteOpener() lazy-imports better-sqlite3 . - createRedisStore({ config, client }) — client is a RedisLike ; adaptIoredis(io) bridges ioredis, tryDefaultRedisClient(url) lazy-imports node-redis. - createVectorStore({ config, vectorStore, embedder }) — exact-key get / set plus a recall(query, k) similarity search. - createKvMemoryFromConfig({ config, sqlite?, redis?, vectorStore?, embedder? }) / createKvMemoryFromConfigAuto(config) — dispatch over a KvMemoryConfig ( in-memory / file / sqlite / localstorage / redis / vector ); the auto form lazy-loads optional drivers. MEMORY BACKEND SUPPORT / isMemoryBackendSupported / MemoryBackendNotImplementedError describe coverage. Minimal example Related - — embedders + retrievers on top of vector memory. - — the ChatMemory / VectorMemory contracts. Source - npm: https://www.npmjs.com/package/@agentskit/memory - repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/memory"
+      "body": "Install Primary exports Chat memory (ordered history) - fileChatMemory({ path }) — JSON file. - sqliteChatMemory — SQLite-backed. - redisChatMemory — Redis-backed. - tursoChatMemory — Turso / libSQL. - createWebStorageMemory from @agentskit/memory/web-storage — injected, SSR-safe localStorage / sessionStorage with runtime validation, byte/message bounds, cancellation, and host-owned legacy migration. Vector memory - fileVectorMemory({ path }) — Vectra-backed index directory (optional vectra peer). - redisVectorMemory — Redis Vector. - pgvector , pinecone , qdrant , chroma , upstashVector — BYO-client / HTTP vector adapters. See . - supabaseVectorStore , weaviateVectorStore , milvusVectorStore , mongoAtlasVectorStore — managed / cluster backends. - matchesFilter(record, filter) — utility for evaluating vector-store filter predicates outside an adapter. Higher-order memory - createVirtualizedMemory (from @agentskit/core ) — hot window + cold retriever. - createHierarchicalMemory — MemGPT tiers (working / recall / archival). - createAutoSummarizingMemory (from @agentskit/core/auto-summarize ) — fold oldest into a summary. - createEncryptedMemory — AES-GCM over any ChatMemory . See . - createInMemoryGraph — knowledge graph (nodes + edges + BFS). See . - createInMemoryPersonalization + renderProfileContext — per-subject profile. See . - wrapChatMemoryWithRedaction(mem, { rules, mode?, vault?, allowedRoles? }) — redact (or tokenize) PII at save() time on any ChatMemory . Pairs with @agentskit/core/security tokenize / reveal for role-gated read. - wrapVectorMemoryWithRedaction(mem, { rules, mode?, vault?, allowedRoles? }) — same for VectorMemory.store() . Embeddings pass through verbatim; redact the input to your embedder separately if it is a hosted provider. - forgetSubject(memory, subjectId) / makeForgettable(memory) — GDPR-style right-to-erasure helpers that purge all records for a subject across ChatMemory and VectorMemory . Key-value store ( AgentskitMemoryStore ) A generic get(key) / set(key,value) store with TTL + max-key eviction, complementing the conversation ChatMemory model — for agent scratchpad, pipeline state, and arbitrary JSON keyed by string. - createInMemoryStore(config) / createFileStore(config) / createLocalStorageStore({ config, storage? }) — zero-dependency backends. - createSqliteStore({ config, open }) — open is a better-sqlite3-style opener; tryDefaultSqliteOpener() lazy-imports better-sqlite3 . - createRedisStore({ config, client }) — client is a RedisLike ; adaptIoredis(io) bridges ioredis, tryDefaultRedisClient(url) lazy-imports node-redis. - createVectorStore({ config, vectorStore, embedder }) — exact-key get / set plus a recall(query, k) similarity search. - createKvMemoryFromConfig({ config, sqlite?, redis?, vectorStore?, embedder? }) / createKvMemoryFromConfigAuto(config) — dispatch over a KvMemoryConfig ( in-memory / file / sqlite / localstorage / redis / vector ); the auto form lazy-loads optional drivers. MEMORY BACKEND SUPPORT / isMemoryBackendSupported / MemoryBackendNotImplementedError describe coverage. Minimal example Related - — embedders + retrievers on top of vector memory. - — the ChatMemory / VectorMemory contracts. Source - npm: https://www.npmjs.com/package/@agentskit/memory - repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/memory"
     },
     {
       "id": "observability-langfuse",
@@ -110,7 +110,7 @@
       "type": "agent-doc",
       "title": "rag",
       "path": "apps/docs-next/content/docs/for-agents/rag.mdx",
-      "body": "Install Primary exports - createRAG({ embed, store, chunkSize, chunkOverlap, topK, threshold }) — ingest(docs) + retrieve(request) + search(query) . - chunkText({ chunkSize, chunkOverlap, split }) — lower-level splitter. - createRerankedRetriever(base, { candidatePool, topK, rerank }) — pluggable reranker (BM25 default). See . - createHybridRetriever(base, { vectorWeight, bm25Weight }) — vector + BM25 hybrid. - bm25Score , bm25Rerank — standalone helpers. - voyageReranker(config) — Voyage AI reranker. - jinaReranker(config) — Jina AI reranker. - RagError / RagErrorCodes — typed error (extends AgentsKitError ) thrown by loaders + rerankers; narrow on error.code ( AK RAG LOAD FAILED , AK RAG PEER MISSING , AK RAG RERANK FAILED ). Document loaders - loadUrl , loadGitHubFile , loadGitHubTree , loadNotionPage , loadConfluencePage , loadGoogleDriveFile , loadPdf (BYO parser). See . - Cloud storage: loadS3 , loadGcs , loadDropbox , loadOneDrive . Failure and cancellation contract - Loader request, response-body, pagination, and total-download failures throw RagError with AK RAG LOAD FAILED . Tree loaders may return partial success only after at least one eligible document loaded. - Loader options accept signal?: AbortSignal ; Voyage and Jina reranker options accept the same additive field. - Notion and OneDrive follow provider pagination and reject repeated or missing continuation cursors instead of returning truncated content. - Scoreless Retriever results keep their order. If any score is present, all scores must be finite and the result is ordered descending; malformed mixed score sets throw. - Hybrid retrieval min-max normalizes candidate scores and normalizes relative weights before blending. Minimal example Related - — vector stores. - — embedders. Source - npm: https://www.npmjs.com/package/@agentskit/rag - repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/rag"
+      "body": "Install Primary exports - createRAG({ embed, store, chunkSize, chunkOverlap, topK, threshold }) — ingest(InputDocument[]) + retrieve({ query, messages }) + search(query, { topK?, threshold? }) . InputDocument uses content , not text . Chunk defaults: 512 / 50. - chunkText(text, { chunkSize, chunkOverlap, split? }) — lower-level splitter. split is (text: string) = string[] . - createRerankedRetriever(base, { candidatePool, topK, rerank }) — pluggable reranker (BM25 default). See . - createHybridRetriever(base, { vectorWeight?, bm25Weight?, topK?, candidatePool? }) — vector + BM25 hybrid; defaults to 0.6 / 0.4 , 20 candidates, and 5 results. - bm25Score , bm25Rerank — standalone helpers. - voyageReranker(config) — Voyage AI reranker. - jinaReranker(config) — Jina AI reranker. - RagError / RagErrorCodes — typed error (extends AgentsKitError ) thrown by loaders + rerankers; narrow on error.code ( AK RAG LOAD FAILED , AK RAG PEER MISSING , AK RAG RERANK FAILED ). Document loaders - loadUrl(url) — raw response text as InputDocument.content . loadGitHubFile(owner, repo, path, opts) , loadGitHubTree(owner, repo, { filter?, ... }) , loadNotionPage(pageId, { token }) , loadConfluencePage(pageId, { baseUrl, token?, authorization? }) , loadGoogleDriveFile(fileId, { accessToken }) , loadPdf(url, { parsePdf }) . All return InputDocument[] . See . - Cloud storage: loadS3 , loadGcs , loadDropbox , loadOneDrive . Failure and cancellation contract - Loader request, response-body, pagination, and total-download failures throw RagError with AK RAG LOAD FAILED . Tree loaders may return partial success only after at least one eligible document loaded. - Loader options accept signal?: AbortSignal ; Voyage and Jina reranker options accept the same additive field. - Notion and OneDrive follow provider pagination and reject repeated or missing continuation cursors instead of returning truncated content. - Scoreless Retriever results keep their order. If any score is present, all scores must be finite and the result is ordered descending; malformed mixed score sets throw. - Hybrid retrieval min-max normalizes candidate scores and normalizes relative weights before blending. Minimal example Related - — vector stores. - — embedders. Source - npm: https://www.npmjs.com/package/@agentskit/rag - repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/rag"
     },
     {
       "id": "react-native",

CONTRIBUTING.md

@@ -210,7 +210,7 @@ CI runs all of these on every PR. Run them locally first to avoid burning CI min
 If your change affects what a consumer sees or does:
 
 - Update the relevant page in `apps/docs-next/content/docs/`
-- Add a recipe if you've added a new building block (`apps/docs-next/content/docs/recipes/`)
+- Add a recipe if you've added a new building block (`apps/docs-next/content/docs/reference/recipes/`)
 - Update the relevant ADR if you've changed how a contract behaves (rare — usually a new ADR superseding the old one)
 - Update the package's `README.md` if its public surface changed
 

README.md

@@ -6,7 +6,7 @@
 
 **The agent toolkit JavaScript actually deserves.**
 
-A 10 KB core budget. Twenty-five focused packages. Zero lock-in. Six formal contracts that make every adapter, tool, skill, memory, retriever, and runtime substitutable.
+A 10 KB core budget. Twenty-two published packages. Zero lock-in. Six formal contracts that make every adapter, tool, skill, memory, retriever, and runtime substitutable.
 
 [![npm](https://img.shields.io/npm/v/@agentskit/react?label=npm)](https://www.npmjs.com/package/@agentskit/react)
 [![bundle](https://img.shields.io/bundlephobia/minzip/@agentskit/react?label=react%20bundle)](https://bundlephobia.com/package/@agentskit/react)
@@ -394,7 +394,7 @@ See the [stability policy](./docs/STABILITY.md), [core v1 release notes](./docs/
 
 AgentsKit is built in the open and ships because contributors show up. Every package, every doc, every example is fair game.
 
-- **[How to contribute →](https://www.agentskit.io/docs/contribute)** — start here
+- **[How to contribute →](https://www.agentskit.io/docs/reference/contribute)** — start here
 - **[Public roadmap board](https://github.com/orgs/AgentsKit-io/projects/1)** — what's planned, in flight, and shipped
 - **[Good-first-issues](https://github.com/AgentsKit-io/agentskit/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)** — curated, tractable tickets
 - **[Help-wanted](https://github.com/AgentsKit-io/agentskit/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)** — larger scoped work

apps/docs-next/README.md

@@ -43,27 +43,23 @@ See [CONTRIBUTING.md](../../CONTRIBUTING.md) and [LICENSE](../../LICENSE).
 
 Profile: <code>public-app</code>
 
-**Spike**: Fumadocs-based documentation site, evaluated as the replacement for the existing Docusaurus app at `apps/docs`.
-
-Tracked by [#238](https://github.com/AgentsKit-io/agentskit/issues/238) in the Phase 0 roadmap.
+Canonical Fumadocs-based documentation site for the AgentsKit package contracts,
+usage guides, recipes, integrations, and ecosystem hubs. The legacy Docusaurus
+app at `apps/docs` is being retired; keep new public documentation here.
 
 ## What's here
 
-A minimal but real Fumadocs site demonstrating:
+The app provides:
 
 - Next.js 16 app router with Fumadocs UI 16.x and Fumadocs MDX 14.x
-- Home page (`app/(home)/page.tsx`) with hero + 3-feature grid
+- Home, ecosystem, integrations, recipes, publications, and resources hubs
 - Docs shell (`app/docs/layout.tsx`) with Fumadocs sidebar and search
 - Catch-all docs page renderer (`app/docs/[[...slug]]/page.tsx`)
-- Search API (`app/api/search/route.ts`)
-- Real content: `index`, `getting-started/quickstart`, `getting-started/installation`, `concepts/mental-model`, plus 6 concept stub pages
+- Search API (`app/api/search/route.ts`) plus `llms.txt`, sitemap, canonical metadata, and JSON-LD
+- 400+ maintained MDX pages, including package guides, for-agents handoffs, recipes, and provider/integration references
 
 Tailwind v4 + `fumadocs-ui/css/preset.css` + neutral theme.
 
-## Why parallel to `apps/docs`
-
-Spike, not migration. The existing Docusaurus site keeps serving traffic at the current URL. Once this Fumadocs spike is approved, a follow-up PR migrates remaining content and the `apps/docs` directory is replaced.
-
 ## Run locally
 
 ```bash
@@ -79,30 +75,15 @@ pnpm --filter @agentskit/docs-next build
 pnpm --filter @agentskit/docs-next start
 ```
 
-## Decision criteria for migration
-
-Compare against `apps/docs` (Docusaurus):
-
-| Criteria | Docusaurus | Fumadocs (this) |
-| --- | --- | --- |
-| Tech stack | React + custom build | Next.js 16 + Tailwind v4 |
-| MDX rendering | OK | Excellent (server components, streaming) |
-| Visual polish out-of-box | Generic | Modern, opinionated |
-| Search | Algolia (paid for OSS via partner) | Built-in (Fumadocs `createFromSource`) |
-| Customization | CSS hacks | Tailwind + React, native |
-| Deploy target | Static (anywhere) | Vercel/Cloudflare Pages (Next.js-native) |
-| i18n | Mature plugin | DIY (acceptable trade) |
-| Build speed | Slow on big sites | Fast (Next.js + Turbopack) |
-| Node 25 compat | Currently broken on `main` | Works |
-
-## Next steps if approved
+## Maintainer checks
 
-1. Port remaining sections from `apps/docs` (adapters, agents, chat-uis, components, data-layer, examples, hooks, infrastructure, packages, theming, contributing)
-2. Decide i18n strategy (Crowdin? freeze pt-BR/es/zh-Hans until EN stabilizes?)
-3. Set up `docs.agentskit.io` deployment on Vercel
-4. Archive `apps/docs`
-5. Add chat-with-docs (RAG over the docs themselves) — dogfooding moment
+- `pnpm --filter @agentskit/docs-next lint:mdx` validates the MDX surface.
+- `pnpm --filter @agentskit/docs-next check:links` validates internal references.
+- `pnpm docs:build` runs the production build from the repository root.
+- Keep package READMEs, `/docs/reference/packages`, and `/docs/for-agents` aligned when an API changes.
 
 ## Status
 
-Not wired into root `pnpm dev` / `pnpm build` yet — install + run manually until the approach is approved. See PR description.
+The app is maintained as the canonical docs surface and is available through the
+root `pnpm docs` / `pnpm docs:build` scripts. Deployment remains an explicit
+release action; local documentation changes do not publish automatically.

apps/docs-next/app/(home)/page.tsx

@@ -17,7 +17,7 @@ import { alternatesFor } from '@/lib/locales'
 import softwareIdentity from '@/lib/software-identity.generated.json'
 
 export const metadata = {
-  title: `${agentsKitIdentity.name}.js — ${agentsKitIdentity.promise}`,
+  title: 'TypeScript AI agent framework',
   description: `${agentsKitIdentity.promise} A composable TypeScript foundation for runtime, tools, memory, RAG, and chat interfaces.`,
   alternates: {
     canonical: canonicalUrl('/'),
@@ -131,6 +131,16 @@ function Hero() {
           <p className="mt-6 max-w-xl border-l-2 border-ak-green pl-4 text-sm leading-relaxed text-ak-graphite">
             Built for {agentsKitIdentity.audience}
           </p>
+          <div className="mt-5 flex flex-wrap items-center gap-x-3 gap-y-2 font-mono text-[11px] uppercase tracking-[0.14em] text-ak-graphite/80">
+            <span>{agentsKitIdentity.role}</span>
+            <span aria-hidden="true">·</span>
+            <span>{agentsKitIdentity.maturity}</span>
+            {agentsKitIdentity.proof.length > 0 && (
+              <span className="w-full normal-case tracking-normal text-ak-graphite">
+                {agentsKitIdentity.proof.map((claim) => `${claim.value} ${claim.noun}`).join(' · ')}
+              </span>
+            )}
+          </div>
         </div>
 
         <div className="min-w-0">