Surface Documentation#

Start here when you are working on the Surface repo or building against @kontourai/surface.

The public docs site at https://kontourai.github.io/surface/ is built from these sources by docs-kit. This index includes both published pages and repo-only references for maintainers and contributors.

Folder Layout#

• product/ — product thesis, vocabulary, positioning, use cases, and what builds on Surface.
• guides/ — task-oriented walkthroughs for builders and consumers.
• reference/ — CLI, schemas, adapters, Console, extension API, analytics, examples, and versioning reference.
• architecture/ — current system architecture and foundation boundaries.
• specs/ — portable trust format and product capability specs.
• audits/ — point-in-time audits and migration maps.
• roadmap/ — forward-looking plans and integration direction.
• adr/ — durable architecture decisions.
• maintenance/ — release and contributor workflow docs.

Keep new docs in the folder that matches the reader's intent. If a page is a durable contract, prefer reference/ or specs/; if it records a point-in-time assessment, prefer audits/; if it is contributor workflow, prefer maintenance/.

Published Site Pages#

corpus.json at the repository root lists every published page, its navigation section, and the topics the Kontour docs MCP serves to agents. Every docs/**/*.md file must be either listed there or named in its exclude list; npm run docs:check fails otherwise, and also checks links, anchors, and topic headings. npm run docs:build renders the site into dist-pages/.

Repo-only material is named in exclude: brand language, the internal sales notes, the source module audit, and Claim Subject Matching while its API settles.

Product Model#

• Overview — public homepage source for the generated docs site
• The Problem in Plain Terms — plain-language explainer of the problem, the recomputable-trust solution, and why it's useful (newcomer entry point)
• Concepts — the trust model: claims, evidence traces, policies, Trust Snapshots, claim groups, status, and transparency gaps
• Use Cases — repo governance, public data trust, fact resolution, dependency audit
• Vision — product transparency thesis
• Principles — kernel and adapter rules
• Where Kontour Fits — Kontour's place in the trust/attestation landscape, with verified evidence, and the AI-evaluation wedge
• Brand Language — product language and positioning
• Selling Kontour — repo-only internal sales enablement (honest pitch, buyers, objection handles, guardrails); not published to the docs site

Building With Surface#

• Getting Started — install Surface, run an example report, and build a first producer
• Consumer SDK — fluent helpers for emitting valid TrustBundle
• Walkthrough — real session walkthrough with native Surface input
• Authoring a Product Profile — register product claim vocabulary without changing Surface trust semantics
• External Adapter Example — minimal package-shaped producer

Reference#

• CLI — surface report, surface claim, and output formats
• Claim Authoring — authored claim stores and surface claim write commands
• Extension API — producer branding, vocabulary, claim types, and policy templates
• Adapters — adapter registry and producer-owned input mapping
• Claim Subject Matching — matching incoming child rows to existing claim subjects by natural key, and disposing of orphaned claims (new, minimal, shape may evolve)
• Schemas — JSON contracts for adapter authors and downstream systems
• Waiver Validity — accepted-gap waiver validity projection: verdicts, precedence, residual, and Flow consumption paths
• Examples — examples used by tests and docs
• Schema Versioning — versioning rules for contract changes
• Trust Analytics Projection — evidence intelligence derived from TrustReport
• Answer Card Projection — compact report-only answer-card read model
• Basis Headless Projection — bounded answer evidence and owner-context projection
• Claim Basis View — the "how was this established" line after a claim's status, and its label tables
• Surface Console — local Console server over producer read models
• Agents and MCP — surface mcp trust-state tools over the Model Context Protocol
• Trust Panel Embed — the dependency-free surface-trust-panel web component

Architecture And Specs#

• Architecture — how the kernel, adapters, and product packages fit together
• Portfolio Layer Doctrine — the cross-product four-layer stack (open format → building-block tools → Surface → products) and its one-way dependency rule
• Developer Architecture — Surface trust/evidence flow and cross-product boundaries
• Surface Foundation Boundary — one-way dependency rule for product layers
• Derivation & Counterfactual Algorithms — the derivation ceiling, claim evaluation invariant, and counterfactual traversal, with the soundness argument for each
• Minimum Trust Panel Spec — Viewer-facing inspection requirements
• Minimum Surface Console Spec — Operator-facing workspace requirements
• Hachure Spec — product-neutral format specification: record shapes, status semantics, and executable conformance
• Open Trust Format and Claim Package Shape — portable trust state shape
• Disclosure Requirements — required claim, evidence, visibility, and gap disclosure
• Transparency Capabilities — producer-owned reverification, access, and dispute affordances
• Producer Extension Limits — customization boundaries that preserve core semantics
• Conformance — the derivation conformance suite for alternate implementations
• Built with Surface Badge — the inspectability signal and its usage requirements

Audits And Direction#

• Source Module Audit — public entrypoint, internal modules, and future split candidates
• Roadmap — what ships today and what comes next
• Adapters and the Producer Boundary — adapter and claim store patterns, boundary rules
• ADR 0001: Product Vocabulary Migration — target product language for Surface

Maintenance#

• Releasing — npm publish checklist and trusted publishing setup
• Repo Hooks — local contributor hook setup and validation
• Generated And Runtime Artifacts — what to edit, what is generated, and what stays local

Package Boundary#

The public npm package exposes @kontourai/surface, the headless @kontourai/surface/basis subpath, the browser-safe @kontourai/surface/display subpath (display names and the claim basis view), and the surface CLI. The root declarations are published through dist/src/index.d.ts; Basis has its own tree-shaken declaration entrypoint. Consumers should not import deep dist/ paths directly.

The package intentionally includes docs, schemas, examples, and built runtime files. It intentionally excludes source files, tests, scripts, generated docs site output, Playwright artifacts, and local workflow artifacts. npm run check:package-contents is the release guard for that boundary.