Reframe support templates as Doc Support Kickstart

.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

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.

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).

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.

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.