diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..8eddc39 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,20 @@ +name: CI + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + validate: + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + - run: npm test diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..adca44f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,20 @@ +# Changelog + +All notable changes to this Kickstart will be documented here. + +The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and releases use semantic versioning. + +## [Unreleased] + +### Added + +- Machine-readable Kickstart manifest and schema. +- Reusable Antfly Kickstart packaging standard. +- September 15 launch plan and release gates. +- Continuous integration for structural and benchmark validation. + +### Changed + +- Reframed the repository around the Doc Support customer outcome and Next.js golden path. +- Added explicit integration maturity definitions. diff --git a/README.md b/README.md index 248eb5d..7d2ce3b 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,103 @@ -# Antfly support-agent templates - -Customer-ready templates for building documentation and knowledge support agents powered by Antfly retrieval. - -The collection separates one portable support-agent contract from thin harness adapters. Customers can bring their own product documentation, Antfly table, model provider, branding, and support workflow without rewriting retrieval rules for every agent framework. - -## Why these templates are different - -These are production-oriented retrieval templates, not merely examples of how -to connect an MCP server to an agent: - -- Adaptive retrieval uses semantic-first search for conceptual questions and - hybrid BM25 plus vector RRF for exact technical questions. -- Answer quality and latency are evaluated together through bounded fallbacks, - warm-session reuse, evidence checks, benchmarks, and regression tests. -- Chunk-level evidence, clean generation context, and citation deduplication - keep answers grounded without discarding multiple useful chunks from a source. -- Read-only credentials, strict tool allowlists, bounded retries, and explicit - failure behavior provide safe defaults. -- One retrieval contract works across Next.js, Codex, Claude, OpenAI Agents, - Google ADK, Copilot, n8n, Hermes, and Pi. -- Operational metrics distinguish semantic-first and hybrid latency, fallback - rate, payload size, source quality, and citation accuracy. - -## Available harnesses - -- Knowledge Support — Next.js/Vercel product template -- Next.js and Vercel -- Claude Code -- Claude Agent SDK -- Hermes Agent -- Pi Agent Harness -- n8n -- Microsoft Copilot Studio -- Google ADK / Agents -- OpenAI Agents SDK -- Codex - -Every harness will also include a working `Antfly Docs Support` example backed by the Antfly documentation table. - -## Shared contract - -The [`shared`](shared) directory defines behavior that every integration must preserve: - -- grounded answers based on retrieved chunks -- one intent-selected query first, with at most one focused fallback -- semantic-first retrieval for broad concepts and hybrid BM25/vector RRF for exact terms -- read-only MCP access -- friendly citations instead of private object-storage paths -- deterministic escalation when evidence is insufficient -- common environment variables, evaluations, and failure handling - -See the [customer quickstart](docs/quickstart.md), [template architecture](docs/architecture.md), [internal harness comparison](docs/harness-comparison.md), and [validation gates](docs/validation.md). - -## Customer path - -1. Load documentation into an Antfly document-search table. -2. Verify extraction, chunking, full-text indexing, and vector indexing. -3. Create an instance-scoped, read-only API key. -4. Pick a harness template. -5. Copy its example environment file and set the Antfly endpoint, key, table, and index names. -6. Customize product identity, documentation links, and escalation contact. -7. Run the shared smoke tests and evaluation set before publishing. - -## Working Antfly Docs examples - -- The [Knowledge Support template](templates/knowledge-support/README.md) links the deployable [`antflydb/knowledge-support`](https://github.com/antflydb/knowledge-support) application with `@antfly/components` to provide the path from connected knowledge to hosted and embedded support. -- The [Next.js/Vercel reference](templates/nextjs/README.md) is a deployable application. -- The [n8n recipe](templates/n8n/README.md) captures the working visual workflow and its bounded system message. -- The [Copilot Studio recipe](templates/copilot/README.md) includes MCP setup, its 10/10 evaluation refinement, and Microsoft 365 publication. -- The [Google ADK template](templates/google-agents/README.md) connects Gemini-powered agents to Antfly MCP. -- The [OpenAI Agents SDK template](templates/openai-agents/README.md) provides a deployable Python agent with Streamable HTTP MCP. -- The [Codex template](templates/codex/README.md) provides project MCP configuration and durable `AGENTS.md` instructions. -- Claude Code, Claude Agent SDK, Hermes, and Pi reuse the same table and query contract; their local configuration or code checks are documented in the [validation matrix](docs/validation.md). - -The example values target `antfly_docs`, `document_vectors`, and the `text` chunk field. Customers replace those values without changing the safety or retrieval behavior. +# Antfly Doc Support Kickstart + +Build a grounded documentation support agent that customers can search, chat +with, customize, evaluate, and deploy. + +This Kickstart combines a production-oriented reference application with a +portable retrieval and answer contract. Connect your documentation to Antfly, +choose an integration path, replace the example branding, run the validation +suite, and deploy. + +> **Release status:** v1 launch candidate. The Next.js reference is the golden +> path. Integrations have explicit maturity labels in the +> [support matrix](templates/README.md); a listed integration is not necessarily +> live-verified. + +## What you get + +- grounded answers based on retrieved document chunks; +- public, friendly citations instead of private storage paths; +- adaptive semantic-first and hybrid retrieval; +- bounded fallbacks, retries, and failure behavior; +- read-only Antfly credentials and tool allowlists; +- a deployable Next.js support experience; +- portable evaluations and performance tests; +- integration paths for agent SDKs, coding agents, and workflow platforms. + +## Golden path + +Use the [Next.js/Vercel reference](templates/nextjs/README.md) when you want the +shortest path to a branded public or embedded documentation assistant. + +1. Prepare a document-search table in Antfly Cloud. +2. Create an instance-scoped, read-only API key. +3. Configure and run the Next.js reference application. +4. Replace the example identity, documentation links, and escalation contact. +5. Run the shared validation and product-specific evaluations. +6. Deploy and complete the live launch gates. + +Start with the [customer quickstart](docs/quickstart.md). Use the +[integration selection guide](docs/harness-comparison.md) only when the Next.js +golden path is not the right delivery surface. + +## How it works + +```text +Customer documentation + | + v +Antfly extraction, chunking, full-text and vector indexes + | + v +Read-only Antfly retrieval + | + v +Grounded answer, citations, feedback, and escalation + | + v +Next.js golden path or a supported integration adapter +``` + +The portable contract selects one semantic-first query for broad conceptual +questions or one hybrid BM25/vector query for exact technical questions. It +allows at most one focused sequential fallback when evidence is insufficient. + +## Validate the Kickstart + +```bash +npm install +npm test +``` + +`npm test` validates the manifest, shared contract, adapter structure, security +rules, links, and benchmark client behavior. Live retrieval and answer-quality +checks require a revocable test credential and are documented in +[validation and release gates](docs/validation.md). + +## Integration paths + +The Kickstart supports multiple delivery surfaces without changing its evidence +contract. See the [support matrix](templates/README.md) for Stable, Beta, and +Preview labels. Preview means the recipe is available; it does not mean the +integration has passed a current live smoke test. + +## Repository map + +| Path | Purpose | +| --- | --- | +| [`kickstart.json`](kickstart.json) | Machine-readable product, maturity, validation, and ownership contract | +| [`shared/`](shared) | Framework-neutral retrieval, safety, prompt, and evaluation assets | +| [`templates/`](templates) | Delivery-surface adapters and companion reference applications | +| [`docs/quickstart.md`](docs/quickstart.md) | Customer setup path | +| [`docs/validation.md`](docs/validation.md) | Automated and live release gates | +| [`docs/launch-plan.md`](docs/launch-plan.md) | September 15 execution plan and release checklist | +| [`docs/kickstart-standard.md`](docs/kickstart-standard.md) | Reusable standard for future Antfly Kickstarts | + +## Kickstart, not framework starter + +A Kickstart is an opinionated, testable path to a customer outcome. Framework +adapters are supporting material; they are not the product identity. Retrieval +quality should remain consistent whether Next.js, n8n, Copilot, Claude, OpenAI, +Gemini, or another runtime writes the final response. + +Licensed under [Apache-2.0](LICENSE). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..33e6b03 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,13 @@ +# Security + +Do not report vulnerabilities through a public issue. Contact +security@antfly.io with the affected component, reproduction details, and +impact. Do not include active credentials in the report. + +The Kickstart must use a dedicated, instance-scoped, read-only Antfly key for +retrieval. Generation credentials remain server-side and separate. The model +and browser must not receive Antfly management credentials. + +See [`shared/security/read-only-tools.json`](shared/security/read-only-tools.json) +and [`docs/validation.md`](docs/validation.md) for enforced boundaries and +release checks. diff --git a/docs/kickstart-standard.md b/docs/kickstart-standard.md new file mode 100644 index 0000000..c598e2e --- /dev/null +++ b/docs/kickstart-standard.md @@ -0,0 +1,79 @@ +# Antfly Kickstart standard + +This standard defines how Antfly packages an opinionated, testable path to a +customer outcome. It applies to Doc Support, Multimodal Search, Memory, +Campaign Agent, and future Kickstarts. + +## Product contract + +Every Kickstart must answer five questions above the fold: + +1. What customer outcome does it produce? +2. What can a customer run immediately? +3. What Antfly capabilities does it demonstrate? +4. What is the supported golden path? +5. How does a customer prove that it works? + +A Kickstart is not a framework matrix, SDK, product documentation collection, +or isolated code sample. Those can be included, but they support the outcome. + +## Required layers + +| Layer | Required content | +| --- | --- | +| Outcome | Concise promise, intended audience, demo, and explicit non-goals | +| Reference application | One runnable golden path covering the complete outcome | +| Domain kit | Schemas, prompts or policies, sample data, and executable evaluations | +| Integration paths | Optional delivery adapters with honest maturity labels | +| Operations | Deployment, observability, security, troubleshooting, and rollback guidance | + +## Required repository assets + +- `README.md` with the outcome and shortest working path; +- `kickstart.json` conforming to `kickstart.schema.json`; +- a runnable reference or an explicitly versioned companion reference; +- a deterministic sample configuration; +- domain-specific evaluation cases; +- `npm test` or an equivalent single validation command; +- continuous integration using that command; +- a support matrix with `stable`, `beta`, `preview`, or `planned` maturity; +- a launch checklist, changelog, license, and security-reporting path. + +## Maturity definitions + +- **Stable:** current automated checks and live end-to-end smoke tests pass; + documentation and rollback paths have been rehearsed. +- **Beta:** the implementation works end to end, but production operations or + compatibility coverage remain incomplete. +- **Preview:** code or a recipe exists and passes structural checks; live + verification is incomplete or stale. +- **Planned:** the intended interface is documented but is not launchable. + +Repository-wide release status and per-adapter maturity are separate. A stable +Kickstart may contain preview adapters as long as its golden path is stable and +the distinction is prominent. + +## Golden-path rule + +Each Kickstart has exactly one golden path for its initial stable release. The +golden path must be possible to evaluate from a clean checkout and must not +require customers to assemble multiple undocumented repositories. + +If the implementation lives in a companion repository, the manifest must say +so and pin a compatible release before the Kickstart is marked stable. + +## Validation evidence + +Validation must cover structure, behavior, live integration, and domain quality. +Passing structural validation alone cannot confer a Stable label. + +## Applying the standard to MemoryAF + +A Memory Kickstart would use persistent agent memory as its outcome, an API plus +dashboard as its reference application, and MCP/HTTP/agent adapters as delivery +paths. Its domain kit would define memory types, identity and visibility, +ephemeral lifecycle, deletion, recall quality, and isolation evaluations. + +This packaging standard is intentionally shared; Doc Support retrieval rules +are not. Future Kickstarts reuse release discipline without inheriting an +unrelated domain contract. diff --git a/docs/launch-plan.md b/docs/launch-plan.md new file mode 100644 index 0000000..d62ac92 --- /dev/null +++ b/docs/launch-plan.md @@ -0,0 +1,89 @@ +# Doc Support Kickstart launch plan + +Target: September 15, 2026. + +The launch goal is a credible v1 with one stable golden path, not equal maturity +across every adapter. + +## Scope + +### Required for v1 + +- Doc Support Kickstart naming and outcome-led onboarding; +- Next.js/Vercel golden path pinned to a compatible release; +- runnable Antfly Docs example and public demo; +- shared structural, security, retrieval, and benchmark validation in CI; +- live evaluation results for the golden path; +- stable support status only for adapters with current proof; +- release notes, support ownership, rollback steps, and a `v1.0.0` tag. + +### Allowed as Preview + +- Claude Code and Claude Agent SDK; +- OpenAI Agents SDK and Codex; +- Google ADK; +- Hermes and Pi; +- adapters whose configuration is validated but whose live test evidence is not current. + +### Out of scope for v1 + +- feature parity across all harnesses; +- automatic migration between harnesses; +- a generic Kickstart generator; +- production claims for unverified extension or agent runtimes. + +## Work plan + +| Window | Deliverable | Exit criterion | +| --- | --- | --- | +| Aug 28–Sep 1 | Product contract and repository packaging | Outcome, golden path, maturity model, manifest, and owners are explicit | +| Sep 2–5 | Golden path and customer onboarding | Clean checkout reaches a working sample; customization and deployment are documented | +| Sep 6–9 | Automated and live evaluation | CI is green; golden-path retrieval, citations, refusal, failure, and latency gates pass | +| Sep 10–12 | Release rehearsal | A person outside the implementation team completes setup; security and rollback are reviewed | +| Sep 13–14 | Release candidate | Documentation is frozen; demo, release notes, version pins, and launch assets are ready | +| Sep 15 | v1 release | Tag and release are published; demo and support monitoring are active | + +## Workstreams and owners + +Assign a directly responsible individual before release: + +| Workstream | Owner | Required evidence | +| --- | --- | --- | +| Product and positioning | TBD | Approved README, demo script, and scope | +| Golden-path engineering | TBD | Clean-checkout recording and deployed commit | +| Retrieval and answer quality | TBD | Versioned evaluation report | +| Security and credentials | TBD | Read-only key and tool-list review | +| Documentation and DX | TBD | Independent setup rehearsal | +| Release and operations | TBD | CI, tag, rollback, monitoring, and support rotation | + +## Launch gates + +- [ ] Repository is renamed or launch naming is approved. +- [ ] GitHub description, topics, homepage, and social preview are configured. +- [ ] Golden-path source and compatible release are unambiguous. +- [ ] `npm test` passes in CI from a clean checkout. +- [ ] Golden-path lint, typecheck, unit tests, and production build pass. +- [ ] Live smoke test passes with a dedicated, revocable read-only key. +- [ ] Portable and Antfly Docs evaluation cases meet recorded thresholds. +- [ ] Public citations resolve and private storage paths never appear. +- [ ] Unsupported, unrelated, write, and outage cases behave as specified. +- [ ] Cold and warm latency results are recorded from the deployment region. +- [ ] Stable/Beta/Preview labels match current evidence. +- [ ] No secret literals or privileged credentials are committed. +- [ ] Independent clean-room setup is completed. +- [ ] Demo, release notes, support contact, monitoring, and rollback are ready. +- [ ] `v1.0.0` is tagged from the exact deployed commit. + +## Release decision + +The release owner makes a go/no-go decision on September 14. Any failure in the +golden path, credential boundary, citations, CI, clean-room setup, or rollback +procedure is a no-go. A Preview adapter failure does not block launch when the +adapter is clearly labeled and omitted from stable claims. + +## Post-launch extraction + +After v1, create the reusable Kickstart starter from evidence gathered here. +Use MemoryAF as the second conformance case, then Multimodal Search and Campaign +Agent. Do not freeze a generic generator until at least two domain Kickstarts +have passed the standard independently. diff --git a/kickstart.json b/kickstart.json new file mode 100644 index 0000000..07fe7ba --- /dev/null +++ b/kickstart.json @@ -0,0 +1,37 @@ +{ + "$schema": "./kickstart.schema.json", + "schemaVersion": 1, + "id": "doc-support", + "name": "Antfly Doc Support Kickstart", + "version": "0.1.0", + "status": "release-candidate", + "owner": "Antfly", + "outcome": "Build, evaluate, and deploy a grounded documentation support agent powered by Antfly retrieval.", + "audience": ["developers", "solutions engineers", "customer support teams"], + "goldenPath": { + "name": "Next.js and Vercel", + "path": "templates/nextjs/README.md", + "kind": "companion-reference" + }, + "capabilities": ["document-ingestion", "hybrid-retrieval", "grounded-generation", "public-citations", "support-escalation"], + "interfaces": ["web", "http-api", "mcp", "agent-sdk", "workflow"], + "security": { + "credentialScope": "instance-scoped-read-only", + "toolPolicy": "shared/security/read-only-tools.json" + }, + "sample": { + "product": "Antfly Docs", + "configuration": "examples/antfly-docs/.env.example", + "evaluations": "shared/evals/antfly-docs.json" + }, + "validation": { + "install": "npm install", + "command": "npm test", + "releaseGates": "docs/validation.md" + }, + "release": { + "targetDate": "2026-09-15", + "plan": "docs/launch-plan.md", + "license": "Apache-2.0" + } +} diff --git a/kickstart.schema.json b/kickstart.schema.json new file mode 100644 index 0000000..6a9d9e3 --- /dev/null +++ b/kickstart.schema.json @@ -0,0 +1,51 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://antfly.io/schemas/kickstart.schema.json", + "title": "Antfly Kickstart manifest", + "type": "object", + "additionalProperties": false, + "required": ["schemaVersion", "id", "name", "version", "status", "owner", "outcome", "goldenPath", "capabilities", "interfaces", "security", "sample", "validation", "release"], + "properties": { + "$schema": { "type": "string" }, + "schemaVersion": { "const": 1 }, + "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, + "name": { "type": "string", "minLength": 1 }, + "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.-]+)?$" }, + "status": { "enum": ["experimental", "preview", "release-candidate", "stable", "deprecated"] }, + "owner": { "type": "string", "minLength": 1 }, + "outcome": { "type": "string", "minLength": 1 }, + "audience": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, + "goldenPath": { + "type": "object", + "additionalProperties": false, + "required": ["name", "path", "kind"], + "properties": { + "name": { "type": "string" }, + "path": { "type": "string" }, + "kind": { "enum": ["in-repository", "companion-reference"] } + } + }, + "capabilities": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, + "interfaces": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, + "security": { + "type": "object", + "required": ["credentialScope", "toolPolicy"], + "properties": { "credentialScope": { "type": "string" }, "toolPolicy": { "type": "string" } } + }, + "sample": { + "type": "object", + "required": ["product", "configuration", "evaluations"], + "properties": { "product": { "type": "string" }, "configuration": { "type": "string" }, "evaluations": { "type": "string" } } + }, + "validation": { + "type": "object", + "required": ["install", "command", "releaseGates"], + "properties": { "install": { "type": "string" }, "command": { "type": "string" }, "releaseGates": { "type": "string" } } + }, + "release": { + "type": "object", + "required": ["targetDate", "plan", "license"], + "properties": { "targetDate": { "type": "string", "format": "date" }, "plan": { "type": "string" }, "license": { "type": "string" } } + } + } +} diff --git a/package.json b/package.json index 0562655..6cb78df 100644 --- a/package.json +++ b/package.json @@ -6,6 +6,7 @@ "scripts": { "validate": "node scripts/validate-shared.mjs", "benchmark:mcp": "node scripts/benchmark-antfly-mcp.mjs", - "test:benchmark:mcp": "node --test scripts/benchmark-antfly-mcp.test.mjs" + "test:benchmark:mcp": "node --test scripts/benchmark-antfly-mcp.test.mjs", + "test": "npm run validate && npm run test:benchmark:mcp" } } diff --git a/scripts/validate-shared.mjs b/scripts/validate-shared.mjs index 52a7026..8438991 100644 --- a/scripts/validate-shared.mjs +++ b/scripts/validate-shared.mjs @@ -3,6 +3,8 @@ import { dirname, resolve } from "node:path"; const jsonFiles = [ "package.json", + "kickstart.json", + "kickstart.schema.json", "shared/retrieval/query-request.json", "shared/retrieval/semantic-query-request.json", "shared/security/read-only-tools.json", @@ -24,6 +26,40 @@ for (const file of jsonFiles) { JSON.parse(await readFile(file, "utf8")); } +const kickstart = JSON.parse(await readFile("kickstart.json", "utf8")); +if (kickstart.schemaVersion !== 1 || kickstart.id !== "doc-support") { + throw new Error("Kickstart manifest must identify the v1 Doc Support contract"); +} +if (kickstart.status === "stable") { + throw new Error("Kickstart cannot be stable before all live launch gates are recorded"); +} +if (kickstart.goldenPath?.kind !== "companion-reference") { + throw new Error("Current golden path must disclose that it is a companion reference"); +} +for (const path of [ + kickstart.goldenPath?.path, + kickstart.security?.toolPolicy, + kickstart.sample?.configuration, + kickstart.sample?.evaluations, + kickstart.validation?.releaseGates, + kickstart.release?.plan, +]) { + if (!path) throw new Error("Kickstart manifest contains an empty required path"); + await access(path); +} +if (kickstart.validation?.command !== "npm test") { + throw new Error("Kickstart must expose one canonical npm test command"); +} +for (const file of [ + ".github/workflows/ci.yml", + "CHANGELOG.md", + "SECURITY.md", + "docs/kickstart-standard.md", + "docs/launch-plan.md", +]) { + await access(file); +} + const prompt = await readFile("shared/prompts/support-agent.md", "utf8"); const queryTemplate = await readFile( "shared/retrieval/query-request.json", @@ -94,7 +130,10 @@ for (const writeTool of [ const harnesses = [ "claude-code", "claude-agent", + "codex", + "google-agents", "hermes", + "openai-agents", "pi", "n8n", "copilot", @@ -106,6 +145,13 @@ for (const harness of harnesses) { await access(`templates/${harness}/README.md`); } +const integrationIndex = await readFile("templates/README.md", "utf8"); +for (const maturity of ["Stable", "Beta", "Preview"]) { + if (!integrationIndex.includes(`**${maturity}:**`)) { + throw new Error(`Integration index must define ${maturity} maturity`); + } +} + await access("templates/claude-code/setup-mcp.sh"); await access("templates/codex/setup-mcp.sh"); diff --git a/templates/README.md b/templates/README.md index b02366e..ff8b7b0 100644 --- a/templates/README.md +++ b/templates/README.md @@ -1,4 +1,13 @@ -# Harness templates +# Integration paths + +These adapters deliver the Doc Support outcome through different runtimes. The +[Next.js/Vercel reference](nextjs/README.md) is the Kickstart's golden path. + +Maturity labels describe current evidence: + +- **Stable:** automated and current live end-to-end release gates pass. +- **Beta:** works end to end, with incomplete production or compatibility proof. +- **Preview:** implementation or recipe exists, but live verification is incomplete. Each harness directory must contain: @@ -12,15 +21,16 @@ Each harness directory must contain: Harnesses consume the shared contract rather than maintaining independent copies of the behavior rules. -| Harness | Template | Status | -| --- | --- | --- | -| Next.js / Vercel | [`nextjs/`](nextjs/) | Working standalone reference | -| Claude Code | [`claude-code/`](claude-code/) | Configuration validated; live approval/key required | -| Claude Agent SDK | [`claude-agent/`](claude-agent/) | Installed and syntax checked; live key required | -| Hermes | [`hermes/`](hermes/) | Configuration ready; Hermes runtime and live key required | -| Pi | [`pi/`](pi/) | Extension installed and type checked; Pi runtime and live key required | -| n8n | [`n8n/`](n8n/) | Recipe captured from validated deployment | -| Microsoft Copilot | [`copilot/`](copilot/) | Recipe captured from validated deployment and 10/10 evaluation | -| Google ADK / Agents | [`google-agents/`](google-agents/) | Reference Python agent with remote MCP configuration | -| OpenAI Agents SDK | [`openai-agents/`](openai-agents/) | Reference Python agent with remote MCP configuration | -| Codex | [`codex/`](codex/) | Project MCP configuration and support instructions | +| Integration | Adapter | Maturity | Current evidence | +| --- | --- | --- | --- | +| Next.js / Vercel | [`nextjs/`](nextjs/) | Beta | Working companion reference; must be release-pinned and re-run through live v1 gates | +| Knowledge Support | [`knowledge-support/`](knowledge-support/) | Preview | Product direction and companion implementation; ingestion/admin work is not yet the v1 golden path | +| n8n | [`n8n/`](n8n/) | Beta | Recipe captured from a validated deployment; requires current launch smoke test | +| Microsoft Copilot | [`copilot/`](copilot/) | Beta | Published recipe previously reached 10/10; requires current launch smoke test | +| Claude Code | [`claude-code/`](claude-code/) | Preview | Configuration validated; live approval and test key required | +| Claude Agent SDK | [`claude-agent/`](claude-agent/) | Preview | Installed and syntax checked; live credentials required | +| OpenAI Agents SDK | [`openai-agents/`](openai-agents/) | Preview | Reference Python agent; live credentials required | +| Codex | [`codex/`](codex/) | Preview | Project MCP configuration and instructions reviewed; live test required | +| Google ADK / Agents | [`google-agents/`](google-agents/) | Preview | Reference Python agent; live runtime test required | +| Hermes | [`hermes/`](hermes/) | Preview | Configuration ready; Hermes runtime and live key required | +| Pi | [`pi/`](pi/) | Preview | Extension type checked; Pi runtime and live key required |