Shared quality contract for AgentsKit documentation, metadata, examples, links, and visuals.

Documentation Standard v1

Status: stable — HITL-approved on 2026-07-13

Profile ID: documentation-standard-v1

Schema version: 1

Documentation Standard v1 is a deterministic Doc Bridge conformance profile for documentation properties in the AgentsKit ecosystem. It turns the shared quality expectations into local evidence that humans, CI, and agents can inspect without a model, API key, or network request.

flowchart LR
  A[Human docs] --> P[Documentation Standard v1]
  L[llms.txt and raw sources] --> P
  H[AgentHandoff index] --> P
  C[Contribution and metadata] --> P
  Q[Quickstart test evidence] --> P
  P --> R[Versioned conformance report]
  R --> CI[CI exit code]
  R --> HITL[Human approval]

Rule set

Rule	Level	Passing evidence
`human-docs`	Required	A configured human adapter discovers at least one non-agent document
`llms-and-raw-source`	Required	`llms.txt` exactly matches the current deterministic Doc Bridge output and every declared raw source is non-empty
`agent-handoffs`	Required	Every emitted handoff has `startHere`, edit roots, checks, and a linked/external human bridge
`contribution`	Required	At least one declared contribution guide exists and is non-empty
`metadata`	Required	Declared metadata files exist and contain every configured marker
`cross-links`	Required	Vendored canonical manifest/claims snapshots agree, include this product, and every declared URL is canonical and occurs in source
`tested-quickstarts`	Required	Each quickstart maps a doc to a test file, identifying test markers, and a CI command
`visual-explanations`	Recommended	Every declared image or animation asset exists
`structured-diagrams`	Recommended	Declared diagram source exists and contains its configured marker

Recommended failures remain visible but do not fail the command. Required failures return exit code 1 unless an approved exception applies.

Approved exceptions

Exceptions are explicit audit records, not hidden exclusions. A valid exception requires the rule ID, a substantive reason, the approver, and a tracking URL:

{
  "ruleId": "structured-diagrams",
  "reason": "The interactive visual already expresses this relationship more clearly.",
  "approvedBy": "Documentation Working Group",
  "trackingUrl": "https://github.com/AgentsKit-io/example/issues/123"
}

The report uses status excepted; it never rewrites an exception as an ordinary pass.

Configuration

{
  "conformance": {
    "documentationStandardV1": {
      "rawSources": ["README.md", "docs/getting-started.md"],
      "contributionPaths": ["CONTRIBUTING.md"],
      "metadata": [
        { "path": "docs/index.html", "contains": ["<title>", "name=\"description\""] }
      ],
      "links": [
        { "url": "https://www.agentskit.io", "paths": ["README.md"] }
      ],
      "ecosystemContract": {
        "manifest": "ecosystem.json",
        "claims": "ecosystem-claims.json",
        "productId": "example"
      },
      "quickstarts": [
        {
          "id": "demo",
          "doc": "README.md",
          "test": "tests/demo.test.ts",
          "command": "pnpm vitest run tests/demo.test.ts",
          "testContains": ["runs the demo"]
        }
      ],
      "visuals": ["docs/assets/overview.webp"],
      "diagrams": [
        { "path": "docs/architecture.md", "contains": ["```mermaid"] }
      ],
      "exceptions": []
    }
  }
}

The profile does not execute the declared quickstart command. The test-evidence file and identifying markers prove that the quickstart has a repository test; the normal CI suite executes that test. This avoids turning documentation configuration into an arbitrary command-execution surface.

The ecosystem contract files are committed, network-free consumer snapshots of the canonical AgentsKit ecosystem.json v2 manifest and ecosystem-claims.json ledger. The gate verifies their schema relationship, product identity parity, the adopting product ID, and that declared cross-links occur both in the manifest's public surfaces and in repository documentation. Doc Bridge also records the upstream ref and SHA-256 digests in ecosystem-upstream.json; pnpm check:ecosystem-upstream compares the local snapshots with AgentsKit main in CI. This network parity check is deliberately separate from the runtime conformance profile, which remains deterministic and offline.

Run the profile

ak-docs conformance run documentation-standard-v1 --text
ak-docs conformance run documentation-standard-v1 --json
ak-docs gate run documentation-standard-v1

JSON output is the stable automation surface. Text output sends the same evidence in a human-scannable form. Both return 0 when required rules pass or are explicitly excepted, and 1 when a required rule fails.

Adoption and stability

The Doc Bridge repository is the first real fixture and dogfoods the profile in its normal ak-docs gate run. Other ecosystem repositories adopt it in their documentation slices. The required/recommended rule split received product-owner HITL approval in issue #27, and the canonical ecosystem contract was delivered by AgentsKit #1208. The profile is stable; future breaking rule changes require a new version.