# HELM Documentation

Dedicated documentation for HELM AI Kernel, HELM AI Enterprise, trust, conformance, SDKs, and evidence verification.

Canonical host: https://helm.docs.mindburn.org
Access tier: public
Generated: 2026-06-04T00:45:59.430Z

---
title: "Architecture"
canonical: "https://helm.docs.mindburn.org/architecture"
source: "helm-ai-enterprise/docs/public/architecture-landing.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/architecture-landing.md"
section: "architecture"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-13"
checksum_sha256: "sha256:5765c34c3783591df7ca0a25532d642a1cb8d1357a8608a8e0d968b54707de95"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Architecture

This page answers the architecture authority question directly: HELM architecture claims must resolve to a source-owned architecture page, ADR, UCS v1.3 section, or implementation source. It is a navigation page for architects, operators, and contributors who need stable, source-backed links before making design, policy, or compliance changes.

This is the first stop for:

- finding the canonical source of architectural truth,
- separating platform conventions from implementation-specific notes,
- and avoiding accidental coupling between `docs` and non-canonical internal references.

## Audience

This page is intended for:

- Architects planning system-level changes
- Protocol and SDK engineers implementing against HELM primitives
- Release managers reviewing boundary changes
- Security and compliance reviewers assessing control-plane placement
- Product operators verifying documentation links used during onboarding and incident response

## Outcome

After reading this page, you should be able to:

- identify the authoritative architectural pages for HELM before editing or reviewing PRs,
- trace each architecture claim to a source page or decision record,
- determine whether a change belongs to Kernel documentation or HELM AI Enterprise documentation,
- find conformance references for implementation-level review,
- and use a consistent vocabulary from the canonical lexicon.

## Mermaid

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Kernel["Kernel Semantics"]
        OSS["OSS"]
        Standards["Unified Canonical Standards"]
        RepoMap["Repository Map"]
        Commercial["Commercial"]
        Control["Console & Control Plane Pages"]
        Conformance["Conformance Boundaries"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        ADRs["Architecture Decisions"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Proof["ProofGraph + Receipts"]
    end

    %% Operational Flow Edges
    Kernel --> Proof
    OSS --> Standards
    OSS --> RepoMap
    OSS --> ADRs
    Commercial --> Control
    Commercial --> Conformance
    Kernel --> Standards
    Standards --> Conformance
    Control --> Standards
    Standards --> ADRs
    Conformance --> ADRs

    %% Premium Styling Rules
    style Proof fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style ADRs fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
```


## Source Truth

- `docs/03_ARCHITECTURE.md`
- `docs/architecture/**`
- `docs/adrs/**`
- `docs/HELM_Unified_Canonical_Standard_v1.3.md`
- `docs/architecture/helm-ai-kernel-vs-commercial.md`

## What is documented as source-backed architecture

- [Architecture Overview](/architecture) — component map, responsibilities, and integration boundaries.
- Repository map source: `docs/04_REPO_MAP.md` — package boundaries, ownership, and module responsibilities.
- Unified platform source: `docs/architecture/UNIFIED_PLATFORM.md` — overall platform organization and design philosophy.
- HELM Genesis source: `docs/architecture/HELM_GENESIS.md` — bootstrap flow and first principles.
- Conformance L3 source: `docs/CONFORMANCE_L3.md` — high-integrity conformance expectations and evidence posture.
- Lexicon source: `docs/16_LEXICON.md` — canonical vocabulary for architecture and operations.

## HELM AI Kernel vs HELM AI Enterprise boundaries (explicit)

Use `docs/architecture/helm-ai-kernel-vs-commercial.md` and `docs/adrs/adr-001-commercial-boundary.md` as the normative boundary definitions. The practical working rule for this site is:

- OSS should be used for baseline kernel, standards, proof semantics, public reference, and reusable specification language.
- HELM AI Enterprise extends operational and product delivery layers (including hosted control-plane surfaces, product-led workflows, and enterprise deployment guidance) but should not redefine OSS semantics.
- If a page documents:
  - contract semantics, or
  - canonical schema-level behavior, or
  - conformance requirements,

  it belongs under OSS source truth unless an explicit Commercial ADR or boundary page overrides it.
- If a page documents pricing, hosted operational behavior, enterprise policy operations, or customer-facing deployment workflows, it belongs to HELM AI Enterprise routing unless OSS explicitly claims ownership.

## ADR map for architecture-facing reviews

- ADR index source: `docs/adrs/README.md` — ordered index for architecture decision context.
- ADR-001 source: `docs/adrs/adr-001-commercial-boundary.md` — baseline split between OSS and Commercial.
- Additional ADRs under `docs/adrs/` — use the index if a specific policy topic requires an ADR-level reference.

If a link is not yet live, treat that as a known gap and flag it in the owning workstream before changing claims.

## Troubleshooting

- If an architecture claim appears in code comments or PR descriptions but no matching source page exists, update first with an ADR or OSS canonical page and then rebase the docs route.
- If a page says "Commercial" but points to OSS-standardized semantics, verify whether the claim is a deployment detail or a canonical protocol claim; only the former can remain Commercial-only.
- If repository structure has changed and a canonical link is broken, update this page and the architecture route map together to keep the link graph consistent.
- If reviewers ask for proof, cite this page plus the owning source file in `docs/architecture/**` rather than internal discussion notes.
- If there is no public page for a newly introduced subsystem, either (a) add the source page through docs authoring first, or (b) classify it as source-only with rationale in the coverage ledger.

## Adoption guide

When adding or editing architecture content:

1. Update or confirm the owning source file under `docs/architecture/**` first.
2. Link the change to the relevant ADR if it affects boundaries, trust assumptions, or protocol interpretation.
3. Reflect the boundary decision in this landing page through the appropriate link entry and keep `oss-vs-commercial` synchronized.
4. Re-check this page for outdated links and align terminology with `docs/architecture/lexicon`.


---
title: "Backend & Protocols"
canonical: "https://helm.docs.mindburn.org/backend"
source: "helm-ai-enterprise/docs/public/backend-landing.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/backend-landing.md"
section: "backend"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-13"
checksum_sha256: "sha256:fb2013dc17cfece1a4f9c9ce631bc0a38d3e62fd33db53692b4233ad3754232f"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Backend & Protocols

This page gives the authoritative backend integration map: which APIs, schemas, and protocol pages exist, which are OSS-owned contracts, and which are HELM AI Enterprise operational extensions. It is the source-backed entrypoint for implementing clients, connectors, and audits that depend on backend contracts.

## Audience

- Protocol engineers implementing or consuming HELM API surfaces
- SDK authors and integrators building against the platform
- Compliance, security, and platform teams consuming Evidence and governance contracts
- Evaluators verifying conformance against public contract pages
- Operators validating backend behavior through versioned API and protocol documentation

## Outcome

After using this page, readers should be able to:

- route to the canonical API, schema, and protocol source pages before coding,
- distinguish OSS-standardized contracts from Commercial-hosted operational contract pages,
- understand where CLI, SDK, and adapter guidance lives,
- validate evidence and governance workflows using the correct backend references,
- and troubleshoot documentation or source-coverage mismatches when integrations fail.

## Mermaid

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        OpenAPI["OpenAPI Spec"]
        Contracts["Schemas and Protocols"]
        OSS["HELM AI Kernel Source Layers"]
        Commercial["HELM AI Enterprise Source Layers"]
        SDKs["SDKs"]
        Clients["Client Integrations"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Runtime["Kernel + Runtime Surfaces"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Evidence["EvidencePacks / Receipts"]
    end

    %% Operational Flow Edges
    OpenAPI --> Contracts
    Contracts --> Runtime
    Runtime --> Evidence
    OSS --> Runtime
    Commercial --> Runtime
    SDKs --> Clients
    Contracts --> SDKs

    %% Premium Styling Rules
    style Runtime fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Evidence fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Source Truth

This landing page is derived from:

- `api/**`
- `protocols/**`
- `schemas/**`
- `core/**`
- `sdk/**`
- `docs/public/reference/**`
- `docs/reference/**`

If a page is added or removed in these paths, update the destination links here first to keep the public route index accurate.

## API Surface and Reference

- [API Reference](/reference) — OpenAPI catalog and endpoint index for HELM backend services.
- CLI reference source: `docs/public/reference/cli-v3/format.md` — CLI operations model and command contracts.
- Schema reference source: `docs/12_SCHEMA_REFERENCE.md` — JSON schema and contract formats.
- API lifecycle source: `docs/api/API_LIFECYCLE.md` — versioning, deprecation, and migration policies.
- [SDK Reference](/reference/sdks) — TypeScript, Python, Go, and Rust SDK guidance.

## Protocol Specifications

- [Spec Overview](/backend) — map of all HELM protocol docs in one index.
- Evidence Merkle source: `docs/specs/protocols/EVIDENCE_MERKLE.md` — evidence tree and inclusion proof semantics.
- Governance spec source: `docs/specs/protocols/GOVERNANCE_SPEC.md` — governance protocol behavior and decision flow.
- Budget spec source: `docs/specs/protocols/BUDGET_SPEC.md` — budget enforcement and policy logic.
- Connector adapter source: `docs/specs/protocols/CONNECTOR_ADAPTER_SPEC.md` — connector design and adapter patterns.
- Contracts spec source: `docs/specs/protocols/CONTRACTS_SPEC.md` — canonical contract definitions and enforcement rules.
- Ingestion engine source: `docs/specs/protocols/INGESTION_ENGINE_SPEC.md` — ingestion process and transport expectations.
- Kernel integration source: `docs/specs/protocols/KERNEL_INTEGRATION.md` — integration patterns with kernel services.
- Registry spec source: `docs/specs/protocols/REGISTRY_SPEC.md` — registry, identity, and policy service model.
- Security spec source: `docs/specs/protocols/SECURITY_SPEC.md` — security enforcement points and threat-relevant expectations.
- Metering spec source: `docs/specs/protocols/METERING_SPEC.md` — usage and metering behavior.

## Core Internals and Verification

- VPL source: `docs/specs/runtime/VPL_SPEC.md` — Verification Pipeline Language contract model.
- Pack ABI source: `docs/specs/packs/PACK_ABI.md` — Evidence pack binary interface and interoperability constraints.
- Kernel TCB source: `docs/public/security-and-trust/tcb-policy.md` — trusted computing base and runtime security assumptions.
- Product contract source: `docs/specs/product/PRODUCT_CONTRACT.md` — higher-level product contract abstractions.

## Integration Guides

- [LangChain](/integrations/langchain) — connector behavior and runtime expectations.
- [OpenAI BaseURL](/integrations/openai-baseurl) — proxy and interoperability reference.
- [MCP](/integrations/mcp) — Model Context Protocol integration surfaces.

## Kernel vs HELM AI Enterprise boundaries (explicit)

- OSS pages define canonical protocol and interface documents and should be treated as baseline truth for contract meaning.
- HELM AI Enterprise pages are where operational packaging, tenant-specific controls, enterprise-grade deployment policies, and commercial support pathways are documented.
- If a protocol claim affects data integrity, contract semantics, or interoperability, keep it on an OSS-owned source unless a specific Commercial ADR relocates that behavior.
- If a page describes contractual terms, paid operational guarantees, or enterprise deployment behavior that does not alter protocol semantics, route it to Commercial documentation with a pointer back to the OSS contract source.

## Troubleshooting

- If a client implementation breaks after an API version bump, first verify route and version docs in `docs/api/API_LIFECYCLE.md` before patching generated SDKs.
- If an integration cannot find a schema, check whether it is in `schemas/**` but not yet linked by `docs/public/reference/specs-research-and-source-families.md`, then add the missing source mapping.
- If a page claims to be source truth but does not describe runtime behavior, confirm whether it is only a migration artifact (source-only) and mark it as such in source coverage.
- If endpoint behavior differs from docs, align with the matching source path under `api/**` and request a docs update on the owning PR.
- If conformance questions appear, cross-check `api`, `protocols`, and `core` pages against conformance expectations in architecture references before changing backend behavior.

## Adoption and change checklist

1. Identify the affected source path (`api`, `protocols`, `schemas`, or `sdk`).
2. Verify the canonical route in this page or add a new source route when first introducing the item.
3. Confirm boundary: if behavior is protocol-level, keep it on OSS pages; if it is enterprise policy packaging, keep it under Commercial-owned pages.
4. Update this landing page only when the public route graph changes.


---
title: "HELM Changelog"
canonical: "https://helm.docs.mindburn.org/changelog"
source: "helm-ai-enterprise/CHANGELOG.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/CHANGELOG.md"
section: "changelog"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:eeffde2bf69e89e91e5f6a8aed0c00dbc565ea901193de041dd54718390825a1"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Changelog

## Audience

This changelog is for developers, operators, security reviewers, and evaluators tracking public HELM product, Console, Teams, Enterprise, and reference changes across releases.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `changelog`
- Source document: `helm-ai-enterprise/CHANGELOG.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

All notable changes to the HELM AI Enterprise/control-plane surface are documented in this file. HELM AI Kernel release notes are surfaced here as a pointer because the HELM
docs site also hosts the OSS pages under `/helm-ai-kernel/*`.

## HELM AI Kernel v0.4.0 — 2026-04-25

Latest public Kernel release:
<https://github.com/Mindburn-Labs/helm-ai-kernel/releases/tag/v0.4.0>.

Use [/helm-ai-kernel/changelog](/helm-ai-kernel/changelog) for the full Kernel release notes.
The `v0.4.0` GitHub release published platform binaries for Darwin, Linux, and
Windows, `SHA256SUMS.txt`, `sbom.json`, `release-attestation.json`,
`evidence-pack.tar`, `release.high_risk.v3.toml`, `helm-ai-enterprise.mcpb`, and `helm-ai-enterprise.rb`.

The tag is `v0.4.0`; no public major-version HELM AI Kernel GitHub release was found
in the 2026-05-05 release audit.

## [3.0.0] — 2026-02-21

### Added

- **`@mindburn/helm-ai-enterprise` CLI v3** — `npx @mindburn/helm-ai-enterprise` for one-command verification with progressive disclosure, cryptographic proof (Ed25519 + real Merkle tree), and HTML evidence reports.
- **v3 bundle format spec** (`docs/cli_v3/FORMAT.md`) — canonicalization rules, Merkle tree construction, attestation schema.
- **Key rotation policy** (`docs/cli_v3/KEYS.md`).
- **Release pipeline** — evidence bundle build job with Ed25519 attestation signing in `release.yml`.
- **Verification guide** (`docs/verify.md`).

### Security

- **Removed `.env.release`** containing plaintext tokens from repo and git history.
- **Purged 376MB of compiled binaries** from `artifacts/` tracked in git history via `git filter-repo`.
- **Hardened `.gitignore`** — secrets hard lock (`.env*`, `*.key`, `*.pem`), `artifacts/` blanket ignore.
- Removed committed encrypted cookie from `core/pkg/console/.auth/`.

### Removed

- `cli/` directory (v2, superseded by `packages/mindburn-helm-ai-enterprise-cli/`).
- Internal planning docs: `OSS_CUTLINE.md`, `UNKNOWNs.md`, TITAN docs, investment memo.
- Dead redirect stubs for `HELM_Unified_Canonical_Standard.md`.


## [0.1.1] — 2026-02-19

### Fixed

- Resolved `MockSigner` build failure in `core/pkg/guardian` by implementing missing `PublicKeyBytes`.
- Fixed redundant signature assignment in `Ed25519Signer.SignDecision`.
- Standardized `ImmunityVerifier` hashing logic and cleaned up misleading test comments.
- Corrected version display in `helm-ai-enterprise` CLI help output.

### Improved

- Increased `governance` package test coverage from 60.8% to 79.5%.
- Added comprehensive unit tests for `LifecycleManager`, `PolicyEngine`, `EvolutionGovernance`, `SignalController`, and `StateEstimator`.

## [0.1.0] — 2026-02-15

### Added

- **Proxy sidecar** (`helm-ai-kernel proxy`) — OpenAI-compatible reverse proxy. One line changed, every tool call gets a receipt.
- **SafeExecutor** — single execution boundary with schema validation, hash binding, and signed receipts.
- **Guardian** — policy engine with configurable tool allowlists and deny-by-default.
- **ProofGraph DAG** — signed nodes (INTENT, ATTESTATION, EFFECT, TRUST_EVENT, CHECKPOINT) with Lamport clocks and causal `PrevHash` chains.
- **Trust Registry** — event-sourced key lifecycle (add/revoke/rotate), replayable at any height.
- **WASI Sandbox** — deny-by-default (no FS, no net) with gas/time/memory budgets and deterministic trap codes.
- **Approval Ceremonies** — timelock + deliberate confirmation + challenge/response, suitable for disputes.
- **EvidencePack Export** — deterministic `.tar.gz` with sorted paths, epoch mtime, root uid/gid.
- **Replay Verify** — offline session replay with full signature and schema re-validation.
- **CLI** — 11 commands: `proxy`, `export`, `verify`, `replay`, `conform`, `doctor`, `init`, `trust add/revoke`, `version`, `serve`.
- **SDK Stubs** — TypeScript and Python client libraries.
- **Regional Profiles** — US, EU, RU, CN with Island Mode for network partitions.
- **12 executable use cases** with scripted validation.
- **Conformance gates** — L1 (kernel invariants) and L2 (profile-specific).

### Security

- Fail-closed execution: undeclared tools are blocked, schema drift is a hard error.
- Ed25519 signatures on all decisions, intents, and receipts.
- ArgsHash (PEP boundary) cryptographically bound into signed receipt chain.
- 8-package TCB with forbidden-import linter.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Changelog"]
        s0["HELM AI Kernel v0.4.0 — 2026-04-25"]
        s1["[3.0.0] — 2026-02-21"]
        s2["[0.1.1] — 2026-02-19"]
        s3["[0.1.0] — 2026-02-15"]
        output["Reader outcome"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> s3
    s3 --> output

    %% Premium Styling Rules
```


---
title: "Authority Boundary"
canonical: "https://helm.docs.mindburn.org/company-ai-os/authority-boundary"
source: "docs-platform/content/docs/company-ai-os/authority-boundary.md"
edit: "https://github.com/Mindburn-Labs/docs-platform/edit/main/content/docs/company-ai-os/authority-boundary.md"
section: "company-ai-os"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-17"
checksum_sha256: "sha256:7f65069cd3639fd18978d59df2c2031add7e9cff0868d835fc391e96daf5ebd2"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Authority Boundary

The Company AI OS story is only safe when the authority boundary stays explicit.

Models, retrieval systems, company graphs, and generated drafts can propose work. HELM decides whether a real side effect may cross the boundary.

## Boundary rule

No consequential side effect should become real unless HELM can evaluate the request, enforce the policy boundary, and preserve proof.

In public copy, the boundary should name the mechanism:

- CPI checks plan shape, policy, actor, tenant, approval, and other required context before the proposal continues.
- PEP gates the side-effect boundary before connectors, production systems, payments, customer messages, access changes, or physical actions run.
- Receipts record the verdict and bind it to reviewable proof.

## What is not authority

The following can help plan or explain work, but they should not be described as execution authority:

- A model answer.
- A valid-looking JSON payload.
- A CompanyArtifactGraph query result.
- An OrgGenome Compiler draft.
- A ticket, meeting note, or customer promise by itself.
- A diagram or Atlas view.

## Verdict posture

Use the current public verdict terms:

- `ALLOW`: HELM permits the action to run.
- `DENY`: HELM blocks the action.
- `ESCALATE`: HELM stops and asks for more facts, policy, or human approval.

Do not use old or softer verdict language on new public pages.

## Diagram

```mermaid
flowchart TD
    subgraph Proposals["1. Proposal Generation (Stochastic)"]
        Model["Model Tool Call Proposal"]
        Tickets["Ticket / External Intent Trigger"]
        Model & Tickets --> Normalize["Parse & Normalize Arguments"]
    end

    subgraph Interceptors["2. Interceptor Evaluation Plane"]
        Normalize --> Temporal["TemporalInterceptor: Check Time Bounds"]
        Temporal --> Freeze["FreezeInterceptor: Inspect Kill Switch"]
        Freeze --> ZeroID["ZeroIDInterceptor: Verify Identity Claims"]
        ZeroID --> PDP{"PDP Evaluation: Cedar / OPA / CEL"}
    end

    subgraph Decision["3. Verdict Resolution & Execution"]
        PDP -->|ALLOW| Sandbox["Allocate Warm Sandbox Lease"]
        PDP -->|DENY| Block["DENY: Fail-Closed Enforced"]
        PDP -->|ESCALATE| Ceremony["ESCALATE: Operator Signing Ceremony"]

        Sandbox --> Dispatch["Dispatch Tool Call in Containment"]
        Ceremony -->|Approved| Sandbox
        Ceremony -->|Rejected| Block
    end

    subgraph Proof["4. Cryptographic Proof & Ledger"]
        Dispatch --> Rec1["Generate signed ALLOW Receipt"]
        Block --> Rec2["Generate signed DENY Receipt"]
        
        Rec1 & Rec2 --> JCS["RFC 8785 JCS Canonicalization"]
        JCS --> ProofGraph["Append to Merkle ProofGraph DAG"]
        ProofGraph --> EvidencePack["Compile Offline EvidencePack Bundle"]
    end

    style PDP fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Sandbox fill:#38a169,stroke:#276749,stroke-width:2px,color:#fff
    style Block fill:#e53e3e,stroke:#9b2c2c,stroke-width:2px,color:#fff
    style Ceremony fill:#dd6b20,stroke:#9c4221,stroke-width:2px,color:#fff
```

## Source truth

- Kernel verdict semantics, receipt headers, ProofGraph routes, replay verification, and conformance vectors: `helm-ai-kernel/README.md`, `helm-ai-kernel/api/openapi/`, `helm-ai-kernel/sdk/ts/src/client.ts`, `helm-ai-kernel/protocols/conformance/v1/test-vectors.json`, and `helm-ai-kernel/tests/conformance/`.
- Enterprise API tags and route surfaces for ProofGraph, EvidencePack, Company Artifact Graph, GeneratedSpec, and connectors: `helm-ai-enterprise/api/openapi/helm.openapi.yaml` and `helm-ai-enterprise/apps/console/src/router/routes.tsx`.
- Enterprise design-system route blueprints for approvals, actions, receipts, evidence, replay, audit, and connectors: `helm-ai-enterprise/packages/helm-ai-enterprise-design-system/src/routes/blueprints.ts`.

## Review checklist

Before publishing a Company AI OS explanation, check that it answers:

- What proposed side effect is being discussed?
- Which boundary evaluates it before dispatch?
- What proof remains after ALLOW, DENY, or ESCALATE?
- Which claims are current product behavior and which are reviewed-access Enterprise direction?


---
title: "CompanyArtifactGraph"
canonical: "https://helm.docs.mindburn.org/company-ai-os/company-artifact-graph"
source: "docs-platform/content/docs/company-ai-os/company-artifact-graph.md"
edit: "https://github.com/Mindburn-Labs/docs-platform/edit/main/content/docs/company-ai-os/company-artifact-graph.md"
section: "company-ai-os"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-17"
checksum_sha256: "sha256:baaa7f697f7613c18558a5b6da855b2f5ef52e13351f0f23331b490e1f9873af"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# CompanyArtifactGraph

CompanyArtifactGraph is the explanatory name for source-backed company memory in the HELM AI Enterprise direction.

It can organize artifacts such as:

- policies and operating rules
- tickets and project records
- pull requests and release notes
- customer commitments and support records
- approvals, receipts, and proof references
- incident records and follow-up work

## What it is for

CompanyArtifactGraph helps the company become queryable and reconcilable. It lets an operator ask what changed, which source supports a claim, where a promise conflicts with shipped behavior, and which proof record belongs to a decision.

It also contributes to Harness State: the operator-facing view of transactional autonomous-work context, including read sets, write sets, assumptions, stale dependencies, verification scope, approvals, and proof references. Harness State is a review and reconciliation surface. It is not execution authority.

## What it is not for

CompanyArtifactGraph is not the side-effect gate.

A graph result can inform a proposal or review path, but real execution still needs HELM checks. Treating graph memory as authority would collapse the separation between knowledge and action.

## Safe public wording

Use wording like:

- "CompanyArtifactGraph organizes source-backed context."
- "CompanyArtifactGraph helps identify drift and truth conflicts."
- "CompanyArtifactGraph can point to receipts and evidence."

Avoid wording like:

- "CompanyArtifactGraph authorizes actions."
- "The graph decides what to execute."
- "Memory makes the company autonomous."

## Relationship to proof

Receipts, ProofGraph records, and EvidencePacks can be referenced from company-context surfaces. That does not mean raw company data should be published or treated as proof by itself.

The safe distinction is:

- Context explains why a proposal exists.
- HELM evaluates whether it may run.
- Proof records what happened.

Harness State follows the same boundary:

- CompanyArtifactGraph can show `reads_from`, `writes_to`, `assumes`, `invalidates`, `blocked_by_policy`, and `proven_by_receipt` edges.
- GeneratedSpecs can carry read/write sets, assumptions, stale dependency references, rollback policy, human review state, and verification scope.
- PEP/CPI still decide whether side effects may dispatch.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Ingestion"]
        Policies["Company Policies & Standard Operating Procedures"]
        Tickets["Jira / GitHub Issues & Task Records"]
        PRs["Pull Requests, Diff Logs, and Release Notes"]
        Commitments["Customer Promises & Support Agreements"]
        
        Policies & Tickets & PRs & Commitments --> CAG["CompanyArtifactGraph Compiler"]
    end

    subgraph Memory["2. Semantic Graph Plane"]
        CAG --> GraphDb["Active Artifact Relationship Graph"]
        
        subgraph Edges["Semantic Relationship Mappings"]
            direction LR
            E1["reads_from"]
            E2["writes_to"]
            E3["assumes"]
            E4["invalidates"]
            E5["blocked_by_policy"]
            E6["proven_by_receipt"]
        end
        GraphDb --> Edges
    end

    subgraph Context["3. Harness State Operational Context"]
        Edges --> Harness["Harness State Context Manager"]
        
        Harness --> ReadSet["Read Sets & Stale Dependency Checks"]
        Harness --> WriteSet["Write Sets & Mutation Boundaries"]
        Harness --> Assumptions["Active Reasoning Assumptions"]
        
        ReadSet & WriteSet & Assumptions --> Spec["GeneratedSpec (Reviewed Action Plan)"]
    end

    subgraph Gate["4. Deterministic Enforcement Gate"]
        Spec --> CPI["CPI Plan Integrity Verification"]
        CPI --> PEP{"HELM PEP Decision Engine"}
        
        PEP -->|ALLOW| Exec["Execution & Proof receipt committed"]
        PEP -->|DENY / ESCALATE| Block["Execution blocked or paused"]
    end

    style GraphDb fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style PEP fill:#e53e3e,stroke:#9b2c2c,stroke-width:2px,color:#fff
    style Spec fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
```

## Source truth

- Enterprise Company AI OS and CompanyArtifactGraph framing: `helm-ai-enterprise/README.md`.
- Enterprise API source family for Company Artifact Graph, should-vs-is detection, GeneratedSpec, ProofGraph, EvidencePack, and connector governance: `helm-ai-enterprise/api/openapi/helm.openapi.yaml`.
- Enterprise Console route and product-surface evidence for proof, receipts, connectors, and replay: `helm-ai-enterprise/apps/console/src/router/routes.tsx` and `helm-ai-enterprise/packages/helm-ai-enterprise-design-system/src/routes/blueprints.ts`.
- Kernel proof and receipt boundary that remains authoritative for execution: `helm-ai-kernel/README.md`, `helm-ai-kernel/api/openapi/`, and `helm-ai-kernel/sdk/ts/src/client.ts`.


---
title: "Connector Drift"
canonical: "https://helm.docs.mindburn.org/company-ai-os/connector-drift"
source: "docs-platform/content/docs/company-ai-os/connector-drift.md"
edit: "https://github.com/Mindburn-Labs/docs-platform/edit/main/content/docs/company-ai-os/connector-drift.md"
section: "company-ai-os"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-17"
checksum_sha256: "sha256:14f0a4169e30ca82c79e427eb399b7d6ffb681480d68cd5fac93a43c734dd970"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Connector Drift

Connectors are where HELM-governed plans touch real systems. They deserve stricter language than generic integration copy because external APIs, permissions, schemas, and operational behavior can drift.

## What drift means

Connector drift is a mismatch between the connector contract HELM expects and the connector behavior available at execution time.

Examples include:

- an upstream API changes a required field
- a permission scope no longer matches the intended action
- a tool starts returning a new error shape
- a vendor changes rate limits or side-effect semantics
- a physical or analog route becomes unavailable

## Safe behavior

When connector verification cannot complete, public copy should say HELM blocks or escalates. It should not imply the agent improvises around the mismatch.

## Certification posture

Connector certification should be described as bounded and specific:

- what action family the connector supports
- what scopes or sandbox grants are allowed
- what policy checks apply before dispatch
- what proof is recorded after the attempt
- how drift is detected, denied, or escalated

## Physical and analog effects

Physical-world effects raise the standard. Shipping goods, moving money, dispatching people, operating devices, or triggering robots can be harder to roll back than software state.

Use stronger language for these paths:

- narrower action contracts
- explicit approval where needed
- route and drift checks
- receipt-backed proof after the decision

## Diagram

```mermaid
flowchart TD
    subgraph Contract["1. Schema & Capability Verification"]
        Plan["Checked Action Plan"] --> TargetCheck["Identify Upstream Connector Target"]
        TargetCheck --> SchemaCheck["Fetch Signed Connector Schema & Scopes"]
        SchemaCheck --> LiveInspect["Query Active Interface State"]
    end

    subgraph DriftCheck["2. Drift Evaluation Plane"]
        LiveInspect --> Validate{"Schema or Scope Mismatch?"}
        
        Validate -->|API Changes / Perm Revocation / Limit Shift| Drift["Drift Detected"]
        Validate -->|Perfect Parity| Sterile["No Drift Detected"]
    end

    subgraph Execution["3. Verdict Gate & Sandbox Containment"]
        Drift --> Halt["DENY / ESCALATE: ERR_CONNECTOR_CONTRACT_DRIFT"]
        Halt --> SafeStop["Halt Execution Thread safely (Zero Side Effects)"]
        SafeStop --> OpsAlert["Emit Out-of-band Operator Patching Alert"]

        Sterile --> Sandbox["Allocate Sandbox with lease restrictions"]
        Sandbox --> EgressCheck{"Egress Firewall (Taint-Tracking)"}
        EgressCheck -->|Clean context| Dispatch["Bounded Side-Effect Dispatch"]
        EgressCheck -->|Tainted context / Unknown dest| EgressDeny["DENY: TAINTED_DATA_EGRESS_DENY"]
    end

    subgraph Proof["4. Audit Receipt Generation"]
        Dispatch --> Signed1["Signed ALLOW Receipt (Successful call)"]
        EgressDeny --> Signed2["Signed DENY Receipt (Firewall Block)"]
        OpsAlert --> Signed3["Signed ESCALATE Receipt (Pending Manual Fix)"]

        Signed1 & Signed2 & Signed3 --> ProofGraph["Append to ProofGraph DAG Ledger"]
    end

    style Validate fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style SafeStop fill:#e53e3e,stroke:#9b2c2c,stroke-width:2px,color:#fff
    style Dispatch fill:#38a169,stroke:#276749,stroke-width:2px,color:#fff
    style EgressCheck fill:#dd6b20,stroke:#9c4221,stroke-width:2px,color:#fff
```

## Source truth

- Kernel connector/tool-call boundary, receipts, conformance vectors, and fail-closed verdict terms: `helm-ai-kernel/README.md`, `helm-ai-kernel/api/openapi/`, `helm-ai-kernel/sdk/ts/src/client.ts`, and `helm-ai-kernel/protocols/conformance/v1/test-vectors.json`.
- Enterprise connector governance API tag, connector route surfaces, and commercial connector lifecycle management: `helm-ai-enterprise/api/openapi/helm.openapi.yaml`, `helm-ai-enterprise/apps/console/src/router/routes.tsx`, and `helm-ai-enterprise/commercial/csr/`.
- Enterprise connector UI and drift surface references: `helm-ai-enterprise/packages/helm-ai-enterprise-design-system/src/routes/blueprints.ts` and `helm-ai-enterprise/packages/helm-ai-enterprise-design-system/src/agent-ui/component-registry.ts`.


---
title: "OrgGenome Compiler"
canonical: "https://helm.docs.mindburn.org/company-ai-os/orggenome-compiler"
source: "docs-platform/content/docs/company-ai-os/orggenome-compiler.md"
edit: "https://github.com/Mindburn-Labs/docs-platform/edit/main/content/docs/company-ai-os/orggenome-compiler.md"
section: "company-ai-os"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-17"
checksum_sha256: "sha256:27b52a4218f1e1834533f69b4b43b34d25922acba026474a9f947a791d880891"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# OrgGenome Compiler

OrgGenome Compiler is the HELM AI Enterprise direction for turning messy company material into reviewable operating rules.

The important public boundary is that compiler output starts as draft material. It does not become executable organizational law until reviewed, signed, and promoted into the appropriate HELM-governed path.

## Inputs

Compiler input can include:

- policies and procedure documents
- interviews and operating examples
- connector manifests and tool constraints
- approval patterns and role boundaries
- existing receipts and proof records

## Outputs

Compiler output can include draft rules, process graphs, GeneratedSpecs, and activation candidates. These outputs are useful because they make implicit company behavior easier to inspect.

They are still not permission to act.

## Promotion boundary

A safe promotion path should preserve these distinctions:

| State | Meaning |
| --- | --- |
| Raw input | Source material such as docs, interviews, examples, and artifacts. |
| Draft output | Compiler-generated proposal for rules or process shape. |
| Reviewed rule | Human and policy-reviewed material suitable for activation. |
| Governed action | A proposed side effect that still passes through HELM before dispatch. |

## Public copy rule

Do not describe OrgGenome Compiler as an autonomous replacement for company governance. Describe it as a way to draft, inspect, review, and promote rule-bearing company material into HELM-governed execution.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion Plane (Messy Source)"]
        Policies["Raw Policies & Standard Procedures"]
        Interviews["Operator Interviews & SOP Examples"]
        Manifests["Connector Manifests & Tool Specifications"]
        
        Policies & Interviews & Manifests --> Compiler["OrgGenome Ingestion Engine"]
    end

    subgraph Compilation["2. OrgGenome Compiler Phase"]
        Compiler --> Engine["VLLM Fine-Tuning & Prompt Contextualization"]
        Engine --> DraftSpecs["GeneratedSpecs: Draft Execution Rules"]
        Engine --> ProcessGraphs["Process Graphs: Logic Relationship Models"]
        Engine --> Candidates["Activation Candidate Profiles"]
    end

    subgraph Promotion["3. Governance & Promotion Boundary"]
        DraftSpecs & ProcessGraphs & Candidates --> SandboxVal["Automated Rule Validation & Conformance Testing"]
        SandboxVal --> Review{"Multi-Party Human Signing Ceremony"}
        
        Review -->|Approved & Signed| Promoted["Promoted Active Rule Set"]
        Review -->|Rejected| Redraft["Flag Conflicts & Request Redraft"]
        Redraft --> Engine
    end

    subgraph Enforcement["4. Active Execution Plane"]
        Promoted --> RulesDb["Active PEP/CPI Rules Store"]
        RulesDb --> HELM["HELM AI Kernel (PEP/CPI Boundary)"]
        HELM --> Enforced["Deterministic Enforcement of Stochastic Proposals"]
    end

    style Review fill:#dd6b20,stroke:#9c4221,stroke-width:2px,color:#fff
    style Promoted fill:#38a169,stroke:#276749,stroke-width:2px,color:#fff
    style RulesDb fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
```

## Source truth

- OrgGenome Compiler product boundary, infrastructure, dataset/schema registry, and training/evaluation/serving docs: `orggenome-compiler/README.md`, `orggenome-compiler/docs/README.md`, `orggenome-compiler/datasets/README.md`, and `orggenome-compiler/datasets/schemas/`.
- Enterprise Company AI OS and OrgGenome integration framing: `helm-ai-enterprise/README.md` and `helm-ai-enterprise/commercial/pipeline/`.
- Enterprise GeneratedSpec and activation-related public API surface: `helm-ai-enterprise/api/openapi/helm.openapi.yaml`.
- Kernel execution boundary that still governs promoted action proposals: `helm-ai-kernel/README.md` and `helm-ai-kernel/protocols/conformance/v1/test-vectors.json`.


---
title: "Company AI OS Overview"
canonical: "https://helm.docs.mindburn.org/company-ai-os/overview"
source: "docs-platform/content/docs/company-ai-os/overview.md"
edit: "https://github.com/Mindburn-Labs/docs-platform/edit/main/content/docs/company-ai-os/overview.md"
section: "company-ai-os"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-17"
checksum_sha256: "sha256:e1ae6325fe3ac266e1bccf4c4b28b07d16731ca54c290e2ab673bb0db12f36cb"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Company AI OS Overview

HELM AI Enterprise may be described as the Company AI OS when the full loop is explicit:

1. Query company state from source-backed artifacts.
2. Compare what should be true with what current evidence shows.
3. Generate reviewed work specifications.
4. Govern execution through HELM AI Kernel semantics.
5. Write receipts and evidence back to proof and company-context surfaces.

The public shorthand is:

> Models propose. HELM governs execution. Proof records.

This page is explanatory. It does not make HELM AI Enterprise a generally available self-serve product and it does not change the HELM AI Kernel contract.

## Public surfaces

- HELM AI Kernel is the public fail-closed execution firewall for AI-agent actions.
- HELM AI Enterprise is the reviewed-access company control-plane direction around the same execution boundary.
- Company context can inform proposals, reconciliation, approvals, and review, but context does not authorize side effects by itself.

## Operating loop

| Stage | Purpose | Execution rule |
| --- | --- | --- |
| Understand | Read policies, tickets, PRs, approvals, meetings, receipts, and other company artifacts. | Reading context is not execution authority. |
| Compare | Find drift, truth conflicts, missing approvals, and should-vs-is gaps. | A detected gap creates review work, not automatic action. |
| Gate | Send proposed action through CPI and PEP before a connector or system is touched. | If verification cannot complete, the action is blocked or escalated. |
| Prove | Preserve receipts, ProofGraph records, and EvidencePack slices. | Later review should not depend on model memory. |

Harness State is the operator-facing name for the live context around autonomous work: read/write sets, assumptions, stale dependencies, verification scope, approval state, connector state, sandbox grants, receipt references, and EvidencePack references. It helps operators inspect work before and after execution, but it does not replace HELM's deterministic execution authority.

## Diagram

```mermaid
flowchart TD
    subgraph Insight["1. Insight & Context Plane"]
        Docs["Company Source Docs"]
        Tickets["Tickets & Project Boards"]
        PRs["Pull Requests & Release Notes"]
        CAG["CompanyArtifactGraph Ingestion"]
        
        Docs & Tickets & PRs --> CAG
    end

    subgraph Reconciliation["2. Reconciliation Plane"]
        CAG --> State["Live Harness State Context"]
        State --> ShouldIs{"Compare Should vs. Is"}
        ShouldIs -->|Drift Detected| GapAlert["Identify Truth Conflicts & Gaps"]
        ShouldIs -->|Aligned Proposal| SpecGen["Compile GeneratedSpec Draft"]
    end

    subgraph Gate["3. PEP/CPI Enforcement Gate"]
        SpecGen --> CPI["CPI Plan Integrity Verification"]
        CPI --> PEP["PEP Fail-Closed Gate"]
    end

    subgraph Ledger["4. Tamper-Evident Proof Plane"]
        PEP --> Execution["Deterministic Sandbox / Bounded Dispatch"]
        Execution --> JCS["Canonical JCS Payload (RFC 8785)"]
        JCS --> Sign["Cryptographic Signature Ceremony"]
        Sign --> ProofGraph["Append to ProofGraph DAG Ledger"]
        Sign --> Evidence["Assemble EvidencePack Slice Archive"]
    end

    style ShouldIs fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style PEP fill:#e53e3e,stroke:#9b2c2c,stroke-width:2px,color:#fff
    style CPI fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
```

## Source posture

These docs use the public Mindburn and HELM claim posture:

- HELM AI Kernel remains the public Kernel surface.
- HELM AI Enterprise remains reviewed-access product direction.
- CompanyArtifactGraph is query and reconciliation memory, not authority.
- OrgGenome Compiler output is draft until reviewed and promoted.
- Harness State is inspectable company execution context, not a side-effect gate.
- ALLOW, DENY, and ESCALATE are the public verdict terms.

## Source truth

- Kernel boundary, verdicts, receipts, ProofGraph, EvidencePack, replay, and conformance: `helm-ai-kernel/README.md`, `helm-ai-kernel/api/openapi/`, `helm-ai-kernel/sdk/ts/src/client.ts`, `helm-ai-kernel/protocols/conformance/v1/test-vectors.json`, `helm-ai-kernel/tests/conformance/`, and `helm-ai-kernel/reference_packs/`.
- Enterprise Company AI OS framing, CompanyArtifactGraph, GeneratedSpec loop, connector governance, proof routes, and reviewed-access posture: `helm-ai-enterprise/README.md`, `helm-ai-enterprise/api/openapi/helm.openapi.yaml`, `helm-ai-enterprise/apps/console/src/router/routes.tsx`, `helm-ai-enterprise/packages/helm-ai-enterprise-design-system/src/routes/blueprints.ts`, and `helm-ai-enterprise/commercial/`.
- OrgGenome Compiler draft material, dataset/schema registry, training, evaluation, and serving boundaries: `orggenome-compiler/README.md`, `orggenome-compiler/datasets/README.md`, `orggenome-compiler/datasets/schemas/`, and `orggenome-compiler/docs/`.

## Where to go next

- [Authority boundary](/company-ai-os/authority-boundary)
- [CompanyArtifactGraph](/company-ai-os/company-artifact-graph)
- [OrgGenome Compiler](/company-ai-os/orggenome-compiler)
- [Proof and replay](/company-ai-os/proof-and-replay)
- [Workstation governance](/company-ai-os/workstation-governance)
- [Connector drift](/company-ai-os/connector-drift)


---
title: "Proof and Replay"
canonical: "https://helm.docs.mindburn.org/company-ai-os/proof-and-replay"
source: "docs-platform/content/docs/company-ai-os/proof-and-replay.md"
edit: "https://github.com/Mindburn-Labs/docs-platform/edit/main/content/docs/company-ai-os/proof-and-replay.md"
section: "company-ai-os"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-17"
checksum_sha256: "sha256:7c19198e1ea9696bcf5204f6a35ee90c1b335893bd78ef452fbbd7885ce373a4"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Proof and Replay

The Company AI OS loop is credible only if decisions remain reviewable after the action has run, been denied, or been escalated.

HELM proof language should name the artifact:

- a receipt for the execution decision
- a ProofGraph record for the proof trail
- an EvidencePack slice for focused review
- a policy or approval reference when relevant

## Why receipts matter

A receipt records what was requested, which verdict was returned, and what proof pointer belongs to the decision. It gives operators and reviewers a bounded object to inspect instead of reconstructing the event from chat history.

## ProofGraph posture

ProofGraph is a proof trail, not a public dump of company memory. Public docs should explain replay and review without implying sensitive raw artifacts are exposed.

## EvidencePack posture

EvidencePacks are focused review bundles. They can collect receipts, policy snapshots, approval records, and context references for one event or review path.

Do not imply every low-risk action must always store the same heavy evidence bundle. The public point is proportional proof: high-risk work needs stronger review evidence.

## Reviewer questions

For a consequential AI-assisted action, proof should help answer:

- Who or what requested the action?
- Which policy and approval state applied?
- Was the verdict ALLOW, DENY, or ESCALATE?
- Did a connector or external system receive the action?
- Which record should be used for later review?

## Diagram

```mermaid
flowchart TD
    subgraph Capture["1. Execution Interception Plane"]
        Request["Proposed Tool Call Context"] --> PEP["PEP Boundary Interception"]
        PEP --> Verdict{"Verdict: ALLOW, DENY, or ESCALATE"}
    end

    subgraph Receipt["2. Cryptographic Receipt Creation"]
        Verdict --> RawPayload["Compile Verdict Payload Struct"]
        RawPayload --> JCS["JCS Canonicalization (RFC 8785)"]
        JCS --> Hashing["Compute SHA-256 Signature Hash"]
        Hashing --> Sign["Asymmetric Signing (Ed25519/JWS)"]
        Sign --> SignedReceipt["Tamper-Evident Signed Receipt"]
    end

    subgraph Causality["3. ProofGraph DAG Causality Ledger"]
        SignedReceipt --> ProofGraph["Append to ProofGraph Session Chain"]
        
        subgraph DAGEdges["Causality Merkle Verification"]
            direction LR
            PrevHash["prev_hash Signature Linkage"]
            Lamport["Increment Lamport Clock"]
            PrevHash --> Lamport
        end
        ProofGraph --> DAGEdges
    end

    subgraph Verification["4. Offline EvidencePack & Replay"]
        DAGEdges --> Archiver["Compile Session Archive"]
        Archiver --> EvidencePack["EvidencePack Offline Bundle (.tar)"]
        EvidencePack --> Auditing["Operator Console Offline Auditing"]
        Auditing --> Replay["Deterministic Replay Validation Sandbox"]
    end

    style Verdict fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style SignedReceipt fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style EvidencePack fill:#38a169,stroke:#276749,stroke-width:2px,color:#fff
```

## Source truth

- Kernel receipts, proof routes, replay verification, SDK receipt/proof headers, conformance evidence, and test vectors: `helm-ai-kernel/README.md`, `helm-ai-kernel/api/openapi/`, `helm-ai-kernel/sdk/ts/src/client.ts`, `helm-ai-kernel/core/pkg/conform/`, `helm-ai-kernel/tests/conformance/`, and `helm-ai-kernel/protocols/conformance/v1/test-vectors.json`.
- Enterprise ProofGraph and EvidencePack API tags and commercial evidence storage: `helm-ai-enterprise/api/openapi/helm.openapi.yaml` and `helm-ai-enterprise/commercial/evidence/`.
- Enterprise Console proof, receipts, evidence, replay, and audit surfaces: `helm-ai-enterprise/apps/console/src/router/routes.tsx` and `helm-ai-enterprise/packages/helm-ai-enterprise-design-system/src/routes/blueprints.ts`.


---
title: "Workstation Governance"
canonical: "https://helm.docs.mindburn.org/company-ai-os/workstation-governance"
source: "docs-platform/content/docs/company-ai-os/workstation-governance.md"
edit: "https://github.com/Mindburn-Labs/docs-platform/edit/main/content/docs/company-ai-os/workstation-governance.md"
section: "company-ai-os"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-20"
checksum_sha256: "sha256:73e42172ced7f368a431ec7b6f2b098f9ae026332cb1521f5f48919d556318e2"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Workstation Governance

HELM workstation governance covers local coding-agent runs when the run is
captured through a HELM adapter or selected-effect wrapper. The public surface is
manifest-first: a run manifest, diff summary, validation output, optional tool
events, signed Agent Run Receipt, ProofGraph references, and EvidencePack
references.

This does not mean HELM provides blanket control over local desktop activity.
Direct actions that bypass the adapter, private browser sessions, local secrets,
and proprietary hosted-agent internals remain outside the claim unless a future
adapter proves a stronger surface through conformance.

```mermaid
flowchart TD
    subgraph AgentSpace["1. Local Workstation Execution"]
        Agent["Local Coding Agent Run (Codex / Claude Code)"] --> Wrapper["Selected-Effect Wrapper Intercept"]
        
        subgraph Intercepts["Monitored Action Classes"]
            direction LR
            I1["Network Egress"]
            I2["MCP Mutation"]
            I3["Shell Operations"]
            I4["Secret Reads"]
        end
        Wrapper --> Intercepts
    end

    subgraph Verification["2. Manifest-First Verification Engine"]
        Intercepts --> Evaluator["Run Constraint Policy Check"]
        Evaluator --> Decision{"Decision: ALLOW or DENY"}
        
        Decision -->|Exec Plan Checked| RunCode["Execute in Container / Bounded Shell"]
        RunCode --> CreateArtifacts["Generate Manifest, Diff Summary, & Event Logs"]
    end

    subgraph Receipt["3. Tamper-Proof Cryptographic Receipting"]
        CreateArtifacts --> Signer["Emit Signed Agent Run Receipt"]
        
        subgraph Refs["Merkle Ledger Registration"]
            direction LR
            R1["ProofGraph Indexing"]
            R2["EvidencePack Packager"]
        end
        Signer --> Refs
    end

    subgraph ControlPlane["4. Enterprise Governance Sync"]
        Refs --> Sync["Secure TLS Telemetry Ingestion"]
        Sync --> Console["HELM Enterprise Console Portal"]
        
        Console --> D1["Interactive Run Timeline"]
        Console --> D2["Denied Attempt Audits"]
        Console --> D3["Loop Execution Registry"]
    end

    style Decision fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Signer fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Console fill:#38a169,stroke:#276749,stroke-width:2px,color:#fff
```

## What is governed

- Imported Codex or Claude Code-style artifact sets.
- Signed Agent Run Receipts.
- Deterministic ProofGraph mapping.
- Workspace-scoped draft edits represented in the receipt.
- Selected-effect decisions for network egress, MCP mutation, memory writes,
  recurring loops, shell operate, deploy/publish, secret read, and payment
  initiate requests.
- Memory writes with TTL and sensitivity.
- Recurring loops with schedule, max runtime, tool scope, and expiration.

## Certification levels

| Level | Meaning |
| --- | --- |
| Observe-only | HELM can import artifacts and explain what happened after the run. |
| Selected-effect enforceable | HELM can allow or deny selected effects routed through the wrapper. |
| High-risk-effect capable | The adapter passes fixtures for memory, recurring loops, tainted context, and other high-risk classes. |

## Operator path

1. Run the local wrapper.
2. Produce the artifact directory.
3. Emit a signed Agent Run Receipt.
4. Import the receipt into Enterprise Console.
5. Review the run list, denied timeline, memory queue, and loop registry.
6. Inspect EvidencePack and ProofGraph references offline.
7. Run conformance certification for the adapter mode.

## Source truth

- Product page: `helm-ai-enterprise/docs/public/product/workstation-governance.md`
- Operator workflow: `helm-ai-enterprise/docs/console/WORKSTATION_GOVERNANCE.md`
- Console routes: `helm-ai-enterprise/apps/controlplane/internal/console/workstation_routes.go`
- OpenAPI: `helm-ai-enterprise/api/openapi/helm.openapi.yaml`
- Kernel adapter examples: `helm-ai-kernel/examples/workstation/`

## Where to go next

- [Authority boundary](/company-ai-os/authority-boundary)
- [Proof and replay](/company-ai-os/proof-and-replay)


---
title: "HELM Source Coverage Map"
canonical: "https://helm.docs.mindburn.org/coverage"
source: "helm-ai-enterprise/docs/public/source-coverage.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/source-coverage.md"
section: "coverage"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:6bce084fb38c1bab0b16bd3bfcdcb1da32d7b13db1c49c584c6eabbf1e60dbdb"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM Source Coverage Map

This page explains how the public HELM docs site maps back to the two HELM
source repositories. Use it when you want to know whether a repo surface is
published as a full page, summarized by a reference hub, available through the
OpenAPI/LLM/MCP exports, or intentionally left as internal implementation
material.

## Audience

This page is for developers integrating HELM AI Kernel, enterprise evaluators
reviewing HELM control-plane and Console material, operators planning a hosted
deployment, and reviewers checking whether public docs stay aligned with source.

## Outcome

After reading it, you should know where to find the public page for every major
HELM surface: install, CLI, SDKs, protocol schemas, examples, conformance,
verification, deployment, Console, audit registries, operations, security, and
release evidence.

## Coverage Model

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        repo["HELM + HELM AI Kernel repos"]
        manifest["public-docs manifests"]
        pages["Rendered docs pages"]
        llms["llms.txt and llms-full.txt"]
        mcp["Docs MCP tools"]
        source["Edit-source links"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        checks["manifest, diagram, coverage, truth checks"]
        release["Validated docs release"]
    end

    %% Operational Flow Edges
    repo --> manifest
    manifest --> pages
    manifest --> llms
    manifest --> mcp
    pages --> source
    pages --> checks
    checks --> release

    %% Premium Styling Rules
    style checks fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style release fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
```


The public docs site does not mirror every repo file one-for-one. That would
make source-generated ownership READMEs, raw JSON schemas, runbook fragments, and
implementation plans harder to use. Instead, the docs publish:

- Full pages for end-to-end developer and evaluator journeys.
- Reference hubs for large source families such as schemas, protocols, examples,
  deployment, audit registries, and Console.
- Direct OpenAPI export at `/openapi.yaml`.
- Full Markdown, search, `llms-full.txt`, and MCP parity for every public page.
- Edit-source links back to the owning repo/path.

## HELM AI Kernel Coverage

| Source family | Repo evidence | Public docs route |
| --- | --- | --- |
| Kernel, CLI, receipts, policy boundary | `helm-ai-kernel/core/`, `helm-ai-kernel/docs/ARCHITECTURE.md`, `helm-ai-kernel/docs/DEVELOPER_JOURNEY.md` | `/helm-ai-kernel`, `/helm-ai-kernel/developer-journey`, `/helm-ai-kernel/architecture` |
| Install and local proxy path | `helm-ai-kernel/docs/QUICKSTART.md`, `helm-ai-kernel/Makefile`, `helm-ai-kernel/.goreleaser.yml` | `/helm-ai-kernel/quickstart`, `/helm-ai-kernel/developer-journey` |
| Deployment and examples | `helm-ai-kernel/deploy/`, `helm-ai-kernel/docker-compose.yml`, `helm-ai-kernel/examples/` | `/helm-ai-kernel/deployment-and-examples` |
| SDKs and language clients | `helm-ai-kernel/sdk/`, `helm-ai-kernel/examples/*_client/`, `helm-ai-kernel/docs/sdks/00_INDEX.md` | `/helm-ai-kernel/sdks` |
| OpenAI-compatible proxy and MCP | `helm-ai-kernel/docs/INTEGRATIONS/`, `helm-ai-kernel/examples/*openai_baseurl/`, `helm-ai-kernel/examples/mcp_client/` | `/helm-ai-kernel/integrations/openai-compatible-proxy`, `/helm-ai-kernel/integrations/mcp` |
| Protocols, schemas, policy language, conformance | `helm-ai-kernel/protocols/`, `helm-ai-kernel/schemas/`, `helm-ai-kernel/docs/architecture/policy-languages.md` | `/helm-ai-kernel/reference/protocols-and-schemas`, `/helm-ai-kernel/conformance`, `/helm-ai-kernel/compatibility` |
| Verification and evidence packs | `helm-ai-kernel/docs/VERIFICATION.md`, `helm-ai-kernel/protocols/spec/evidence-pack-v1.md`, `helm-ai-kernel/examples/receipt_verification/` | `/helm-ai-kernel/verification`, `/helm-ai-kernel/developer-journey` |
| Release, security, supply chain | `helm-ai-kernel/SECURITY.md`, `helm-ai-kernel/RELEASE.md`, `helm-ai-kernel/BEST_PRACTICES.md`, `helm-ai-kernel/release/` | `/helm-ai-kernel/security/release-security`, `/helm-ai-kernel/publishing` |

## HELM AI Enterprise Coverage

| Source family | Repo evidence | Public docs route |
| --- | --- | --- |
| Five-minute integration | `helm-ai-enterprise/docs/public/getting-started/integrate-in-5-min.md` | `/start` |
| Individual governance | `helm-ai-enterprise/docs/public/product/agent-skills-governance.md`, policy bundle docs | `/helm-ai-enterprise/individual`, `/product/policy-bundles` |
| Enterprise control plane | `helm-ai-enterprise/docs/COMMERCIAL_OVERVIEW.md`, `helm-ai-enterprise/docs/COMMERCIAL_DEPLOY.md` | `/enterprise` |
| Console | `helm-ai-enterprise/docs/console/` | `/product/console` |
| Observability and tracing | `helm-ai-enterprise/docs/public/observability/observability.md`, `helm-ai-enterprise/docs/public/tracing.md` | `/observability`, `/tracing` |
| API and audit registries | `helm-ai-enterprise/docs/api/`, `helm-ai-enterprise/docs/audit/`, `helm-ai-enterprise/api/openapi/` | `/reference`, `/reference/api-and-audit-registries`, `/openapi.yaml` |
| Operations | `helm-ai-enterprise/docs/operations/` | `/operations/operator-guide` |
| Security, TCB, threat model, verifier trust | `helm-ai-enterprise/docs/public/security-and-trust/` | `/proof`, `/security/threat-model`, `/security/tcb-policy`, `/security/verifier-trust-model` |
| Procurement, regional, and RFP material | `helm-ai-enterprise/docs/public/product/` | `/product/procurement`, `/product/regional-compat`, `/product/rfp-answers` |

## Publication Rules

HELM publishes public documentation when a source surface is useful to one of
the public audiences and does not depend on private credentials, private
deployment inventory, unfinished implementation phase notes, or customer-specific
runbooks. Internal generated surface READMEs remain source-truth inputs, but the
public site normally exposes them through a curated hub page.

## Source Truth

The public site is driven by:

- `helm-ai-kernel/docs/public-docs.manifest.json`
- `helm-ai-enterprise/docs/public-docs.manifest.json`
- `helm-ai-kernel/docs/developer-coverage.manifest.json`
- `docs-platform/scripts/check-developer-coverage.ts`
- `docs-platform/scripts/check-diagram-coverage.ts`

The HELM AI Kernel repo also runs `make docs-coverage docs-truth`, which verifies that
coverage rows resolve to live source and canonical docs.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| A repo doc is not visible on the site | Look for the source family in this page, then check the manifest for its public hub or direct page. |
| A public page links to stale source | Run `npm run validate` in `docs-platform` and `make docs-coverage docs-truth` in `helm-ai-kernel`. |
| A claim appears in docs without source evidence | Add or correct the row in `developer-coverage.manifest.json`, then rerun `npm run coverage:check`. |
| A page is missing from agent exports | Check `/llms.txt`, `/llms-full.txt`, `/mcp`, and the search index generated by the docs platform. |


---
title: "Frontend & Console"
canonical: "https://helm.docs.mindburn.org/frontend"
source: "helm-ai-enterprise/docs/public/frontend-landing.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/frontend-landing.md"
section: "frontend"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-13"
checksum_sha256: "sha256:98b8b8a6f142cd42d9697ac2e2baa634681b5e5a544af1693e12da7f5b50c961"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Frontend & Console

This page answers where HELM's frontend, console, and UI design truth pages live, and which of them are OSS-owned versus HELM AI Enterprise-owned product surfaces. It consolidates the accepted source targets for console development, design-system work, and UX architecture.

## Audience

- Frontend engineers implementing or modifying Console surfaces
- Design-system contributors adding components and interaction states
- Product teams validating UX alignment for evidence workflows
- Security and SRE engineers reviewing auth and session behavior in frontend context
- Technical writers creating product-facing frontend documentation

## Outcome

After reading this page you should be able to:

- locate the source-backed page for every major frontend and console topic before changing implementation,
- avoid duplicating design decisions across OSS and Commercial docs,
- identify the correct public route for a given UI domain,
- and apply the same boundary criteria used by architecture when classifying future console content.

## Mermaid

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Console["apps/console"]
        Design["Design System"]
        Control["Control Plane API Consumer"]
        OSS["HELM AI Kernel"]
        Commercial["HELM AI Enterprise"]
        ProductConsole["Product Console Surface"]
        Accessibility["Accessibility & a11y"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Evidence["Receipts / Replay Views"]
    end

    %% Operational Flow Edges
    Console --> Design
    Console --> Control
    Control --> Evidence
    OSS --> Design
    Commercial --> ProductConsole
    Design --> Accessibility
    Control --> ProductConsole

    %% Premium Styling Rules
    style Evidence fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Source Truth

- `apps/console/**`
- `apps/controlplane/**`
- `docs/console/**`
- `docs/ui/**`
- `docs/public/product/console.md`
- `docs/public/frontend/**`

## Console and product pages

- [Console Overview](/product/console) — consolidated product introduction and capabilities.
- Console deployment source: `docs/console/DEPLOYMENT.md` — deployment architecture for console operations.
- Console security source: `docs/console/SECURITY_MODEL.md` — auth and session behavior for user-facing interfaces.
- Console product boundary source: `docs/OSS_VS_COMMERCIAL.md` — explicit OSS vs hosted Console ownership rules.
- Console replay source: `docs/console/REPLAY_AND_RECEIPTS.md` — receipt inspection and replay flows.
- Console lifecycle source: `docs/console/RUN_LIFECYCLE.md` — run states and transitions during execution.
- Console scenarios source: `docs/console/SCENARIOS.md` — scenario-based usage patterns and behavior expectations.

## Design system and component architecture

- Design system source: `docs/public/product/design-system.md` — overall design principles and primitives.
- Design-system package source: `packages/helm-ai-enterprise-design-system/` — package reference.
- Accessibility source: `docs/ui/ACCESSIBILITY.md` — accessibility guidance and validation posture.
- Components and states source: `docs/ui/COMPONENT_STATES.md` — component behavior and documented interaction states.
- Flows source: `docs/ui/FLOWS.md` — user flow and interaction mapping for Console operations.

## UX architecture references

- UX specification source: `docs/ui/UX_SPEC.md` — source spec for UX decisions.
- Information architecture source: `docs/ui/IA_MAP.md` — navigation model and information hierarchy.
- Evidence UX source: `docs/ui/EVIDENCE_UX.md` — design treatment for trust and proof artifacts.
- Agents UX source: `docs/ui/AGENTS_UX.md` — UX patterns for agent-centered interfaces.

## Kernel vs HELM AI Enterprise boundaries (explicit)

For frontend content, OSS ownership typically covers reusable primitives, conventions, and open standards:

- component behavior and accessibility expectations that are intended to be generally reusable,
- route conventions and navigation standards with no commercial operational assumptions,
- and design-system contracts that are expected to apply across deployment contexts.

HELM AI Enterprise ownership typically covers:

- hosted Console operational experience, including enterprise UX policy and product support workflow,
- customer-specific orchestration surfaces where entitlement or tenant policy changes behavior,
- and product packaging where deployment model changes semantics outside shared OSS conventions.

When a page crosses both areas, keep protocol semantics on OSS pages and keep policy packaging or entitlement behaviors on Commercial pages, with explicit links between the two.

## Troubleshooting

- If Console behavior appears inconsistent with docs, verify the implementation path under `apps/console/**` and compare it with `/product/console` or the source paths listed above.
- If component behavior is undocumented, add or update component state docs before adding production changes to reduce drift.
- If accessibility guidance is missing for a change, route that update through `docs/ui/ACCESSIBILITY.md`.
- If a page was moved between OSS and Commercial, update both this page and the boundary page used for that classification.
- If evidence visualizations differ from implementation, check `docs/console/REPLAY_AND_RECEIPTS.md` and `docs/ui/EVIDENCE_UX.md` together; both should reference the same contract assumptions.

## Adoption notes for frontend changes

1. Confirm whether your change is a public UI primitive (OSS) or a Commercial product surface.
2. If primitive: update `docs/ui/**` and/or relevant `docs/console/**` page first, then reflect via this landing page.
3. If Commercial surface: validate that user-facing behavior still links back to OSS baseline contracts, and do not duplicate those contracts in the Commercial page.
4. Keep this page updated whenever new frontend routes are added or ownership changes.


---
title: "HELM for Humans"
canonical: "https://helm.docs.mindburn.org/getting-started/for-humans"
source: "helm-ai-enterprise/docs/public/getting-started/for-humans.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/getting-started/for-humans.md"
section: "start"
access: "public"
sensitivity: "public"
last_reviewed: "2026-02-21"
checksum_sha256: "sha256:637d1833cf0d4feeb2bac45b43ebd23d664bf384f8020a3cfcf794b0ffb00cda"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM for Humans

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `getting-started/for-humans`
- Source document: `helm-ai-enterprise/docs/public/getting-started/for-humans.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

If you just want to stop your AI from doing things it shouldn't, this is for you. No UCS/UCS jargon, just the facts.

### 1. What does HELM actually do?

Imagine your AI agent has a credit card and access to your terminal. HELM is the person standing over its shoulder.

- If the AI tries to buy a $10,000 server, HELM stops it (Budgeting).
- If the AI tries to run `rm -rf /`, HELM stops it (Sandboxing).
- If the AI tries to call a tool you haven't approved, HELM stops it (Fail-Closed).

### 2. How do I install it?

```bash
curl -fsSL https://raw.githubusercontent.com/Mindburn-Labs/helm-ai-enterprise/main/install.sh | bash
helm server
```

That's it. It starts a local server. You then point your Python/Node.js OpenAI client to `http://localhost:9090/v1`.

### 3. Do I need a database?

Nope. By default, it uses a local file (`data/helm.db`) so you can try it out instantly. For big companies, we support Postgres.

### 4. What is a "Receipt"?

Every time your AI does something, HELM signs a digital "receipt".

- **The AI says**: "I'm going to read this file."
- **HELM says**: "Allowed. Here is your signed receipt #42."
  You can use these receipts later to prove exactly what happened if something goes wrong.

### 5. Does it slow down my AI?

Barely. HELM adds about **5-10ms** of overhead per request. For a model that takes 2 seconds to think, this is invisible.

### 6. Is it free?

Yes, it's Open Source under the [Apache License 2.0](../../../LICENSE). Free for any use — personal, commercial, or enterprise.

---

**Ready to go?** Head back to the Quickstart (protected staff doc).

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["HELM for Humans"]
        s0["Source truth"]
        s1["Public docs"]
        s2["Validation"]
        output["Reader outcome"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> output

    %% Premium Styling Rules
```


## Operational Readiness

Use this page as the public operating layer for **HELM for Humans**. The source of truth is `helm-ai-enterprise/docs/public/getting-started/for-humans.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "HELM AI Enterprise"
canonical: "https://helm.docs.mindburn.org/helm-ai-enterprise"
source: "helm-ai-enterprise/docs/COMMERCIAL_OVERVIEW.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/COMMERCIAL_OVERVIEW.md"
section: "helm-ai-enterprise"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:918c5324e7f1b7a2433790dfd49418b40d47bd844b3e87948b7f5096c3caa5f4"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM AI Enterprise Overview

HELM AI Enterprise is the organizational control plane around the HELM AI Kernel execution kernel. It is for teams that need shared administration, identity, approval workflows, retention, evidence export, and evaluator-ready security posture around governed AI execution.

## Audience

This page is for enterprise evaluators, platform leaders, security architects, procurement reviewers, and operators deciding whether HELM can become the execution boundary for autonomous work.

## Outcome

After reading this page, an evaluator should understand:

- what stays in the OSS kernel and what the commercial control plane adds;
- how Individual and Enterprise differ;
- where Console, Console proof, SSO/RBAC, tenancy, SIEM, retention, deployment, and upgrades fit;
- which evidence an enterprise reviewer can ask for before a pilot;
- which pages contain exact APIs and trust details.

## Control Plane Map

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Kernel["HELM AI Kernel kernel"]
        Individual["Individual workspaces"]
        Console["Console operations UI"]
        SSO["SSO / RBAC / SCIM"]
        SIEM["SIEM export"]
        Retention["Retention and archival"]
        Enterprise["Enterprise admin"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Receipts["Receipts and evidence"]
        Proof["Console proof routes"]
    end

    %% Operational Flow Edges
    Kernel --> Receipts
    Individual --> Kernel
    Console --> Individual
    SSO --> Individual
    SIEM --> Receipts
    Proof --> Receipts
    Retention --> Receipts
    Enterprise --> SSO
    Enterprise --> Retention

    %% Premium Styling Rules
    style Receipts fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Proof fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Source Truth

This commercial overview is a routing page. Exact operational details live in:

- `docs/public/product/agent-skills-governance.md`
- `docs/public/product/console-api.md`
- `docs/public/product/procurement.md`
- `docs/public/product/rfp-answers.md`
- `docs/public/product/regional-compat.md`
- `docs/public/security-and-trust/security-model.md`
- `docs/public/security-and-trust/threat-model.md`
- `docs/11_API_REFERENCE.md`

Do not use this page as a substitute for endpoint, policy, or deployment references.

## Product Tiers

| Tier | Primary User | What It Adds |
| --- | --- | --- |
| OSS Kernel | Developers and framework authors | Local execution boundary, policy evaluation, receipts, verification, SDKs, MCP, OpenAI-compatible proxy. |
| Individual | Product teams and internal platforms | Workspaces, role models, approvals, API key management, shared policy bundles, audit trails, team administration. |
| Enterprise | Regulated or large organizations | Control plane governance, SSO/RBAC/SCIM path, tenancy controls, SIEM export, retention policies, certification evidence, deployment and upgrade support. |

Commercial value comes from shared organizational control around the kernel, not from artificial OSS gaps.

## Enterprise Capabilities

### Control Plane

The control plane coordinates workspaces, policy bundle attachment, approval flows, key issuance, audit trails, and evidence export. It does not replace the kernel. The kernel remains the decision boundary.

### Console

Console is the operational surface for inspecting decisions, receipts, approvals, policy versions, and workspace state. Evaluators should look for whether operators can answer "why was this action allowed?" without reading application logs.

### Console Proof

The Console proof should expose security model, TCB, threat model, evidence pack semantics, SBOM/SLSA/Cosign material where available, OWASP mappings, and compliance pack references.

### SSO, RBAC, and Tenancy

Enterprise deployments should align identity with the customer directory and map roles to concrete actions: administer workspace, issue keys, approve escalations, export evidence, and change policy. Tenancy should isolate workspaces, policy state, receipts, and exports.

### SIEM, Retention, and Archival

Receipts and audit events are useful only when they leave the product cleanly. Enterprise posture requires export to security tooling, explicit retention policy, and archival behavior that survives vendor or model-provider changes.

### Deployment and Upgrades

Enterprise reviewers should ask:

1. Which components run in our network?
2. Which components are hosted?
3. How are policy bundles promoted?
4. How are signing keys and evidence exports rotated?
5. How are upgrades rolled back?
6. What is the minimum evidence package for an audit?

## Evaluator Checklist

| Question | Where to Verify |
| --- | --- |
| Can a developer integrate in under 10 minutes? | [Start guide](/start) |
| Can an auditor verify a receipt offline? | [Verify](/reference/verify) |
| What is in the trusted computing base? | [TCB Policy](/security/tcb-policy) |
| What threats are modeled? | [Threat Model](/security/threat-model) |
| Which APIs exist for operators? | [API Reference](/reference) and [Console API](/product/console-api) |
| How do procurement teams evaluate the product? | [Procurement FAQ](/product/procurement) and [RFP Answers](/product/rfp-answers) |

## Troubleshooting

| Symptom | Likely Cause | Fix |
| --- | --- | --- |
| Enterprise review stalls on "what is hosted?" | Deployment model not stated for the pilot | Write the chosen deployment model into the evaluation packet. |
| Security team cannot trace a decision | Receipts are not exported or linked to policy versions | Require receipt export and bundle hashes in pilot acceptance. |
| SSO/RBAC discussion stays abstract | Roles are not tied to actions | Map each role to workspace, approval, key, policy, and export permissions. |
| Compliance asks for a claim that is not in docs | Claim has no source-truth page | Add a source-backed doc or remove the claim. |

## Next Pages

- [Individual Governance](/teams)
- [Security Model](/trust)
- [Threat Model](/security/threat-model)
- [Regional Compatibility](/product/regional-compat)


---
title: "Enterprise plan"
canonical: "https://helm.docs.mindburn.org/helm-ai-enterprise/enterprise"
source: "helm-ai-enterprise/docs/COMMERCIAL_OVERVIEW.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/COMMERCIAL_OVERVIEW.md"
section: "helm-ai-enterprise"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:918c5324e7f1b7a2433790dfd49418b40d47bd844b3e87948b7f5096c3caa5f4"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM AI Enterprise Overview

HELM AI Enterprise is the organizational control plane around the HELM AI Kernel execution kernel. It is for teams that need shared administration, identity, approval workflows, retention, evidence export, and evaluator-ready security posture around governed AI execution.

## Audience

This page is for enterprise evaluators, platform leaders, security architects, procurement reviewers, and operators deciding whether HELM can become the execution boundary for autonomous work.

## Outcome

After reading this page, an evaluator should understand:

- what stays in the OSS kernel and what the commercial control plane adds;
- how Individual and Enterprise differ;
- where Console, Console proof, SSO/RBAC, tenancy, SIEM, retention, deployment, and upgrades fit;
- which evidence an enterprise reviewer can ask for before a pilot;
- which pages contain exact APIs and trust details.

## Control Plane Map

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Kernel["HELM AI Kernel kernel"]
        Individual["Individual workspaces"]
        Console["Console operations UI"]
        SSO["SSO / RBAC / SCIM"]
        SIEM["SIEM export"]
        Retention["Retention and archival"]
        Enterprise["Enterprise admin"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Receipts["Receipts and evidence"]
        Proof["Console proof routes"]
    end

    %% Operational Flow Edges
    Kernel --> Receipts
    Individual --> Kernel
    Console --> Individual
    SSO --> Individual
    SIEM --> Receipts
    Proof --> Receipts
    Retention --> Receipts
    Enterprise --> SSO
    Enterprise --> Retention

    %% Premium Styling Rules
    style Receipts fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Proof fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Source Truth

This commercial overview is a routing page. Exact operational details live in:

- `docs/public/product/agent-skills-governance.md`
- `docs/public/product/console-api.md`
- `docs/public/product/procurement.md`
- `docs/public/product/rfp-answers.md`
- `docs/public/product/regional-compat.md`
- `docs/public/security-and-trust/security-model.md`
- `docs/public/security-and-trust/threat-model.md`
- `docs/11_API_REFERENCE.md`

Do not use this page as a substitute for endpoint, policy, or deployment references.

## Product Tiers

| Tier | Primary User | What It Adds |
| --- | --- | --- |
| OSS Kernel | Developers and framework authors | Local execution boundary, policy evaluation, receipts, verification, SDKs, MCP, OpenAI-compatible proxy. |
| Individual | Product teams and internal platforms | Workspaces, role models, approvals, API key management, shared policy bundles, audit trails, team administration. |
| Enterprise | Regulated or large organizations | Control plane governance, SSO/RBAC/SCIM path, tenancy controls, SIEM export, retention policies, certification evidence, deployment and upgrade support. |

Commercial value comes from shared organizational control around the kernel, not from artificial OSS gaps.

## Enterprise Capabilities

### Control Plane

The control plane coordinates workspaces, policy bundle attachment, approval flows, key issuance, audit trails, and evidence export. It does not replace the kernel. The kernel remains the decision boundary.

### Console

Console is the operational surface for inspecting decisions, receipts, approvals, policy versions, and workspace state. Evaluators should look for whether operators can answer "why was this action allowed?" without reading application logs.

### Console Proof

The Console proof should expose security model, TCB, threat model, evidence pack semantics, SBOM/SLSA/Cosign material where available, OWASP mappings, and compliance pack references.

### SSO, RBAC, and Tenancy

Enterprise deployments should align identity with the customer directory and map roles to concrete actions: administer workspace, issue keys, approve escalations, export evidence, and change policy. Tenancy should isolate workspaces, policy state, receipts, and exports.

### SIEM, Retention, and Archival

Receipts and audit events are useful only when they leave the product cleanly. Enterprise posture requires export to security tooling, explicit retention policy, and archival behavior that survives vendor or model-provider changes.

### Deployment and Upgrades

Enterprise reviewers should ask:

1. Which components run in our network?
2. Which components are hosted?
3. How are policy bundles promoted?
4. How are signing keys and evidence exports rotated?
5. How are upgrades rolled back?
6. What is the minimum evidence package for an audit?

## Evaluator Checklist

| Question | Where to Verify |
| --- | --- |
| Can a developer integrate in under 10 minutes? | [Start guide](/start) |
| Can an auditor verify a receipt offline? | [Verify](/reference/verify) |
| What is in the trusted computing base? | [TCB Policy](/security/tcb-policy) |
| What threats are modeled? | [Threat Model](/security/threat-model) |
| Which APIs exist for operators? | [API Reference](/reference) and [Console API](/product/console-api) |
| How do procurement teams evaluate the product? | [Procurement FAQ](/product/procurement) and [RFP Answers](/product/rfp-answers) |

## Troubleshooting

| Symptom | Likely Cause | Fix |
| --- | --- | --- |
| Enterprise review stalls on "what is hosted?" | Deployment model not stated for the pilot | Write the chosen deployment model into the evaluation packet. |
| Security team cannot trace a decision | Receipts are not exported or linked to policy versions | Require receipt export and bundle hashes in pilot acceptance. |
| SSO/RBAC discussion stays abstract | Roles are not tied to actions | Map each role to workspace, approval, key, policy, and export permissions. |
| Compliance asks for a claim that is not in docs | Claim has no source-truth page | Add a source-backed doc or remove the claim. |

## Next Pages

- [Individual Governance](/teams)
- [Security Model](/trust)
- [Threat Model](/security/threat-model)
- [Regional Compatibility](/product/regional-compat)


---
title: "Individual Governance"
canonical: "https://helm.docs.mindburn.org/helm-ai-enterprise/individual"
source: "helm-ai-enterprise/docs/public/product/individual-governance.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/individual-governance.md"
section: "helm-ai-enterprise"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-20"
checksum_sha256: "sha256:f43b424949525438ad0420405e4af49d7bdd7c80b282fe5d98ffee9ebd7efd02"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Individual Governance

HELM AI Enterprise Individual is the team-scale control plane around HELM AI Kernel. It gives developers and small platform teams shared workspaces, scoped keys, approvals, policy bundles, audit trails, and receipt search without changing the kernel's execution semantics.

## Audience

Use this page if you are evaluating the Individual route for a small team, setting up shared governance for local or CI agents, or comparing Individual and Enterprise operating responsibilities.

## Outcome

After reading this page, you should know what the Individual route adds, which source files own the implementation, and where to verify the API and receipt behavior before a rollout.

## Governance Flow

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        workspace["Workspace"]
        roles["Roles and keys"]
        review["Review and refine"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        policy["Policy bundle"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        runtime["Governed runtime"]
        decision{"ALLOW, DENY, or ESCALATE"}
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["Receipt and audit trail"]
    end

    %% Operational Flow Edges
    workspace --> roles
    roles --> policy
    policy --> runtime
    runtime --> decision
    decision --> receipt
    receipt --> review
    review --> policy

    %% Premium Styling Rules
    style policy fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style runtime fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style decision fill:#e53e3e,stroke:#9b2c2c,stroke-width:2px,color:#fff
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## What Individual Adds

- Shared workspaces for product teams and internal platforms.
- Role models for developers, approvers, auditors, and admins.
- Scoped API keys for local development, CI, staging, and production.
- Policy bundles that define allowed, denied, and escalated actions.
- Audit trails that connect actions to receipts.
- Review practices for denied and escalated receipts during rollout.

The implementation route family is mounted at `/api/basic/` for compatibility. Public docs should refer to the product route as Individual while keeping exact implementation paths visible where operators need them.

## Rollout Shape

Start with one workspace and one narrow policy bundle. Bind a local-development key to that workspace, route one non-production agent through the HELM boundary, and require a denied-action receipt before expanding the rollout. Once the team can find allowed, denied, and escalated receipts without reading application logs, add a staging key and a stricter policy bundle for higher-risk effects.

Production use should split developer, approver, auditor, and admin roles. Developers can request governed actions and inspect their own receipts. Approvers review escalations and record decisions. Auditors export evidence and verify receipts. Admins manage workspace membership, keys, retention, and policy attachment. The same person can hold multiple roles in a small team, but production policies should still prevent self-approval for consequential effects.

## Boundary

Individual does not change the HELM AI Kernel decision model. It adds shared administration around the same receipts, policy bundles, and evidence paths. Hosted Enterprise deployments add broader tenant, directory, retention, SIEM, and upgrade controls; Individual is the smaller team route for getting shared governance in place before those organization-wide controls are required.

## Source Truth

- Implementation router: `commercial/basic/server.go`
- Workspace model: `commercial/basic/workspace.go`
- RBAC model: `commercial/basic/rbac.go`
- API key model: `commercial/basic/apikey.go`
- Approval model: `commercial/basic/approval.go`
- Evidence index: `commercial/basic/evidence_index.go`
- Runtime bridge: `commercial/basic/runtime_bridge.go`
- API reference: `docs/11_API_REFERENCE.md`
- Team governance guide: `docs/public/product/agent-skills-governance.md`

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Individual route behavior is unclear | Check `commercial/basic/server.go` and `docs/11_API_REFERENCE.md`. |
| A team cannot find its receipts | Confirm the workspace ID, active policy bundle, and evidence index route. |
| A developer can approve their own production action | Split developer and approver roles before production rollout. |
| Public route names and implementation paths look different | Treat Individual as the product route and `/api/basic/` as the compatibility implementation path. |


---
title: "HELM AI Kernel"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel"
source: "helm-ai-kernel/docs/index.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/index.md"
section: "helm-ai-kernel"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:b67092b1f76329c3eb76076791d0b99ba1e1fb772b384ae00ae1f4b8d416ff3b"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM AI Kernel Developer Portal

HELM AI Kernel is the fail-closed execution firewall for AI agents. It gives developers a local kernel, policy bundle loader, OpenAI-compatible proxy path, MCP firewall, receipts, EvidencePacks, and offline verification without requiring a hosted service.

## Audience

This page is for open-source developers, platform teams, security reviewers, and framework authors who need to integrate or inspect the HELM AI Kernel kernel directly.

## Outcome

After this page you should know which public HELM AI Kernel surface to use:

- quickstart for a local boundary;
- developer journey for end-to-end install, runtime, SDK, deployment, and verification coverage;
- architecture for the trust and execution model;
- CLI and SDKs for integration;
- MCP and OpenAI-compatible proxy for agent frameworks;
- conformance and verification for CI and audits;
- publishing and compatibility docs for release consumers.

## OSS Boundary Map

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Dev["Developer app"]
        Proxy["OpenAI-compatible proxy"]
        Agent["MCP or agent client"]
        MCP["MCP integration"]
        Kernel["HELM AI Kernel kernel"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        Policy["Policy bundle"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Receipt["Receipt and evidence pack"]
        Verify["Offline verifier"]
    end

    %% Operational Flow Edges
    Dev --> Proxy
    Agent --> MCP
    Proxy --> Kernel
    MCP --> Kernel
    Kernel --> Policy
    Kernel --> Receipt
    Receipt --> Verify
    Policy --> Verify

    %% Premium Styling Rules
    style Policy fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Source Truth

This portal is assembled from source-owned docs:

- `docs/QUICKSTART.md`
- `docs/DEVELOPER_JOURNEY.md`
- `docs/ARCHITECTURE.md`
- `docs/CONFORMANCE.md`
- `docs/VERIFICATION.md`
- `docs/COMPATIBILITY.md`
- `docs/PUBLISHING.md`
- `docs/INTEGRATIONS/`
- `docs/security/`
- `docs/compliance/`

The code, command output, and verification artifacts override marketing language. If a doc claim cannot be mapped to a source file, command, or artifact, remove or qualify it.

## Start Here

1. Run the quickstart: [Quickstart](/helm-ai-kernel/quickstart).
2. Use the complete source-backed path: [Developer Journey](/helm-ai-kernel/developer-journey).
3. Read the execution model: [Architecture](/helm-ai-kernel/architecture).
4. Pick an integration:
   - [OpenAI-compatible proxy](/helm-ai-kernel/integrations/openai-compatible-proxy)
   - [MCP integration](/helm-ai-kernel/integrations/mcp)
   - [Highflame ZeroID Integration](INTEGRATIONS/zeroid.md)
   - [Vaultak State Transaction Bridge](INTEGRATIONS/vaultak.md)
   - [BGT Labs Sentinel Authorization Gateway](INTEGRATIONS/sentinel.md)
   - [SDK index](/helm-ai-kernel/sdks)
5. Verify an output: [Verification](/helm-ai-kernel/verification).
6. Add conformance checks: [Conformance](/helm-ai-kernel/conformance).

## Interfaces

| Interface | Use When | Public Doc |
| --- | --- | --- |
| CLI | You want local serving, policy loading, receipts, or verification commands. | [Quickstart](/helm-ai-kernel/quickstart) |
| OpenAI-compatible proxy | You have an existing OpenAI-style client and want a small integration diff. | [Proxy integration](/helm-ai-kernel/integrations/openai-compatible-proxy) |
| MCP | You are exposing governed tools to MCP-capable clients. | [MCP integration](/helm-ai-kernel/integrations/mcp) |
| SDKs | You need typed wrappers or generated examples. | [SDK index](/helm-ai-kernel/sdks) |
| Verifier | You need replayable evidence independent of the model provider. | [Verification](/helm-ai-kernel/verification) |

## Trust and Compliance

HELM AI Kernel docs separate implementation security from compliance mapping:

- [Execution Security Model](/helm-ai-kernel/execution-security-model) describes containment, policy evaluation, receipts, and evidence.
- [OWASP MCP Threat Mapping](/helm-ai-kernel/owasp-mcp-threat-mapping) maps MCP-specific risks to HELM controls.
- [OWASP Agentic Top 10 Mapping](/helm-ai-kernel/security/owasp-agentic-top10-mapping) maps agentic failure modes to boundary controls.
- [NIST AI RMF to ISO 42001 Crosswalk](/helm-ai-kernel/compliance/nist-ai-rmf-iso-42001-crosswalk) explains how reference packs can support operator evidence without claiming certification.

## Compatibility and Publishing

Use [Compatibility](/helm-ai-kernel/compatibility) before relying on a public surface. Use [Publishing](/helm-ai-kernel/publishing) before consuming release artifacts or publishing downstream packages. The docs intentionally distinguish retained compatibility paths from preferred paths so agents and humans can choose the least surprising integration.

## Troubleshooting

| Problem | Where to Go |
| --- | --- |
| Local proxy starts but receipts are missing | [Troubleshooting](/helm-ai-kernel/troubleshooting) and [Proxy integration](/helm-ai-kernel/integrations/openai-compatible-proxy) |
| A bundle does not verify | [Verification](/helm-ai-kernel/verification) |
| A framework adapter behaves differently from direct CLI use | [Compatibility](/helm-ai-kernel/compatibility) |
| A public release artifact cannot be trusted | [Publishing](/helm-ai-kernel/publishing) |
| A security reviewer asks what is in the trust boundary | [Execution Security Model](/helm-ai-kernel/execution-security-model) |

## Support Path

For bugs, include the HELM version, policy bundle hash, command used, receipt ID or bundle path, and verifier output. Do not include provider keys, private prompts, customer data, or unredacted receipts from production tenants.


---
title: "Architecture"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/architecture"
source: "helm-ai-kernel/docs/ARCHITECTURE.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/ARCHITECTURE.md"
section: "start-here"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:a3a5bcc16f3cb2e6ebc52bb0a516e84c44e9764c6fe20f92b73c8192a9c5671d"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Architecture

## Audience

Maintainers and operators who need the current HELM AI Kernel execution-boundary model before changing kernel, Console, API, or integration docs.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/architecture`
- Source document: `helm-ai-kernel/docs/ARCHITECTURE.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

This scheme maps the main sections of Architecture in reading order.
Use [Canonical diagrams](/helm-ai-kernel/architecture/canonical-diagrams) for public
execution-boundary, MCP quarantine, evidence, drift, and long-horizon visuals.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["Architecture"]
        B["2. Execution and Proxy Surface"]
        D["4. Contracts and Schemas"]
        E["5. SDKs"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        A["1. Policy Boundary"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        C["3. Receipts and Evidence"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C
    C --> D
    D --> E

    %% Premium Styling Rules
    style A fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style C fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


HELM is organized around an execution boundary rather than around model prompting. The retained OSS implementation has five main pieces.

## 1. Policy Boundary

The policy boundary evaluates requests before tool dispatch. In the OSS kernel this includes:

- request parsing and normalization
- manifest and schema validation
- policy evaluation
- deterministic allow or deny decisions
- receipt generation for the decision outcome
- boundary records, checkpoints, approval ceremonies, MCP quarantine state, authz snapshots, sandbox grants, and evidence envelope manifests

The core implementation lives under `core/pkg/guardian/`, `core/pkg/manifest/`, `core/pkg/policy/`, `core/pkg/boundary/`, and related contract packages. `helm-ai-kernel serve` stores the boundary surface snapshot in the runtime database; local CLI-only workflows use the same contracts through the file-backed boundary registry.

## 2. Execution and Proxy Surface

The kernel exposes:

- a Go CLI in `core/cmd/helm-ai-kernel`
- an HTTP API and OpenAI-compatible proxy surface
- an MCP server surface for governed tool access
- route-backed Console workspaces for boundary records, MCP registry/auth profiles, sandbox grants, approvals, budgets, conformance, evidence envelopes, telemetry exports, and coexistence manifests

The proxy path is the easiest way to insert HELM into an existing client without changing application control flow. Framework adapters and coexistence manifests must call HELM before dispatch; passive tracing is non-authoritative.

## 3. Receipts and Evidence

Every retained proof surface is built around durable, verifiable records:

- signed receipts
- proof graph data structures
- exported evidence bundles
- offline verification
- tamper-evident boundary checkpoints and optional DSSE, JWS, in-toto, SLSA, and Sigstore envelope wrappers over HELM-native roots

The export and verify paths are implemented in `core/pkg/evidence*`, `core/pkg/proofgraph/`, `core/pkg/replay/`, and supporting crypto packages.

## 4. Contracts and Schemas

Public contracts are kept in:

- `api/openapi/helm.openapi.yaml`
- `protocols/`
- `schemas/`

The SDK HTTP client/types layer is generated from the OpenAPI contract. Protobuf message bindings are generated from `protocols/proto/` where a language SDK ships them. The protocol and schema directories document the retained on-disk and over-the-wire shapes the kernel uses.

## 5. SDKs

The public client surface is:

- Go SDK in `sdk/go`
- Python SDK in `sdk/python`
- TypeScript SDK in `sdk/ts`
- Rust SDK in `sdk/rust`
- Java SDK in `sdk/java`

The repository ships one bundled interactive client: `apps/console`, the HELM AI Kernel Console. It is a self-hostable operator surface over the kernel contracts, CLI/API JSON output, SDKs, evidence bundles, and conformance reports. No second browser UI, hosted SaaS control plane, static viewer, Node CLI wrapper, or generated browser-rendered report is shipped from this repository.

## Directory Layout

| Path | Role |
| --- | --- |
| `core/` | Kernel implementation, CLI, API, proxy, verification |
| `sdk/` | Public generated SDKs and their tests |
| `protocols/` | Protocol sources and specifications |
| `schemas/` | JSON schemas for receipts, work, connectors, and related contracts |
| `tests/conformance/` | Conformance profile and verification suite |
| `deploy/helm-chart/` | Kubernetes deployment chart |

## Non-Goals of the OSS Repo

This repository does not present a hosted SaaS control plane, a second product UI surface, a bundled viewer, or private operational material. The OSS shape is a kernel, its CLI, its contracts, its SDKs, and the self-hostable `apps/console` operator surface.


---
title: "Canonical Diagrams"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/architecture/canonical-diagrams"
source: "helm-ai-kernel/docs/architecture/canonical-diagrams.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/architecture/canonical-diagrams.md"
section: "architecture"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-13"
checksum_sha256: "sha256:4277b03557f650b279fd51a917464a29e1198dd8bbb9abf85c107205f1bbec85"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM AI Kernel Canonical Diagrams

This page defines the public diagram doctrine for HELM AI Kernel. Diagrams must show the implemented execution boundary: agents propose actions, deterministic HELM systems evaluate authority before dispatch, and signed receipts plus EvidencePacks make the result verifiable offline.

## Audience

This page is for maintainers writing, reviewing, or embedding public HELM AI Kernel diagrams. It defines the canonical visual language for the execution boundary, MCP quarantine, receipts, ProofGraph, EvidencePack, and sandbox grants.

## Outcome

Every public HELM AI Kernel diagram should describe a current source-backed mechanism and avoid implying hosted operations, commercial account management, or roadmap-only control planes. If a diagram cannot be traced to the source map below, keep it out of current-state docs.

## Source Truth

This page is owned by `docs/source-inventory.manifest.json`, `docs/public-docs.manifest.json`, `docs/EXECUTION_SECURITY_MODEL.md`, `docs/INTEGRATIONS/mcp.md`, `core/pkg/kernel/README.md`, and `core/pkg/proofgraph/README.md`.

Do not use HELM AI Kernel diagrams to describe commercial products, hosted services, organization compilers, portfolio systems, private domains, or roadmap-only surfaces.

## Diagram Rules

- Use `ALLOW`, `DENY`, and `ESCALATE` for current runtime decisions.
- Use `Console` for the self-hostable OSS UI.
- Use `EvidencePack` and `ProofGraph` for canonical evidence terms.
- Show MCP quarantine as fail-closed before tool dispatch.
- Mark any non-implemented idea as roadmap outside current-state docs.
- Do not imply hosted operations, private account-management, non-OSS extension, or tenant-admin capabilities ship in HELM AI Kernel.

## Review Checklist

Before publishing a HELM AI Kernel diagram, check the direction of authority. The
agent, model, MCP client, or OpenAI-compatible client may propose work, but it
does not authorize the side effect. The authorization step belongs inside the
HELM AI Kernel execution boundary, and dispatch appears only after an `ALLOW`
decision. `DENY` and `ESCALATE` are terminal for the proposed side effect until
new policy, evidence, or approval is supplied.

Check the evidence path next. A diagram that shows execution should also show a
signed receipt, ProofGraph event, or EvidencePack export unless the page is
explicitly about pre-execution discovery. Public proof should be represented by
hashes, signatures, inclusion proofs, deterministic redaction, or offline
verification, not by raw secrets or customer payloads.

Finally, check product boundaries. HELM AI Kernel diagrams may show the CLI, kernel,
self-hostable Console, MCP firewall, OpenAI-compatible proxy, sandbox grants,
schemas, receipts, and conformance harness. Commercial tenant administration,
hosted billing, private connectors, and portfolio operating systems belong in
their own docs and must not appear as current HELM AI Kernel surfaces.

Use one diagram per claim. If a page needs to explain both MCP quarantine and
EvidencePack verification, show those as separate flows or explicitly label the
handoff between them. Dense diagrams invite readers to infer authority that the
kernel does not grant.

## 1. Execution Boundary

```text
Agent / MCP client / OpenAI-compatible client
        |
        v
Proposed tool call or model request
        |
        v
HELM AI Kernel execution boundary
identity -> policy bundle -> PEP -> CPI -> sandbox grant -> MCP approval state
        |
        v
ALLOW / DENY / ESCALATE
        |
        v
Dispatch only on ALLOW
        |
        v
Signed receipt -> ProofGraph -> EvidencePack
```

Plain version: the model or agent proposes. HELM checks. The side effect runs only after `ALLOW`. Every outcome records a signed receipt.

## 2. Models Propose, HELM Governs

```mermaid
sequenceDiagram
    participant Agent as Agent / client
    participant PEP as PEP boundary
    participant CPI as CPI validator
    participant Tool as Tool / upstream
    participant PG as ProofGraph

    Agent->>PEP: Proposed action
    PEP->>CPI: Validate identity, policy, sandbox, and MCP state
    CPI-->>PEP: ALLOW / DENY / ESCALATE
    alt ALLOW
        PEP->>Tool: Dispatch side effect
        Tool-->>PEP: Result
        PEP->>PG: Signed allow receipt
    else DENY
        PEP->>PG: Signed denial receipt
    else ESCALATE
        PEP->>PG: Signed escalation receipt
    end
```

`ESCALATE` stops execution and asks for more facts, policy, or human approval. It must not dispatch the side effect.

## 3. MCP Quarantine Lifecycle

```text
Discovered MCP server
        |
        v
Quarantined by default
        |
        v
Metadata and schema inspection
        |
        v
Risk classification
        |
        v
Approval record
server identity · endpoint · tools · approver · receipt · expiry
        |
        v
Policy-bound active state
        |
        v
ALLOW / DENY / ESCALATE per tool call
        |
        v
Signed receipt + ProofGraph event
```

If registry state, approval state, metadata, schema validation, or policy evaluation is unavailable, the boundary fails closed.

## 4. Evidence And Redaction

```text
Sensitive payloads
PII · secrets · customer data
        |
        v
Off-graph storage or redaction
ciphertext hash · blob ref · policy ref
        |
        v
ProofGraph
hashes · signatures · decisions · inclusion proofs
        |
        v
EvidencePack
minimal replay slice
        |
        v
Offline verification
```

Proof should not require publishing secrets. Public proof uses hashes, signatures, decision records, inclusion proofs, and deterministic redactions.

## 5. Sandbox Grants

```text
Requested execution
        |
        v
Sandbox profile
runtime · image/template digest · filesystem preopens · env policy · network policy
        |
        v
Grant hash
        |
        v
PEP / CPI decision
        |
        v
ALLOW / DENY / ESCALATE
        |
        v
Signed receipt
```

Sandbox grants should expose `grant_id`, runtime, runtime version, backend profile, image or template digest, filesystem preopens, environment variables, network policy, resource limits, policy epoch, and `grant_hash`.

## 6. Connector Drift

```text
Connector response
        |
        v
Schema hash / contract check
        |
        v
Drift detected
        |
        v
DENY with connector contract reason
        |
        v
Execution thread halts safely
        |
        v
Out-of-band remediation
```

Runtime drift is not healed probabilistically. Compatibility shims are proposed out of band, simulated offline, and approved before replay.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A diagram shows side effects before `ALLOW` | Rewrite the flow so dispatch happens only after the PEP/CPI decision. |
| A diagram mentions hosted tenants or commercial control planes | Move it out of HELM AI Kernel current-state docs or mark it as non-OSS context. |
| A diagram uses old verdict terms | Replace them with `ALLOW`, `DENY`, and `ESCALATE` unless the page is explicitly describing compatibility migration. |
| A diagram cannot be traced to a source file | Remove it or add the missing source-backed doc before publication. |

When in doubt, diagrams should be narrower and more literal. The public HELM AI Kernel diagram set exists to make execution boundaries, quarantine, signed receipts, and offline verification easier to inspect, not to describe future product strategy.


---
title: "Cognitive Firewall Pattern"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/architecture/cognitive-firewall"
source: "helm-ai-kernel/docs/architecture/cognitive-firewall.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/architecture/cognitive-firewall.md"
section: "architecture"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:cbbcaa9a59615df146c54f0c5e8aa70430d5ac4ae6a657f211d0434bb50408e7"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Cognitive Firewall Split-Compute Pattern

## Audience

Architecture reviewers evaluating the fail-closed execution firewall pattern and its HELM AI Kernel implementation boundaries.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/architecture/cognitive-firewall`
- Source document: `helm-ai-kernel/docs/architecture/cognitive-firewall.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

Source: Qianlong Lan and Anuj Kaul, "The Cognitive Firewall: Securing Browser Based AI Agents Against Indirect Prompt Injection Via Hybrid Edge Cloud Defense", arXiv:2603.23791.

The HELM AI Kernel mapping keeps the paper's three-stage split:

| Paper stage | HELM AI Kernel mapping |
| --- | --- |
| Local visual Sentinel | `BrowserSplitObservation`: URL, DOM hash, visual-text hash, Sentinel risk, findings |
| Cloud Deep Planner | `BrowserSplitPlan`: tool intent, side-effect flag, planner reference hash |
| Deterministic Guard | `BrowserSplitAdapter`: domain policy, Sentinel risk gate, planner-reference gate, ProofGraph intent node |

The adapter lives at `core/pkg/runtimeadapters/browser_split.go`. It does not ship a browser UI or cloud planner. Instead, it defines the boundary contract a browser extension, OpenClaw-style gateway, or MCP browser tool can use when forwarding an already-scanned action into HELM governance.

## Egress Gate Composition

The split-compute guard should run before browser side effects are dispatched:

1. The browser-side Sentinel hashes the DOM and visual text, scores presentation-layer prompt-injection risk, and forwards only risk metadata and hashes.
2. The planner returns a tool intent with `planner_ref` instead of raw chain-of-thought.
3. `BrowserSplitAdapter` denies side-effecting actions when the Sentinel risk exceeds policy, when the destination is outside domain scope, or when the planner reference is missing.
4. Deployments that also use Guardian should pass the same destination as `destination`, the page text hash as evidence, and tainted browser content as `user_input`/`source_channel=TOOL_OUTPUT` so Guardian's threat scanner and egress checker can produce the final signed decision.

This keeps semantic reasoning and execution authority split: the planner may propose, but the deterministic guard owns the last pre-dispatch decision.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        intent["Agent intent"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        normalize["Normalize context"]
        policy["Policy decision"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        permit{"Permit?"}
        execute["Execute tool"]
        block["Block effect"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["Receipt"]
        verify["Verification"]
    end

    %% Operational Flow Edges
    intent --> normalize
    normalize --> policy
    policy --> permit
    permit -->|allow| execute
    permit -->|deny| block
    execute --> receipt
    block --> receipt
    receipt --> verify

    %% Premium Styling Rules
    style normalize fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style policy fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style permit fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style execute fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style block fill:#e53e3e,stroke:#9b2c2c,stroke-width:2px,color:#fff
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```



<!-- docs-depth-final-pass -->

## Implementation Checklist

A change to this pattern is complete only when the adapter test covers allow, deny, and missing-planner-reference paths, the receipt records the Sentinel risk and planner reference, and the public page still describes the browser UI and cloud planner as integration points rather than bundled HELM AI Kernel features. Keep examples focused on the boundary contract: input hashes, domain scope, side-effect flag, destination, policy threshold, and resulting receipt. If a downstream browser extension or MCP browser tool adds richer context later, update this page by linking to that source-owner document instead of widening the core adapter claim.


---
title: "eIDAS QTSP Anchoring"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/architecture/eidas-qtsp"
source: "helm-ai-kernel/docs/architecture/eidas-qtsp.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/architecture/eidas-qtsp.md"
section: "architecture"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:f5c2ee389c16967e470e219fa92897c914ccb12a91478043f47c2d4ee79ecc19"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# eIDAS QTSP Anchoring

## Audience

Security and compliance reviewers checking the current eIDAS/QTSP evidence mapping limits for HELM AI Kernel.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/architecture/eidas-qtsp`
- Source document: `helm-ai-kernel/docs/architecture/eidas-qtsp.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

helm-ai-kernel timestamps every evidence pack against an RFC 3161 anchor. For
EU regulated workloads, the anchor must be a **Qualified Trust Service
Provider** (QTSP) under [Regulation (EU) No 910/2014 (eIDAS)](https://eur-lex.europa.eu/eli/reg/2014/910/oj),
giving the timestamp **presumption of legal reliability** in every EU
member state.

This document covers:

- Why eIDAS qualified timestamps matter for the EU AI Act high-risk track
- How helm-ai-kernel validates qualified timestamps against the EU LOTL
- Operator workflow: configuring a QTSP, refreshing trust, verifying
- Recognized QTSP options + a fallback for testing

## Why qualified timestamps

Article 12 of the EU AI Act requires high-risk AI systems to keep
automatic logs of operations across their lifecycle. Article 50 obligates
providers to mark the time and provenance of system outputs. Article 14
on human oversight implicitly demands a tamper-evident audit trail.

A plain RFC 3161 timestamp answers *"the receipt existed at time T"*. A
**qualified** RFC 3161 timestamp under eIDAS adds a legal layer: any
court in the EU treats the timestamp as authentic until rebutted, no
extra evidence required (Art. 41(2) of eIDAS). For an AI execution
governance kernel, that is the difference between a useful audit trail
and a *defensible* audit trail.

## Architecture

### Anchor pipeline

Each receipt-anchoring decision composes optional layers:

1. **Internal proof DAG** — Lamport-ordered causal graph in
   `core/pkg/proofgraph/`. Always present.
2. **Sigstore Rekor** — public transparency log entry in
   `core/pkg/proofgraph/anchor/rekor.go`. Optional.
3. **RFC 3161 timestamp** — generic time-stamp authority in
   `core/pkg/proofgraph/anchor/rfc3161.go`. Optional.
4. **eIDAS qualified timestamp** — restricted variant of (3), validated
   against the EU LOTL in `core/pkg/proofgraph/anchor/eidas.go`. Optional
   but **required** when `qtsp_required: true` in the loaded reference
   pack (see `reference_packs/eu_ai_act_high_risk.v1.json`).

The verifier accepts any subset; the strictest verifier (`helm-ai-kernel verify
--require-eidas`) demands the eIDAS layer.

### LOTL refresh

The EU **List of Trusted Lists** (LOTL) is a signed XML document that
enumerates per-member-state trusted lists; each member-state list
enumerates that country's qualified TSAs.

`core/pkg/trust/eu_trusted_list.go` fetches and validates the LOTL on a
configurable interval (default 24h, controlled by
`qtsp_lotl_freshness_hours` in the loaded pack). Validation:

1. Fetch the LOTL XML from the configured endpoint
   (default `https://ec.europa.eu/tools/lotl/eu-lotl.xml`).
2. Verify the LOTL XML signature against the EU Commission's pinned
   signing certificate set.
3. For each pointer in the LOTL, fetch and verify the country-level
   trusted list signature.
4. Extract the X.509 certificate set authorized for qualified
   timestamping.
5. Cache the parsed roots; expose them to `eidas.go` for chain
   validation.

A stale LOTL beyond the freshness threshold blocks `helm-ai-kernel verify
--require-eidas`. The status is observable via:

```bash
helm-ai-kernel trust eu-list status
```

### Receipt anchor

When an evidence pack is assembled with a configured QTSP endpoint:

1. The receipt's pre-signature canonical form (JCS RFC 8785 + SHA-256)
   becomes the message imprint of an RFC 3161 TSP request.
2. The QTSP returns a `TimeStampToken` (RFC 3161 §2.4) signed by a
   certificate that chains to a root in the EU LOTL.
3. The `EIDASAnchor` validator parses the token, walks the chain, and
   confirms termination at a LOTL root.
4. The validated token is embedded next to the existing Rekor / RFC 3161
   anchor in the proof-graph node.

A modified receipt invalidates the message imprint; a fabricated token
fails chain validation; an expired LOTL fails the freshness gate.

## Operator workflow

### Configure a QTSP

Set the QTSP endpoint and (optional) refresh interval in your kernel
config:

```yaml
trust:
  eu_lotl:
    endpoint: https://ec.europa.eu/tools/lotl/eu-lotl.xml
    refresh_hours: 24
  qtsp:
    endpoint: https://qtsp.example.eu/tsa
    digest_algorithm: SHA-256
```

### Verify with eIDAS strictness

```bash
helm-ai-kernel verify --require-eidas eu-evidence-pack.tar
```

Failure modes (each emits a structured diagnostic):

- `eidas: anchor missing` — receipt lacks an eIDAS qualified token.
- `eidas: chain does not terminate at LOTL root` — token signed by a
  TSA not on any member-state trusted list.
- `eidas: lotl stale` — local LOTL cache older than
  `qtsp_lotl_freshness_hours`.
- `eidas: lotl signature invalid` — LOTL fetched but its signature
  cannot be validated against the pinned EU Commission key set.

### Inspect the trust state

```bash
helm-ai-kernel trust eu-list status
```

Output: last-refresh timestamp, LOTL signer, count of qualified TSAs by
member state, and any expired entries.

## Recognized QTSP options

helm-ai-kernel does not maintain commercial QTSP relationships. The list below
is informational. Verify against the
[official Trusted List Browser](https://eidas.ec.europa.eu/efda/tl-browser/)
before depending on a specific provider in production.

| Provider | Country | Endpoint hint |
| --- | --- | --- |
| SK ID Solutions | Estonia | timestamping service per their service catalog |
| Sectigo Qualified Time Stamping | Multi-EU | per Sectigo documentation |
| Trustpro Qualified TSA | Multiple | per Trustpro service portal |
| Buypass AS | Norway (EEA) | per Buypass service portal |

For local testing, [FreeTSA](https://www.freetsa.org/) provides a
non-qualified RFC 3161 endpoint suitable for the
`core/pkg/proofgraph/anchor/rfc3161.go` path. It does **not** chain to
the EU LOTL and therefore fails `--require-eidas`.

## Reference pack semantics

When a loaded reference pack carries
`evidence_requirements.qtsp_required: true` (e.g.
`reference_packs/eu_ai_act_high_risk.v1.json`), the kernel:

- Refuses to mint receipts at runtime if no QTSP endpoint is configured.
- Refuses to verify packs missing eIDAS anchors at the boundary.
- Surfaces an actionable error rather than silently downgrading.

This makes QTSP enforcement a static property of the deployment plus its
loaded packs, not a runtime flag the operator can forget.

## See also

- [Verification](/helm-ai-kernel/verification) — full `helm-ai-kernel verify` reference
- [Architecture](/helm-ai-kernel/architecture) — kernel and anchor architecture
- [`core/pkg/proofgraph/anchor/eidas.go`](../../core/pkg/proofgraph/anchor/eidas.go) — implementation
- [`core/pkg/trust/eu_trusted_list.go`](../../core/pkg/trust/eu_trusted_list.go) — LOTL validator

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        qtsp["Optional QTSP workflow"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        auditor["Auditor / verifier"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        action["Governed action"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["HELM receipt"]
        evidence["Evidence pack"]
        legal["Legal signature layer"]
    end

    %% Operational Flow Edges
    action --> receipt
    receipt --> evidence
    evidence --> auditor
    evidence --> qtsp
    qtsp --> legal

    %% Premium Styling Rules
    style action fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style evidence fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style auditor fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style legal fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


---
title: "Policy Languages — CEL, Rego, Cedar"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/architecture/policy-languages"
source: "helm-ai-kernel/docs/architecture/policy-languages.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/architecture/policy-languages.md"
section: "architecture"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:f33a5fac42d5cbd7d851be96026676392fb751299f06d405398139a4ad4b0239"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Policy Languages — CEL, Rego, Cedar

## Audience

Policy authors and runtime maintainers comparing supported policy-language inputs with current enforcement behavior.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/architecture/policy-languages`
- Source document: `helm-ai-kernel/docs/architecture/policy-languages.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

helm-ai-kernel accepts policy sources written in three languages and routes
them through one enforcement boundary. The kernel never branches on
language at decision time; only the multi-language registry in
[`core/pkg/policybundles/registry.go`](../../core/pkg/policybundles/registry.go)
does, and only at compile/load.

## CEL — historical baseline

[Common Expression Language](https://github.com/google/cel-spec). Single
expression returning a verdict envelope. Carried via the existing
`core/pkg/celcheck/` and `core/pkg/policybundles/builtin.go` pipeline.

- Inputs: `request.action`, `request.principal.roles`, `request.context`.
- Strengths: fastest evaluation, smallest dependency footprint, best
  fit for attribute-mostly rules.
- Weaknesses: limited control flow; nested ternaries get unwieldy.
- Example: [`examples/policies/cel/example.cel`](../../examples/policies/cel/example.cel).

## OPA / Rego — procurement standard

[Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) via
[`core/pkg/policybundles/rego/`](../../core/pkg/policybundles/rego/).

- Inputs: top-level `input` document.
- Strengths: rich set semantics, partial evaluation, mature ecosystem.
- Determinism guard:
  [`core/pkg/policybundles/rego/capabilities.json`](../../core/pkg/policybundles/rego/capabilities.json)
  forbids `http.send`, `time.now_ns`, `rand.intn`, and
  `crypto.x509.parse_certificates`.
- Example: [`examples/policies/rego/example.rego`](../../examples/policies/rego/example.rego).

## Cedar — entity-shape model

[Cedar](https://docs.cedarpolicy.com) via
[`core/pkg/policybundles/cedar/`](../../core/pkg/policybundles/cedar/).

- Inputs: principal/action/resource as `EntityUID` (`Type::"id"`); an
  optional entities document declares parent chains for the `in`
  operator.
- Strengths: explicit entity types, native role/group reasoning, AWS
  Verified Permissions interop.
- Example:
  [`examples/policies/cedar/example.cedar`](../../examples/policies/cedar/example.cedar)
  with companion entities at
  [`examples/policies/cedar/entities.json`](../../examples/policies/cedar/entities.json).

## Side-by-side: same logical rule

*Anyone may view; only admins may delete; default deny.*

```cel
request.action == "view"
  ? {"verdict": "ALLOW"}
  : (request.action == "delete" && ("admin" in request.principal.roles)
       ? {"verdict": "ALLOW"}
       : {"verdict": "DENY"})
```

```rego
package helm.policy
import rego.v1

default decision := {"verdict": "DENY"}
decision := {"verdict": "ALLOW"} if { input.action == "view" }
decision := {"verdict": "ALLOW"} if {
  input.action == "delete"
  "admin" in input.principal.roles
}
```

```cedar
permit(principal, action == Action::"view", resource);
permit(principal, action == Action::"delete", resource)
when { principal in Role::"admin" };
```

A regression test under `tests/conformance/policy-langs/` (Workstream
F1) will assert byte-identical decisions across all three on a
50-policy reference suite.

## Edge-case behavior

| Edge case | CEL | Rego | Cedar |
| --- | --- | --- | --- |
| Negation of undefined | undefined propagates | `not` is well-defined | requires explicit guards |
| Set membership on missing list | error / `false` | empty set | `in` returns `false` |
| Numeric overflow | int64 wraps | bignum-correct | int64 wraps |
| Role / group reasoning | flat `in roles` | set semantics + virtual docs | parent-chain via entities |
| Time predicates | `request.now()` injected | `time.now_ns` forbidden; use `input.now` | supply `context.now` |
| Recursion | not allowed | partial-eval supported | not allowed |

## Non-determinism rules (uniform)

Across all three languages, helm-ai-kernel enforces:

- No network I/O during evaluation.
- No random number generation.
- No system clock reads; the kernel injects `now`.
- No filesystem reads.
- No environment-variable reads.

Rego uses OPA's capabilities file. CEL uses the curated function set in
`core/pkg/celcheck/`. Cedar's spec excludes these operations natively.

## Choose your lane

| You want | Pick |
| --- | --- |
| Smallest footprint, fastest eval, attribute-mostly rules | **CEL** |
| Procurement-team-already-on-OPA, rich set semantics | **Rego** |
| Entity-rich auth, AWS Verified Permissions interop | **Cedar** |

Bundle manifests carry `language: cel | rego | cedar`. The kernel loads
+ dispatches via
[`core/pkg/policybundles/registry.go`](../../core/pkg/policybundles/registry.go).
The `helm-ai-kernel bundle build` subcommand auto-detects from file extension when
`--language` is omitted.

## See also

- [`core/pkg/policybundles/registry.go`](../../core/pkg/policybundles/registry.go) — language dispatch
- [Conformance Profile v1](/helm-ai-kernel/conformance) — required behavior across implementations
- [Verification](/helm-ai-kernel/verification) — verifying a built bundle's hash

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        cel["CEL"]
        rego["Rego"]
        cedar["Cedar"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        input["Canonical policy input"]
        decision["Normalized decision"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["Signed receipt"]
    end

    %% Operational Flow Edges
    input --> cel
    input --> rego
    input --> cedar
    cel --> decision
    rego --> decision
    cedar --> decision
    decision --> receipt

    %% Premium Styling Rules
    style input fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style decision fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


---
title: "Benchmarks"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/benchmarks"
source: "helm-ai-kernel/docs/BENCHMARKS.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/BENCHMARKS.md"
section: "supporting-material"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:aa607211b821aa1cd5ac99f81f2c5a5804dc3c893117fe4a60cddb73530e5910"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Benchmarks

## Audience

Maintainers comparing local benchmark harnesses and reported performance measurements against source-backed results.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/benchmarks`
- Source document: `helm-ai-kernel/docs/BENCHMARKS.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

This scheme maps the main sections of Benchmarks in reading order.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["Benchmarks"]
        A["Targets"]
        B["What the Harness Covers"]
        C["Output"]
        D["Test-case count (referenced by pitch decks)"]
        E["Machine-readable output"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C
    C --> D
    D --> E

    %% Premium Styling Rules
```


The benchmark harness measures retained kernel paths locally. This page documents how to run the harness, not a frozen set of numbers.

## Targets

```bash
make bench
make bench-report
```

## What the Harness Covers

The benchmark code in `core/benchmarks/` focuses on the hot paths used by the OSS kernel, including decision evaluation, signing, and persistence-related work.

## Output

`make bench-report` writes a local JSON report under `benchmarks/results/`. That path is treated as a generated artifact, not as committed repository truth.

## Test-case count (referenced by pitch decks)

As of 2026-04-18, `helm-ai-kernel/core` ships **8,930 Go test cases**, counted via:

```bash
cd core && go test -list '.*' ./... 2>&1 | grep -c '^Test'
```

This is the number the Mindburn Labs pitch decks cite under "tests" (see `docs/ai/deck-facts.md` row `h3` in the monorepo). Rerun the command above to refresh. Any deck edit claiming a different number must update this doc and the ledger in the same pass.

## Machine-readable output

## Reproducing Results

For component-level work:

```bash
cd core
go test -bench=. -benchmem ./pkg/crypto/ ./pkg/store/ ./pkg/guardian/ ./benchmarks/
```

<!-- docs-depth-final-pass -->

## Benchmark Evidence Checklist

Every benchmark claim must name the runner, fixture, hardware or container profile, sample size, and validation command. Treat benchmark numbers as release-scoped facts: keep the command output with the release evidence pack and update this page only after the same command passes against the current tree. For developer trust, include both the success metric and the failure interpretation. A slow verification run should point to verifier profiling and receipt bundle size; an unexpected pass/fail split should point to the conformance fixture and ProofGraph row that produced it. Avoid competitive claims unless the compared artifact, version, and command are reproducible from public sources.

<!-- docs-depth-final-pass-extra -->
 Keep benchmark tables paired with raw artifacts and exact commit SHA. If the result cannot be reproduced from a clean checkout, move it to a lab note instead of the public benchmark page.


---
title: "HELM AI Kernel Changelog"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/changelog"
source: "helm-ai-kernel/CHANGELOG.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/CHANGELOG.md"
section: "helm-ai-kernel"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-19"
checksum_sha256: "sha256:1dbc5c1024ffa61cd7de569bfacdda87e78312880f84f93dea5f3de8100a1278"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Changelog

## Audience

This changelog is for developers, operators, security reviewers, and evaluators tracking public HELM AI Kernel interface changes across releases.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/changelog`
- Source document: `helm-ai-kernel/CHANGELOG.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

## Diagram

This scheme maps the main sections of HELM AI Kernel Changelog in reading order.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["HELM AI Kernel Changelog"]
        A["[Unreleased]"]
        B["[0.5.4] - 2026-05-20"]
        C["[0.5.3] - 2026-05-19"]
        D["[0.5.2] - 2026-05-19"]
        E["[0.5.1] - 2026-05-18"]
        F["[0.5.0] - 2026-05-13"]
        G["[0.4.0] - 2026-04-25"]
        H["Validation"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H

    %% Premium Styling Rules
```


All notable changes to the retained HELM AI Kernel surface are documented here. Public entries focus on developer-visible interfaces, compatibility, verification, SDKs, and security-relevant documentation.

## [Unreleased]

### Added
- **UCS v1.5 Super-Sovereign Execution Standard**: Scaffolded zero-knowledge execution proof boundaries and Trusted Execution Environment (TEE) sealed secrets vault.
- **zkVM Guest Safety Checker**: Introduced the `ZKVMGuestSafetyChecker` and `SafetyGuestProgram` inside `pkg/crypto/zk` to simulate AST static analysis inside zero-knowledge execution enclaves.
- **TEE Secrets Enclave**: Introduced `SovereignKMSVault` and `SecretProxyFilter` inside `pkg/crypto/tee` to enforce hardware-sealed secrets isolation and inline proxy token injection with constant-time verification.

## [0.5.4] - 2026-05-20

Published at <https://github.com/Mindburn-Labs/helm-ai-kernel/releases/tag/v0.5.4>.

Chart page polish on ArtifactHub. No kernel binary or API changes;
the v0.5.3 work landed three of four chart-page badges -- this release
lights the fourth and makes the values reference panel useful.

- Moved ArtifactHub package metadata (changes, images, links, license,
  prerelease, containsSecurityUpdates, signKey, category) from
  `deploy/helm-chart/artifacthub-pkg.yml` into `Chart.yaml` annotations,
  which is the only file ArtifactHub reads for `kind=helm`. Lights the
  Changelog badge that stayed grey under v0.5.3.
- Annotated every field in `deploy/helm-chart/values.schema.json` with
  a description. The "Values schema reference" panel on the chart's
  ArtifactHub page now shows a one-line description per setting instead
  of an empty pane.
- Deleted the now-redundant `artifacthub-pkg.yml`.

## [0.5.3] - 2026-05-19

Published at <https://github.com/Mindburn-Labs/helm-ai-kernel/releases/tag/v0.5.3>.

Chart distribution polish. No kernel binary or API changes; this release
lights up the previously-grey ArtifactHub badges on the chart page.

- Added `deploy/helm-chart/values.schema.json` (JSON Schema draft 2020-12)
  covering every documented field in `values.yaml`. Enables IDE autocomplete
  for chart values, lets `helm install` reject malformed values before
  reaching the cluster, and lights the ArtifactHub Values Schema badge.
- Added `deploy/helm-chart/artifacthub-pkg.yml` with display name, license
  tag, structured changelog, container image inventory (main + slim,
  multi-arch), and six external project links. Lights the ArtifactHub
  Changelog badge and replaces the otherwise sparse Chart.yaml description.
- Added `artifacthub-repo` release job that pushes `artifacthub-repo.yml`
  as an OCI artifact (tag `:artifacthub.io`) into the chart namespace so
  ArtifactHub picks up the Verified Publisher UID for the OCI-backed
  Helm repository.
- Added `cosign-chart` release job that signs the chart OCI artifact by
  digest with sigstore keyless OIDC, lighting the ArtifactHub Signed badge.

## [0.5.2] - 2026-05-19

Published at <https://github.com/Mindburn-Labs/helm-ai-kernel/releases/tag/v0.5.2>
on 2026-05-19T16:13:38Z.

- Fixed default boundary policy initialization so the retained production
  surface starts fail-closed when default policy material is missing or invalid.
- Anchored KMS keystore state under the configured runtime data directory and
  added regression coverage for that path.
- Wired release build metadata into container builds and disabled the phantom
  chart metrics port by default.
- Refreshed Artifact Hub repository metadata and bumped the Helm chart release
  contract to `0.5.2` / `v0.5.2`.
- Kept release asset export and verification output visible during staging so
  failing commands are diagnosable from workflow logs.

## [0.5.1] - 2026-05-18

Published at <https://github.com/Mindburn-Labs/helm-ai-kernel/releases/tag/v0.5.1>.

- Fixed tag-driven release asset staging so release binaries, SBOM, OpenVEX,
  Homebrew formula metadata, and release attestations use the tag version
  instead of falling back to `VERSION` when a tag is cut before the file is
  bumped.
- Fixed audit EvidencePack export so every file listed in `00_INDEX.json`,
  including `01_SCORE.json.sha256`, is preserved in exported tar archives and
  verified during `make release-assets`.
- Added release staging diagnostics for exact failing commands and conformance
  gate failures, and require exact OpenVEX documents for tag release assets.
- Normalized pull-request Scorecard SARIF categories so GitHub code scanning
  sees the same `supply-chain/branch-protection` configuration on PR refs as it
  sees on `main`.
- Moved first-party GitHub setup actions to Node 24-capable pinned SHAs and
  configured Go workflow caching against `**/go.sum` for the monorepo layout.
- Downgraded the local release-smoke missing-cosign message from a GitHub
  warning annotation to a plain informational log unless cosign bundles are
  explicitly required.
- Bumped source, CLI fallback, SDK package manifests, Helm chart `appVersion`,
  OpenAPI version metadata, generated SDK version comments, Console visible
  version, and launch verification scripts to `0.5.1`.

## [0.5.0] - 2026-05-13

Published at <https://github.com/Mindburn-Labs/helm-ai-kernel/releases/tag/v0.5.0>
on 2026-05-13T09:15:00Z.

- Bumped source, CLI fallback, OpenAPI, SDK package manifests, generated SDK
  version comments, Helm chart metadata, and Console visible version to
  `0.5.0`.
- Added canonical release asset staging through `make release-assets`, including
  five CLI binaries, checksums, SBOM, OpenVEX, release attestation,
  `evidence-pack.tar`, `helm-ai-kernel.mcpb`, `helm-ai-kernel.rb`, and complete sample policy
  material.
- Fixed offline EvidencePack verification for canonical
  `02_PROOFGRAPH/receipts/` packs while preserving legacy root `receipts/`
  compatibility.
- Made audit export include `04_EXPORTS`.
- Added local launch-smoke coverage for MCP wrapping and the HTTP proxy using
  checked-in local fixtures with no external side effects.
- Retargeted Homebrew release workflow/docs to `mindburnlabs/homebrew-tap`.
- Corrected the release baseline: no public `v0.4.1` GitHub Release exists, so
  `v0.4.0` is the actual public baseline for the `v0.5.0` delta.

- Established `helm.docs.mindburn.org` as the canonical product docs surface while keeping HELM AI Kernel source docs in this repository.
- Reduced duplicate public docs routes so `/helm-ai-kernel` is the Kernel portal entry and older `/oss` links redirect.
- Expanded the OpenAI-compatible proxy, MCP, SDK, OWASP mapping, verification, publishing, and compatibility docs for agent-readable exports.
- Normalized the retained OSS surface around the kernel, contracts, SDKs, static viewer, examples, deployment material, and verification artifacts that remain in the repository.
- Removed stale workflows, hosted-demo collateral, internal planning material, tracked binaries, and generated repository junk from the public documentation path.

## [0.4.0] - 2026-04-25

- Published the public quickstart release at
  <https://github.com/Mindburn-Labs/helm-ai-kernel/releases/tag/v0.4.0>.
- Shipped `helm-ai-kernel serve --policy` TOML policy support and local receipt APIs.
- Shipped positional `helm-ai-kernel verify <pack>` with optional `--online`.
- Shipped `helm-ai-kernel receipts tail` for SSE receipt streaming.
- Published the `release.high_risk.v3.toml` sample policy and an
  offline-verifiable `evidence-pack.tar` fixture.
- Published platform binaries for Darwin, Linux, and Windows, plus
  `SHA256SUMS.txt`, `sbom.json`, `helm-ai-kernel.mcpb`, `helm-ai-kernel.rb`, and
  `release-attestation.json`.
- Documented that the included `evidence-pack.tar` verifies offline and reports
  `anchor offline`; public proof anchoring depends on the Titan proof deployment
  and public proof credentials.


---
title: "Compatibility"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/compatibility"
source: "helm-ai-kernel/docs/COMPATIBILITY.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/COMPATIBILITY.md"
section: "start-here"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:754e0bc67fbc71321d4fa538adc69cacd6b72e425295cc6880d9abdc441472cb"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Compatibility

HELM AI Kernel compatibility is the retained public surface that maps to code, examples, tests, or canonical docs. Historical experiments are not supported unless they appear in the source-backed tables below.

## Audience

This page is for developers and operators deciding whether HELM AI Kernel supports their operating system, SDK language, framework helper, policy language, deployment target, or verification path today.

## Outcome

After this page you should know which surfaces are supported, example-only, or outside HELM AI Kernel; which source paths prove each claim; and which validation commands must pass before a compatibility claim changes.

## Surface Map

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Kernel["Go kernel and CLI"]
        API["HTTP API and proxy"]
        Console["self-hostable HELM AI Kernel Console"]
        SDKs["SDKs and adapters"]
        Starters["provider starters"]
        Deploy["Docker and Kubernetes"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        Policy["CEL, Rego, Cedar bundles"]
    end

    %% Operational Flow Edges
    Kernel --> API
    API --> Console
    API --> SDKs
    SDKs --> Starters
    Kernel --> Policy
    Policy --> Deploy

    %% Premium Styling Rules
    style Policy fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
```


## Source Truth

This page is backed by:

- `docs/developer-coverage.manifest.json`
- `sdk/ts/src/adapters/agent-frameworks.ts`
- `sdk/ts/src/adapters/agent-frameworks.test.ts`
- `sdk/ts/README.md`
- `examples/starters/anthropic/`
- `examples/starters/google/`
- `examples/policies/`
- `docs/architecture/policy-languages.md`
- `deploy/helm-chart/`
- `apps/console/`
- `docs/CONSOLE.md`

## Supported Public Surfaces

| Surface | Status | Proof |
| --- | --- | --- |
| Go kernel and CLI | Supported | `make build`, `make test` |
| OpenAI-compatible proxy | Supported | `core/cmd/helm-ai-kernel/proxy_cmd.go`, proxy examples |
| MCP server, OAuth scope enforcement, and bundle generation | Supported | `core/cmd/helm-ai-kernel/mcp_*`, MCP tests |
| Boundary records, MCP quarantine, sandbox grants, authz snapshots, approvals, budgets, telemetry, and coexistence APIs | Supported | `api/openapi/helm.openapi.yaml`, `core/cmd/helm-ai-kernel/route_registry.go`, `core/cmd/helm-ai-kernel/contract_routes.go` |
| Evidence export and offline verification | Supported | `core/cmd/helm-ai-kernel/export_cmd.go`, `core/cmd/helm-ai-kernel/verify_cmd.go` |
| Self-hostable HELM AI Kernel Console | Supported | `apps/console/`, `make test-console` |
| Python SDK | Supported | `make test-sdk-py` |
| TypeScript SDK and JavaScript OpenAI-compatible path | Supported | `make test-sdk-ts` |
| Go SDK | Supported | `cd sdk/go && go test ./...` |
| Rust SDK | Supported | `make test-sdk-rust` |
| Java SDK | Supported | `make test-sdk-java` |
| Docker and Docker Compose | Supported | `Dockerfile`, `docker-compose.yml` |
| Kubernetes Helm chart | Supported | `deploy/helm-chart/` |

## Framework Adapter Helpers

The TypeScript SDK ships compatibility helpers for normalizing tool-call events from common agent frameworks into HELM governance requests. These helpers are source-backed adapter helpers, not full framework runtimes and not vendor certification.

| Framework | Status | Test Surface |
| --- | --- | --- |
| LangGraph | Compatible helper | `sdk/ts/src/adapters/agent-frameworks.test.ts` |
| CrewAI | Compatible helper | `sdk/ts/src/adapters/agent-frameworks.test.ts` |
| OpenAI Agents SDK | Compatible helper | `sdk/ts/src/adapters/agent-frameworks.test.ts` |
| PydanticAI | Compatible helper | `sdk/ts/src/adapters/agent-frameworks.test.ts` |
| LlamaIndex | Compatible helper | `sdk/ts/src/adapters/agent-frameworks.test.ts` |

Validation:

```bash
make test-sdk-ts
```

## Provider Starters

| Starter | Status | Source | Validation |
| --- | --- | --- | --- |
| Anthropic starter | Example-only | `examples/starters/anthropic/` | `bash examples/starters/anthropic/ci-smoke.sh` |
| Google ADK / A2A starter | Example-only | `examples/starters/google/` | `bash examples/starters/google/ci-smoke.sh` |
| Codex starter | Example-only | `examples/starters/codex/` | `bash examples/starters/codex/ci-smoke.sh` |
| OpenAI starter | Example-only | `examples/starters/openai/` | `bash examples/starters/openai/ci-smoke.sh` |

Example-only means the repository contains a starter layout and smoke script. It does not mean HELM AI Kernel owns the provider SDK or certifies every feature of that ecosystem.

## Policy Languages

HELM AI Kernel supports CEL, Rego, and Cedar policy bundle examples.

| Language | Source example | Notes |
| --- | --- | --- |
| CEL | `examples/policies/cel/example.cel` | Small footprint and direct attribute rules. |
| Rego | `examples/policies/rego/example.rego` | Useful when teams already operate OPA/Rego workflows. |
| Cedar | `examples/policies/cedar/example.cedar`, `examples/policies/cedar/entities.json` | Requires entity context for authorization evaluation. |

Use `docs/architecture/policy-languages.md` for the longer comparison and command examples.

## Deployment Surface

The repository keeps Docker, Docker Compose, a Kubernetes Helm chart, and the self-hostable HELM AI Kernel Console. It does not ship hosted operations, a static report viewer, or tenant-admin services in HELM AI Kernel.

| Deployment | Status | Source |
| --- | --- | --- |
| Local source build | Supported | `Makefile` |
| Docker image | Supported | `Dockerfile` |
| Docker Compose | Supported | `docker-compose.yml` |
| Kubernetes Helm chart | Supported | `deploy/helm-chart/` |
| Self-hostable HELM AI Kernel Console | Supported | `apps/console/` |

## Verdict Compatibility

Current HELM AI Kernel runtime docs use `ALLOW`, `DENY`, and `ESCALATE`.
Historical docs and generated compatibility code may still contain older
verdict labels. Treat them only as migration aliases:

| Legacy label | Current meaning |
| --- | --- |
| `DEFER` | `ESCALATE` |
| `REQUIRE_APPROVAL` | `ESCALATE` |
| `APPROVAL_REQUIRED` | `ESCALATE` |

Do not use legacy verdict labels in new runtime docs, policy examples, or
quickstart paths.

## Source Build Expectations

The retained CI verifies:

- Go build and test for the kernel;
- Python SDK tests;
- TypeScript SDK tests and adapter helper tests;
- Rust SDK build and test;
- Java SDK build and test;
- fixture root verification through the Go verifier;
- docs coverage and docs truth resolution.

```bash
make test-all
make docs-coverage
make docs-truth
```

## Unsupported Claim Policy

Do not claim a language, framework, deployment target, or provider integration as supported unless one of these is true:

- `docs/developer-coverage.manifest.json` has a `supported`, `example-only`, or `experimental` row for it;
- the row points at live source paths and example paths;
- the row names the validation command that proves the claim;
- the public docs page exposes the same claim in Markdown, LLM, and MCP surfaces.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A docs page claims support that is missing here | Add or fix the row in `docs/developer-coverage.manifest.json`, then link the source, example, and validation command. |
| A framework helper is mistaken for full framework ownership | Keep the status as compatible helper unless HELM owns runnable framework integration code and tests. |
| A deployment target lacks a smoke command | Mark it example-only or not-supported until a source-backed validation command exists. |

## MCP 2026 Radar Notes

The original Linear radar item pointed at `https://modelcontextprotocol.io/roadmap`; as of April 30, 2026 that URL returns a 404 and the current source is [MCP Roadmap](https://modelcontextprotocol.io/development/roadmap). The current roadmap frames enterprise-managed auth, gateway/proxy authorization propagation, and finer-grained least-privilege scopes as active enterprise/security directions, while RFC 8707 remains the normative OAuth source for resource indicators. HELM AI Kernel implements this as an additive auth and metadata layer; protocol versions and existing tool schemas remain backward compatible.


---
title: "EU AI Act High-Risk Pack"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/compliance/eu-ai-act-high-risk-pack"
source: "helm-ai-kernel/docs/compliance/eu-ai-act-high-risk-pack.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/compliance/eu-ai-act-high-risk-pack.md"
section: "compliance"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:cbdfce26608b094f5a5d0a5c59efba059d58888888b8e65ce529ea50bee10d3d"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# EU AI Act High-Risk Pack

## Audience

Compliance reviewers using HELM AI Kernel evidence outputs to map, not certify, EU AI Act high-risk controls.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/compliance/eu-ai-act-high-risk-pack`
- Source document: `helm-ai-kernel/docs/compliance/eu-ai-act-high-risk-pack.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

This scheme maps the main sections of EU AI Act High-Risk Pack in reading order.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["EU AI Act High-Risk Pack"]
        A["Source Status"]
        B["Pack Coverage"]
        C["Validation"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C

    %% Premium Styling Rules
```


The HELM AI Kernel EU AI Act reference pack is `reference_packs/eu_ai_act_high_risk.v1.json`.

## Source Status

Primary source verified on April 30, 2026: the European Commission AI Act Service Desk timeline says the majority of AI Act rules start applying on August 2, 2026, including Annex III high-risk AI system rules, Article 50 transparency rules, innovation-support measures, and national/EU-level enforcement.

The same source notes that high-risk AI embedded in regulated products applies on August 2, 2027. The reference pack therefore distinguishes:

- `high_risk_full`: `2026-08-02`
- `high_risk_annex_i`: `2027-08-02`

## Pack Coverage

The pack maps HELM evidence requirements and policy rules to:

- Article 9 risk management;
- Article 11 technical documentation;
- Article 13 transparency;
- Article 14 human oversight;
- Annex III high-risk deployment areas.

The April 2026 MCP update also records two evidence requirements relevant to high-risk agent deployments:

- `oauth_resource_binding`: bearer tokens used at the MCP gateway are checked against the intended resource indicator;
- `tool_scope_enforcement`: per-tool scopes can be exposed in MCP metadata and enforced before execution.

These requirements complement, but do not replace, receipt signing, ProofGraph verification, AI-BOM availability, conformity-assessment evidence, and QTSP timestamp anchoring.

<!-- docs-depth-final-pass -->

## Evidence Boundary

This pack is a documentation and evidence mapping layer, not a legal conclusion. A release-ready pack should identify the receipt fields, policy bundle, evidence export, operator control, and verification command that support each mapped obligation. When the implementation changes, update the mapping by linking to schemas, tests, and example EvidencePacks instead of copying unsupported compliance language. Public docs can describe what HELM AI Kernel can produce for an evaluator; customer or legal-specific filings belong outside anonymous exports. The minimum acceptance path is: generate a governed decision, export its EvidencePack, verify the receipt offline, and show which mapped controls the exported artifact supports.


---
title: "NIST AI Agent Critical Infrastructure Alignment"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/compliance/nist-ai-agent-critical-infrastructure"
source: "helm-ai-kernel/docs/compliance/nist-ai-agent-critical-infrastructure.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/compliance/nist-ai-agent-critical-infrastructure.md"
section: "compliance"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:e02985af532eab6450c92a17bb69591603d3d05aedf4c0ef064d3517f92d7674"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# NIST AI Agent Critical Infrastructure Alignment

## Audience

Security and compliance reviewers mapping HELM AI Kernel receipts and conformance evidence to NIST critical-infrastructure concerns.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/compliance/nist-ai-agent-critical-infrastructure`
- Source document: `helm-ai-kernel/docs/compliance/nist-ai-agent-critical-infrastructure.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

This scheme maps the main sections of NIST AI Agent Critical Infrastructure Alignment in reading order.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["NIST AI Agent Critical Infrastructure Alignment"]
        A["Source Status"]
        B["Control Crosswalk"]
        C["Reference Pack Semantics"]
        D["Operator Notes"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C
    C --> D

    %% Premium Styling Rules
```


This page maps current NIST AI-agent and critical-infrastructure work to HELM AI Kernel controls.

## Source Status

NIST has not published a finalized "AI Agent - Critical Infrastructure Profile" as of April 29, 2026. The implemented HELM artifact is therefore an early alignment pack grounded in these current NIST sources:

| Source | Status | HELM use |
| --- | --- | --- |
| [NIST AI Agent Standards Initiative](https://www.nist.gov/artificial-intelligence/ai-agent-standards-initiative) | Created February 17, 2026, updated April 20, 2026 | Agent identity, authorization, secure protocol, and interoperability mapping |
| [NIST AI RMF Profile on Trustworthy AI in Critical Infrastructure concept note](https://www.nist.gov/programs-projects/concept-note-ai-rmf-profile-trustworthy-ai-critical-infrastructure) | Started April 2026, ongoing | Critical-infrastructure risk-management mapping |
| [NCCoE Software and AI Agent Identity and Authorization](https://www.nccoe.nist.gov/projects/software-and-ai-agent-identity-and-authorization) | Reviewing comments after the April 2, 2026 comment deadline | Non-human identity, delegated authority, auditing, and non-repudiation mapping |

The reference pack is `reference_packs/nist_ai_agent_cip.v1.json`. It should be treated as a concept-note alignment until NIST publishes a stable control catalog or profile.

## Control Crosswalk

| NIST direction | HELM control surface | Evidence emitted |
| --- | --- | --- |
| Agents operate securely on behalf of users | `DecisionRequest.Principal`, machine identity schemas, delegation sessions | Signed `DecisionRecord`, `AuthorizedExecutionIntent`, delegation metadata |
| Agent access and actions are authorized before execution | Guardian freeze, context, identity, egress, taint, threat, delegation, privilege, and PRG gates | Decision verdict, reason code, policy content hash, effect digest |
| Agent-to-tool protocols need secure interoperability | Connector manifests, MCP integration, effect schemas, capability packs | Tool schema reference, connector manifest hash, evidence pack export |
| Critical-infrastructure AI needs lifecycle risk management | Reference-pack overlays, effect type catalog, P0/P1/P2 ceilings, approval artifacts | ProofGraph, receipt chain, approval references, audit logs |
| Supply-chain trust must extend across AI and CI lifecycles | Pack verifier, module provenance, AI-BOM, content-addressed policy state | Pack attestation, policy hash, provenance envelope, evidence retention |

## Reference Pack Semantics

The `nist-ai-agent-cip-v1` pack contains four active programs:

1. `prog-agent-identity-authorization` - binds every autonomous action to a principal and scoped delegation authority.
2. `prog-critical-infrastructure-risk` - requires approval or fail-closed denial for high-impact critical-infrastructure effects.
3. `prog-secure-interoperable-protocols` - denies unmanaged connector and protocol surfaces.
4. `prog-supply-chain-assurance` - requires provenance and policy-content evidence for critical-infrastructure activation.

The pack deliberately uses HELM's existing reference-pack vocabulary. It does not claim NIST endorsement or final profile conformance.

## Operator Notes

For critical-infrastructure deployments, set `critical_infrastructure=true` in the policy context and bind the `nist-ai-agent-cip-v1` reference pack alongside jurisdiction and industry packs. The pack assumes:

- Agent identity is present before any side-effecting action.
- Delegated authority is validated when an agent acts for a user or another agent.
- High-risk CI effects have approval evidence before execution.
- Policy and artifact state is content-addressed.
- Evidence packs are retained long enough for incident reconstruction and audit review.


---
title: "NIST AI RMF to ISO 42001 Crosswalk"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/compliance/nist-ai-rmf-iso-42001-crosswalk"
source: "helm-ai-kernel/docs/compliance/nist-ai-rmf-iso-42001-crosswalk.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/compliance/nist-ai-rmf-iso-42001-crosswalk.md"
section: "compliance"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:155aee8413c231edbfcc042d375ed9f06f5a9907e6cd935f2241ca5b814f6433"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# NIST AI RMF to ISO 42001 Crosswalk

## Audience

Compliance reviewers comparing HELM AI Kernel evidence surfaces with NIST AI RMF and ISO 42001 control language.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/compliance/nist-ai-rmf-iso-42001-crosswalk`
- Source document: `helm-ai-kernel/docs/compliance/nist-ai-rmf-iso-42001-crosswalk.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

This scheme maps the main sections of NIST AI RMF to ISO 42001 Crosswalk in reading order.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["NIST AI RMF to ISO 42001 Crosswalk"]
        A["Source Status"]
        B["Important Limit"]
        C["Pack Semantics"]
        D["Operator Use"]
        E["Sales Language"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C
    C --> D
    D --> E

    %% Premium Styling Rules
```


This page maps the HELM AI Kernel `reference_packs/iso_42001.v1.json` pack to NIST AI RMF 1.0 functions. The goal is one runtime evidence set that can support ISO 42001 AI management system audit readiness and NIST AI RMF reporting.

## Source Status

| Source | Status | HELM use |
| --- | --- | --- |
| [NIST AI RMF crosswalks](https://www.nist.gov/itl/ai-risk-management-framework/crosswalks-nist-artificial-intelligence-risk-management-framework) | NIST page updated December 17, 2024 | Confirms NIST publishes AI RMF crosswalks and treats international standards alignment as a priority |
| [NIST AI RMF to ISO/IEC 42001 crosswalk](https://airc.nist.gov/docs/NIST_AI_RMF_to_ISO_IEC_42001_Crosswalk.pdf) | Public crosswalk PDF | Maps AI RMF functions and categories to ISO 42001 clauses and Annex B controls |
| [ISO/IEC 42001:2023](https://www.iso.org/standard/42001) | Published international standard, December 2023 | Defines the AI management system standard that this reference pack models |

## Important Limit

This is a dual-framework evidence pack, not a dual-certification claim. ISO/IEC 42001 can be certified only through an appropriate audit process. NIST AI RMF is a voluntary risk-management framework, not a certification program. HELM produces signed runtime evidence that can support both conversations; it does not grant certification or substitute for legal, auditor, or certification-body review.

## Pack Semantics

The pack remains `iso-42001-v1`; ISO 42001 is the primary control vocabulary. The NIST AI RMF crosswalk is embedded as `nist_ai_rmf_crosswalk` metadata on each program:

| Pack program | ISO 42001 basis | NIST AI RMF functions | HELM evidence |
| --- | --- | --- | --- |
| `prog-leadership` | Clauses 5 and 6 | Govern, Map | Policy content hash, decision owner, management review interval, approval trace |
| `prog-operational-control` | Clause 8 and Annex B lifecycle controls | Govern, Map | Policy simulation, risk treatment verdict, AI-BOM presence, receipt chain, human oversight requirement |
| `prog-performance-evaluation` | Clause 9 | Measure, Govern | Decision record, evidence pack, policy replay result, audit chain verification |
| `prog-improvement` | Clause 10 | Manage | Compliance score, nonconformity escalation, corrective action reference, policy activation history |

## Operator Use

Attach `reference_packs/iso_42001.v1.json` to an AI system or workspace when the operator needs both:

1. ISO 42001-style AIMS control evidence.
2. NIST AI RMF reporting categories for governance, mapping, measurement, and risk management.

The pack should be used with HELM receipt signing, ProofGraph, AI-BOM, and evidence-pack export enabled. A complete evidence export should include:

- Signed `DecisionRecord` for every relevant action.
- Active policy bundle hash.
- Pack ID and pack version.
- AI-BOM or equivalent system inventory reference.
- Policy replay output for sampled or disputed decisions.
- Management review interval and escalation evidence.

## Sales Language

Use: "one runtime evidence pack for ISO 42001 audit readiness and NIST AI RMF reporting."

Do not use: "one pack, two certifications." That overstates NIST AI RMF and implies certification outcomes HELM cannot grant.


---
title: "Conformance"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/conformance"
source: "helm-ai-kernel/docs/CONFORMANCE.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/CONFORMANCE.md"
section: "start-here"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:f1e058127c58f80f11749ad22a8300db29174a027c961f640a187299cce9d1bd"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Conformance

## Audience

Policy/runtime implementers and maintainers validating behavior with conformance packs and fixture replay.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/conformance`
- Source document: `helm-ai-kernel/docs/CONFORMANCE.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

This scheme maps the main sections of Conformance in reading order.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["Conformance"]
        C["Profile Material"]
        D["What L1 and L2 Mean in This Repo"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        A["Run the Kernel Conformance Command"]
        B["Run the Conformance Test Suite"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C
    C --> D

    %% Premium Styling Rules
    style A fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style B fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
```


HELM keeps a retained conformance profile under `tests/conformance/profile-v1/`. The profile describes the minimum checks an implementation must pass to match the public OSS kernel behavior documented in this repository.

## Run the Kernel Conformance Command

```bash
./bin/helm-ai-kernel conform --level L1 --json
./bin/helm-ai-kernel conform --level L2 --json
./bin/helm-ai-kernel conform negative --json
./bin/helm-ai-kernel conform vectors --json
```

The public API exposes the same negative gates at
`GET /api/v1/conformance/negative` and `GET /api/v1/conformance/vectors`.
Reports can be created and read through `POST /api/v1/conformance/run`,
`GET /api/v1/conformance/reports`, and
`GET /api/v1/conformance/reports/{report_id}`.

## Run the Conformance Test Suite

```bash
cd tests/conformance
go test ./...
```

## Profile Material

The profile directory contains:

- `checklist.yaml` for the machine-readable checklist
- `profile_test.go` for profile assertions
- `README.md` for the human-readable profile summary

## What L1 and L2 Mean in This Repo

- `L1` covers core structural correctness such as canonicalization, schema handling, receipt shape, offline verification, and checkpoint roots.
- `L2` adds MCP execution-firewall behavior: quarantine, tool-list/call consistency, OAuth resource and scope checks, schema pinning, direct-bypass denial, and deny-path receipt emission.
- `L3` covers sandbox grants, ReBAC snapshots, approval ceremonies, budget ceilings, stale tuple/model mismatch denial, and backend outage denial.
- `L4` covers non-authoritative telemetry/coexistence exports, evidence envelope wrappers, framework middleware, and checkpoint inclusion verification.

The exact checks are defined by the code and checklist in `tests/conformance/`, not by this page.

<!-- docs-depth-final-pass -->

## Conformance Completion Path

A conformance page is complete only when it tells a maintainer how to run the profile, how to interpret a failure, and which fixture owns the expected behavior. Keep profiles explicit: runtime decision, receipt canonicalization, verifier replay, policy denial, MCP boundary, and OpenAI-compatible proxy behavior are different surfaces. When adding a profile, add a fixture, a golden expected output, a negative case, and a short compatibility note. Public users should be able to run the command from a clean checkout, compare output to the documented profile, and decide whether a failure is a local environment issue, a schema drift, or an implementation regression.


---
title: "HELM AI Kernel Console"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/console"
source: "helm-ai-kernel/docs/CONSOLE.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/CONSOLE.md"
section: "start-here"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:fe7c07a1456bc22670df67d110f3814c98e3daceadbb8eab4f2c3320de174bce"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM AI Kernel Console

## Audience

Operators and frontend maintainers running the self-hostable Console against a local HELM API.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/console`
- Source document: `helm-ai-kernel/docs/CONSOLE.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

This scheme maps the main sections of HELM AI Kernel Console in reading order.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["HELM AI Kernel Console"]
        A["What It Covers"]
        C["Production Boundary"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        B["Running Locally"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        D["Verification"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C
    C --> D

    %% Premium Styling Rules
    style B fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style D fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


HELM AI Kernel ships one browser frontend: `apps/console`.

The Console is a self-hostable operator surface for the OSS kernel. It is built
with React, Vite, TypeScript, and `@mindburn/ui-core`; it does not carry a
second component system, Tailwind layer, private package, or generated marketing
surface.

## What It Covers

- Command-first governance over the local kernel.
- Live receipts from `/api/v1/receipts` and `/api/v1/receipts/tail`.
- Intent evaluation through `/api/v1/evaluate`.
- Route-backed boundary records, MCP quarantine, sandbox grants, authz
  snapshots, approvals, budgets, evidence envelopes, conformance reports,
  telemetry export configuration, and coexistence manifests.
- ProofGraph, replay, trust, audit, developer, and settings navigation surfaces.
- A read-only bootstrap contract at `/api/v1/console/bootstrap` for kernel
  version, workspace, health, counts, recent receipts, conformance, and MCP
  scope state.

The Console does not invent private state. The new operational workspaces load
from public API routes such as `/api/v1/boundary/records`,
`/api/v1/mcp/registry`, `/api/v1/sandbox/grants`,
`/api/v1/authz/snapshots`, `/api/v1/approvals`, `/api/v1/budgets`,
`/api/v1/evidence/envelopes`, `/api/v1/conformance/reports`,
`/api/v1/telemetry/otel/config`, and `/api/v1/coexistence/capabilities`.

## Running Locally

Build the design-system package and Console:

```bash
make build-console
```

Console installs are locked to the public npm registry. The npm path is pinned
to npm `11.14.1` and uses `apps/console/.npmrc` for registry pinning, strict
TLS, audit-on-install, and a two-day release-age floor. The pnpm compatibility
path uses `apps/console/pnpm-workspace.yaml` for the same registry and a
2,880-minute release-age floor. Use `npm audit signatures` as the report-only
signature and provenance check for packages whose registry metadata exposes
signatures or attestations.

Start the kernel with the Console enabled:

```bash
./bin/helm-ai-kernel serve --policy ./release.high_risk.v3.toml --console
```

The default `helm-ai-kernel serve` bind is `127.0.0.1:7714`. Console assets are loaded from
`apps/console/dist` by default, or from `HELM_CONSOLE_DIR` / `--console-dir` when
set.

## Production Boundary

The Console is OSS and self-hostable. It is not the managed Mindburn hosted
service. The OSS repository still excludes hosted retention, private
account-management systems, org-specific operator workflows, and managed
multi-region operations.

`helm-ai-kernel serve --console` serves static assets with the same security middleware as
the API. API-like paths never fall through to `index.html`, so broken contracts
remain visible during development and deployment.

## Verification

Run the Console gate:

```bash
make test-console
```

Run the broader platform gate:

```bash
make test-platform
```

<!-- docs-depth-final-pass -->

## Scope Boundary

HELM AI Kernel does not promise the commercial Console experience. This page should describe the OSS inspection and source artifacts that the Console consumes: receipts, ProofGraph nodes, policy bundle metadata, verification output, and exported evidence. If a screen or workflow exists only in HELM commercial, link to authenticated customer documentation from the product site and keep anonymous OSS docs focused on the data contracts a developer can generate locally. The validation path is to create a receipt, inspect it through the CLI or export, and verify that the fields named here are present in the public schema.


---
title: "Deployment and Examples"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/deployment-and-examples"
source: "helm-ai-kernel/docs/DEPLOYMENT_AND_EXAMPLES.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/DEPLOYMENT_AND_EXAMPLES.md"
section: "deployment"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:a3b2f85203a2f6bc74c35f8f5b0196cf485a121804f4272164f789b036ece69c"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM AI Kernel Deployment and Examples

This page gathers the public deployment and runnable example material that lives
outside the core docs directory.

## Audience

This page is for developers moving from a local HELM run to repeatable examples,
Docker Compose, or Kubernetes deployment.

## Outcome

You should be able to find the right example or deployment path, run it, and
know which command validates the path before relying on it.

## Deployment Path

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Source checkout"]
        local["Local CLI / proxy"]
        compose["Docker Compose"]
        chart["Kubernetes Helm chart"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["Receipt and evidence export"]
        verify["Offline verification"]
    end

    %% Operational Flow Edges
    source --> local
    local --> compose
    compose --> chart
    chart --> receipt
    receipt --> verify

    %% Premium Styling Rules
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Deployment Targets

| Target | Source path | Public contract |
| --- | --- | --- |
| Local CLI or proxy | `core/cmd/helm-ai-kernel/`, `docs/QUICKSTART.md` | Start with `/helm-ai-kernel/developer-journey`. |
| Docker image | `Dockerfile`, `Makefile`, `docker-compose.yml` | Build and run through the retained Docker targets. |
| Docker Compose | `docker-compose.yml` | Use for local boundary testing and example orchestration. |
| Kubernetes Helm chart | `deploy/helm-chart/Chart.yaml`, `deploy/helm-chart/values.yaml`, `deploy/helm-chart/templates/` | Lint with `helm lint deploy/helm-chart` before applying. |
| Release artifacts | `.goreleaser.yml`, `.github/workflows/release.yml`, `release/` | Verify checksums, SBOM, Cosign, provenance, and reproducibility. |

## Runnable Examples

| Example | Source path | Use when |
| --- | --- | --- |
| Go client | `examples/go_client/` | You want direct Go SDK integration. |
| Java client | `examples/java_client/` | You want JVM integration. |
| Rust client | `examples/rust_client/` | You want Rust receipt or policy client behavior. |
| Python OpenAI base URL | `examples/python_openai_baseurl/` | You want an OpenAI-compatible Python client behind HELM. |
| TypeScript OpenAI base URL | `examples/ts_openai_baseurl/` | You want typed JavaScript/TypeScript proxy integration. |
| JavaScript OpenAI base URL | `examples/js_openai_baseurl/` | You want a minimal JavaScript proxy example. |
| MCP client | `examples/mcp_client/` | You want MCP invocation through HELM. |
| Receipt verification | `examples/receipt_verification/` | You want offline verification examples. |
| Starters | `examples/starters/` | You want provider starter layouts for OpenAI, Anthropic, Google, or Codex-style agents. |
| Policies | `examples/policies/` | You want CEL/Rego/Cedar policy examples. |

## Validation Commands

```bash
make build
make test
make test-all
make docker
helm lint deploy/helm-chart
make verify-fixtures
```

The developer coverage manifest records the exact validation command per
surface. If an example is not listed there, the public docs should describe it
as example-only or omit a support claim.

## Source Truth

- `deploy/README.md`
- `deploy/helm-chart/README.md`
- `examples/README.md`
- `docs/developer-coverage.manifest.json`
- `docs/DEVELOPER_JOURNEY.md`

## Troubleshooting

| Problem | First check |
| --- | --- |
| Docker build fails | Confirm the local tree builds with `make build`, then rerun the Docker target. |
| Helm chart lint fails | Check `deploy/helm-chart/values.yaml` and required Kubernetes settings. |
| Example cannot reach the proxy | Confirm `helm-ai-kernel proxy` is running and the client base URL points at the HELM boundary. |
| Receipt verification fails | Use `/helm-ai-kernel/verification` and compare against `examples/golden/`. |

<!-- docs-depth-final-pass -->

## Deployment Acceptance Checklist

Each deployment example should name the supported target, prerequisites, port exposure, persistence model, health check, and rollback signal. Docker Compose examples must identify which services are durable and which can be recreated. Kubernetes examples must identify ConfigMaps, Secrets, Services, probes, and the release artifact version. A deployment doc should not claim production readiness unless the chart or manifest is linted, the health endpoint is exercised, and receipt verification still works after restart. Include the first diagnostic to collect for failed startup: container logs, effective environment, policy bundle path, and verifier command output.


---
title: "Kubernetes Deployment"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/deployment/kubernetes"
source: "helm-ai-kernel/docs/KUBERNETES_DEPLOYMENT.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/KUBERNETES_DEPLOYMENT.md"
section: "deployment"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-19"
checksum_sha256: "sha256:29dc0a05d558ca155ee0a4b0a3837a930d0a9ad1fb8b07c634b58ddb78cf4e0e"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Kubernetes Deployment

This page is for operators deploying the HELM AI Kernel runtime with the repository-owned Kubernetes Helm chart. The outcome is a chart render, a production-safe value set, and a smoke path for health, receipts, and evidence persistence.

## Audience

Use this page if you operate Kubernetes and need to run HELM AI Kernel as a self-hosted execution boundary with durable receipts, signing keys, and optional ingress.

## Outcome

After this page you should be able to lint the chart, render manifests, provide production signing and API-key material, install the chart, and smoke health plus receipt persistence.

## Source Truth

The chart source is [`deploy/helm-chart`](../deploy/helm-chart). Runtime container wiring is in [`deploy/helm-chart/templates/deployment.yaml`](../deploy/helm-chart/templates/deployment.yaml), values are in [`deploy/helm-chart/values.yaml`](../deploy/helm-chart/values.yaml), and chart-level production notes live in `deploy/helm-chart/README.md` (protected staff doc).

## Deployment Topology

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Values["values.yaml"]
        ControlPlane["controlplane source"]
        Mounted["ConfigMap/Secret mounted file"]
        PVC["persistent /data PVC"]
        Pod["helm-ai-kernel serve pod"]
        Service["ClusterIP service"]
        Ingress["optional ingress TLS"]
        Metrics["metrics port / ServiceMonitor"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        Source["policy.source config"]
        CRD["HelmPolicyBundle CRD"]
        Snapshot["verified EffectivePolicySnapshot"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Runtime["runtime reconciler"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Secrets["signing and API-key Secrets"]
    end

    %% Operational Flow Edges
    Values --> Source
    Source --> Runtime
    ControlPlane --> Runtime
    CRD --> Runtime
    Mounted --> Runtime
    Runtime --> Snapshot
    Values --> Secrets
    Values --> PVC
    Snapshot --> Pod
    Secrets --> Pod
    PVC --> Pod
    Pod --> Service
    Service --> Ingress
    Pod --> Metrics

    %% Premium Styling Rules
    style Source fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Runtime fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style CRD fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Snapshot fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Secrets fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Validate The Chart

```bash
make helm-chart-smoke
helm lint deploy/helm-chart
helm template helm-ai-kernel deploy/helm-chart
```

Expected output: lint succeeds, `helm template` emits Deployment, Service, ConfigMap, Secret, PVC, and optional ServiceMonitor manifests, and `make helm-chart-smoke` completes without rendering a production chart that lacks signing or API key material.

## Policy Authority Boundary

The chart does not make Kubernetes objects the HELM execution authority. It
deploys the runtime and configures a `policy.source` backend. The runtime
reconciler owns policy truth: it reads the active head, loads the canonical
bundle, verifies the expected hash and signature/provenance, compiles a
snapshot, validates it, then atomically swaps the per-scope
`EffectivePolicySnapshot`.

`POST /internal/policy/reconcile` is a wake-up hint protected by service auth.
It does not accept policy bytes and does not directly install policy. Lost
hints are recovered by `helm.policy.source.pollInterval`.

## Production Install Skeleton

```bash
helm install helm-ai-kernel deploy/helm-chart \
  --set helm.production=true \
  --set helm.signing.key=<64-char-ed25519-seed-hex> \
  --set helm.auth.adminAPIKey=<admin-api-key> \
  --set helm.auth.serviceAPIKey=<service-api-key> \
  --set persistence.enabled=true
```

For production, prefer existing Kubernetes Secrets over inline values:

```bash
kubectl create secret generic helm-signing \
  --from-literal=signing-key=<64-char-ed25519-seed-hex>

kubectl create secret generic helm-auth \
  --from-literal=HELM_ADMIN_API_KEY=<admin-api-key> \
  --from-literal=HELM_SERVICE_API_KEY=<service-api-key>

kubectl create secret generic helm-policy-trust \
  --from-literal=HELM_POLICY_TRUST_PUBLIC_KEY=<64-char-ed25519-public-key-hex>

helm upgrade --install helm-ai-kernel deploy/helm-chart \
  --set helm.production=true \
  --set helm.policy.source.kind=controlplane \
  --set helm.policy.source.controlplane.url=https://helm-controlplane.example.internal \
  --set helm.policy.signature.required=true \
  --set helm.policy.signature.existingSecret=helm-policy-trust \
  --set helm.signing.existingSecret=helm-signing \
  --set helm.auth.existingSecret=helm-auth
```

## Values That Control Runtime Behavior

| Value | Default | Source-backed behavior |
| --- | --- | --- |
| `image.repository` | `ghcr.io/mindburn-labs/helm-ai-kernel` | Container image used by the Deployment. |
| `image.tag` | chart `appVersion` | Defaults to `v0.5.6` from `Chart.yaml`. |
| `helm.bindAddr` | `0.0.0.0` | Required because the pod must bind beyond loopback. |
| `service.port` | `8080` | Runtime HTTP port passed to `helm-ai-kernel serve --port`. |
| `service.healthPort` | `8081` | Health probe port via `HELM_HEALTH_PORT`. |
| `service.metricsPort` | `9090` | Metrics container port when metrics are enabled. |
| `helm.production` | `false` | Production rendering refuses missing signing/auth material. |
| `helm.dataDir` | `/data` | Mounted from the chart PVC or `emptyDir`. |
| `helm.proxy.enabled` | `true` | Sets `HELM_ENABLE_OPENAI_PROXY=1` and `HELM_UPSTREAM_URL`. |
| `helm.policy.source.kind` | `mountedFile` | `controlplane`, `crd`, or `mountedFile`; production should use `controlplane`, or `crd` in builds that include a CRD source client. |
| `helm.policy.source.pollInterval` | `10s` | Runtime polling interval; correctness does not depend on delivery hints. |
| `helm.policy.signature.required` | `false` | When true, unsigned policy heads are rejected before compilation. Production control-plane renders require this. |
| `helm.policy.signature.publicKey` | empty | 64-char hex Ed25519 public key for canonical policy bundle verification. |
| `helm.policy.signature.existingSecret` | empty | Existing secret containing `HELM_POLICY_TRUST_PUBLIC_KEY`. |
| `helm.policy.reloadHints.httpWakeEndpoint` | `/internal/policy/reconcile` | Service-auth wake-only route for reconciler hints. |
| `helm.policy.reloadHints.configReloaderSidecar.enabled` | `false` | Optional mounted-file hint sidecar, disabled by default. |
| `helm.storage.type` | `sqlite` | Uses local SQLite unless Postgres is configured. |
| `persistence.enabled` | `true` | Creates or reuses a PVC for receipts, state, and artifacts. |
| `ingress.enabled` | `false` | Optional ingress; provide TLS and ingress class explicitly. |

## Smoke Checks

```bash
kubectl rollout status deploy/helm-ai-kernel
kubectl port-forward svc/helm-ai-kernel 8080:8080
curl -fsS http://127.0.0.1:8080/health
```

Then run a governed request through the public API or OpenAI-compatible proxy and verify that receipts persist after pod restart when `persistence.enabled=true`.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| pod starts but readiness fails | health port or initial snapshot failure | inspect `HELM_HEALTH_PORT`, policy source env, mounted-file bytes, and pod logs |
| `/internal/policy/reconcile` returns unauthorized | missing service API key | set `helm.auth.serviceAPIKey` or `helm.auth.existingSecret` |
| policy ConfigMap changed but decisions did not | ConfigMap delivery is only a source backend | verify the bundle hash/signature and reconciler status; enable sidecar only as a wake hint |
| policy reconcile fails with signature error | missing trust public key, missing signature, or invalid bundle signature | set `helm.policy.signature.existingSecret` or `publicKey`, and verify the active source signs canonical bundle bytes |
| production render fails | missing signing key or API key material | set `helm.signing.existingSecret` and `helm.auth.existingSecret`, or provide explicit values |
| receipts disappear after restart | persistence disabled or PVC not bound | set `persistence.enabled=true` and verify PVC status |
| ingress works but upstream calls bypass HELM | client points at upstream provider | point clients at the service or ingress URL for HELM, not the provider URL |

## Not Covered

This page documents the repository-owned HELM AI Kernel chart only. Managed deployment, tenant migrations, SSO, SIEM, and retention controls belong to the HELM AI Enterprise docs.


---
title: "HELM AI Kernel Design System Surface"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/design-system"
source: "helm-ai-kernel/docs/DESIGN_SYSTEM.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/DESIGN_SYSTEM.md"
section: "interfaces"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:f40fefb145435b5cadba95cb119a4bbc34fb0d022f6bafff5e95b371432ead14"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM AI Kernel Design System Surface

This page documents the public HELM AI Kernel console and design-system surface. It
exists so the docs site covers the frontend package family instead of burying it
inside repository-only package READMEs.

## Audience

This page is for contributors extending the HELM AI Kernel Console, maintainers
reviewing frontend package changes, and developers who need to understand which
UI assets are part of the self-hostable OSS surface.

## Outcome

You should know which packages and docs own console UI primitives, how the
design-system package is validated, and where the public console docs fit into
the larger HELM AI Kernel developer journey.

## Surface Model

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        console["HELM AI Kernel Console"]
        package["packages/design-system-core"]
        docs["docs/design-system/*"]
        public["Public console docs"]
        release["Self-hostable OSS release"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        tests["package tests and CI gates"]
    end

    %% Operational Flow Edges
    console --> package
    package --> docs
    docs --> tests
    tests --> public
    public --> release

    %% Premium Styling Rules
    style tests fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
```


## Source Families

| Source family | Purpose | Public handling |
| --- | --- | --- |
| `apps/console/` | Browser console for receipts, policy, MCP, evidence, replay, conformance, trust, incidents, audit, developer, and settings workflows. | Covered by `/helm-ai-kernel/console`. |
| `packages/design-system-core/` | Frontend primitives, tokens, grammar highlighting, and package-level tests. | Covered by this page and package README truth checks. |
| `docs/design-system/` | Accessibility, architecture, CI gates, contrast, decisions, library adoption, primitive coverage, and theming docs. | Summarized here; detailed source remains edit-linked in repo. |
| `docs/CONSOLE.md` | Public user-facing Console docs. | Rendered directly at `/helm-ai-kernel/console`. |

## Validation

Use the package and docs gates before changing console or design-system behavior:

```bash
make test-design-system
make test-console
make docs-coverage docs-truth
```

The design system is part of the OSS self-hostable surface, but it is not a
separate product. Public docs should explain how it supports the Console and
developer experience, not position it as a standalone commercial UI kit.

## Source Truth

- `apps/console/`
- `packages/design-system-core/README.md`
- `docs/design-system/README.md`
- `docs/design-system/accessibility.md`
- `docs/design-system/architecture.md`
- `docs/design-system/ci-gates.md`
- `docs/CONSOLE.md`

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Console UI copy diverges from docs | Update `docs/CONSOLE.md` and the relevant component tests together. |
| Token or contrast behavior changes | Review `docs/design-system/contrast-table.md` and package token tests. |
| A primitive lacks accessibility coverage | Add or update the design-system accessibility and primitive coverage docs before release. |
| A package change is invisible in public docs | Update this page or `/helm-ai-kernel/console`, then rerun diagram and source-coverage gates. |

<!-- docs-depth-final-pass -->

## Documentation And UI Contract

The design system docs should connect visual components to governance meaning. Status badges, receipt summaries, policy decisions, warnings, and verifier output must use stable labels that match schemas and CLI output. When a token or component changes, update screenshots, accessibility notes, and any consuming Console or docs-platform page together. A reader should know which styles are illustrative, which are required for accessible evidence review, and which are outside the OSS surface. Keep color and icon decisions tied to state semantics such as allow, deny, warning, pending verification, and stale evidence rather than decorative preference.

<!-- docs-depth-final-pass-extra -->
 Include keyboard focus, color contrast, reduced-motion behavior, and copy semantics for each stateful component. Evidence review UI must remain usable in screenshots, Markdown exports, and assistive technology.

<!-- docs-depth-final-pass-extra-2 -->
 State ownership for token changes and keep component examples aligned with generated screenshots.


---
title: "Developer Journey"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/developer-journey"
source: "helm-ai-kernel/docs/DEVELOPER_JOURNEY.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/DEVELOPER_JOURNEY.md"
section: "start-here"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-20"
checksum_sha256: "sha256:74512c1a7ba05890dada7944bf909f1e2b3aa37e37170d23344a666236e8e030"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Developer Journey

This page is the source-backed end-to-end path for evaluating HELM AI Kernel. It ties install, runtime, SDKs, policy, receipts, verification, deployment, conformance, release artifacts, and troubleshooting to live repository surfaces.

## Audience

This journey is for developers and platform teams evaluating HELM AI Kernel beyond the first quickstart. It is the source-backed path for proving local runtime behavior, SDK calls, receipts, EvidencePack verification, conformance, deployment, and release verification.

## Outcome

After completing the path you should know which local command owns each public claim, how to route OpenAI-compatible and MCP traffic through the execution boundary, how to inspect receipts, and which validation commands keep docs aligned with code.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Install["install or build helm-ai-kernel"]
        Proxy["optional helm-ai-kernel proxy"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        Serve["helm-ai-kernel serve --policy"]
        Gates["docs and conformance gates"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Demo["local proof demo"]
        Receipts["receipts and boundary records"]
        Verify["offline verification"]
    end

    %% Operational Flow Edges
    Install --> Serve
    Serve --> Demo
    Serve --> Proxy
    Serve --> Receipts
    Receipts --> Verify
    Verify --> Gates

    %% Premium Styling Rules
    style Serve fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Demo fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Receipts fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Gates fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
```


## Source Truth

- `Makefile`, `Dockerfile`, `docker-compose.yml`
- `core/cmd/helm-ai-kernel/*`
- `api/openapi/helm.openapi.yaml`
- `docs/reference/cli.md`
- `docs/reference/http-api.md`
- `docs/reference/execution-boundary.md`
- `sdk/go`, `sdk/python`, `sdk/ts`, `sdk/rust`, `sdk/java`
- `examples/`, `deploy/helm-chart/`, `tests/conformance/`
- `scripts/check_documentation_coverage.py`
- `scripts/check_documentation_truth.py`

## Install

Use one of these current paths. The published Homebrew path is the macOS path;
source builds and Docker remain the portable paths for Linux and WSL.

:::selector os
### macOS

```bash
brew install mindburnlabs/tap/helm-ai-kernel
helm-ai-kernel --version
```

### Linux

```bash
git clone https://github.com/Mindburn-Labs/helm-ai-kernel.git
cd helm-ai-kernel
make build
./bin/helm-ai-kernel --version
```

### Windows / WSL

Use WSL with the source build path. Run the build from the Linux filesystem so Go module and shell-script behavior matches the repository validation path.

```bash
docker build -t ghcr.io/mindburn-labs/helm-ai-kernel:local .
docker compose up -d
```
:::

```bash
brew install mindburnlabs/tap/helm-ai-kernel
helm-ai-kernel --version
```

```bash
git clone https://github.com/Mindburn-Labs/helm-ai-kernel.git
cd helm-ai-kernel
make build
./bin/helm-ai-kernel --version
```

```bash
docker build -t ghcr.io/mindburn-labs/helm-ai-kernel:local .
docker compose up -d
```

Docker Compose exposes the service on its compose-configured port. The local source quickstart uses `helm-ai-kernel serve` on `127.0.0.1:7714`.

## First Local Boundary

```bash
./bin/helm-ai-kernel serve --policy ./release.high_risk.v3.toml
```

Expected ready line:

```text
helm-edge-local - listening :7714 - ready
```

Open the self-hostable Console by adding `--console`:

```bash
make build-console
./bin/helm-ai-kernel serve --policy ./release.high_risk.v3.toml --console
```

## First Proof

Run, verify, and tamper-check a local receipt:

```bash
curl http://127.0.0.1:7714/api/demo/run \
  -H 'content-type: application/json' \
  -d '{"action_id":"export_customer_list","policy_id":"agent_tool_call_boundary"}'
```

```bash
curl http://127.0.0.1:7714/api/demo/verify \
  -H 'content-type: application/json' \
  -d '{"receipt":{...},"expected_receipt_hash":"<receipt_hash>"}'
```

```bash
curl http://127.0.0.1:7714/api/demo/tamper \
  -H 'content-type: application/json' \
  -d '{"receipt":{...},"expected_receipt_hash":"<receipt_hash>","mutation":"flip_verdict"}'
```

## Optional OpenAI-Compatible Proxy

Use the proxy when the application already supports an OpenAI-compatible `base_url` or `baseURL`.

```bash
python3 scripts/launch/mock-openai-upstream.py --port 19090
./bin/helm-ai-kernel proxy --upstream http://127.0.0.1:19090/v1 --port 9090 --receipts-dir ./helm-receipts
```

Configure the client base URL as:

```text
http://localhost:9090/v1
```

The example directories named `*_openai_baseurl` currently exercise HELM HTTP or SDK clients. They are not evidence that the OpenAI SDK examples are runnable unless their code imports the OpenAI SDK and reads the documented base URL variable.

:::selector framework
### OpenAI-Compatible Proxy

Use the OpenAI-compatible proxy path when an application already supports an OpenAI-compatible `base_url` or `baseURL`. Keep HELM on `http://localhost:9090/v1` and keep the provider or fixture upstream behind the proxy.

### MCP

Use this path when the client expects an MCP server, MCP bundle, or tool-oriented transport. Unknown tools remain quarantined until inspected and approved.

### LangGraph

Use this path for graph-style agent orchestration only when tool effects still cross the HELM execution boundary. LangGraph owns graph control flow; HELM owns policy evaluation, denials, receipts, and verification evidence.
:::

## Receipts And Boundary Records

HELM AI Kernel is useful only when both allowed and denied outcomes are recorded.

```bash
./bin/helm-ai-kernel receipts tail --agent agent.demo.exec --server http://127.0.0.1:7714
curl 'http://127.0.0.1:7714/api/v1/receipts?limit=20'
./bin/helm-ai-kernel boundary records --json
```

The CLI receipt tail requires `--agent`; the HTTP list route is the unfiltered inspection path.

## Policy Fixtures

**Launch Demo Suite:** You can evaluate a complete, end-to-end set of `ALLOW`,
`DENY`, and `ESCALATE` outcomes using the canonical launch suite in
`examples/launch/`. Run `make launch-smoke` to verify policy execution,
receipt proof generation, MCP quarantine behavior, and localhost-only proxy
behavior.

**SDK Examples:** Run `make sdk-examples-smoke` to build the Python and
TypeScript SDKs, start a local boundary, and validate ALLOW, DENY, MCP
fail-closed denial, signed receipt verification, sandbox preflight, and
EvidencePack verification.

Use allow and deny fixtures from `examples/policies/` when validating
policy-language behavior. The policy bundle command supports CEL, Rego, and
Cedar:

```bash
./bin/helm-ai-kernel bundle build --language cel examples/policies/cel/example.cel
./bin/helm-ai-kernel bundle build --language rego examples/policies/rego/example.rego
./bin/helm-ai-kernel bundle build --language cedar --entities examples/policies/cedar/entities.json examples/policies/cedar/example.cedar
```

`helm-ai-kernel bundle build` takes the policy source as the positional argument. It does not accept `--policy`; that flag belongs to `helm-ai-kernel serve`.

## EvidencePack Verification

Run offline verification first:

```bash
./bin/helm-ai-kernel verify evidence-pack.tar
./bin/helm-ai-kernel verify evidence-pack.tar --json
```

Run online verification only after offline verification passes:

```bash
./bin/helm-ai-kernel verify evidence-pack.tar --online
```

`--online` checks envelope or root metadata against `HELM_LEDGER_URL` or the public proof verifier. Online checks are additive and do not replace offline receipt and ProofGraph verification.

## SDKs

| Language | Public package status | Validation |
| --- | --- | --- |
| Python | `pip install helm-sdk` | `make test-sdk-py` |
| TypeScript / JavaScript | `npm install @mindburn/helm-ai-kernel` | `make test-sdk-ts` |
| Rust | `cargo add helm-sdk` | `make test-sdk-rust` |
| Go | source/module path `github.com/Mindburn-Labs/helm-ai-kernel/sdk/go`; pin `@main` or a commit until tagged module releases are aligned | `cd sdk/go && go test ./...` |
| Java | Maven Central coordinate `io.github.mindburnlabs:helm-sdk:0.5.2` | `make test-sdk-java` |

Use [SDK Index](/helm-ai-kernel/sdks) before publishing SDK install instructions.

:::selector language
### Python

Use `pip install helm-sdk` for the public Python package path and validate with `make test-sdk-py` before changing Python SDK examples.

### TypeScript / JavaScript

Use `npm install @mindburn/helm-ai-kernel` for the public TypeScript package path and validate with `make test-sdk-ts` before changing JavaScript examples.

### Go

Use `github.com/Mindburn-Labs/helm-ai-kernel/sdk/go` from source, pinned to `main` or a commit until tagged module releases are aligned. Validate with `cd sdk/go && go test ./...`.

### Rust

Use `cargo add helm-sdk` for the public Rust package path and validate with `make test-sdk-rust`.

### Java

Use the source-available local Maven build under `sdk/java`; the public package coordinate is not verified. Validate with `make test-sdk-java`.
:::

## MCP

Use MCP when the integration is tool-oriented and the client expects an MCP server, client config, or MCP bundle:

```bash
./bin/helm-ai-kernel mcp serve
./bin/helm-ai-kernel mcp pack --client claude-desktop --out helm-ai-kernel.mcpb
./bin/helm-ai-kernel mcp install --client claude-code
```

Unknown MCP servers and tools start in quarantine. They must be inspected and approved before side effects are dispatched.

## Deployment

Use Docker Compose for local deployment checks:

```bash
docker compose up -d
docker compose ps
```

Use the Kubernetes Helm chart only with a Kubernetes Helm v3 binary:

```bash
helm lint deploy/helm-chart
helm install helm-ai-kernel deploy/helm-chart
```

If the `helm` command on your machine resolves to this HELM AI Kernel binary, use `KUBE_HELM_CMD` or a pinned containerized chart runner instead.

## Release And Conformance Gates

Current source release target: `v0.5.6`: <https://github.com/Mindburn-Labs/helm-ai-kernel/releases/tag/v0.5.6>.

The release is complete only after the release page includes Darwin/Linux/Windows binaries, `SHA256SUMS.txt`, `sbom.json`, `v0.5.6.openvex.json`, `release-attestation.json`, `evidence-pack.tar`, `release.high_risk.v3.toml`, `sample-policy-material.tar`, `helm-ai-kernel-launchpad-data.tar`, `helm-ai-kernel.mcpb`, `helm-ai-kernel.rb`, `v0.5.6.json`, `version-status.json`, and matching `*.cosign.bundle` files for each primary asset.

Run conformance and docs gates:

```bash
cd tests/conformance && go test ./...
cd ../..
make docs-coverage
make docs-truth
```

Run release checks when release docs or packaging behavior changes:

```bash
make test
make test-console
make test-platform
make test-all
make crucible
make launch-smoke
make launch-ready
make verify-fixtures
make release-assets
```

## Troubleshooting

| Symptom | Likely cause | First check |
| --- | --- | --- |
| `helm-ai-kernel serve` starts but clients still bypass HELM | client base URL still points to upstream provider | log request host and set the client base URL to HELM |
| no receipts appear | wrong server, directory, or agent id | run `helm-ai-kernel receipts tail --agent <id> --server http://127.0.0.1:7714` or query `/api/v1/receipts` |
| denied call retries forever | app treats policy denial as transient | handle `DENY` as a final authorization result |
| offline verification fails | EvidencePack is incomplete or modified | verify a complete pack and run `make verify-fixtures` |
| MCP call fails with OAuth scope error | token lacks required scope or resource indicator | inspect `HELM_OAUTH_RESOURCE` and `HELM_OAUTH_SCOPES` |
| chart deploy fails | wrong Helm binary or invalid values | use Kubernetes Helm v3 and run `helm lint deploy/helm-chart` |


---
title: "HELM AI Kernel Examples Matrix"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/examples"
source: "helm-ai-kernel/docs/EXAMPLES.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/EXAMPLES.md"
section: "deployment"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:12eea8d60f94c24efee115c30d71ee1069fa78a6099654dae6bb8a8d81f40ea0"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM AI Kernel Examples Matrix

This page is for developers choosing the shortest source-backed example for a language, framework, receipt, MCP, OpenTelemetry, or policy workflow. The outcome is a runnable example path, the server mode it expects, and the validation command that proves the public docs claim.

## Audience

This page is for developers who need to pick a runnable source-backed example for HELM AI Kernel rather than infer support from a language name or integration slogan.

## Outcome

After this page you should know which example to run, which HELM server mode it expects, what output proves success, and which command validates the claim.

## Source Truth

Example source lives under [`examples`](../examples). SDK package docs live under [`sdk`](../sdk). Deployment examples are separated into [`deploy`](../deploy) and the Kubernetes chart at [`deploy/helm-chart`](../deploy/helm-chart).

## Example Flow

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Reader["developer"]
        Pick["choose example"]
        Server["start helm-ai-kernel serve or helm-ai-kernel proxy"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        Gate["docs and example validation"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Run["run language/framework code"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Receipt["capture receipt or decision"]
        Verify["verify receipt/EvidencePack"]
    end

    %% Operational Flow Edges
    Reader --> Pick
    Pick --> Server
    Server --> Run
    Run --> Receipt
    Receipt --> Verify
    Verify --> Gate

    %% Premium Styling Rules
    style Run fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Gate fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
```


## Runnable Matrix

| Example | Server mode | What it proves | Source | Validation |
| --- | --- | --- | --- | --- |
| Python SDK | `helm-ai-kernel serve --policy examples/launch/policies/agent_tool_call_boundary.toml` | ALLOW, DENY, MCP fail-closed denial, receipt verification, sandbox preflight, and evidence verification | [`examples/python_sdk`](../examples/python_sdk) | `make sdk-examples-smoke` |
| TypeScript SDK | `helm-ai-kernel serve --policy examples/launch/policies/agent_tool_call_boundary.toml` | ALLOW, DENY, MCP fail-closed denial, receipt verification, sandbox preflight, and evidence verification | [`examples/ts_sdk`](../examples/ts_sdk) | `make sdk-examples-smoke` |
| Python OpenAI base URL | `helm-ai-kernel proxy --port 9090` | OpenAI-compatible base URL, receipt headers, deny path | [`examples/python_openai_baseurl`](../examples/python_openai_baseurl) | `make test-sdk-py` |
| TypeScript OpenAI base URL | `helm-ai-kernel proxy --port 9090` | JavaScript/TypeScript client base URL and receipt extraction | [`examples/ts_openai_baseurl`](../examples/ts_openai_baseurl) | `make test-sdk-ts` |
| JavaScript raw fetch | `helm-ai-kernel proxy --port 9090` | Raw HTTP client compatibility | [`examples/js_openai_baseurl`](../examples/js_openai_baseurl) | `make docs-truth` |
| Go client | `helm-ai-kernel serve --policy <file>` | typed client request, decision, receipt handling | [`examples/go_client`](../examples/go_client) | `go test ./examples/go_client/... -run '^$'` |
| Rust client | `helm-ai-kernel serve --policy <file>` | Rust client and verifier-facing types | [`examples/rust_client`](../examples/rust_client) | `make test-sdk-rust` |
| Java client | `helm-ai-kernel serve --policy <file>` | JVM client request and error handling | [`examples/java_client`](../examples/java_client) | `make test-sdk-java` |
| MCP client | `helm-ai-kernel mcp serve` or `/mcp` runtime | docs/tool boundary and MCP authorization path | [`examples/mcp_client`](../examples/mcp_client) | `make docs-truth` |
| Receipt verification | existing receipt/EvidencePack | offline verification path | [`examples/receipt_verification`](../examples/receipt_verification) | `make docs-truth` |
| Golden evidence | fixture evidence | stable conformance material | [`examples/golden`](../examples/golden) | `make docs-coverage` |
| OpenTelemetry GenAI | `helm-ai-kernel proxy` with telemetry enabled | telemetry export shape | [`examples/otel-genai`](../examples/otel-genai) | `go test ./examples/otel-genai/...` |
| OpenCLAW | local example harness | compatibility with OpenCLAW-style policy material | [`examples/openclaw`](../examples/openclaw) | `make docs-truth` |
| Policy examples | `helm-ai-kernel bundle build <source>` | CEL, Rego, Cedar bundle inputs | [`examples/policies`](../examples/policies) | `make docs-truth` |
| Starters | selected starter README | scaffolded integrations only where source exists | [`examples/starters`](../examples/starters) | `make docs-truth` |

## Common Environment

```bash
export HELM_URL=http://127.0.0.1:7714
export HELM_PROXY_BASE_URL=http://127.0.0.1:9090/v1
export OPENAI_API_KEY="${OPENAI_API_KEY:?set upstream key when proxying}"
```

Examples may also use framework-native `baseURL` or `base_url` options. Prefer the variable names used inside the example README or code; do not invent a new variable in public docs without adding it to the example.

## Expected Output

Every runnable example should produce at least one of these observable outputs:

- an HTTP response from HELM instead of the upstream provider;
- a receipt header or receipt file under the configured receipts directory;
- a deny decision and denial receipt for the blocked-path test;
- a verifier or conformance command that exits zero.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| example reaches the upstream provider directly | base URL bypassed HELM | set the framework base URL to `http://127.0.0.1:9090/v1` or use `HELM_PROXY_BASE_URL` where the example supports it |
| receipt is missing | wrong server mode | use `helm-ai-kernel proxy` for OpenAI-compatible examples and `helm-ai-kernel serve` for runtime API examples |
| Java package cannot be fetched from a public registry | artifact is source-backed but not registry-backed | build from `sdk/java` locally and avoid claiming Maven Central availability |

## Not Covered

This page does not claim support for languages or frameworks that lack source, an example, or an SDK README. Planned examples must remain out of public support tables until code and validation exist.


---
title: "EXECUTION_SECURITY_MODEL"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/execution-security-model"
source: "helm-ai-kernel/docs/EXECUTION_SECURITY_MODEL.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/EXECUTION_SECURITY_MODEL.md"
section: "interfaces"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:42f02601d8a1e489a5380a2bb422de028399fe918f1eaec7f9b56e6b533d9952"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Execution Security Model

## Audience

Security reviewers and runtime maintainers checking how HELM AI Kernel fails closed before dispatch.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/execution-security-model`
- Source document: `helm-ai-kernel/docs/EXECUTION_SECURITY_MODEL.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

This scheme maps the main sections of Execution Security Model in reading order.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["Execution Security Model"]
        A["Overview"]
        E["Why Three Layers"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        B["Layer A — Surface Containment"]
        C["Layer B — Dispatch Enforcement"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        D["Layer C — Verifiable Receipts"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C
    C --> D
    D --> E

    %% Premium Styling Rules
    style B fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style C fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style D fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


> **Canonical** · v1.0 · Normative
>
> This document defines HELM's three-layer execution security model.
> It is the canonical reference for how HELM reduces, enforces, and
> proves execution safety for AI agent tool calls.
>
> **Terminology**: follows the Unified Canonical Standard (UCS v1.3).

---

## Overview

HELM implements three independent, composable layers of execution security.
Each layer addresses a distinct class of threat and operates at a different
point in the execution lifecycle. No single layer is sufficient on its own.

```
                ┌─────────────────────────────────────────┐
                │        Agent / Orchestrator              │
                └──────────────────┬──────────────────────┘
                                   │
          ┌────────────────────────▼────────────────────────┐
          │  Layer A — Surface Containment (design-time)    │
          │  Reduces WHAT can be called                     │
          │  capability manifests · tool bundles · profiles │
          │  connector allowlists · destination scoping     │
          └────────────────────────┬────────────────────────┘
                                   │
          ┌────────────────────────▼────────────────────────┐
          │  Layer B — Dispatch Enforcement (dispatch-time)  │
          │  Gates EACH call at PEP boundary                │
          │  schema PEP · budget locks · contract pinning   │
          │  PDP/CPI verdict · deny-by-default              │
          └────────────────────────┬────────────────────────┘
                                   │
          ┌────────────────────────▼────────────────────────┐
          │  Layer C — Verifiable Receipts (post-execution)  │
          │  Proves WHAT happened                           │
          │  Ed25519 receipts · ProofGraph DAG · replay     │
          │  EvidencePack · Merkle condensation              │
          └─────────────────────────────────────────────────┘
                                   │
                                   ▼
                            Tools / Systems
```

---

## Layer A — Surface Containment

**When**: Design-time / configuration-time.
**Purpose**: Structural attack surface reduction. Shrink what can be called
before any runtime evaluation begins.

Surface containment is a **design-time property** — it is configured before
execution, not computed per-call. It defines the **bounded execution surface**:
the maximum possible set of tools, destinations, and side-effect classes that
an agent can reach.

### Mechanisms

| Mechanism | Description |
| :--- | :--- |
| **Capability manifests** | Explicit declaration of permitted tools per agent/profile |
| **Domain-scoped tool bundles** | Tools grouped by domain with independent governance |
| **Side-effect class profiles** | Read-only, write-limited, or full profiles per tool class |
| **Connector allowlists** | Per-tenant/app/profile restrictions on which connectors are reachable |
| **Destination scoping** | Explicit target domain/URL/resource allowlists |
| **Filesystem/network deny-by-default** | WASI sandbox denies all I/O unless explicitly granted |
| **Sandbox profile requirement** | Each tool class requires a declared sandbox profile before execution |

### Architectural Property

Surface containment reduces the **blast radius** of any exploitation.
Even if dispatch enforcement (Layer B) has a bug, the bounded surface
limits what an attacker can reach. This is defense in depth by construction,
not by runtime checking.

### Implementation References

| Component | Package |
| :--- | :--- |
| Sandbox isolation | `core/pkg/runtime/sandbox/` |
| Tool catalog / MCP gateway | `core/pkg/mcp/` |
| Manifest validation | `core/pkg/manifest/` |
| Budget ceiling (P0) | `core/pkg/runtime/budget/` |

---

## Layer B — Dispatch Enforcement

**When**: Dispatch-time (per-call).
**Purpose**: Runtime per-call admissibility. Every tool call passes through a
fail-closed policy gate that evaluates **execution admissibility** — the
determination that a specific call, with specific args, at a specific time,
under a specific policy stack, is permitted.

Dispatch enforcement is a **dispatch-time property** — it is computed for
every individual call. No call reaches an executor without a signed
`DecisionRecord`.

### Mechanisms

| Mechanism | Description |
| :--- | :--- |
| **Schema PEP** | JCS canonicalization + SHA-256, fail-closed on input/output schema mismatch |
| **PDP/CPI evaluation** | Canonical Policy Index resolves P0 → P1 → P2 → verdict |
| **Budget enforcement** | ACID-locked budget gates, fail-closed on ceiling breach (`BUDGET_EXCEEDED`) |
| **Contract pinning** | Connector response schemas are pinned; any drift produces `ERR_CONNECTOR_CONTRACT_DRIFT` |
| **PRG evaluation** | Proof Requirement Graph checks cryptographic prerequisites |
| **Deny-by-default** | Unknown tools → `DENY_TOOL_NOT_FOUND`. Unknown args → `DENY`. Policy error → `FAIL_CLOSED_ERROR` |
| **Delegation session enforcement** | Session capabilities ⊆ delegator's policy; expired/invalid sessions → `DELEGATION_INVALID` |
| **Threat scan** | TCB scanner detects prompt injection / command injection signals → `THREAT_SIGNAL_DETECTED` |
| **zkVM Safety Attestation** | Compiles and verifies agent safety assertions (AST static analysis) in ZK (RISC Zero zkVM) generating verifiable execution receipts |
| **TEE Enclave Secrets** | Silicon-sealed KMS vault wrapping (`SovereignKMSVault`) and inline token replacement proxy (`SecretProxyFilter`), preventing credentials from leaking to host memory/logs |

### Architectural Property

**Runtime execution enforcement** provides per-call guarantees:
every call is individually evaluated, every verdict is signed, every
denial is recorded. This is the choke point — the single enforcement
boundary that separates intent from effect.

### Key Term: Execution Admissibility

**Execution admissibility** is the canonical term for the PEP/CPI
determination that a specific tool call is permitted:

    Admissible iff:
      (1) tool ∈ declared surface (Layer A)
      (2) args conform to pinned schema
      (3) budget sufficient
      (4) PRG requirements satisfied
      (5) identity authorized for resource boundary
      (6) delegation session valid and in scope
      (7) no threat signals detected
      (8) all P0 ceilings respected

If any condition fails, the call is **inadmissible** and produces a
signed `DENY` verdict with a deterministic reason code.

### Implementation References

| Component | Package |
| :--- | :--- |
| Guardian (PEP) | `core/pkg/guardian/` |
| Policy contracts | `core/pkg/contracts/` |
| Gated execution | `core/pkg/executor/` |
| Canonicalization | `core/pkg/canonicalize/` |
| Approval ceremonies | `core/pkg/escalation/ceremony/` |
| zkVM Safety Checker | `core/pkg/crypto/zk/` |
| TEE Secrets Enclave | `core/pkg/crypto/tee/` |

---

## Layer C — Verifiable Receipts

**When**: Post-execution.
**Purpose**: Post-hoc verifiability. Every execution — allowed or denied —
produces cryptographic evidence that can be independently verified without
network access.

Verifiable receipts provide **offline-verifiable proof** that the execution
boundary operated correctly.

### Mechanisms

| Mechanism | Description |
| :--- | :--- |
| **Ed25519 signed receipts** | Every verdict (ALLOW and DENY) produces a signed record |
| **ProofGraph DAG** | Append-only directed acyclic graph with Lamport causal ordering |
| **Causal hash chain** | Each receipt signs over the previous receipt's signature (`PrevHash`) |
| **EvidencePack** | Deterministic `.tar` export — same inputs produce identical output bytes |
| **Merkle condensation** | Risk-tiered checkpoints; low-risk receipts replaceable by inclusion proofs |
| **Offline replay** | Replay from genesis without network access |
| **Deny receipts** | Denied calls produce signed receipts with reason codes — not just silently dropped |

### Architectural Property

The receipts layer is **independent of enforcement**. Even if enforcement
logic changes (Layer B), the receipt chain proves what actually happened.
This separation is critical: enforcement can err, but errors are always
visible in the receipt chain.

### Implementation References

| Component | Package |
| :--- | :--- |
| Receipt enforcement | `core/pkg/receipts/` |
| ProofGraph DAG | `core/pkg/proofgraph/` |
| Cryptographic signing | `core/pkg/crypto/` |
| Evidence export/verify | `core/pkg/evidence/` |
| Replay engine | `core/pkg/replay/` |
| Trust registry | `core/pkg/trust/registry/` |

---

## Why Three Layers

A single layer is insufficient:

| Single-Layer Approach | Failure Mode |
| :--- | :--- |
| Surface containment only | Correct tools can still be called with malicious args |
| Dispatch enforcement only | Correct enforcement with too-large surface = high blast radius |
| Receipts only | You see what happened after the damage is done |

The three-layer model provides **defense in depth by construction**:

1. **Layer A** reduces the maximum possible attack surface
2. **Layer B** gates every individual call at the choke point
3. **Layer C** provides independent proof of correct operation

Each layer protects against failures in the other two.

---

## Canonical Vocabulary

| Term | Layer | Definition |
| :--- | :--- | :--- |
| **Bounded surface** | A | The maximum set of reachable tools/destinations. Design-time property |
| **Surface containment** | A | The act of constraining the bounded surface |
| **Runtime execution enforcement** | B | Per-call policy evaluation and verdict issuance |
| **Execution admissibility** | B | The determination that a specific call is permitted |
| **Verifiable receipts** | C | Cryptographic evidence of execution decisions |
| **Execution authority** | All | The composite property: containment + enforcement + proof |

---

## Conformance Mapping

| Conformance Gate | Layer |
| :--- | :--- |
| JCS Canonicalization | B |
| PEP Boundary | B |
| WASI Sandbox | A |
| Approval Ceremony | B |
| ProofGraph DAG | C |
| Trust Registry | C |
| Evidence Pack | C |
| Offline Replay | C |
| Output Drift | B |
| Idempotency | B + C |
| Island Mode | A + C |
| Conformance Gates | All |

---

## Normative References

| Document | Relevance |
| :--- | :--- |
| [ARCHITECTURE.md](/helm-ai-kernel/architecture) | System-level model, VPL, TCB |
| [core/pkg/receipts](../core/pkg/receipts/) | Execution pipeline and receipt chain implementation |
| [OWASP_MCP_THREAT_MAPPING.md](/helm-ai-kernel/owasp-mcp-threat-mapping) | Adversary classes and defenses |
| [OWASP_MCP_THREAT_MAPPING.md](/helm-ai-kernel/owasp-mcp-threat-mapping) | OWASP MCP alignment |
| [core/pkg/manifest](../core/pkg/manifest/) | Layer A configuration primitives |
| [core/pkg/trust/registry](../core/pkg/trust/registry/) | TCB boundary and trust-registry rules |
| [CONFORMANCE.md](/helm-ai-kernel/conformance) | Gate definitions, levels |

_Canonical revision: 2026-05-21 · HELM UCS v1.5_


---
title: "MCP Integration"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/integrations/mcp"
source: "helm-ai-kernel/docs/INTEGRATIONS/mcp.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/INTEGRATIONS/mcp.md"
section: "integrations"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:fe77988561232d63bf6cfbbd5cd7514044c43abc7cad141b2796ea7495d1444a"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# MCP Integration

## Audience

Integration developers and operators routing MCP tool calls through the HELM AI Kernel firewall/quarantine path.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/integrations/mcp`
- Source document: `helm-ai-kernel/docs/INTEGRATIONS/mcp.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

This scheme maps the main sections of MCP Integration in reading order.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["MCP Integration"]
        B["OAuth Resource and Scope Enforcement"]
        C["Build a Bundle"]
        D["Install a Local Client Configuration"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        A["Run the Server"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C
    C --> D

    %% Premium Styling Rules
    style A fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
```


HELM retains an MCP surface for governed tool access.

The local boundary quickstart remains the entry point:

```bash
helm-ai-kernel serve --policy ./release.high_risk.v3.toml
```

## Run the Server

```bash
./bin/helm-ai-kernel mcp serve
```

## OAuth Resource and Scope Enforcement

`./bin/helm-ai-kernel mcp serve --auth oauth` supports production JWKS validation and the dev-only `HELM_OAUTH_BEARER_TOKEN` fallback. Production mode validates issuer, audience, expiration, issued-at, configured global scopes, and the MCP resource indicator before forwarding the request to the gateway.

Configure production OAuth with:

| Variable | Purpose |
| --- | --- |
| `HELM_OAUTH_JWKS_URL` | JWKS endpoint used to verify bearer-token signatures |
| `HELM_OAUTH_ISSUER` | Required `iss` claim |
| `HELM_OAUTH_AUDIENCE` | Required `aud` claim |
| `HELM_OAUTH_RESOURCE` | Required RFC 8707 resource indicator; defaults to `<base-url>/mcp` |
| `HELM_OAUTH_SCOPES` | Comma- or space-separated scopes required before gateway entry |

Tool definitions may also declare `required_scopes`. These are surfaced to MCP clients as `requiredScopes` in `tools/list` and are enforced again at execution time for both `/mcp/v1/execute` and JSON-RPC `tools/call`. A missing per-tool scope returns `MCP.OAUTH.INSUFFICIENT_SCOPE` on the REST surface or a JSON-RPC application error on the streamable MCP surface.

The resource check follows [RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707): the MCP gateway treats the token audience plus `resource` / `resources` token members as accepted resource indicators and rejects tokens that are not minted for this MCP endpoint.

## Build a Bundle

```bash
./bin/helm-ai-kernel mcp pack --client claude-desktop --out helm-ai-kernel.mcpb
```

## Install a Local Client Configuration

```bash
./bin/helm-ai-kernel mcp install --client claude-code
```

Use `./bin/helm-ai-kernel mcp print-config --client <name>` for text configuration snippets where supported by the CLI.

## Quarantine and Schema Pins

Unknown MCP servers are quarantined by default. A call is dispatchable only
after server discovery, metadata/schema inspection, risk classification,
approval bound to a HELM receipt, and a matching pinned schema hash.

The maintained local demo covers this full path:

```bash
./scripts/launch/demo-mcp.sh
```

The demo asserts that unknown servers, unknown tools, and missing schema pins
return `DENY` or `ESCALATE`; they never dispatch to the fixture server.

MCP activity that emits receipts can be inspected with:

```bash
helm-ai-kernel receipts tail --agent <agent-id>
```

<!-- docs-depth-final-pass -->

## MCP Integration Checklist

A complete MCP integration claim includes the transport, tool list, input schema, output schema, receipt behavior, denial behavior, and a validation command. The public example must show at least one allowed call and one policy-denied call, with the receipt or diagnostic ID a developer should capture. Keep model-provider setup separate from MCP governance: the server exposes a controlled tool boundary, while HELM owns policy evaluation, evidence capture, and verifier replay. If a tool is experimental, mark it as such and keep it out of conformance tables until it has schema and fixture coverage.


---
title: "Microsoft Agent Governance Toolkit Coexistence"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/integrations/microsoft-agent-governance-toolkit"
source: "helm-ai-kernel/docs/INTEGRATIONS/microsoft_agent_governance_toolkit.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/INTEGRATIONS/microsoft_agent_governance_toolkit.md"
section: "integrations"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:f72438b635c12d5c4f5e6fdba9f1489c3231af76e7f15a7327dec49add3a390c"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Microsoft Agent Governance Toolkit Coexistence

## Audience

Integration developers mapping Microsoft agent tooling through the HELM OpenAI-compatible proxy and receipt flow.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/integrations/microsoft-agent-governance-toolkit`
- Source document: `helm-ai-kernel/docs/INTEGRATIONS/microsoft_agent_governance_toolkit.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

This scheme maps the main sections of Microsoft Agent Governance Toolkit Coexistence in reading order.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["Microsoft Agent Governance Toolkit Coexistence"]
        A["TypeScript SDK Coverage"]
        B["Deployment Pattern"]
        C["Limits"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C

    %% Premium Styling Rules
```


Microsoft announced Agent Governance Toolkit (AGT) on 2026-04-02 as an open-source runtime governance layer for autonomous AI agents. The announcement and repository position AGT around deterministic action policy, zero-trust identity, sandboxing, SRE controls, and framework integrations across LangGraph, CrewAI, OpenAI Agents SDK, PydanticAI, LlamaIndex, and adjacent agent stacks.

HELM should not replace AGT in a customer environment that has already standardized on it. The narrow integration stance is:

- AGT can remain the framework-local governance layer.
- HELM sits below it as the non-bypassable, receipt-bearing boundary for tool execution.
- HELM evidence packs remain the audit artifact when execution must be replayed or independently verified.

## TypeScript SDK Coverage

The `@mindburn/helm-ai-kernel` TypeScript SDK includes adapter helpers for the framework families called out in the AGT launch surface:

| Framework | Helper |
| --- | --- |
| LangGraph | `fromLangGraphToolCall` |
| CrewAI | `fromCrewAITask` |
| OpenAI Agents SDK | `fromOpenAIAgentsToolCall` |
| PydanticAI | `fromPydanticAIToolCall` |
| LlamaIndex | `fromLlamaIndexToolCall` |

Each helper normalizes a native tool-call event into an OpenAI-compatible HELM request and submits it through `chatCompletionsWithReceipt`. The framework adapter does not execute the tool. It prepares the intent for HELM policy, then returns the kernel-issued governance metadata from `X-Helm-*` headers.

```ts
import { HelmClient, createAgentFrameworkAdapter, fromLangGraphToolCall } from "@mindburn/helm-ai-kernel";

// This example targets `helm-ai-kernel server` on its default API port. Use
// http://localhost:7714 for `helm-ai-kernel serve` or http://localhost:9090/v1 for the
// OpenAI-compatible proxy path.
const helm = new HelmClient({ baseUrl: "http://127.0.0.1:7714" });
const adapter = createAgentFrameworkAdapter(helm, {
  model: "helm-governance",
  metadata: { boundary: "agt-coexistence" },
});

const governed = await adapter.submit(
  fromLangGraphToolCall({
    id: "call-lg-1",
    name: "warehouse.query",
    args: { table: "orders", limit: 10 },
  }),
);

console.log(governed.governance.receiptId);
```

## Deployment Pattern

Run the framework agent exactly where it already runs. Configure AGT or framework-local middleware first. Before any side-effecting tool executes, normalize that tool event with the HELM SDK helper and submit it to the HELM boundary. Execute the original tool only when the HELM response path returns a permitted result and a receipt is present.

For OpenAI-compatible stacks, prefer routing through the HELM proxy base URL when possible. For native framework hooks, use the adapter helpers so the same action metadata reaches HELM even when the framework does not speak OpenAI's request shape directly.

## Limits

This is compatibility coverage, not Microsoft certification. The helpers do not import AGT packages, do not modify AGT policies, and do not validate AGT evidence files. They give HELM a typed bridge for the same framework families so AGT and HELM can coexist without duplicating framework-specific glue in every customer project.

Primary sources verified on 2026-04-30:

- Microsoft Open Source Blog: <https://opensource.microsoft.com/blog/2026/04/02/introducing-the-agent-governance-toolkit-open-source-runtime-security-for-ai-agents/>
- Microsoft AGT repository: <https://github.com/microsoft/agent-governance-toolkit>
- Microsoft AGT releases: <https://github.com/microsoft/agent-governance-toolkit/releases>


---
title: "OpenAI-Compatible Proxy Integration"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/integrations/openai-compatible-proxy"
source: "helm-ai-kernel/docs/INTEGRATIONS/openai_baseurl.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/INTEGRATIONS/openai_baseurl.md"
section: "integrations"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-12"
checksum_sha256: "sha256:cb3d9b9c6b6ebf7da4457d43d8776f57871e460934012bd742d4ffff647fbd57"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# OpenAI-Compatible Proxy Integration

## Audience

Developers who already use OpenAI-shaped clients and want requests to cross the HELM AI Kernel execution boundary before they reach an upstream provider.

## Outcome

After this integration you should have a local OpenAI-compatible base URL at `http://127.0.0.1:9090/v1`, a HELM AI Kernel boundary on `127.0.0.1:7714`, and a receipt inspection path that proves the application did not bypass HELM.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Client["OpenAI-compatible client"]
        Proxy["helm-ai-kernel proxy :9090/v1"]
        Boundary["HELM execution boundary"]
        Upstream["configured upstream"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Receipts["signed receipts"]
    end

    %% Operational Flow Edges
    Client --> Proxy
    Proxy --> Boundary
    Boundary --> Upstream
    Boundary --> Receipts

    %% Premium Styling Rules
    style Receipts fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Source Truth

- CLI proxy implementation: [`core/cmd/helm-ai-kernel/proxy_cmd.go`](../../core/cmd/helm-ai-kernel/proxy_cmd.go)
- Local boundary command: [`core/cmd/helm-ai-kernel/server_cmd.go`](../../core/cmd/helm-ai-kernel/server_cmd.go), [`core/cmd/helm-ai-kernel/serve_policy.go`](../../core/cmd/helm-ai-kernel/serve_policy.go)
- Receipt routes: [`core/cmd/helm-ai-kernel/receipt_routes.go`](../../core/cmd/helm-ai-kernel/receipt_routes.go)
- Source-backed examples: [`examples/python_openai_baseurl/`](../../examples/python_openai_baseurl/), [`examples/ts_openai_baseurl/`](../../examples/ts_openai_baseurl/), [`examples/js_openai_baseurl/`](../../examples/js_openai_baseurl/)

The proxy is an OpenAI-compatible request boundary. It is not hosted operations and it does not certify provider SDK behavior.

The current naming is deliberate: this integration is the OpenAI-compatible
proxy, not a Vercel-specific adapter. Existing framework or provider examples
should describe the base URL contract they exercise and keep provider-specific
claims in source-backed example pages. Do not reintroduce deleted Vercel example
paths or document a framework SDK as supported unless the retained example
imports that SDK and is covered by a validation command.

The proxy path has one job: preserve an OpenAI-shaped client interface while
moving authorization and receipt emission into HELM. A successful upstream
response is not enough evidence. The operator should be able to show that the
request host was HELM, that the boundary emitted a decision, and that receipt
inspection works for the same request.

## Start The Boundary

```bash
make build
./bin/helm-ai-kernel serve --policy ./release.high_risk.v3.toml
```

`helm-ai-kernel serve --policy` binds the local policy boundary to `http://127.0.0.1:7714` by default.

Start a mock upstream and the OpenAI-compatible proxy:

```bash
python3 scripts/launch/mock-openai-upstream.py --port 19090
./bin/helm-ai-kernel proxy \
  --upstream http://127.0.0.1:19090/v1 \
  --port 9090 \
  --receipts-dir ./helm-receipts
```

Applications that use OpenAI-shaped HTTP clients should point their base URL at:

```text
http://127.0.0.1:9090/v1
```

Do not document `3000` as a default. Use it only when the local command explicitly binds that port.

## Python Example

```bash
cd examples/python_openai_baseurl
HELM_URL=http://127.0.0.1:7714 PYTHONPATH=../../sdk/python python main.py
```

## TypeScript Example

```bash
cd examples/ts_openai_baseurl
HELM_URL=http://127.0.0.1:7714 npx tsx main.ts
```

## JavaScript Fetch Example

```bash
cd examples/js_openai_baseurl
HELM_URL=http://127.0.0.1:7714 node main.js
```

## Receipt Behavior

Allowed and denied requests should produce HELM receipts. The CLI receipt tail requires an agent filter:

```bash
./bin/helm-ai-kernel receipts tail --agent <agent-id> --server http://127.0.0.1:7714
```

The HTTP route `GET /api/v1/receipts/tail` can be used directly when an unfiltered stream is appropriate.

| Metadata | Meaning |
| --- | --- |
| `X-Helm-Decision-ID` | Decision identifier emitted by the HELM boundary |
| `X-Helm-Receipt-ID` | Receipt identifier for the governed request |
| `X-Helm-Reason-Code` | ALLOW, DENY, or ESCALATE reason context |
| `X-Helm-Output-Hash` | Hash of the governed output |
| `X-Helm-Status` | Governance status for the proxied response |
| `X-Helm-Correlation-ID` | Trace and receipt correlation value |

Some OpenAI-compatible clients hide raw response headers. In that case, inspect the receipt stream or use a HELM SDK path that exposes receipt metadata.

## Verification

Before publishing a new proxy example, prove both outcomes:

- an allowed request returns upstream-shaped output and a HELM receipt;
- a denied or escalated request does not silently dispatch;
- the application does not call the upstream provider directly.

```bash
make test-sdk-py
make test-sdk-ts
cd core && go test ./cmd/helm-ai-kernel -run 'Test.*Route|Test.*OpenAPI|Test.*Receipt' -count=1
```

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| no receipts appear | the app still calls the upstream provider directly | log the request host and set the client base URL to HELM |
| denied request retries forever | client treats a policy denial as transient | do not retry definitive DENY decisions |
| upstream auth fails | provider credentials are not configured for the selected upstream | configure provider auth in the upstream environment |
| receipt tail exits with usage | missing CLI agent filter | pass `--agent <agent-id>` or use the HTTP route directly |
| examples use the wrong port | local command used a non-default port | align `--port`, `HELM_URL`, and client `baseURL` |

When troubleshooting, prove the request host first. A successful model response is not proof that the request crossed HELM unless the receipt route or SDK response metadata shows a HELM decision.


---
title: "KERNEL_SCOPE"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/kernel-scope"
source: "helm-ai-kernel/docs/KERNEL_SCOPE.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/KERNEL_SCOPE.md"
section: "helm-ai-kernel"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-12"
checksum_sha256: "sha256:d1e6b32fa2990d840ed4d838dc70b2c31c112afbf3557d6e2b4871e2a58d7cea"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM AI Kernel Scope

## Audience

Maintainers, adopters, and downstream packagers deciding what is in HELM AI Kernel and what is outside this repository.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/helm-ai-kernel-scope`
- Source document: `helm-ai-kernel/docs/KERNEL_SCOPE.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

> **Canonical architecture**: see [ARCHITECTURE.md](/helm-ai-kernel/architecture) for the
> normative trust boundary model and TCB definition. For the canonical
> 8-package TCB inventory, see [ARCHITECTURE.md](/helm-ai-kernel/architecture).

HELM AI Kernel is the **open execution kernel and self-hostable Console** of the HELM stack.

It exists to keep the deterministic boundary small, portable, and independently trustworthy. Downstream HELM layers must extend this kernel through public contracts, not replace it.

## Kernel TCB (Trusted Computing Base)

The canonical TCB is bounded to **8 packages** — the minimal trusted core.
See [ARCHITECTURE.md](/helm-ai-kernel/architecture) for the authoritative package list,
expansion criteria, and CI enforcement details.

## Active OSS Packages

The following packages are part of the OSS kernel, including both TCB and
non-TCB supporting infrastructure:

### TCB Packages

| Package            | Purpose                                                       | Status    |
| ------------------ | ------------------------------------------------------------- | --------- |
| `contracts/`       | Canonical data structures (Decision, Effect, Receipt, Intent) | ✅ Active |
| `crypto/`          | Ed25519 signing, JCS canonicalization                         | ✅ Active |
| `guardian/`        | Policy Enforcement Point (PEP), PRG enforcement               | ✅ Active |
| `executor/`        | SafeExecutor with receipt generation                          | ✅ Active |
| `proofgraph/`      | Cryptographic ProofGraph DAG                                  | ✅ Active |
| `trust/registry/`  | Event-sourced trust registry                                  | ✅ Active |
| `runtime/sandbox/` | WASI sandbox (wazero, deny-by-default)                        | ✅ Active |
| `receipts/`        | Receipt policy enforcement (fail-closed)                      | ✅ Active |

### Supporting Infrastructure (Non-TCB)

| Package                | Purpose                                    | Status    |
| ---------------------- | ------------------------------------------ | --------- |
| `canonicalize/`        | RFC 8785 JCS implementation                | ✅ Active |
| `manifest/`            | Tool args/output validation (PEP boundary) | ✅ Active |
| `agent/adapter.go`     | KernelBridge choke point                   | ✅ Active |
| `runtime/budget/`      | Compute budget enforcement                 | ✅ Active |
| `escalation/ceremony/` | RFC-005 Approval Ceremony                  | ✅ Active |
| `genesis/ceremony/`    | VGL six-phase Genesis ceremony state machine | ✅ Active |
| `evidence/`            | Evidence pack export/verify                | ✅ Active |
| `replay/`              | Replay engine for verification             | ✅ Active |
| `mcp/`                 | Tool catalog + MCP gateway                 | ✅ Active |
| `kernel/`              | Rate limiting, backpressure                | ✅ Active |
| `a2a/`                 | Agent-to-Agent trust protocol              | ✅ Active |
| `otel/`                | OpenTelemetry governance telemetry         | ✅ Active |
| `identity/did/`        | W3C DID-based agent identity               | ✅ Active |
| `policy/reconcile/`    | Runtime policy source reconciliation and snapshot swap | ✅ Active |

### Frontier / Spec-Only Surfaces

The following names appear in strategy, standard, or roadmap material but are not active source paths in this OSS repository as of the v1.3 convergence pass. They MUST NOT be documented as shipped packages until source, tests, and conformance vectors exist under the matching path:

- `crypto/hybrid/`
- `crypto/zkproof/`
- `memory/`
- `threatscan/ensemble/`
- `evidencepack/summary/`
- `skillfortify/`
- `provenance/`
- `budget/cost/`
- `delegation/aip/`
- `replay/comparison/`
- `a2a/federation/`
- `mcptox/`
- `effects/reversibility/`
- `observability/slo_engine/`
- `otel/cloudevents/`
- `connectors/ddipe/`

### Deployment Infrastructure

| Package                         | Purpose                                  | Status    |
| ------------------------------- | ---------------------------------------- | --------- |
| `deploy/helm-chart/`            | Kubernetes Helm chart, optional HelmPolicyBundle CRD template | ✅ Active |
| `protocols/spec/`               | RFC-style protocol specification         | ✅ Active |
| `protocols/conformance/v1/owasp/` | Machine-readable OWASP threat vectors  | ✅ Active |

### Product Surfaces

The OSS boundary ships exactly one browser UI: `apps/console`, the HELM AI Kernel Console. It is a self-hostable operator surface over the local kernel and uses `@mindburn/ui-core` for all product UI primitives and styling. The repository does not ship a second browser UI, a static report viewer, a Node CLI wrapper, a Next starter, or generated HTML report surface.

`@mindburn/ui-core` remains a reusable React/token package. The Console consumes it through public package entrypoints so package integrity, app fidelity, and OSS boundary truth are tested together.

## Removed from TCB (Enterprise)

The following packages were removed to minimize the attack surface:

| Package                    | Reason                        |
| -------------------------- | ----------------------------- |
| `access/`                  | Enterprise access control     |
| `ingestion/`               | Brain subsystem data pipeline |
| `verification/refinement/` | Enterprise verification       |
| `cockpit/`                 | Product console               |
| `ops/`                     | Operations tooling            |
| `multiregion/`             | Multi-region orchestration    |
| `hierarchy/`               | Enterprise hierarchy          |
| `heuristic/`               | Heuristic analysis            |
| `perimeter/`               | Network perimeter             |

## First-Class Execution Surfaces

### MCP Interceptor

The MCP gateway (`core/pkg/mcp/`) is a **first-class governed surface**,
not an adapter. It provides:

- Tool discovery with governance metadata (`/mcp/v1/capabilities`)
- Governed tool execution with signed receipts (`/mcp/v1/execute`)
- Schema validation against pinned tool contracts
- Full ProofGraph integration — MCP calls produce the same receipt chain
  as OpenAI proxy calls

### OpenAI-Compatible Proxy

The governed proxy (`/v1/chat/completions`) intercepts OpenAI-compatible
tool calls and routes them through the PEP boundary.

### Bounded-Surface Primitives

The OSS kernel includes configurable surface containment primitives
(see [EXECUTION_SECURITY_MODEL.md](/helm-ai-kernel/execution-security-model)):

- Domain-scoped tool bundles
- Explicit capability manifests
- Read-only / write-limited / side-effect-class profiles
- Connector allowlists
- Destination scoping
- Filesystem/network deny-by-default (WASI)
- Sandbox profile requirement per tool class

## Boundary Truth

OSS includes:

- **Surface containment** — capability manifests, tool bundles, sandbox profiles
- **Dispatch enforcement** — fail-closed PEP, policy evaluation, budget gates
- **Verifiable receipts** — signed receipts, ProofGraph, replay
- **MCP interceptor** — first-class governed MCP surface
- **OpenAI proxy** — governed proxy for OpenAI-compatible SDKs
- **HELM AI Kernel Console** — one self-hostable browser UI for command, receipts, policy, MCP, evidence, replay, ProofGraph, conformance, trust, incidents, audit, developer, and settings workflows
- Adapters and integration surfaces

OSS does not include:

- Hosted Mindburn operations
- Enterprise identity and admin beyond the OSS runtime contract
- Legal hold, long-term hosted retention, or regulator-facing workflows
- Organization-scale rollout, staging, or shadow enforcement on live production traffic
- Managed federation or hosted trust registries
- Private entitlement, seat management, usage metering, or account-management systems
- Non-OSS connector certification programs

The invariant is simple: OSS must stay fully useful on its own as a developer-first execution kernel and self-hostable Console: Go CLI, HTTP/API contracts, SDKs, evidence export, offline verification, replay, conformance, Console assets, and release artifacts. Hosted or organization-specific operations live outside this repository and integrate through those public contracts.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        kernel["Kernel scope"]
        retain["Retained public surfaces"]
        cli["CLI and proxy"]
        sdk["SDKs and examples"]
        protocol["Protocols and schemas"]
        exclude["Excluded hosted surfaces"]
        commercial["HELM commercial docs"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        verify["Receipts and verification"]
    end

    %% Operational Flow Edges
    kernel --> retain
    retain --> cli
    retain --> sdk
    retain --> protocol
    retain --> verify
    kernel --> exclude
    exclude --> commercial

    %% Premium Styling Rules
    style verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


---
title: "HELM Launchpad"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/launchpad"
source: "helm-ai-kernel/docs/LAUNCHPAD.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/LAUNCHPAD.md"
section: "start-here"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-20"
checksum_sha256: "sha256:b02f61386ff66b8758fdb6a056b1b1159d3a93481792f8161532f371d335c1e6"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM Launchpad

Status: OpenClaw, Hermes, OpenCode, and Kilo Code are `oss_supported` for
`local-container` after signed artifact, SBOM, vulnerability scan, live
conformance, teardown, receipt, and offline EvidencePack verification in
workflow `26198407296`. Codex, Claude Code, Cursor, and Junie remain external
BYO adapters.

LaunchKit is the product entrypoint for one-command app bootstrap. It uses the
existing Launchpad registry/runtime/receipt implementation as the compatibility
foundation, then exposes the Tier-1 operator command:

```bash
helm up openclaw
helm up hermes --target cloud:aws --verify-only
```

Launchpad remains the OSS local-container implementation layer. LaunchKit starts
verified AI apps through a fail-closed execution firewall, preserves the MCP
interceptor posture, records signed receipts, emits EvidencePacks that verify
offline, and opens the Console at the receipt-backed run URL.

## Audience

Operators and maintainers validating the release-backed Launchpad path in HELM
AI Kernel.

## Outcome

You can identify the supported app matrix, the exact verifier commands, the
GHCR digests promoted by CI, and the passing clean-install gate behind public
GA claims.

## Source Truth

- CLI entrypoint: `core/cmd/helm-ai-kernel/launch_cmd.go`
- Runtime package: `core/pkg/launchpad/`
- App and substrate registry: `registry/launchpad/`
- Policy packs: `policies/launchpad/`
- Contract schemas: `schemas/launchpad/`
- UX architecture: `docs/launchpad/UX_ARCHITECTURE.md`
- Hosted account/entitlement target contract:
  `docs/launchpad/MINDBURN_ACCOUNT_ENTITLEMENTS_SPEC.md`
- Release report: `docs/launchpad/final_report.json`
- Clean-install GA gate: `docs/launchpad/CLEAN_INSTALL_GA.md`
- v1.0 redacted evidence report: `docs/launchpad/v1_report.json`

## Current CLI

```bash
helm up openclaw
helm up hermes --target local
helm up openclaw --demo
helm up hermes --verify-only
helm up hermes --target cloud:aws --yes
helm up openclaw --resume <run_id>
helm-ai-kernel launch matrix --json
helm-ai-kernel launch apps --json
helm-ai-kernel launch substrates --json
helm-ai-kernel launch secrets set model_gateway --provider openrouter --value-env OPENROUTER_API_KEY
helm-ai-kernel launch secrets status
helm-ai-kernel launch plan openclaw local-container --json
helm-ai-kernel launch openclaw local-container --headless --output json
helm-ai-kernel launch hermes local-container --headless --output json
helm-ai-kernel launch opencode local-container --headless --output json
helm-ai-kernel launch kilocode local-container --headless --output json
helm-ai-kernel launch openclaw digitalocean --live-cloud-beta --approval <approval_id> --cost-ceiling-usd <n> --headless --output json
helm-ai-kernel launch hermes hetzner --live-cloud-beta --approval <approval_id> --cost-ceiling-usd <n> --headless --output json
helm-ai-kernel launch status <launch_id> --json
helm-ai-kernel launch logs <launch_id>
helm-ai-kernel launch repair <launch_id>
helm-ai-kernel launch delete <launch_id> --cascade
helm-ai-kernel launch evidence <launch_id> --export --json
helm-ai-kernel launch evidence <launch_id> --output <dir>
helm-ai-kernel evidence inspect <pack>
helm-ai-kernel evidence diff <pack-a> <pack-b>
helm-ai-kernel verify --bundle <pack>
```

`helm-ai-kernel` remains the backwards-compatible binary and command namespace.
Release builds also ship `helm` as the primary product command.

## Account and Entitlement Boundary

The Kernel repo currently exposes one self-hostable Launchpad surface backed by
the existing Launchpad APIs. Free, Individual, and Enterprise hosted account
entitlements are target architecture, not production Kernel behavior in this
repo. Console must not infer account tier or invent entitlement state; it may
only render explicit backend fields or clearly labeled test fixtures. The
hosted integration contract lives in
`docs/launchpad/MINDBURN_ACCOUNT_ENTITLEMENTS_SPEC.md`.

## App Classification

| App | Availability | Evidence |
| --- | --- | --- |
| OpenClaw | `oss_supported` | `ghcr.io/mindburn-labs/helm-launchpad/openclaw@sha256:4da80a1e48b5603fd203b7d2b98539a01f796142b0ed9315e5ed86b25bf5d995`; workflow `26198407296`; live conformance, teardown, receipts, and offline EvidencePack verification passed |
| Hermes | `oss_supported` | `ghcr.io/mindburn-labs/helm-launchpad/hermes@sha256:4ec024dd8d0191fc887f04dc92c959fc865808d1526f782b5093f395fdd41652`; workflow `26198407296`; live conformance, teardown, receipts, and offline EvidencePack verification passed |
| OpenCode | `oss_supported` | `ghcr.io/mindburn-labs/helm-launchpad/opencode@sha256:cdbeb88cfbd698809e673339d525083cdf1cdb3e91529e01c6834cd90b778550`; workflow `26198407296`; live conformance, teardown, receipts, and offline EvidencePack verification passed |
| Kilo Code | `oss_supported` | `ghcr.io/mindburn-labs/helm-launchpad/kilocode@sha256:7b03834725235714ea8e698d38d89ce9b8bd81230b7e784016cb20a2c3c93ca6`; workflow `26198407296`; live conformance, teardown, receipts, and offline EvidencePack verification passed |
| Codex / Claude Code / Cursor / Junie | `external_proprietary_adapter` | BYO/external adapters only; HELM governs execution and does not redistribute them |

## Safety Model

- Runtime verdicts are only `ALLOW`, `DENY`, or `ESCALATE`.
- `oss_supported` requires license, immutable signed OCI artifact, policy pack,
  sandbox, healthcheck, e2e, signed MCP manifest refs, teardown, signed
  receipts, a hash-chained EvidencePack graph, and offline-verifiable proof.
- Local default substrate is `local-container`.
- Registry substrate metadata now declares isolation strength, network
  enforcement, secret mode, receipt support, teardown proof, and lifecycle
  support. Substrates without receipts or teardown proof cannot graduate beyond
  experimental.
- OpenRouter egress uses launch-scoped proxy receipts; non-OpenRouter allowlists
  are rejected.
- Current local-container model access uses a logical `model_gateway` secret
  binding that projects the provider env var only inside the launch process.
  Proxy-only secretless model access remains the stricter target and is not yet
  a public GA claim.
- Supported apps route MCP through HELM-owned signed manifest refs. Unknown
  servers/tools quarantine, schema pins are required, and side-effect tools
  require approval receipts.
- DigitalOcean and Hetzner cloud substrates remain opt-in beta and dry-run by
  default. CLI live paths require `--live-cloud-beta`, an approval receipt, a
  cost ceiling, provider readiness, and idempotency reconciliation before any
  public claim can move beyond beta.
- Host `curl | bash`, mutable live git update, and package-manager mutation
  inside the current worktree are denied by installer tests.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Registry["Registry entry"]
        Plan["Deterministic launch plan"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        Policy["Policy pack"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Gate["ALLOW / DENY / ESCALATE"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Receipt["Signed receipt"]
        Evidence["Offline EvidencePack"]
    end

    %% Operational Flow Edges
    Registry --> Policy
    Policy --> Plan
    Plan --> Gate
    Gate --> Receipt
    Receipt --> Evidence

    %% Premium Styling Rules
    style Policy fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Gate fill:#e53e3e,stroke:#9b2c2c,stroke-width:2px,color:#fff
    style Receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Evidence fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Evidence Inspection

Every generated Launchpad EvidencePack includes `04_EXPORTS/launchpad_evidence_graph.json`.
The graph hash-chains receipts for plan/verdict, sandbox preflight, MCP
quarantine, model gateway grant, install, start, healthcheck, teardown, and
failure paths when present.

```bash
helm-ai-kernel evidence inspect <pack>
helm-ai-kernel evidence inspect <pack> --json
helm-ai-kernel evidence diff <pack-a> <pack-b>
helm-ai-kernel verify --bundle <pack>
```

## Clean Install Gate

Clean-install validation is intentionally separate from the build machine:

```bash
brew update
brew install mindburnlabs/tap/helm-ai-kernel
helm-ai-kernel launch matrix --json
helm-ai-kernel launch openclaw local-container --headless --output json
helm-ai-kernel launch hermes local-container --headless --output json
helm-ai-kernel launch opencode local-container --headless --output json
helm-ai-kernel launch kilocode local-container --headless --output json
helm-ai-kernel launch delete <launch_id> --cascade
helm-ai-kernel verify --bundle <pack>
```

The reusable gate is `scripts/launch/clean_install_gate.sh`. It writes only
redacted JSON evidence to `docs/launchpad/clean_install_report.json`; raw logs,
provider keys, key fragments, and host identifiers are not committed.

`--include-candidates` remains accepted for backward compatibility, but
OpenCode and Kilo Code are part of the supported clean-install app set after
workflow `26198407296`.

For current source-backed details, use the Launchpad specs and conformance docs:
`docs/launchpad/APP_SPEC.md`, `docs/launchpad/SUBSTRATE_SPEC.md`,
`docs/launchpad/POLICY_PACKS.md`, `docs/launchpad/SECURITY_REVIEW.md`,
`docs/launchpad/CONFORMANCE.md`, and `docs/launchpad/CLEAN_INSTALL_GA.md`.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A launch reaches `REPAIR_REQUIRED` | Check `helm-ai-kernel launch logs <launch_id>` and `helm-ai-kernel launch evidence <launch_id> --export --json`; logs redact scoped provider keys. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |


---
title: "Launchpad Clean Install GA"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/launchpad/clean-install-ga"
source: "helm-ai-kernel/docs/launchpad/CLEAN_INSTALL_GA.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/launchpad/CLEAN_INSTALL_GA.md"
section: "start-here"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-20"
checksum_sha256: "sha256:90b7b0399cf9bd55d47b5b5ec528ba11a7739b82f6e100f9e8fa141e23e4f178"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Launchpad Clean Install GA

Status: v0.5.5 gate implemented; v1 promotes OpenClaw, Hermes, OpenCode, and
Kilo Code into the supported-app clean-install set after workflow
`26198407296` passed signed artifact, live conformance, teardown, receipts, and
offline EvidencePack verification.

Launchpad GA is a product-adoption gate for the `v0.5.5` release. It proves the
Homebrew package, signed Launchpad artifacts, local-container app launcher,
MCP interceptor posture, signed receipts, teardown, and offline EvidencePack
verification survive a machine that did not build the release.

## Audience

This page is for release owners, Launchpad maintainers, and operators who need
to prove a supported app can be installed and removed from a clean workstation
without relying on a developer checkout.

## Outcome

You should leave with the supported-app gate, the exact clean-machine command
sequence, and the evidence files that prove install, launch, teardown, and
offline verification.

## Source Truth

- Release target: `v0.5.5`
- Current four-app Launchpad artifact workflow: <https://github.com/Mindburn-Labs/helm-ai-kernel/actions/runs/26198407296>
- Current macOS Homebrew clean-install workflow: <https://github.com/Mindburn-Labs/helm-ai-kernel/actions/runs/26199878246>
- Current Launchpad v1 report: `docs/launchpad/v1_report.json`
- Historical `v0.5.4` release report: `docs/launchpad/final_report.json`
- Clean-install report: `docs/launchpad/clean_install_report.json`

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        brew["Homebrew install"]
        matrix["Launch matrix"]
        apps["OpenClaw / Hermes / OpenCode / Kilo"]
        teardown["Cascade delete"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        secret["Logical model_gateway secret"]
        audit["Secret-fragment audit"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        verify["Offline EvidencePack verify"]
    end

    %% Operational Flow Edges
    brew --> matrix
    matrix --> secret
    secret --> apps
    apps --> teardown
    teardown --> verify
    verify --> audit

    %% Premium Styling Rules
    style secret fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style audit fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
```


## Required Secret

Live local-container conformance uses a scoped OpenRouter test key. Store the
fresh CI-only key as `HELM_LAUNCHPAD_CI_OPENROUTER_API_KEY`. Workflows map it to
`OPENROUTER_API_KEY` only inside the live Launchpad test step. Do not commit the
key, fragments, screenshots, or raw logs.

## Clean Machine Commands

Run these from a clean macOS developer machine with Homebrew, `gh`, and a
Docker-compatible runtime such as Docker Desktop or Colima:

```bash
brew update
brew install mindburnlabs/tap/helm-ai-kernel
helm-ai-kernel launch matrix --json
helm-ai-kernel launch secrets set model_gateway --provider openrouter --value-env OPENROUTER_API_KEY
helm-ai-kernel launch openclaw local-container --headless --output json
helm-ai-kernel launch hermes local-container --headless --output json
helm-ai-kernel launch opencode local-container --headless --output json
helm-ai-kernel launch kilocode local-container --headless --output json
helm-ai-kernel launch delete <launch_id> --cascade
helm-ai-kernel verify --bundle <pack>
```

Use the repo-native gate to collect redacted evidence:

```bash
export HELM_LAUNCHPAD_CI_OPENROUTER_API_KEY='<fresh CI-only key>'
bash scripts/launch/clean_install_gate.sh \
  --release-tag v0.5.5 \
  --artifact-run-id 26198407296 \
  --host-kind developer_macos \
  --output docs/launchpad/clean_install_report.json
```

The script downloads the signed Launchpad artifact manifest, resolves the
immutable egress-proxy image, confirms app GHCR digests, launches the selected
app set through `local-container`, deletes each launch with `--cascade`, verifies every
produced EvidencePack, and scans command output, GitHub logs, release
notes/assets, reports, and EvidencePacks for the CI key and fixed-length key
fragments without printing the secret. The default supported app set is
OpenClaw, Hermes, OpenCode, and Kilo Code. `--include-candidates` remains
accepted for backward compatibility.

## Supported App Digests

| App | Availability | Image |
| --- | --- | --- |
| OpenClaw | `oss_supported` | `ghcr.io/mindburn-labs/helm-launchpad/openclaw@sha256:4da80a1e48b5603fd203b7d2b98539a01f796142b0ed9315e5ed86b25bf5d995` |
| Hermes | `oss_supported` | `ghcr.io/mindburn-labs/helm-launchpad/hermes@sha256:4ec024dd8d0191fc887f04dc92c959fc865808d1526f782b5093f395fdd41652` |
| OpenCode | `oss_supported` | `ghcr.io/mindburn-labs/helm-launchpad/opencode@sha256:cdbeb88cfbd698809e673339d525083cdf1cdb3e91529e01c6834cd90b778550` |
| Kilo Code | `oss_supported` | `ghcr.io/mindburn-labs/helm-launchpad/kilocode@sha256:7b03834725235714ea8e698d38d89ce9b8bd81230b7e784016cb20a2c3c93ca6` |

Codex, Claude Code, Cursor, and Junie remain external/BYO adapters.

## CI Gate

Manual CI entrypoint:

```bash
gh workflow run launchpad-clean-install.yml \
  --repo Mindburn-Labs/helm-ai-kernel \
  -f release_tag=v0.5.5 \
  -f artifact_run_id=26198407296
```

The CI report is the current repeatable macOS Homebrew gate. A separately
operated clean Mac transcript can be attached as an additional adoption artifact
when release owners need a non-CI workstation record.

## Troubleshooting

| Condition | Response |
| --- | --- |
| Homebrew package is unavailable | Recheck the release tag, tap PR, and release workflow before running app launch commands. |
| Launch fails before receipts | Treat the gate as failed and inspect policy, sandbox, and provider readiness from the redacted report. |
| EvidencePack verification fails | Do not promote the app; rerun with fresh artifacts and preserve the failed verification output. |
| Teardown leaves resources | Reconcile local/container resources before declaring the machine clean. |


---
title: "Launchpad Conformance"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/launchpad/conformance"
source: "helm-ai-kernel/docs/launchpad/CONFORMANCE.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/launchpad/CONFORMANCE.md"
section: "start-here"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-20"
checksum_sha256: "sha256:8be8901166e68d1108dd44d9ae96ed2f067fb694097024e17aa15d109dce8fc4"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Launchpad Conformance

Status: OpenClaw, Hermes, OpenCode, and Kilo Code passed the v1.0 signed
artifact, live local-container, teardown, receipt, and offline EvidencePack
bar in workflow `26198407296`. DigitalOcean opt-in beta passed for all four
apps; Hetzner remains fail-closed until a scoped provider token is available.

## Audience

Maintainers validating whether Launchpad app, substrate, registry, policy,
runtime, receipt, and public GA claims are backed by source and release evidence.

## Outcome

You can see which Launchpad checks are release-backed, which apps are promoted,
and which commands prove the local-container app launcher and EvidencePacks on
a clean machine.

## Source Truth

- Runtime package and tests: `core/pkg/launchpad/`
- CLI launch command: `core/cmd/helm-ai-kernel/launch_cmd.go`
- Registry fixtures: `registry/launchpad/`
- Policy fixtures: `policies/launchpad/`
- Schemas under test: `schemas/launchpad/`
- Launchpad artifact workflow: `.github/workflows/launchpad-artifacts.yml`
- Clean install workflow: `.github/workflows/launchpad-clean-install.yml`
- Release evidence: `docs/launchpad/final_report.json`
- v1.0 evidence status: `docs/launchpad/v1_report.json`

Implemented checks currently prove:

- `launchpad-artifacts` workflow `26198407296` built pinned OpenClaw, Hermes,
  OpenCode, and Kilo Code upstream refs into GHCR OCI images, signed them with
  GitHub OIDC keyless cosign, generated syft SBOMs, ran grype scans, and
  published a promotion manifest.
- `helm-ai-kernel launch promote` refuses promotion unless the CI artifact
  manifest, immutable image digest, cosign signature, syft SBOM, grype/trivy
  scan, live e2e run, teardown receipt, and EvidencePack refs are present and
  tied to the same workflow run.
- OpenClaw, Hermes, OpenCode, and Kilo Code are `oss_supported` in the registry
  from signed CI evidence, live e2e, teardown, receipts, and offline
  EvidencePack verification, not from assertion.
- OpenClaw image:
  `ghcr.io/mindburn-labs/helm-launchpad/openclaw@sha256:4da80a1e48b5603fd203b7d2b98539a01f796142b0ed9315e5ed86b25bf5d995`.
- Hermes image:
  `ghcr.io/mindburn-labs/helm-launchpad/hermes@sha256:4ec024dd8d0191fc887f04dc92c959fc865808d1526f782b5093f395fdd41652`.
- OpenCode image:
  `ghcr.io/mindburn-labs/helm-launchpad/opencode@sha256:cdbeb88cfbd698809e673339d525083cdf1cdb3e91529e01c6834cd90b778550`.
- Kilo Code image:
  `ghcr.io/mindburn-labs/helm-launchpad/kilocode@sha256:7b03834725235714ea8e698d38d89ce9b8bd81230b7e784016cb20a2c3c93ca6`.
- Local-container OpenRouter egress requires a launch-scoped egress proxy
  receipt, can use the signed egress-proxy image from the artifact workflow, and
  rejects non-OpenRouter allowlists.
- Installer tests reject missing digests, host `curl | bash`, mutable git
  update patterns, and package-manager mutation inside the current worktree.
- MCP governance rejects unknown or revoked tools and requires schema pins.
- Supported app specs must reference signed MCP manifests with pinned package
  digest, schema hashes, tool effects, required secrets, and grants.
- Substrate specs must declare capability metadata. `local-container` is the GA
  baseline; Docker microVM and hosted sandbox substrates are registry-visible
  but experimental until their adapters pass the same receipt/evidence/teardown
  bar.
- Generated Launchpad EvidencePacks include a hash-chained receipt graph at
  `04_EXPORTS/launchpad_evidence_graph.json`.
- Session store rejects `RUNNING` without launch receipt, healthcheck receipt,
  sandbox grant refs, and egress refs for networked launches.
- Session store rejects `DELETED` without teardown receipt.
- Generated and static Launchpad EvidencePacks verify offline through
  `helm-ai-kernel verify --bundle`.
- Enterprise Launchpad route tests, route registry/OpenAPI parity, Console
  Playwright coverage, evidence refs, teardown receipt, and EvidencePack
  visibility passed in PR #30.

Still gated:

- Clean Homebrew install from a separate developer machine.
- Hetzner live app launches across the four-app matrix.
- Codex redistribution; Codex remains external/BYO unless redistribution proof
  changes.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Candidate["Candidate app"]
        Supported["oss_supported"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        Registry["Registry and policy validation"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Runtime["Live local-container e2e"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        SupplyChain["Signed OCI, SBOM, vuln scan, license proof"]
        Teardown["Cascade teardown receipt"]
        Evidence["Offline EvidencePack verification"]
    end

    %% Operational Flow Edges
    Candidate --> Registry
    Registry --> SupplyChain
    SupplyChain --> Runtime
    Runtime --> Teardown
    Teardown --> Evidence
    Evidence --> Supported

    %% Premium Styling Rules
    style Registry fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style SupplyChain fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Runtime fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Teardown fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Evidence fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


No additional app may move to `oss_supported` until it passes the same bar.

## Clean Install Validation

```bash
brew update
brew install mindburnlabs/tap/helm-ai-kernel
helm-ai-kernel launch matrix --json
helm-ai-kernel launch secrets set model_gateway --provider openrouter --value-env OPENROUTER_API_KEY
helm-ai-kernel launch openclaw local-container --headless --output json
helm-ai-kernel launch hermes local-container --headless --output json
helm-ai-kernel launch opencode local-container --headless --output json
helm-ai-kernel launch kilocode local-container --headless --output json
helm-ai-kernel launch delete <launch_id> --cascade
helm-ai-kernel evidence inspect <pack>
helm-ai-kernel evidence diff <pack-a> <pack-b>
helm-ai-kernel verify --bundle <pack>
```

`scripts/launch/clean_install_gate.sh` automates the command sequence, digest
confirmation, EvidencePack verification, and secret-fragment audit. It writes
redacted JSON only.

OpenCode and Kilo Code are now part of the supported clean-install app set.
`--include-candidates` remains accepted by the clean-install gate for backward
compatibility only.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |


---
title: "HELM Launchpad Flow Catalog"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/launchpad/flow-catalog"
source: "helm-ai-kernel/docs/launchpad/FLOW_CATALOG.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/launchpad/FLOW_CATALOG.md"
section: "interfaces"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-20"
checksum_sha256: "sha256:19d3b861e2465d2a8a34f7f4f47de203316d475eedf8b45d6d8a2306b5e6095f"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM Launchpad Flow Catalog

HELM Launchpad is the OSS local-container app launcher for AI agents. Launchpad starts apps; HELM governs execution.

## Audience

This page is for developers, operators, and reviewers validating the OSS
Launchpad matrix, plan, local-container launch, repair, and teardown flows.

## Outcome

You should leave with the supported Launchpad command path and the receipts,
EvidencePack, sandbox, and policy checks required before an app is considered
available.

## Source Truth

- CLI launch command: `core/cmd/helm-ai-kernel/launch_cmd.go`
- Launchpad runtime: `core/pkg/launchpad/`
- App registry: `registry/launchpad/apps/`
- Substrate registry: `registry/launchpad/substrates/`
- App policies: `policies/launchpad/apps/`
- Release truth: `docs/launchpad/v1_report.json`
- Clean-install truth: `docs/launchpad/clean_install_report.json`

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        matrix["matrix"]
        plan["plan"]
        launch["local-container launch"]
        repair["repair plan"]
        teardown["cascade teardown"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipts["signed receipts"]
        evidence["EvidencePack export"]
        verify["offline verify"]
    end

    %% Operational Flow Edges
    matrix --> plan
    plan --> launch
    launch --> receipts
    receipts --> evidence
    evidence --> verify
    launch --> repair
    launch --> teardown

    %% Premium Styling Rules
    style receipts fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style evidence fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Matrix

`helm-ai-kernel launch matrix --json`

Loads AppSpecs, SubstrateSpecs, policy packs, and conformance metadata. No app is `AVAILABLE` without license, artifact, policy, sandbox, healthcheck, e2e, receipts, teardown, and offline EvidencePack proof.

## Plan

`helm-ai-kernel launch plan <app> <substrate> --json`

Compiles a LaunchPlan with app/substrate/policy/sandbox hashes, required secrets, network allowlist, filesystem mounts, MCP policy, budgets, action IR, CPI output, verdict, state, teardown plan, and evidence requirements.

## Launch Local Container

`helm-ai-kernel launch openclaw local-container --headless --output json`

Required path:

1. Resolve AppSpec and SubstrateSpec.
2. Verify signed artifact evidence and conformance metadata.
3. Compile policy and action IR.
4. Pass CPI/PEP/boundary checks.
5. Run sandbox preflight.
6. Bind MCP as quarantined.
7. Install immutable artifact.
8. Start local-container with deny-by-default filesystem and network.
9. Project scoped secrets.
10. Route OpenRouter egress through launch-owned proxy.
11. Run healthcheck.
12. Emit receipts and EvidencePack.

## Repair

`helm-ai-kernel launch repair <launch_id>`

Produces a deterministic repair plan for missing secrets, healthcheck failures, MCP auth expiry, sandbox failure, policy denial, dirty install attempts, port/proxy collisions, and ambiguous cloud state. Repair side effects still require CPI/PEP.

## Teardown

`helm-ai-kernel launch delete <launch_id> --cascade`

Stops containers and proxy, revokes scoped secrets, revokes sandbox grants, quarantines or revokes MCP registrations, reconciles remote resources when applicable, emits teardown receipt, and updates the final EvidencePack.

## Current Truth

[KEEP] OpenClaw, Hermes, OpenCode, and Kilo Code are `oss_supported` from
workflow `26198407296`, with signed artifacts, live local-container e2e,
teardown receipts, and offline EvidencePack verification.

[REFACTOR] The CPI/PEP/boundary path still needs deeper action-by-action authority binding.

[REBUILD] Clean install GA is not complete until `scripts/launch/clean_install_gate.sh`
passes against `v0.5.5` on both the macOS CI runner and a separate developer Mac.

Deferred: DigitalOcean and Hetzner stay dry-run by default.

## Troubleshooting

| Condition | Response |
| --- | --- |
| App is not `AVAILABLE` | Check license, artifact, policy, sandbox, healthcheck, e2e, receipt, teardown, and EvidencePack proof. |
| Launch is denied | Treat the policy verdict as final and inspect the action IR and policy pack hashes. |
| Repair proposes side effects | Re-run CPI/PEP checks before accepting any repair action. |
| Teardown is incomplete | Keep the launch non-promotable until container, proxy, secret, MCP, and evidence state reconcile. |


---
title: "OWASP MCP Threat Mapping"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/owasp-mcp-threat-mapping"
source: "helm-ai-kernel/docs/OWASP_MCP_THREAT_MAPPING.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/OWASP_MCP_THREAT_MAPPING.md"
section: "interfaces"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:0472940edd70ad0ceb31536db83c35db1704d2eddb2bda2387ac85e24dc430b4"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# OWASP MCP Threat Mapping

## Audience

Security reviewers mapping MCP firewall behavior to OWASP-style agentic threat categories.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/owasp-mcp-threat-mapping`
- Source document: `helm-ai-kernel/docs/OWASP_MCP_THREAT_MAPPING.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

This scheme maps the main sections of OWASP MCP Threat Mapping in reading order.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        A["Source truth"]
        C["Validation"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        Page["OWASP MCP Threat Mapping"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        B["Reader action"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C

    %% Premium Styling Rules
    style Page fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style B fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
```


This page maps retained HELM AI Kernel control points to OWASP-style MCP and agent-tooling threat areas. It is a public engineering map, not a certification statement.

| Risk Area | Primary HELM Control Points | Evidence To Review |
| --- | --- | --- |
| unauthorized tool use | policy evaluation, manifest/schema validation, fail-closed execution boundary | policy bundle, denial reason code, receipt |
| connector contract drift | schema handling, typed contracts, conformance checks | generated schema, connector conformance output |
| outbound data movement | egress rules, boundary packages, approval gates | policy bundle and proof graph |
| prompt-injection tool misuse | untrusted context handling, tool allowlists, effect levels | denied examples and threat-model tests |
| auditability gaps | signed receipts, proof graph, exported evidence bundles | receipt timeline and verifier output |
| replay and dispute handling | offline verification, causal hashes, evidence pack export | verifier command and evidence archive |

For a deeper agentic threat inventory, use [security/owasp-agentic-top10-coverage.md](/helm-ai-kernel/security/owasp-agentic-top10-mapping). For product-level trust language, use the HELM trust docs on `helm.docs.mindburn.org`.

<!-- docs-depth-final-pass -->

## Mapping Rules

Every OWASP mapping row should connect a threat to a HELM AI Kernel control, the evidence a reviewer can inspect, and the command that proves the control. Do not treat the mapping as automatic protection for arbitrary MCP servers. The developer must still define tool scope, policy thresholds, allowed destinations, and evidence retention. A useful public mapping includes negative examples: prompt-injected tool output, oversized argument payload, missing user intent, untrusted destination, and replay without expected receipt metadata. If a control depends on deployment configuration rather than code, call that out and link to the deployment or policy page that owns the configuration.


---
title: "Publishing"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/publishing"
source: "helm-ai-kernel/docs/PUBLISHING.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/PUBLISHING.md"
section: "start-here"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-22"
checksum_sha256: "sha256:bb190c66216fe61e71126b902107e191ddce37b99af2b81182272448926a3354"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Publishing

Publishing defines the current source-backed release and package artifact contract for HELM AI Kernel.

## Audience

This page is for maintainers preparing a release and consumers checking whether a binary, SDK package, container image, or evidence bundle is actually part of the current HELM AI Kernel release surface.

## Outcome

You should know which package identities are source-backed, which registry claims require separate proof, and which checks must pass before a release artifact is documented as published.

## Source Truth

- Public route: `helm-ai-kernel/publishing`
- Source document: `helm-ai-kernel/docs/PUBLISHING.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

This scheme maps the main sections of Publishing in reading order.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["Publishing"]
        A["Package Identities"]
        B["Release Inputs"]
        C["Release Automation"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        D["Verification"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C
    C --> D

    %% Premium Styling Rules
    style D fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


The repository retains packaging metadata for the kernel binaries, container image, and the public SDKs.

## Package Identities

| Surface | Package Identity |
| --- | --- |
| CLI/Homebrew | GitHub Release binaries, attached `helm-ai-kernel.rb`, and `mindburnlabs/tap/helm-ai-kernel` |
| TypeScript SDK | `@mindburn/helm-ai-kernel` |
| Python SDK | `helm-sdk` |
| Rust SDK | `helm-sdk` |
| Java SDK | Maven Central coordinate `io.github.mindburnlabs:helm-sdk:0.5.6` |
| Go SDK | `github.com/Mindburn-Labs/helm-ai-kernel/sdk/go@main`; pin `@main` or a commit until tagged module releases are aligned |

## Release Inputs

Before tagging a release:

1. run `python3 scripts/release/prepare_version.py <version>` and review the
   coordinated bump across `VERSION`, chart metadata, SDK manifests, OpenAPI
   metadata, generated SDK headers, and release docs
2. update `CHANGELOG.md`
3. run `make version-drift`
4. run `make build`, `make test`, `make test-console`,
   `make test-platform`, `make test-all`, `make crucible`, and
   `make launch-smoke`
5. run `make sdk-openapi-check` and `make sdk-examples-smoke`
6. run `make release-assets`
7. verify `helm-ai-kernel verify evidence-pack.tar`; run
   `helm-ai-kernel verify evidence-pack.tar --online` only when the public proof endpoint
   and credentials for that release are available
8. run `make release-binaries-reproducible` when validating that release binaries are reproducible from the checked-in source and pinned build metadata

Tag-triggered release workflows fail if the tag `v<version>` does not match
the checked-in `VERSION` file. The chart and SDK package manifests are not
patched in CI; source-controlled release metadata is the authority.

## Release Automation

The retained workflow set under `.github/workflows/` covers:

- main CI
- GitHub Release creation for tagged versions
- Homebrew formula generation for `mindburnlabs/homebrew-tap`
- GHCR image publication for `latest`, version tag, and slim tag
- tag-triggered npm, PyPI, crates.io, and Maven-compatible SDK publication
- daily published registry drift monitoring through `make version-drift-published`

Release target: `v0.5.6`. The release is complete only after the tagged
workflow publishes every lockstep channel, attaches `version-status.json` to
the GitHub Release, and `make version-drift-published` passes for that version:
<https://github.com/Mindburn-Labs/helm-ai-kernel/releases/tag/v0.5.6>.

There is no public GitHub Release object for `v0.4.1`; use `v0.4.0` as the
actual release baseline when auditing the `v0.5.0` delta.

The release workflow attaches these assets:

- `helm-ai-kernel-darwin-amd64`
- `helm-ai-kernel-darwin-arm64`
- `helm-ai-kernel-linux-amd64`
- `helm-ai-kernel-linux-arm64`
- `helm-ai-kernel-windows-amd64.exe`
- `SHA256SUMS.txt`
- `sbom.json`
- `v0.5.6.openvex.json`
- `release-attestation.json`
- `evidence-pack.tar`
- `release.high_risk.v3.toml`
- `sample-policy-material.tar`
- `helm-ai-kernel-launchpad-data.tar`
- `helm-ai-kernel.mcpb`
- `helm-ai-kernel.rb`
- `v0.5.6.json`
- matching `*.cosign.bundle` files for every primary asset

`sample-policy-material.tar` includes the sample policy and its referenced EU
AI Act high-risk reference pack. The `v0.5.6` release attaches a
`helm-ai-kernel.rb` formula asset for version `0.5.6` and publishes the same
version to `mindburnlabs/homebrew-tap`; `version-status.json` must include a
passing `homebrew-tap` surface before documenting
`brew install mindburnlabs/tap/helm-ai-kernel` as current.

SDK package manifests and registry versions must remain lockstep with the
GitHub release tag. npm, PyPI, crates.io, Maven, and Homebrew publication
require the corresponding registry secrets. If `NPM_TOKEN`, `PYPI_TOKEN`,
`CRATES_TOKEN`, `HOMEBREW_TAP_TOKEN`, or Maven credentials are absent, the
release workflow must fail instead of documenting a partial release as
complete.

Do not document an asset as published unless it appears on the GitHub release
or is produced by a retained workflow and attached to that release.

If a package or channel is not represented in the retained workflow set, it should not be described as a supported public publication channel in repository documentation.

`make release-assets` stages only verifiable release material. On tag builds it
requires `release/vex/v<version>.openvex.json`, exports the audit EvidencePack,
runs `helm-ai-kernel verify` against the staged `evidence-pack.tar`, and then
writes the final `SHA256SUMS.txt`.

## Verification

Every public release must include enough material to verify what was downloaded.
For `v0.5.6`, use `SHA256SUMS.txt`, `sbom.json`, `v0.5.6.openvex.json`,
`release-attestation.json`, the platform binary assets, attached
`*.cosign.bundle` files, and the offline `evidence-pack.tar`.

Verify a downloaded binary blob:

```bash
cosign verify-blob \
  --bundle helm-ai-kernel-linux-amd64.cosign.bundle \
  --certificate-identity-regexp "https://github.com/Mindburn-Labs/helm-ai-kernel" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  helm-ai-kernel-linux-amd64
```

Verify a published container image when a container image has been published
for the release:

```bash
cosign verify \
  --certificate-identity-regexp "Mindburn-Labs/helm-ai-kernel" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/mindburn-labs/helm-ai-kernel:<version>
```

The same recipe is documented in `docs/VERIFICATION.md`. The local helper
`scripts/release/verify_cosign.sh` is called via `make verify-cosign`, but it
requires matching `*.cosign.bundle` files in the downloaded release directory.
A zero-bundle run is not signature evidence.


---
title: "Quickstart"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/quickstart"
source: "helm-ai-kernel/docs/QUICKSTART.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/QUICKSTART.md"
section: "start-here"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-20"
checksum_sha256: "sha256:21a5290c4b20e602a1d487c73e21f25b5a7249c71dce8eb07067be2181fc5d6f"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Quickstart

This is the shortest current HELM AI Kernel path: build or install the CLI, run
a LaunchKit app through `helm up`, inspect the receipt-backed Console run, and
verify the exported EvidencePack offline. The lower-level boundary demo remains
available for integration testing.

## Audience

This quickstart is for developers, security reviewers, and integration owners who need the shortest local proof that HELM AI Kernel can sit between an agent-facing request and infrastructure side effects.

## Outcome

By the end you should have a LaunchKit run URL under `/runs/<run_id>`, a demo or
live receipt chain, an offline verification command, and the narrow docs and
route tests that prove this page still matches the CLI.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Install["install or build helm"]
        Up["helm up openclaw"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Console["Console /runs/<run_id>"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Receipts["signed receipts"]
        Verify["offline verification"]
    end

    %% Operational Flow Edges
    Install --> Up
    Up --> Console
    Up --> Receipts
    Receipts --> Verify

    %% Premium Styling Rules
    style Console fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Receipts fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Source Truth

- `core/cmd/helm-ai-kernel/server_cmd.go`
- `core/cmd/helm-ai-kernel/demo_routes.go`
- `core/cmd/helm-ai-kernel/proxy_cmd.go`
- `core/cmd/helm-ai-kernel/receipts_cmd.go`
- `core/cmd/helm-ai-kernel/verify_cmd.go`
- `api/openapi/helm.openapi.yaml`
- `release.high_risk.v3.toml`

The quickstart deliberately uses the local OSS runtime rather than hosted
services. `helm-ai-kernel serve` owns the boundary, demo routes create and verify a
receipt, and the OpenAPI file is the route contract. If an example requires a
credential, customer tenant, or managed control plane, it does not belong in the
first-run OSS path. Keep this page focused on proving the boundary can allow,
deny, record, and verify a local action.

## 1. Install Or Build

Use Homebrew for the published macOS CLI:

```bash
brew install mindburnlabs/tap/helm-ai-kernel
helm-ai-kernel --version
```

Use a source build when editing this repository:

```bash
git clone https://github.com/Mindburn-Labs/helm-ai-kernel.git
cd helm-ai-kernel
make build
./bin/helm-ai-kernel --version
./bin/helm --version
```

Use Docker when you want a clean local runtime:

```bash
docker build -t ghcr.io/mindburn-labs/helm-ai-kernel:local .
docker compose up -d
```

## 2. Launch A Supported App

For the instant no-secret path, run demo mode:

```bash
./bin/helm up openclaw --demo --no-open
```

For live mode, bind a scoped model secret first:

```bash
export OPENROUTER_API_KEY='<key>'
./bin/helm secret set model_gateway --provider openrouter --value-env OPENROUTER_API_KEY
./bin/helm up openclaw --live
```

The command prints a Console URL like:

```text
http://127.0.0.1:7714/runs/<run_id>
```

It also prints an offline verifier command:

```bash
helm evidence verify <evidence-pack> --offline
```

Use `--verify-only` to compile and verify gates without starting runtime:

```bash
./bin/helm up hermes --verify-only
```

## 3. Optional: Start A Local Boundary

```bash
./bin/helm-ai-kernel serve --policy ./release.high_risk.v3.toml
```

Expected ready line:

```text
helm-edge-local - listening :7714 - ready
```

If you installed with Homebrew, replace `./bin/helm-ai-kernel` with `helm-ai-kernel`.

Run the basic boundary checks in another shell:

```bash
./bin/helm-ai-kernel boundary status --json
./bin/helm-ai-kernel conform negative --json
./bin/helm-ai-kernel mcp authorize-call --server-id new-server --tool-name file.delete --json
./bin/helm-ai-kernel sandbox preflight --runtime wazero --json
```

The MCP authorization example should fail closed until the server identity, tool schema, scopes, and policy state are approved.

## 4. Run The Built-In Proof Demo

The local demo routes are implemented in the CLI server and exercise receipt verification without requiring a hosted service.

```bash
curl http://127.0.0.1:7714/api/demo/run \
  -H 'content-type: application/json' \
  -d '{"action_id":"export_customer_list","policy_id":"agent_tool_call_boundary"}'
```

Copy the returned `receipt` and `proof_refs.receipt_hash`, then verify it:

```bash
curl http://127.0.0.1:7714/api/demo/verify \
  -H 'content-type: application/json' \
  -d '{"receipt":{...},"expected_receipt_hash":"<receipt_hash>"}'
```

Tamper checks must fail:

```bash
curl http://127.0.0.1:7714/api/demo/tamper \
  -H 'content-type: application/json' \
  -d '{"receipt":{...},"expected_receipt_hash":"<receipt_hash>","mutation":"flip_verdict"}'
```

## 5. Optional OpenAI-Compatible Proxy

Start the proxy only when an existing client can set an OpenAI-style base URL:

```bash
python3 scripts/launch/mock-openai-upstream.py --port 19090
```

Then start the proxy against that local upstream:

```bash
./bin/helm-ai-kernel proxy \
  --upstream http://127.0.0.1:19090/v1 \
  --port 9090 \
  --receipts-dir ./helm-receipts
```

Point the client at:

```text
http://localhost:9090/v1
```

The retained source examples under `examples/*_openai_baseurl/` are HELM HTTP/SDK examples, not verified OpenAI SDK examples. Use [OpenAI-Compatible Proxy Integration](/helm-ai-kernel/integrations/openai-compatible-proxy) for the proxy contract.

## 6. Inspect Receipts

The CLI receipt tail requires an agent id:

```bash
./bin/helm-ai-kernel receipts tail --agent agent.demo.exec --server http://127.0.0.1:7714
```

For an unfiltered local list, use the HTTP API:

```bash
curl 'http://127.0.0.1:7714/api/v1/receipts?limit=20'
```

## 7. Verify Evidence

`helm-ai-kernel verify` is offline-first and succeeds only when the EvidencePack contains the required roots, proof material, and receipts.

```bash
./bin/helm-ai-kernel verify evidence-pack.tar
./bin/helm-ai-kernel verify evidence-pack.tar --json
```

Use the `v0.5.6` release `evidence-pack.tar` after `version-status.json` confirms all lockstep channels, or use an operator-generated pack known to contain ProofGraph and receipt material. Do not treat the local onboarding demo export as verified unless it includes those records.

## 8. Validate The Checkout

```bash
make docs-coverage
make docs-truth
cd core && go test ./cmd/helm-ai-kernel -run 'Test.*Route|Test.*OpenAPI|Test.*Receipt' -count=1
```

Run broader targets when you changed their surface:

```bash
make test-console
make test-design-system
make verify-fixtures
```

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| client call reaches the upstream provider directly | base URL still points to the provider | set the client base URL to HELM and log the request host |
| `helm-ai-kernel receipts tail` exits with usage | missing required agent filter | pass `--agent <id>` or use `GET /api/v1/receipts` for an unfiltered list |
| denied request retries forever | client treats policy denial as transient | handle `DENY` as a final authorization result |
| `helm-ai-kernel verify` fails | EvidencePack is incomplete or modified | use a complete pack and run `make verify-fixtures` |
| Docker path fails | local image or compose state is stale | rebuild the image and restart `docker compose` |

If a command differs from this page, inspect the matching source path in `Source Truth` before changing docs. Update the CLI source, OpenAPI route, and documentation together only when the source proves the behavior changed.


---
title: "HELM AI Kernel CLI Reference"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/reference/cli"
source: "helm-ai-kernel/docs/reference/cli.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/reference/cli.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:11916e7db0a0839b84eff22d611d13d49992382c598275a0579e42d66263c378"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM AI Kernel CLI Reference

The `helm-ai-kernel` binary is wired in [`core/cmd/helm-ai-kernel`](../../core/cmd/helm-ai-kernel). Command registration is centralized in [`registry.go`](../../core/cmd/helm-ai-kernel/registry.go), with startup handling in [`main.go`](../../core/cmd/helm-ai-kernel/main.go) and `helm-ai-kernel serve` flag parsing in [`server_cmd.go`](../../core/cmd/helm-ai-kernel/server_cmd.go).

## Audience

Use this page if you run the HELM AI Kernel binary, copy CLI snippets into automation, or update command docs after changing `core/cmd/helm-ai-kernel`.

## Outcome

After this page you should know the supported top-level command families, the source file that owns each command, the flag contracts that public docs may claim, and the tests that must pass after command changes.

## Source Truth

This page is generated from the active CLI implementation and must stay aligned with [`core/cmd/helm-ai-kernel`](../../core/cmd/helm-ai-kernel), `core/cmd/README.md` (protected staff doc), the command tests in [`core/cmd/helm-ai-kernel`](../../core/cmd/helm-ai-kernel), and the public manifest row for `helm-ai-kernel/reference/cli`.

## Runtime Map

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        User["operator or client"]
        CLI["helm-ai-kernel command"]
        Registry["command registry"]
        Server["serve / server"]
        Proxy["proxy"]
        API["HTTP API"]
        Upstream["OpenAI-compatible upstream"]
        State["boundary surface registry"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Boundary["boundary / mcp / sandbox / authz"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Evidence["receipts / evidence / verify"]
        Pack["EvidencePack or receipt stream"]
    end

    %% Operational Flow Edges
    User --> CLI
    CLI --> Registry
    Registry --> Server
    Registry --> Proxy
    Registry --> Boundary
    Registry --> Evidence
    Server --> API
    Proxy --> Upstream
    Boundary --> State
    Evidence --> Pack

    %% Premium Styling Rules
    style Boundary fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Evidence fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Pack fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Primary Commands

| Command | Purpose | Source truth |
| --- | --- | --- |
| `helm up <app>` / `helm-ai-kernel up <app>` | Launch any supported AppSpec through HELM LaunchKit with environment preflight, supply-chain checks, policy/CPI compile, scoped secrets, sandbox grants, MCP quarantine, receipts, EvidencePack export, offline verify command, and Console deep link. | [`up_cmd.go`](../../core/cmd/helm-ai-kernel/up_cmd.go), [`core/pkg/launchkit`](../../core/pkg/launchkit) |
| `helm-ai-kernel serve` | Start the local execution boundary from a policy file. | [`server_cmd.go`](../../core/cmd/helm-ai-kernel/server_cmd.go), [`serve_policy.go`](../../core/cmd/helm-ai-kernel/serve_policy.go) |
| `helm-ai-kernel server` | Start the default Guardian API and proxy services. | [`main.go`](../../core/cmd/helm-ai-kernel/main.go), [`subsystems.go`](../../core/cmd/helm-ai-kernel/subsystems.go) |
| `helm-ai-kernel proxy` | Run the OpenAI-compatible governance proxy. | [`proxy_cmd.go`](../../core/cmd/helm-ai-kernel/proxy_cmd.go) |
| `helm-ai-kernel receipts tail` | Tail durable receipt events for a specific agent. | [`receipts_cmd.go`](../../core/cmd/helm-ai-kernel/receipts_cmd.go), [`receipt_routes.go`](../../core/cmd/helm-ai-kernel/receipt_routes.go) |
| `helm-ai-kernel evidence` | Export evidence envelopes over native EvidencePacks. | [`evidence_cmd.go`](../../core/cmd/helm-ai-kernel/evidence_cmd.go), [`contract_routes.go`](../../core/cmd/helm-ai-kernel/contract_routes.go) |
| `helm-ai-kernel export` | Export an EvidencePack from local evidence material. | [`export_cmd.go`](../../core/cmd/helm-ai-kernel/export_cmd.go), [`export_pack.go`](../../core/cmd/helm-ai-kernel/export_pack.go) |
| `helm-ai-kernel verify` | Verify an EvidencePack directory or archive offline, with optional online proof checks. | [`verify_cmd.go`](../../core/cmd/helm-ai-kernel/verify_cmd.go), [`core/pkg/verifier`](../../core/pkg/verifier) |
| `helm-ai-kernel bundle` | List, inspect, verify, or build policy bundles. | [`bundle_cmd.go`](../../core/cmd/helm-ai-kernel/bundle_cmd.go), [`core/pkg/policybundles`](../../core/pkg/policybundles) |
| `helm-ai-kernel conform` | Run conformance gates and list negative boundary vectors. | [`conform.go`](../../core/cmd/helm-ai-kernel/conform.go), [`core/pkg/conformance`](../../core/pkg/conformance) |
| `helm-ai-kernel mcp` | Serve, package, scan, quarantine, approve, and authorize MCP surfaces. | [`mcp_cmd.go`](../../core/cmd/helm-ai-kernel/mcp_cmd.go), [`mcp_boundary_cmd.go`](../../core/cmd/helm-ai-kernel/mcp_boundary_cmd.go), [`mcp_runtime.go`](../../core/cmd/helm-ai-kernel/mcp_runtime.go) |
| `helm-ai-kernel boundary` | Inspect execution-boundary status, capabilities, records, verification, and checkpoints. | [`boundary_surface_cmd.go`](../../core/cmd/helm-ai-kernel/boundary_surface_cmd.go), [`core/pkg/boundary`](../../core/pkg/boundary) |
| `helm-ai-kernel identity` | Inspect HELM AI Kernel agent identities. | [`boundary_surface_cmd.go`](../../core/cmd/helm-ai-kernel/boundary_surface_cmd.go), [`core/pkg/identity`](../../core/pkg/identity) |
| `helm-ai-kernel sandbox` | Run governed sandbox execution and inspect sandbox grants. | [`sandbox_cmd.go`](../../core/cmd/helm-ai-kernel/sandbox_cmd.go), [`sandbox_inspect_cmd.go`](../../core/cmd/helm-ai-kernel/sandbox_inspect_cmd.go) |
| `helm-ai-kernel authz`, `helm-ai-kernel approvals`, `helm-ai-kernel budget` | Inspect ReBAC snapshots, approval ceremonies, and budget ceilings. | [`boundary_surface_cmd.go`](../../core/cmd/helm-ai-kernel/boundary_surface_cmd.go), [`core/pkg/contracts`](../../core/pkg/contracts) |
| `helm-ai-kernel telemetry`, `helm-ai-kernel coexistence`, `helm-ai-kernel integrate` | Emit non-authoritative telemetry, coexistence, and pre-dispatch integration scaffolds. | [`boundary_surface_cmd.go`](../../core/cmd/helm-ai-kernel/boundary_surface_cmd.go) |
| `helm-ai-kernel policy`, `helm-ai-kernel plan`, `helm-ai-kernel pack` | Work with policy tests, execution plans, and governed self-extension packs. | [`policy_cmd.go`](../../core/cmd/helm-ai-kernel/policy_cmd.go), [`plan_cmd.go`](../../core/cmd/helm-ai-kernel/plan_cmd.go), [`pack_cmd.go`](../../core/cmd/helm-ai-kernel/pack_cmd.go) |
| `helm-ai-kernel test` | Run local HELM smoke checks exposed by the CLI. | [`test_cmd.go`](../../core/cmd/helm-ai-kernel/test_cmd.go) |
| `helm-ai-kernel scaffold`, `helm-ai-kernel dev` | Create a local governance scaffold and start HELM in development mode. | [`init_cmd.go`](../../core/cmd/helm-ai-kernel/init_cmd.go) |
| `helm-ai-kernel pack coverage` | Show governed self-extension pack coverage statistics. | [`pack_cmd.go`](../../core/cmd/helm-ai-kernel/pack_cmd.go) |
| `helm-ai-kernel doctor`, `helm-ai-kernel init`, `helm-ai-kernel onboard`, `helm-ai-kernel demo` | Initialize, diagnose, and run local demonstration flows. | [`doctor_cmd.go`](../../core/cmd/helm-ai-kernel/doctor_cmd.go), [`doctor_init_trust.go`](../../core/cmd/helm-ai-kernel/doctor_init_trust.go), [`onboard_cmd.go`](../../core/cmd/helm-ai-kernel/onboard_cmd.go), [`demo_cmd.go`](../../core/cmd/helm-ai-kernel/demo_cmd.go) |
| `helm-ai-kernel replay`, `helm-ai-kernel report`, `helm-ai-kernel certify`, `helm-ai-kernel rollup` | Replay evidence, report compliance, certify packs, and build receipt rollups. | [`replay_cmd.go`](../../core/cmd/helm-ai-kernel/replay_cmd.go), [`report_cmd.go`](../../core/cmd/helm-ai-kernel/report_cmd.go), [`certify_cmd.go`](../../core/cmd/helm-ai-kernel/certify_cmd.go), [`rollup_cmd.go`](../../core/cmd/helm-ai-kernel/rollup_cmd.go) |
| `helm-ai-kernel freeze`, `helm-ai-kernel unfreeze`, `helm-ai-kernel incident`, `helm-ai-kernel brief`, `helm-ai-kernel risk-summary` | Operate local safety, incident, brief, and risk surfaces. | [`freeze_cmd.go`](../../core/cmd/helm-ai-kernel/freeze_cmd.go), [`incident_cmd.go`](../../core/cmd/helm-ai-kernel/incident_cmd.go), [`risk_cmd.go`](../../core/cmd/helm-ai-kernel/risk_cmd.go) |
| `helm-ai-kernel trust`, `helm-ai-kernel threat`, `helm-ai-kernel shadow`, `helm-ai-kernel did`, `helm-ai-kernel tee`, `helm-ai-kernel local` | Inspect trust roots, threats, shadow-AI patterns, identifiers, TEE attestations, and local provider profiles. | [`trust_cmd.go`](../../core/cmd/helm-ai-kernel/trust_cmd.go), [`threat_cmd.go`](../../core/cmd/helm-ai-kernel/threat_cmd.go), [`shadow_cmd.go`](../../core/cmd/helm-ai-kernel/shadow_cmd.go), [`did_cmd.go`](../../core/cmd/helm-ai-kernel/did_cmd.go), [`tee_cmd.go`](../../core/cmd/helm-ai-kernel/tee_cmd.go), [`local_cmd.go`](../../core/cmd/helm-ai-kernel/local_cmd.go) |
| `helm-ai-kernel health`, `helm-ai-kernel version`, `helm-ai-kernel help` | Global utility commands for local health checks, version reporting, and usage output. | [`main.go`](../../core/cmd/helm-ai-kernel/main.go), [`registry.go`](../../core/cmd/helm-ai-kernel/registry.go) |

Auxiliary binaries under `core/cmd/bootstrap`, `core/cmd/channel_gateway`, `core/cmd/pack_verify`, `core/cmd/skill_lint`, and `core/cmd/skill_pack` are source-owned helpers. They are not top-level `helm-ai-kernel` subcommands unless wired through `core/cmd/helm-ai-kernel`.

This table documents registered top-level `helm-ai-kernel` command families and global utility commands. Aliases are documented in source and should be exposed here only when public examples rely on them.

## Key Flag Contracts

| Command | Contract |
| --- | --- |
| `helm up <app>` | Defaults to `--target local --mode auto`; accepts `--target local|cloud|cloud:helm|cloud:aws|cloud:kubernetes`, `--demo`, `--verify-only`, `--live`, `--resume <run_id>`, `--yes`, `--no-open`, and `--json`. `--verify-only` never starts runtime. `--live` never falls back to demo. Cloud targets escalate before paid resources unless provider auth and explicit approval are present. |
| `helm-ai-kernel serve --policy <path>` | `--policy` is required. Optional flags are `--addr`, `--port`, `--data-dir`, `--console`, `--console-dir`, and `--json`. If the policy does not override bind or port, `serve` uses `127.0.0.1:7714`. |
| `helm-ai-kernel server` | Starts without `--policy` and defaults to `127.0.0.1:8080` unless flags, env, or config override it. `HELM_BIND_ADDR` overrides the bind address when no explicit flag is set. `HELM_PORT` overrides the API port when no explicit flag is set. The separate health server uses `HELM_HEALTH_PORT` and defaults to `8081`. |
| `helm-ai-kernel proxy` | Defaults to `--upstream https://api.openai.com/v1`, `--port 9090`, and `--receipts-dir ./helm-receipts`. `--websocket` is explicitly unsupported in the OSS proxy runtime. |
| `helm-ai-kernel health` | Checks `http://localhost:$HELM_HEALTH_PORT/healthz`; if `HELM_HEALTH_PORT` is unset, it checks `http://localhost:8081/healthz`. |
| `helm-ai-kernel receipts tail` | Requires `--agent <id>`. `--server` defaults from `HELM_URL` or `http://127.0.0.1:7714`. |
| `helm-ai-kernel bundle build` | Takes the policy source as the positional argument: `helm-ai-kernel bundle build [--language=cel|rego|cedar] [--entities=path] <source>`. There is no `--policy` flag for this subcommand. |
| `helm-ai-kernel bundle verify` | Requires `--file <bundle.yaml>` and `--hash <expected-hash>`. |
| `helm-ai-kernel verify` | Accepts a positional EvidencePack path or `--bundle`. `--online` only adds public proof-ledger verification after offline checks pass. |
| `helm-ai-kernel boundary` | Uses `status`, `capabilities`, `records`, `get`, `verify`, and `checkpoint` subcommands. |

## Boundary And API References

- [HTTP API Reference](/helm-ai-kernel/reference/http-api) covers the route registry, auth classes, OpenAPI contract, and local API behavior.
- [Execution Boundary Reference](/helm-ai-kernel/reference/execution-boundary) covers boundary records, checkpoints, fail-closed cases, and native evidence authority.

## Validation

Run CLI-focused validation after changing command flags or public examples:

```bash
cd core
go test ./cmd/helm-ai-kernel -count=1
```

Then run the documentation gates from the repository root:

```bash
make docs-coverage
make docs-truth
```

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A command snippet fails with an unknown flag | Compare the snippet with `core/cmd/helm-ai-kernel/*_cmd.go`; for example, `helm-ai-kernel bundle build` takes the policy source positionally, not through `--policy`. |
| A helper binary appears in public docs as a `helm-ai-kernel` subcommand | Keep helper binaries source-owned unless they are registered in `core/cmd/helm-ai-kernel/registry.go`. |
| CLI docs and tests disagree | Update the source command, the command test, and this reference in the same change. |


---
title: "Execution Boundary Reference"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/reference/execution-boundary"
source: "helm-ai-kernel/docs/reference/execution-boundary.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/reference/execution-boundary.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-21"
checksum_sha256: "sha256:9dd3a1de82b1dbfb60c61b886ecdd83e34b6e67d695e0d0de0d6fd5673d41e48"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Execution Boundary Reference

HELM AI Kernel is the proof-bearing execution boundary for governed AI tool use. The authoritative runtime record is the HELM boundary record plus its receipt binding; telemetry, coexistence manifests, external evidence envelopes, and scanner outputs are compatibility surfaces around that native authority.

## Audience

Use this page if you build integrations that cross the HELM execution boundary, audit receipts, run MCP/sandbox surfaces, or maintain conformance tests.

## Outcome

After this page you should know the public boundary surfaces, their CLI and HTTP entry points, what durable state they produce, how fail-closed cases are recorded, and which validation commands prove the behavior.

## Boundary Flow

```mermaid
flowchart TD
    subgraph Evaluation["2. Evaluation & Policy Plane"]
        Normalize["normalize and validate"]
        PDP["fail-closed PEP/PDP"]
        Checkpoint["boundary checkpoint"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Request["tool, proxy, MCP, or sandbox request"]
        Record["seal boundary record"]
        Deny["seal deny record"]
        Dispatch["dispatch governed action"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Receipt["emit receipt"]
        Evidence["EvidencePack / offline verification"]
    end

    %% Operational Flow Edges
    Request --> Normalize
    Normalize --> PDP
    PDP -->|allow| Record
    PDP -->|deny| Deny
    Record --> Dispatch
    Deny --> Receipt
    Dispatch --> Receipt
    Receipt --> Checkpoint
    Checkpoint --> Evidence

    %% Premium Styling Rules
    style Request fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Normalize fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style PDP fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Record fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Deny fill:#e53e3e,stroke:#9b2c2c,stroke-width:2px,color:#fff
    style Dispatch fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Checkpoint fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Evidence fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Source Truth

| Surface | Source |
| --- | --- |
| CLI commands | [`core/cmd/helm-ai-kernel/boundary_surface_cmd.go`](../../core/cmd/helm-ai-kernel/boundary_surface_cmd.go), [`core/cmd/helm-ai-kernel/mcp_boundary_cmd.go`](../../core/cmd/helm-ai-kernel/mcp_boundary_cmd.go), [`core/cmd/helm-ai-kernel/sandbox_cmd.go`](../../core/cmd/helm-ai-kernel/sandbox_cmd.go), [`core/cmd/helm-ai-kernel/evidence_cmd.go`](../../core/cmd/helm-ai-kernel/evidence_cmd.go) |
| HTTP routes | [`core/cmd/helm-ai-kernel/route_registry.go`](../../core/cmd/helm-ai-kernel/route_registry.go), [`core/cmd/helm-ai-kernel/contract_routes.go`](../../core/cmd/helm-ai-kernel/contract_routes.go), [`api/openapi/helm.openapi.yaml`](../../api/openapi/helm.openapi.yaml) |
| Durable boundary state | [`core/pkg/boundary`](../../core/pkg/boundary), [`core/pkg/contracts`](../../core/pkg/contracts) |
| Receipt and evidence contracts | [`schemas/receipts`](../../schemas/receipts), [`core/pkg/receipts`](../../core/pkg/receipts), [`core/pkg/evidencepack`](../../core/pkg/evidencepack), [`core/pkg/verifier`](../../core/pkg/verifier) |
| Conformance vectors | [`core/pkg/conformance`](../../core/pkg/conformance), [`tests/conformance`](../../tests/conformance), [`protocols/conformance/v1`](../../protocols/conformance/v1) |

## Public Boundary Surfaces

| Capability | CLI | HTTP API | Authority |
| --- | --- | --- | --- |
| Boundary health and capability inventory | `helm-ai-kernel boundary status`, `helm-ai-kernel boundary capabilities` | `GET /api/v1/boundary/status`, `GET /api/v1/boundary/capabilities` | Runtime status and capability summaries. |
| Boundary records | `helm-ai-kernel boundary records`, `helm-ai-kernel boundary get`, `helm-ai-kernel boundary verify` | `GET /api/v1/boundary/records`, `GET /api/v1/boundary/records/{record_id}`, `POST /api/v1/boundary/records/{record_id}/verify` | JCS-hashed boundary records linked to receipts. |
| Checkpoints | `helm-ai-kernel boundary checkpoint` | `GET|POST /api/v1/boundary/checkpoints` | Tamper-evident roots over records and receipts. |
| Negative conformance vectors | `helm-ai-kernel conform negative --json`, `helm-ai-kernel conform vectors --json` | `GET /api/v1/conformance/negative`, `GET /api/v1/conformance/vectors` | Clean-room fail-closed behavior fixtures. |
| MCP quarantine and authorization | `helm-ai-kernel mcp scan`, `helm-ai-kernel mcp wrap`, `helm-ai-kernel mcp list`, `helm-ai-kernel mcp get`, `helm-ai-kernel mcp approve`, `helm-ai-kernel mcp revoke`, `helm-ai-kernel mcp auth-profile`, `helm-ai-kernel mcp authorize-call` | `/api/v1/mcp/*`, `/.well-known/oauth-protected-resource/mcp` | Pre-dispatch MCP firewall state and OAuth/profile bindings. |
| Sandbox grants | `helm-ai-kernel sandbox profiles`, `helm-ai-kernel sandbox grant`, `helm-ai-kernel sandbox list`, `helm-ai-kernel sandbox get`, `helm-ai-kernel sandbox verify`, `helm-ai-kernel sandbox preflight`, `helm-ai-kernel sandbox inspect` | `/api/v1/sandbox/profiles`, `/api/v1/sandbox/grants`, `/api/v1/sandbox/preflight`, `/api/v1/sandbox/grants/inspect` | Grant hashes, deny-default profiles, and dispatch preflight results. |
| Authz snapshots | `helm-ai-kernel identity agents`, `helm-ai-kernel authz health`, `helm-ai-kernel authz check`, `helm-ai-kernel authz snapshots`, `helm-ai-kernel authz get` | `/api/v1/identity/agents`, `/api/v1/authz/health`, `/api/v1/authz/check`, `/api/v1/authz/snapshots` | ReBAC snapshot hash and relationship freshness. |
| Approvals and budgets | `helm-ai-kernel approvals *`, `helm-ai-kernel budget *` | `/api/v1/approvals`, `/api/v1/budgets` | Local approval ceremonies and spend/tool/egress ceilings. |
| Evidence envelopes | `helm-ai-kernel evidence export --envelope`, `helm-ai-kernel evidence envelope *` | `/api/v1/evidence/envelopes`, `/api/v1/evidence/export`, `/api/v1/evidence/verify`, `/api/v1/replay/verify` | Native EvidencePack roots; external envelopes are wrappers. |
| External host evidence | `helm-ai-kernel verify external-receipt --chain <path> --public-key <hex|file>`, `helm-ai-kernel evidence attach-host-chain --bundle <bundle> --chain <path> --out <bundle> --source <name>`, `helm-ai-kernel evidence correlate-host --bundle <bundle>` | none | Vendor-neutral host/network evidence import, offline verification, and Boundary Drift correlation. |
| Telemetry and coexistence | `helm-ai-kernel telemetry otel-config`, `helm-ai-kernel coexistence manifest`, `helm-ai-kernel integrate scaffold` | `/api/v1/telemetry/otel/config`, `/api/v1/telemetry/export`, `/api/v1/coexistence/capabilities` | Non-authoritative export and integration metadata. |

## Durable State

`helm-ai-kernel serve` persists boundary surface state in the runtime database through `boundary_surface_snapshots`. SQLite Lite Mode and Postgres use the same table contract. Standalone CLI commands use `HELM_BOUNDARY_REGISTRY_PATH` or `HELM_DATA_DIR/boundary/surfaces.json`, so records, approvals, checkpoints, envelopes, and budget changes survive separate CLI invocations.

## Fail-Closed Cases

The boundary must deny before dispatch when policy or authorization state is not trustworthy. Public conformance vectors cover at least these cases:

- missing or stale policy;
- PDP outage;
- stale relationship snapshots;
- missing credentials;
- malformed tool arguments;
- schema drift;
- direct upstream bypass;
- sandbox overgrant;
- blocked egress;
- denial receipt emission.

Deny paths are still proof paths: they produce a boundary record and receipt rather than silently dropping the action.

## Native Evidence Authority

External envelopes can help auditors and procurement teams move evidence between systems, but they do not become the source of truth. Verification starts with HELM receipts, grant or snapshot hashes, boundary record hashes, checkpoints, and the EvidencePack manifest.

HELM can consume and correlate external host evidence produced by independent
recorders. Imported host chains can prove that a host observed outbound network
behavior; HELM correlation then checks whether that behavior aligns with HELM
authority receipts, policy verdicts, sandbox leases, and egress ceilings. A
host event with no matching HELM intent, a host event after a HELM deny, a
destination mismatch, or a byte-volume excess is reported as Boundary Drift.

This OSS kernel does not claim eBPF, seccomp, TPM, or packet-blocking network
enforcement unless a specific code path and verifier prove it. Hardware-rooted
claims in imported host evidence are retained and structurally checked; unknown
or unsupported roots are reported as not verified.

## Validation

```bash
cd core
go test ./pkg/contracts ./pkg/boundary ./cmd/helm-ai-kernel -run 'Test.*Boundary|Test.*Route|Test.*Evidence|Test.*MCP|Test.*Sandbox' -count=1
cd ../tests/conformance
go test ./...
```

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A denied request has no receipt | Check the fail-closed path in the CLI/API route and conformance vector; denial should still seal a boundary record. |
| Boundary state disappears between commands | Confirm `HELM_BOUNDARY_REGISTRY_PATH` or `HELM_DATA_DIR` points at a durable location. |
| External envelope verification passes but native verification fails | Treat native HELM receipt, checkpoint, and EvidencePack roots as authoritative and repair the wrapper metadata. |


---
title: "HELM AI Kernel HTTP API Reference"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/reference/http-api"
source: "helm-ai-kernel/docs/reference/http-api.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/reference/http-api.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:47efe7f7e6cda0c4804ba62b5582144e7f18e3028a0a2d36aaacedc4a41739bb"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM AI Kernel HTTP API Reference

The public HTTP contract is anchored in [`api/openapi/helm.openapi.yaml`](../../api/openapi/helm.openapi.yaml). Runtime route ownership is mirrored in [`core/cmd/helm-ai-kernel/route_registry.go`](../../core/cmd/helm-ai-kernel/route_registry.go), enforced by [`route_auth.go`](../../core/cmd/helm-ai-kernel/route_auth.go), and wired into the local server through [`subsystems.go`](../../core/cmd/helm-ai-kernel/subsystems.go), [`contract_routes.go`](../../core/cmd/helm-ai-kernel/contract_routes.go), [`receipt_routes.go`](../../core/cmd/helm-ai-kernel/receipt_routes.go), and [`console_routes.go`](../../core/cmd/helm-ai-kernel/console_routes.go).

## Audience

Use this page if you call HELM AI Kernel over HTTP, generate a client from OpenAPI, configure auth headers, or debug route drift between the runtime and public docs.

## Outcome

After this page you should know each public route family, its auth class, the source file that owns it, and the tests that catch route/OpenAPI drift.

## Source Truth

This page is source-backed by [`api/openapi/helm.openapi.yaml`](../../api/openapi/helm.openapi.yaml), [`core/cmd/helm-ai-kernel/route_registry.go`](../../core/cmd/helm-ai-kernel/route_registry.go), [`core/cmd/helm-ai-kernel/route_auth.go`](../../core/cmd/helm-ai-kernel/route_auth.go), [`core/cmd/helm-ai-kernel/contract_routes.go`](../../core/cmd/helm-ai-kernel/contract_routes.go), [`core/cmd/helm-ai-kernel/receipt_routes.go`](../../core/cmd/helm-ai-kernel/receipt_routes.go), [`core/cmd/helm-ai-kernel/console_routes.go`](../../core/cmd/helm-ai-kernel/console_routes.go), and route parity tests under [`core/cmd/helm-ai-kernel`](../../core/cmd/helm-ai-kernel).

## Contract Flow

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        OpenAPI["api/openapi/helm.openapi.yaml"]
        Auth["route_auth.go"]
        Mux["serve/server mux"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Registry["RuntimeRouteSpecs"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Handlers["contract, receipt, console, subsystem handlers"]
        Stores["receipts, boundary registry, services"]
        Response["JSON, SSE, or EvidencePack bytes"]
    end

    %% Operational Flow Edges
    OpenAPI --> Registry
    Registry --> Auth
    Auth --> Mux
    Mux --> Handlers
    Handlers --> Stores
    Stores --> Response

    %% Premium Styling Rules
    style Registry fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Handlers fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Stores fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Response fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Runtime Auth Classes

| Class | Runtime behavior |
| --- | --- |
| `public` | No runtime admin credential required by `protectRuntimeHandler`. |
| `tenant_scoped` | Requires `Authorization: Bearer $HELM_ADMIN_API_KEY` and `X-Helm-Tenant-ID` or `tenant_id`. `X-Helm-Principal-ID` can narrow the principal recorded in context. |
| `admin` / `authenticated` | Requires `Authorization: Bearer $HELM_ADMIN_API_KEY`. |
| `service_internal` | Requires `Authorization: Bearer $HELM_SERVICE_API_KEY`; used for service-to-service kernel approval. |

The OpenAPI security blocks describe the external contract. `route_auth.go` is the runtime source for local OSS enforcement.

## Public Route Families

| Family | Methods and paths | Source truth |
| --- | --- | --- |
| Health and version | `GET /healthz`, `GET /version` | [`subsystems.go`](../../core/cmd/helm-ai-kernel/subsystems.go), [`route_registry.go`](../../core/cmd/helm-ai-kernel/route_registry.go), [`main.go`](../../core/cmd/helm-ai-kernel/main.go) |
| Local proof demo | `POST /api/demo/run`, `POST /api/demo/verify`, `POST /api/demo/tamper` | [`demo_routes.go`](../../core/cmd/helm-ai-kernel/demo_routes.go) |
| OpenAI-compatible boundary | `POST /v1/chat/completions` | [`subsystems.go`](../../core/cmd/helm-ai-kernel/subsystems.go), [`core/pkg/api/openai_proxy.go`](../../core/pkg/api/openai_proxy.go), [`proxy_cmd.go`](../../core/cmd/helm-ai-kernel/proxy_cmd.go) |
| Kernel approval and evaluation | `POST /api/v1/kernel/approve`, `POST /api/v1/evaluate` | [`core/pkg/api/approve_handler.go`](../../core/pkg/api/approve_handler.go), [`route_registry.go`](../../core/cmd/helm-ai-kernel/route_registry.go) |
| Receipts | `GET /api/v1/receipts`, `GET /api/v1/receipts/tail`, `GET /api/v1/receipts/{receipt_id}` | [`receipt_routes.go`](../../core/cmd/helm-ai-kernel/receipt_routes.go) |
| ProofGraph receipts | `GET /api/v1/proofgraph/sessions`, `GET /api/v1/proofgraph/sessions/{session_id}/receipts`, `GET /api/v1/proofgraph/receipts/{receipt_hash}` | [`contract_routes.go`](../../core/cmd/helm-ai-kernel/contract_routes.go) |
| Evidence and replay | `POST /api/v1/evidence/export`, `POST /api/v1/evidence/verify`, `GET|POST /api/v1/evidence/envelopes`, `GET /api/v1/evidence/envelopes/{manifest_id}`, `GET /api/v1/evidence/envelopes/{manifest_id}/payload`, `POST /api/v1/evidence/envelopes/{manifest_id}/verify`, `POST /api/v1/replay/verify` | [`contract_routes.go`](../../core/cmd/helm-ai-kernel/contract_routes.go) |
| Boundary | `GET /api/v1/boundary/status`, `GET /api/v1/boundary/capabilities`, `GET /api/v1/boundary/records`, `GET /api/v1/boundary/records/{record_id}`, `POST /api/v1/boundary/records/{record_id}/verify`, `GET|POST /api/v1/boundary/checkpoints`, `POST /api/v1/boundary/checkpoints/{checkpoint_id}/verify` | [`contract_routes.go`](../../core/cmd/helm-ai-kernel/contract_routes.go), [`core/pkg/boundary`](../../core/pkg/boundary) |
| Conformance | `POST /api/v1/conformance/run`, `GET /api/v1/conformance/reports`, `GET /api/v1/conformance/reports/{report_id}`, `GET /api/v1/conformance/vectors`, `GET /api/v1/conformance/negative` | [`contract_routes.go`](../../core/cmd/helm-ai-kernel/contract_routes.go), [`conform.go`](../../core/cmd/helm-ai-kernel/conform.go) |
| MCP and A2A runtime | `GET|POST /mcp`, `GET /.well-known/oauth-protected-resource/mcp`, `GET /.well-known/agent-card.json`, `GET /mcp/v1/capabilities`, `POST /mcp/v1/execute` | [`mcp_runtime.go`](../../core/cmd/helm-ai-kernel/mcp_runtime.go), [`mcp_cmd.go`](../../core/cmd/helm-ai-kernel/mcp_cmd.go), [`wellknown.go`](../../core/pkg/a2a/wellknown.go) |
| MCP registry and authorization | `GET|POST /api/v1/mcp/registry`, `POST /api/v1/mcp/registry/approve`, `GET /api/v1/mcp/registry/{server_id}`, `POST /api/v1/mcp/registry/{server_id}/approve`, `POST /api/v1/mcp/registry/{server_id}/revoke`, `POST /api/v1/mcp/scan`, `GET /api/v1/mcp/auth-profiles`, `PUT /api/v1/mcp/auth-profiles/{profile_id}`, `POST /api/v1/mcp/authorize-call` | [`contract_routes.go`](../../core/cmd/helm-ai-kernel/contract_routes.go), [`mcp_boundary_cmd.go`](../../core/cmd/helm-ai-kernel/mcp_boundary_cmd.go) |
| Sandbox | `GET /api/v1/sandbox/profiles`, `GET|POST /api/v1/sandbox/grants`, `GET /api/v1/sandbox/grants/{grant_id}`, `POST /api/v1/sandbox/grants/{grant_id}/verify`, `POST /api/v1/sandbox/preflight`, `GET /api/v1/sandbox/grants/inspect` | [`contract_routes.go`](../../core/cmd/helm-ai-kernel/contract_routes.go), [`sandbox_cmd.go`](../../core/cmd/helm-ai-kernel/sandbox_cmd.go) |
| Identity and authz | `GET /api/v1/identity/agents`, `GET /api/v1/authz/health`, `POST /api/v1/authz/check`, `GET /api/v1/authz/snapshots`, `GET /api/v1/authz/snapshots/{snapshot_id}` | [`contract_routes.go`](../../core/cmd/helm-ai-kernel/contract_routes.go), [`subsystems.go`](../../core/cmd/helm-ai-kernel/subsystems.go), [`core/pkg/authz`](../../core/pkg/authz) |
| Approvals and budgets | `GET|POST /api/v1/approvals`, `POST /api/v1/approvals/{approval_id}/webauthn/challenge`, `POST /api/v1/approvals/{approval_id}/webauthn/assert`, `POST /api/v1/approvals/{approval_id}/{action}`, `GET /api/v1/budgets`, `PUT /api/v1/budgets/{budget_id}` | [`contract_routes.go`](../../core/cmd/helm-ai-kernel/contract_routes.go), [`boundary_surface_cmd.go`](../../core/cmd/helm-ai-kernel/boundary_surface_cmd.go) |
| Console bootstrap | `GET /api/v1/console/bootstrap`, `GET /api/v1/console/surfaces`, `GET /api/v1/console/surfaces/{surface_id}` | [`console_routes.go`](../../core/cmd/helm-ai-kernel/console_routes.go) |
| Agent UI and AG-UI | `GET /api/v1/agent-ui/info`, `POST /api/v1/agent-ui/run`, `GET /api/ag-ui/info`, `POST /api/ag-ui/run` | [`contract_routes.go`](../../core/cmd/helm-ai-kernel/contract_routes.go), [`subsystems.go`](../../core/cmd/helm-ai-kernel/subsystems.go) |
| Trust keys | `POST /api/v1/trust/keys/add`, `POST /api/v1/trust/keys/revoke` | [`contract_routes.go`](../../core/cmd/helm-ai-kernel/contract_routes.go), [`trust_cmd.go`](../../core/cmd/helm-ai-kernel/trust_cmd.go) |
| Telemetry and coexistence | `GET /api/v1/telemetry/otel/config`, `POST /api/v1/telemetry/export`, `GET /api/v1/coexistence/capabilities` | [`contract_routes.go`](../../core/cmd/helm-ai-kernel/contract_routes.go), [`boundary_surface_cmd.go`](../../core/cmd/helm-ai-kernel/boundary_surface_cmd.go) |

`api/openapi/helm.openapi.yaml` is the public HTTP source truth. Routes mounted directly by `subsystems.go` but absent from OpenAPI are implementation or compatibility routes until they are added to the OpenAPI contract and parity tests.

`helm-ai-kernel server` runs API routes on `HELM_PORT` or `8080` by default. Its health server is separate and uses `HELM_HEALTH_PORT` or `8081` by default; `helm-ai-kernel serve` keeps the local policy boundary default at `127.0.0.1:7714`.

## Request And Response Notes

- JSON routes return HELM error envelopes through [`core/pkg/api/apierror.go`](../../core/pkg/api/apierror.go).
- `GET /api/v1/receipts/tail` is an SSE stream. The HTTP route can stream without an `agent` query; the CLI wrapper `helm-ai-kernel receipts tail` requires `--agent`.
- `POST /api/v1/evidence/export` returns EvidencePack bytes and sets `X-Helm-Evidence-Hash`.
- Boundary and evidence verification endpoints are offline-first. Online ledger checks are additive and never replace native receipts or EvidencePack roots.

## Validation

```bash
cd core
go test ./cmd/helm-ai-kernel -run 'Test.*Route|Test.*OpenAPI|Test.*Receipt|Test.*Boundary' -count=1
cd ..
make docs-truth
```

## Troubleshooting

| Symptom | First check |
| --- | --- |
| `401` or `403` on a protected route | Confirm `Authorization`, `HELM_ADMIN_API_KEY`, `HELM_SERVICE_API_KEY`, and tenant/principal headers match the route auth class. |
| A route appears in OpenAPI but not runtime | Compare `api/openapi/helm.openapi.yaml` with `core/cmd/helm-ai-kernel/route_registry.go` and run the route parity tests. |
| SSE receipt tail does not stream | Verify the runtime was started with receipt storage enabled; add an `agent` query only when you want to filter the stream. |


---
title: "HELM AI Kernel JSON Schema Reference"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/reference/json-schemas"
source: "helm-ai-kernel/docs/reference/json-schemas.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/reference/json-schemas.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-21"
checksum_sha256: "sha256:4d0214b633190b7fd08e24818ad3c50bad6ce01de2c4a2bfad5aad51c554feeb"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM AI Kernel JSON Schema Reference

This page is for developers who need the public schema inventory before writing validators, SDK bindings, conformance tests, or receipt processors. The outcome is a concrete map from schema family to source path, validation command, and public docs surface.

## Audience

Use this page if you validate HELM JSON artifacts, generate types, add a receipt field, or need to know whether a schema family is a public contract.

## Outcome

After this page you should know where public schema files live, how schema families map to consumers, how to validate schema index freshness, and what is not yet a stable public API.

## Source Truth

The schema source is [`protocols/json-schemas`](../../protocols/json-schemas), with the generated index at `protocols/json-schemas/SCHEMA_INDEX.md` (protected staff doc). The current tree contains 192 schema-related files across the public schema families listed below. Legacy compatibility schemas under [`schemas`](../../schemas) remain source-owned and are referenced from the protocol hub when they back public receipt examples.

## Schema Family Flow

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Schemas["protocols/json-schemas"]
        Index["SCHEMA_INDEX.md"]
        Docs["public schema reference"]
        Tests["docs-truth and conformance"]
        SDKs["generated types and SDK examples"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Receipts["receipt and EvidencePack validation"]
    end

    %% Operational Flow Edges
    Schemas --> Index
    Index --> Docs
    Schemas --> Tests
    Tests --> SDKs
    SDKs --> Receipts

    %% Premium Styling Rules
    style Receipts fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Public Families

| Family | Source path | Primary consumers |
| --- | --- | --- |
| access | [`protocols/json-schemas/access`](../../protocols/json-schemas/access) | privileged access requests and receipts |
| audit | [`protocols/json-schemas/audit`](../../protocols/json-schemas/audit) | merged audit reports |
| certification | [`protocols/json-schemas/certification`](../../protocols/json-schemas/certification) | conformance and deploy attestations |
| cli | [`protocols/json-schemas/cli`](../../protocols/json-schemas/cli) | CLI schema snapshots |
| compliance | [`protocols/json-schemas/compliance`](../../protocols/json-schemas/compliance) | control mappings |
| core | [`protocols/json-schemas/core`](../../protocols/json-schemas/core) | envelopes, effects, EvidencePacks, receipts, and error IR |
| effects / evidence | [`protocols/json-schemas/effects`](../../protocols/json-schemas/effects), [`protocols/json-schemas/evidence`](../../protocols/json-schemas/evidence) | governed action effects and external host evidence receipts |
| identity | [`protocols/json-schemas/identity`](../../protocols/json-schemas/identity) | agent and principal identity envelopes |
| packs | [`protocols/json-schemas/packs`](../../protocols/json-schemas/packs) | policy and reference pack manifests |
| policy | [`protocols/json-schemas/policy`](../../protocols/json-schemas/policy) | policy bundles and rule inputs |
| receipt / receipts | [`protocols/json-schemas/receipt`](../../protocols/json-schemas/receipt), [`protocols/json-schemas/receipts`](../../protocols/json-schemas/receipts) | native HELM receipt verification |
| registry | [`protocols/json-schemas/registry`](../../protocols/json-schemas/registry) | module, connector, and pack registries |
| safety / verification | [`protocols/json-schemas/safety`](../../protocols/json-schemas/safety), [`protocols/json-schemas/verification`](../../protocols/json-schemas/verification) | fail-closed checks and verifier outputs |
| telemetry / tooling | [`protocols/json-schemas/telemetry`](../../protocols/json-schemas/telemetry), [`protocols/json-schemas/tooling`](../../protocols/json-schemas/tooling) | OpenTelemetry and tool governance exports |

Families not listed here are still indexed in `SCHEMA_INDEX.md`; they are intentionally routed through the protocol hub until they become direct public contracts.

## Validation

Run these after changing a schema, generated type, or public example:

```bash
make docs-coverage
make docs-truth
cd protocols/json-schemas
rg -n '"$schema"|"type"|"properties"' .
```

Expected output: the docs gates pass, and every public schema path referenced by this page exists in `protocols/json-schemas`.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| A public docs page references a schema missing from `SCHEMA_INDEX.md` | schema index drift | regenerate or update `SCHEMA_INDEX.md`, then run `make docs-truth` |
| An SDK type does not match a schema field | generated type drift | update the generator or SDK type source before documenting the field |
| A receipt example validates against `schemas/receipts` but not `protocols/json-schemas` | legacy compatibility path | link both paths and explain which verifier accepts each contract |

## Not Covered

This page does not claim that every schema is a stable public API. The public contract is the subset tied to documented CLI, HTTP, receipt, EvidencePack, conformance, and SDK examples.


---
title: "Protocols and Schemas"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/reference/protocols-and-schemas"
source: "helm-ai-kernel/docs/REFERENCE_PROTOCOLS.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/REFERENCE_PROTOCOLS.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:cc3aef896055e875ef0b24d861e311d4d636a2128c92e9671fc6c3f2949014b3"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM AI Kernel Protocols and Schemas

This page is the public hub for HELM AI Kernel protocols, JSON schemas, policy
language material, conformance fixtures, and evidence-pack formats.

## Audience

This page is for developers implementing clients, auditors checking wire
contracts, and maintainers changing protocol or schema files.

## Outcome

You should know which protocol family to use, where the normative schema lives,
and which public route explains the behavior.

## Protocol Topology

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        conformance["Conformance profile"]
        registry["Compatibility registry"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        request["PDP request"]
        policy["Policy bundle"]
        decision["Policy decision"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["Receipt v2"]
        evidence["Evidence pack"]
    end

    %% Operational Flow Edges
    request --> policy
    policy --> decision
    decision --> receipt
    receipt --> evidence
    evidence --> conformance
    conformance --> registry

    %% Premium Styling Rules
    style request fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style policy fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style decision fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style evidence fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Protocol Families

| Family | Source path | Public use |
| --- | --- | --- |
| Core protocol | `protocols/spec/PROTOCOL.md` | Conceptual contract for HELM wire behavior. |
| Evidence pack | `protocols/spec/evidence-pack-v1.md` | Offline verification and auditor evidence exchange. |
| JSON schemas | `protocols/json-schemas/SCHEMA_INDEX.md`, `protocols/json-schemas/` | Normative schema references for receipts, policy, effects, packs, telemetry, and tooling. |
| Policy schema | `protocols/policy-schema/v1/` | DSL grammar, canonicalization, reason codes, and localization keys. |
| Conformance | `protocols/conformance/v1/` | Test vectors, compatibility registry, and conformance guide. |
| Effect specs | `protocols/specs/effects/` | OpenAPI and taxonomy for effect contracts. |
| Authority court specs | `protocols/specs/authority-court/` | Authorization request and decision schema material. |
| Reference packs | `reference_packs/` | Public compliance and industry evidence pack templates. |

## Schema Domains

The JSON schema index covers access, actor context, audit, authority,
autonomy envelope, business controls, certification, CLI, compliance, core,
cybernetics, effects, identity, intent, intervention, jurisdiction, kernel,
module provenance, organization DNA, packs, policy, profiles, reason codes,
receipts, registry, safety, telemetry, tooling, truth, and verification.

Use `/openapi.yaml` for the public HTTP API where available. Use the schema
index and protocol files for non-REST interfaces such as receipts, evidence
packs, policy bundles, effects, MCP-adjacent contracts, and conformance vectors.

## Source Truth

- `protocols/json-schemas/SCHEMA_INDEX.md`
- `protocols/spec/PROTOCOL.md`
- `protocols/spec/evidence-pack-v1.md`
- `protocols/policy-schema/v1/dsl_grammar.md`
- `protocols/conformance/v1/CONFORMANCE_GUIDE.md`
- `docs/architecture/policy-languages.md`

## Troubleshooting

| Problem | Check |
| --- | --- |
| Schema validation disagrees across clients | Confirm canonical JSON handling and the exact schema version in `SCHEMA_INDEX.md`. |
| A policy bundle evaluates differently | Check policy language canonicalization and reason-code mapping. |
| A conformance implementation fails | Compare against `protocols/conformance/v1/test-vectors.json`. |
| A receipt cannot be replayed | Check the evidence-pack schema, receipt version, and referenced artifact hashes. |

<!-- docs-depth-final-pass -->

## Protocol Update Rules

Protocol documentation is current only when schemas, examples, tests, and public references agree. Any change to a JSON schema, bundle layout, receipt field, MCP message shape, or verifier payload must update the schema index, at least one valid example, one invalid example, and the compatibility note. Public docs should distinguish stable contracts from implementation details; generated files and private operator payloads can be indexed without being explained as public APIs. When drift appears, prefer generated schemas and conformance fixtures over prose, then repair the prose and rerun docs truth.

<!-- docs-depth-final-pass-extra -->
 The public protocol hub should also state which generated registries are authoritative and which compatibility windows apply to clients pinned to older receipt or bundle versions.

<!-- docs-depth-final-pass-extra-2 -->
 Include migration notes whenever a field is renamed, deprecated, or promoted to stable.


---
title: "SDK Index"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/sdks"
source: "helm-ai-kernel/docs/sdks/00_INDEX.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/sdks/00_INDEX.md"
section: "interfaces"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-19"
checksum_sha256: "sha256:bba894d9749733cb4659d5e2f73f652d060c0805df541560e2986a66156934f5"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# SDK Index

HELM AI Kernel retains typed SDK surfaces for developers who want clients over the HTTP API instead of raw requests. Package publication status must be proven separately from source availability.

## Audience

This page is for developers who need a typed client for the HELM AI Kernel HTTP API and reviewers auditing whether a language SDK is source-only, locally buildable, or published under a verified package identity.

## Outcome

You should leave with the current SDK matrix, local validation command for each language, and the right base URL for direct HELM boundary calls versus the OpenAI-compatible proxy.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        OpenAPI["OpenAPI contract"]
        SDKs["Python SDK / TypeScript / Go SDK / Rust SDK / Java"]
        Boundary["HELM HTTP boundary"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Receipts["signed receipts"]
        Verify["offline verification"]
    end

    %% Operational Flow Edges
    OpenAPI --> SDKs
    SDKs --> Boundary
    Boundary --> Receipts
    Receipts --> Verify

    %% Premium Styling Rules
    style Receipts fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Source Truth

- `api/openapi/helm.openapi.yaml`
- `sdk/go/`
- `sdk/python/`
- `sdk/ts/`
- `sdk/rust/`
- `sdk/java/`
- `examples/go_client/`
- `examples/java_client/`
- `examples/rust_client/`
- `examples/python_openai_baseurl/`
- `examples/ts_openai_baseurl/`
- `examples/js_openai_baseurl/`
- `docs/developer-coverage.manifest.json`

SDK documentation should separate three facts: source exists, local tests pass,
and a package is published under a public registry identity. Source availability
is proven by this repository. Local behavior is proven by the validation command
listed in the matrix. Registry publication must be verified independently before
docs claim that an install command fetches a released package. This prevents the
SDK docs from turning generated clients or local examples into unsupported
distribution promises.

## SDK Matrix

| Language | Public package status | Source | Validation |
| --- | --- | --- | --- |
| Python SDK | Package name `helm-sdk`; source manifest currently declares `0.5.1`. Verify registry state before publishing pinned install claims. | `sdk/python/helm_sdk/client.py` | `make test-sdk-py` |
| TypeScript | Package name `@mindburn/helm-ai-kernel`; source manifest currently declares `0.5.1`. Verify registry state before publishing pinned install claims. | `sdk/ts/src/client.ts` | `make test-sdk-ts` |
| JavaScript | Uses `@mindburn/helm-ai-kernel` or raw HTTP/fetch | `sdk/ts/src/client.ts`, `examples/js_openai_baseurl/` | `make test-sdk-ts` |
| Go SDK | Source/module path only; pin `@main` or a commit until tagged SDK modules are aligned | `sdk/go/client/client.go` | `cd sdk/go && go test ./...` |
| Rust SDK | Package name `helm-sdk`; source manifest currently declares `0.5.1`. Verify registry state before publishing pinned install claims. | `sdk/rust/src/client.rs` | `make test-sdk-rust` |
| Java SDK | Maven Central coordinate `io.github.mindburnlabs:helm-sdk:0.5.2`; verified by remote Maven resolution and repo1 artifacts. | `sdk/java/pom.xml` | `make test-sdk-java` |

Use `http://127.0.0.1:7714` for the local `helm-ai-kernel serve --policy` quickstart, `http://localhost:8080` for `helm-ai-kernel server` or the current Docker Compose mapping, and `http://localhost:9090/v1` only for the OpenAI-compatible proxy.

## Python

```bash
pip install helm-sdk
cd sdk/python
python -m pip install '.[dev]'
pytest -v --tb=short
```

```python
from helm_sdk import HelmApiError, HelmClient, ChatCompletionRequest, ChatMessage

client = HelmClient(base_url="http://127.0.0.1:7714")
```

## TypeScript / JavaScript

```bash
npm install @mindburn/helm-ai-kernel
cd sdk/ts
npm ci
npm test -- --run
npm run build
```

```ts
import { HelmApiError, HelmClient } from "@mindburn/helm-ai-kernel";

const client = new HelmClient({ baseUrl: "http://127.0.0.1:7714" });
```

Use the OpenAI-compatible proxy instead of the SDK when an existing OpenAI-style client can set `base_url` or `baseURL`.

## Go

```bash
go get github.com/Mindburn-Labs/helm-ai-kernel/sdk/go@main
cd sdk/go
go test ./...
```

```go
client := helm.New("http://127.0.0.1:7714")
```

## Rust

```bash
cargo add helm-sdk
```

```bash
cd sdk/rust
cargo test
```

```rust
let client = HelmClient::new("http://127.0.0.1:7714");
```

## Java

Use the verified Maven Central coordinate:

```xml
<dependency>
  <groupId>io.github.mindburnlabs</groupId>
  <artifactId>helm-sdk</artifactId>
  <version>0.5.2</version>
</dependency>
```

Use a local Maven build when editing this repository:

```bash
cd sdk/java
mvn -q test
```

```java
HelmClient client = new HelmClient("http://127.0.0.1:7714");
```

## Agent Framework Helpers

The TypeScript SDK includes adapter helpers for LangGraph, CrewAI, OpenAI Agents SDK, PydanticAI, and LlamaIndex tool-call events. The helpers normalize framework events into a HELM governance request and submit it through `chatCompletionsWithReceipt`, preserving the kernel receipt returned in `X-Helm-*` headers.

```bash
make test-sdk-ts
```

These helpers do not add vendor framework packages as HELM dependencies and do not claim vendor certification.

## Troubleshooting

| Condition | Developer behavior |
| --- | --- |
| policy denial | treat as a final authorization result and surface the reason code |
| network failure | retry only when no HELM decision was returned |
| malformed request | fix the request shape against the OpenAPI types |
| missing receipt metadata | verify the app is calling the HELM boundary |
| SDK drift | rerun generated-type checks and update code plus docs together |

If registry state and source manifests disagree, treat the repository source as buildable code and do not publish an install claim until the registry package can be verified independently.


---
title: "ClawGuard Taint Tracking"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/security/clawguard-taint-tracking"
source: "helm-ai-kernel/docs/security/clawguard-taint-tracking.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/security/clawguard-taint-tracking.md"
section: "security"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:1358f594b1d3d48f3cd9a6b0198d7681b0528c464be160af10f6fdf5ec0ed68b"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# ClawGuard Taint Tracking Prototype

## Audience

Security researchers and maintainers reviewing the source-backed ClawGuard taint-tracking mapping for HELM AI Kernel.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/security/clawguard-taint-tracking`
- Source document: `helm-ai-kernel/docs/security/clawguard-taint-tracking.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

Source: Wei Zhao, Zhe Li, Peixin Zhang, and Jun Sun, "ClawGuard: A Runtime Security Framework for Tool-Augmented LLM Agents Against Indirect Prompt Injection", arXiv:2604.11790.

ClawGuard's core operational move is deterministic enforcement at every tool-call boundary. HELM AI Kernel maps that into the existing Guardian and PRG surfaces:

| ClawGuard concept | HELM AI Kernel implementation |
| --- | --- |
| Task/tool boundary rule set | PRG/CEL requirements evaluated by Guardian |
| Taint on tool-returned or external content | `Effect.Taint` and `AuthorizedExecutionIntent.Taint` |
| Deterministic tool-call interception | Feature-flagged Guardian tainted-egress gate |
| Auditable enforcement | signed `DecisionRecord`, intent taint binding, TLA invariant |

## Runtime Contract

Callers may attach taint labels through `DecisionRequest.Context`:

```json
{
  "destination": "https://external.example/upload",
  "taint": ["pii", "tool_output"]
}
```

When `HELM_TAINT_TRACKING=1`, Guardian denies outbound egress carrying sensitive taint (`pii`, `credential`, or `secret`) unless the context explicitly contains:

```json
{
  "allow_tainted_egress": true
}
```

The decision remains fail-closed: denial uses `TAINTED_DATA_EGRESS_DENY`, and issued execution intents copy normalized taint labels from the effect they authorize.

## CEL Helper

PRG requirements can use either explicit or shorthand forms:

```cel
taint_contains(input.taint, "pii")
taint_contains("pii")
```

The shorthand is rewritten to the explicit form inside the PRG evaluator. Policy-pack validation supports the same shorthand against the top-level `taint` variable.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        input["Untrusted input"]
        taint["Taint label"]
        transform["Transform / sanitize"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        check["Boundary check"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        effect["Permitted effect"]
        deny["Denied effect"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["Receipt evidence"]
    end

    %% Operational Flow Edges
    input --> taint
    taint --> transform
    transform --> check
    check -->|safe| effect
    check -->|unsafe| deny
    effect --> receipt
    deny --> receipt

    %% Premium Styling Rules
    style check fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style effect fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style deny fill:#e53e3e,stroke:#9b2c2c,stroke-width:2px,color:#fff
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


<!-- docs-depth-final-pass -->

## Security Review Checklist

A taint-tracking claim is publishable only when the source channel, propagation rule, egress decision, and receipt evidence are all visible to a reviewer. Keep examples concrete: user input, tool output, retrieved document, browser observation, and connector payloads should be classified separately. The expected failure mode is an explicit deny or escalation, not silent sanitization. If a new adapter bypasses taint metadata, document the gap as unsupported until the adapter attaches source channel and destination context. Reviewers should be able to reproduce the deny path, inspect the receipt, and verify the bundle offline.

<!-- docs-depth-final-pass-extra -->
 Record the specific adapter and policy bundle used for each reproduced deny path so a verifier can distinguish taint propagation from a generic policy denial.


---
title: "OWASP Agentic Top 10 Mapping"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/security/owasp-agentic-top10-mapping"
source: "helm-ai-kernel/docs/security/owasp-agentic-top10-coverage.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/security/owasp-agentic-top10-coverage.md"
section: "security"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:f19eedcb0f47d23421aa2c672f02ef8b78571c59ea290ec75f2ecbf29dbbeae6"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# OWASP Agentic Top 10 Mapping

## Audience

Security reviewers checking which OWASP Agentic AI Top 10 risks are covered by current HELM AI Kernel evidence.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/security/owasp-agentic-top10-mapping`
- Source document: `helm-ai-kernel/docs/security/owasp-agentic-top10-coverage.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

This scheme maps the main sections of OWASP Agentic Top 10 Mapping in reading order.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["OWASP Agentic Top 10 Mapping"]
        A["Source truth"]
        C["Validation"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        B["Reader action"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C

    %% Premium Styling Rules
    style B fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
```


This file is a code-oriented inventory of retained control points in the OSS kernel.

| OWASP Category | Repository Control Points |
| --- | --- |
| ASI-01 Prompt Injection | `core/pkg/threatscan/`, guarded execution boundary |
| ASI-02 Tool Poisoning | contract validation, firewall, connector validation |
| ASI-03 Excessive Permission | policy and effect-boundary packages |
| ASI-04 Insufficient Validation | guardian, manifest, schema, and policy packages |
| ASI-05 Improper Output Handling | evidence, receipts, and verification flow |
| ASI-06 Resource Overuse | budget and execution-control packages |
| ASI-07 Cascading Effects | proof graph and effect tracking |
| ASI-08 Sensitive Data Exposure | firewall, policy, and receipt material |
| ASI-09 Insecure Tool Integration | MCP, connector, and schema surfaces |
| ASI-10 Insufficient Monitoring | evidence export, proof graph, and verification commands |

Use this page as an implementation map. Validation still depends on the code, tests, and verification commands in the repository.

<!-- docs-depth-final-pass -->

## Coverage Discipline

OWASP Agentic Top 10 coverage must stay evidence-backed. For each risk, name the HELM AI Kernel control, the code or schema that implements it, the public example or fixture that exercises it, and the residual risk that remains outside the OSS boundary. Do not imply that policy evaluation replaces app authorization, secrets management, sandboxing, or network egress controls. The strongest public page shows both prevention and observability: how a risky action is blocked, how the receipt records it, how the verifier checks it, and what an operator should inspect when the action is allowed under policy.

<!-- docs-depth-final-pass-extra -->
 Link every mitigation to a concrete evidence artifact so evaluators can check the claim without reading unrelated implementation internals.


---
title: "Prompt Injection Watchlist - April 2026"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/security/prompt-injection-watchlist-2026-04"
source: "helm-ai-kernel/docs/security/prompt-injection-watchlist-2026-04.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/security/prompt-injection-watchlist-2026-04.md"
section: "security"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:eb65c26695c33cafc472d344cc37d5e36608973a13095bd91e6fd8b53814f487"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Prompt Injection Watchlist - April 2026

## Audience

Security maintainers tracking public prompt-injection research that affects HELM AI Kernel execution-boundary design.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/security/prompt-injection-watchlist-2026-04`
- Source document: `helm-ai-kernel/docs/security/prompt-injection-watchlist-2026-04.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

This scheme maps the main sections of Prompt Injection Watchlist - April 2026 in reading order.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["Prompt Injection Watchlist - April 2026"]
        A["Source Verification"]
        B["HELM Mapping"]
        C["No-Go Criteria"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C

    %% Premium Styling Rules
```


This note records the source verification and implementation decision for the April 2026 HOSS radar items on upstream prompt-injection defenses. It is not a production commitment; HELM remains the deterministic downstream execution boundary.

## Source Verification

| Linear | Source | Verification | Decision |
| --- | --- | --- | --- |
| `MIN-237` | [AgentWatcher: A Rule-based Prompt Injection Monitor](https://arxiv.org/abs/2604.01194v1) | arXiv record exists, submitted April 1, 2026; title and authors match the radar text | Keep as watchlist/prototype material |
| `MIN-238` | [ICON: Indirect Prompt Injection Defense for Agents based on Inference-Time Correction](https://arxiv.org/abs/2602.20708v1) | arXiv record exists, submitted February 24, 2026; title and authors match the radar text | Keep as watchlist/prototype material |

## HELM Mapping

AgentWatcher is useful to evaluate because its rule-oriented framing can provide an explainable pre-filter before requests reach Guardian. A production implementation should live behind a policy toggle and emit evidence about which rule, source segment, and confidence threshold caused a short-circuit.

ICON is an inference-time defense. It is complementary to HELM, not a replacement for HELM: the model-layer probe may reduce compromised plans before they are proposed, while HELM still governs the downstream action boundary with policy, effect, delegation, and receipt evidence.

## No-Go Criteria

Do not merge either approach into the default path until:

- the implementation can run deterministically or preserve a deterministic evidence envelope around model-assisted decisions;
- benchmark fixtures show the false-positive impact on benign tool-use workflows;
- policy authors can disable the pre-filter without weakening HELM's existing Guardian gate;
- emitted evidence can be replayed or independently inspected during incident review.

<!-- docs-depth-final-pass -->

## Review Cadence

Keep this watchlist tied to dated examples, affected adapters, and the receipt fields that expose attempted injection.


---
title: "Release and Security Evidence"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/security/release-security"
source: "helm-ai-kernel/docs/RELEASE_SECURITY.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/RELEASE_SECURITY.md"
section: "security"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-20"
checksum_sha256: "sha256:781ed0724ad6f246b15c2f723ed37af32ac63fdab03c19f2225d60718af45ae0"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM AI Kernel Release and Security Evidence

This page collects the public release, vulnerability disclosure, supply-chain,
fuzzing, OpenSSF, VEX, SBOM, Cosign, and reproducibility material for HELM AI Kernel.

## Audience

This page is for developers installing release artifacts, security reviewers,
package maintainers, and organizations validating HELM AI Kernel before adoption.

## Outcome

You should know how a release is produced, how to verify it, where to report
vulnerabilities, and which evidence files support supply-chain review.

## Release Evidence Chain

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        tag["Version tag"]
        ci["Release workflow"]
        binaries["Binaries and packages"]
        sbom["SBOM"]
        attestation["Release metadata / attestation when present"]
        optional["Optional Cosign / OpenVEX assets"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        verify["Artifact verification"]
    end

    %% Operational Flow Edges
    tag --> ci
    ci --> binaries
    ci --> sbom
    ci --> attestation
    ci --> optional
    binaries --> verify
    sbom --> verify
    attestation --> verify
    optional --> verify

    %% Premium Styling Rules
    style verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


Current source release target: `v0.5.6`:
<https://github.com/Mindburn-Labs/helm-ai-kernel/releases/tag/v0.5.6>. The
release is complete only when GitHub shows Darwin/Linux/Windows binaries,
`SHA256SUMS.txt`, `sbom.json`, `v0.5.6.openvex.json`,
`release-attestation.json`, `evidence-pack.tar`, `release.high_risk.v3.toml`,
`sample-policy-material.tar`, `helm-ai-kernel-launchpad-data.tar`,
`helm-ai-kernel.mcpb`, `helm-ai-kernel.rb`, `v0.5.6.json`,
`version-status.json`, and matching `*.cosign.bundle` files for each primary
asset.

## Public Release Material

| Need | Source path | Public route |
| --- | --- | --- |
| Release preparation | `RELEASE.md`, `VERSION`, `CHANGELOG.md` | `/helm-ai-kernel/publishing`, `/helm-ai-kernel/changelog` |
| Vulnerability reporting | `SECURITY.md` | This page and `/helm-ai-kernel/publishing` |
| OpenSSF mapping | `BEST_PRACTICES.md` | This page |
| SBOM and release metadata | `release/README.md`, `scripts/ci/generate_sbom.sh`, release asset `sbom.json`, release asset `release-attestation.json` | This page |
| OpenVEX policy source | `release/vex.openvex.json`, `release/vex/policies.yaml` | This page; only claim published VEX when attached to the GitHub release |
| Cosign and reproducible binaries | `.github/workflows/release.yml`, `scripts/release/`, `docs/VERIFICATION.md` | `/helm-ai-kernel/verification`, `/helm-ai-kernel/publishing`; Cosign verification requires attached `*.cosign.bundle` files |
| Fuzzing | `oss-fuzz/`, Go fuzz tests under `core/pkg/` | This page and `/helm-ai-kernel/execution-security-model` |

## Verification Commands

```bash
make release-binaries-reproducible
make release-smoke
make release-assets
make verify-cosign
make verify-fixtures
make docs-coverage docs-truth
```

Release artifacts should not be treated as trustworthy only because they are
downloaded from a release page. Verify checksums, release metadata,
receipt/evidence material, reproducible-build behavior, and signatures when
signature bundles are attached.

For tag-triggered releases, the workflow requires the tag ref to match the
checked-in `VERSION` file, requires an exact `v<version>.openvex.json`, exports
the audit EvidencePack, verifies the staged `evidence-pack.tar`, and only then
writes final checksums. A failed EvidencePack verification blocks release asset
publication.

For `v0.5.6`, use checksum verification, SBOM inspection, OpenVEX inspection,
release metadata inspection, offline EvidencePack verification,
reproducible-build validation, and Cosign verification against the attached
bundles.

## Source Truth

- `SECURITY.md`
- `RELEASE.md`
- `BEST_PRACTICES.md`
- `release/README.md`
- `docs/PUBLISHING.md`
- `docs/VERIFICATION.md`

## Troubleshooting

| Problem | Check |
| --- | --- |
| Signature verification fails | Confirm the release actually includes `*.cosign.bundle` files, then check the expected workflow identity and Rekor entry documented in `SECURITY.md`. |
| Reproducible build hashes differ | Confirm `SOURCE_DATE_EPOCH`, `-trimpath`, and build-id settings match the release workflow. |
| VEX status is unclear | Inspect `release/vex/policies.yaml`; only rely on a release VEX file when it is attached to the GitHub release. |
| Kubernetes Helm validation runs the HELM AI Kernel CLI | Set `KUBE_HELM_CMD` to a Kubernetes Helm v3 binary or run `make helm-chart-smoke`, which uses a pinned containerized Helm runner when needed. |
| A security issue needs disclosure | Use `security@mindburn.org`; do not open a public issue. |

<!-- docs-depth-final-pass -->

## Release Verification Path

A release security page should let a developer verify an artifact without trusting prose. Include the expected version, checksum file, SBOM location, signature or provenance command, and the receipt/verifier compatibility note for that release. If a release artifact is missing, mark the verification mode as unavailable rather than implying Cosign, SBOM, or reproducible-build coverage. The minimum public acceptance path is: download release artifact, verify checksum, inspect SBOM/provenance when present, run the binary or container health check, create one receipt, and verify that receipt offline.


---
title: "Session Risk Memory"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/security/session-risk-memory"
source: "helm-ai-kernel/docs/security/session-risk-memory.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/security/session-risk-memory.md"
section: "security"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:e701d813e9db5fa6098da665de3df28c75f7bd0aa847b4ceca5e8d0c53684bdd"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Session Risk Memory

## Audience

Security reviewers and maintainers checking session-risk memory assumptions against current HELM AI Kernel evidence behavior.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/security/session-risk-memory`
- Source document: `helm-ai-kernel/docs/security/session-risk-memory.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

Source: Florin Adrian Chitan, "Session Risk Memory (SRM): Temporal Authorization for Deterministic Pre-Execution Safety Gates", arXiv:2603.22350.

Session Risk Memory adds a trajectory gate after Guardian's existing pre-PDP checks:

1. Freeze and kill-switch checks.
2. Context, identity, egress, taint, threat, and delegation gates.
3. Session-history enrichment.
4. Session Risk Memory trajectory scoring.
5. Behavioral trust, privilege, PRG, temporal, compliance, and signing.

The implementation is deterministic and offline. It does not call an embedding model or classifier. Instead, it derives a compact three-axis semantic centroid from action/resource/context signals:

| Axis | Signals |
| --- | --- |
| Exfiltration | credential, token, PII, customer data, export/upload/webhook/external destinations |
| Privilege | sudo/admin/root, policy changes, write/delete/deploy/publish/exec operations |
| Compliance drift | HIPAA, GDPR, SOX, PCI, audit, regulated-data markers |

For each turn, Guardian computes a bounded risk signal, subtracts a baseline, and updates an exponential moving average. The signed `DecisionRecord` carries:

- `trajectory_risk_score`
- `session_centroid_hash`
- `risk_accumulation_window`

If the trajectory score crosses the configured threshold across at least two turns, Guardian returns `DENY` with `SESSION_RISK_MEMORY_DENY`. The centroid itself is not stored in the decision record; only a deterministic SHA-256 hash is emitted for audit correlation.

## Configuration

```go
srm := guardian.NewSessionRiskMemory(
    guardian.WithSessionRiskThreshold(0.38),
    guardian.WithSessionRiskWindow(8),
)
g := guardian.NewGuardian(signer, graph, registry, guardian.WithSessionRiskMemory(srm))
```

Use `session_id` or `delegation_session_id` in `DecisionRequest.Context` to scope SRM state. If neither is present, Guardian falls back to the principal ID.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        event["Session event"]
        score["Risk score"]
        memory["Session risk memory"]
        intervention["Intervention"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        policy["Policy evaluation"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        action{"Allow action?"}
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["Receipt"]
    end

    %% Operational Flow Edges
    event --> score
    score --> memory
    memory --> policy
    policy --> action
    action -->|yes| receipt
    action -->|no| intervention
    intervention --> receipt

    %% Premium Styling Rules
    style policy fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style action fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


<!-- docs-depth-final-pass -->

## Session Risk Evidence

Session-risk memory should explain what is remembered, why it changes policy, and how a developer proves the change occurred. Keep examples scoped to metadata and risk state, not raw secrets or private browser sessions. A complete update names the storage key or schema, the event that raises risk, the event that lowers or expires it, and the receipt fields that record the decision. If a deployment stores richer session state, that detail belongs in protected operator docs; public docs should describe the OSS contract and verification path only.


---
title: "HELM Skill Packs Flow Catalog"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/skills/flow-catalog"
source: "helm-ai-kernel/docs/skills/FLOW_CATALOG.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/skills/FLOW_CATALOG.md"
section: "interfaces"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-20"
checksum_sha256: "sha256:d3f3d16f910e096a357d3252364eecfcb6509ae79235fc010bf10da8ef8191e3"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM Skill Packs Flow Catalog

HELM Skill Packs are signed, scoped procedural packages for agents. A skill can guide behavior, but it cannot grant tool permissions or execution authority.

## Audience

This page is for developers and reviewers evaluating HELM-managed skill
installation, projection, disable, revoke, and marketplace flows.

## Outcome

You should leave with the command sequence for each skill-pack flow and the
authority boundary that keeps skills from granting tools or execution rights.

## Source Truth

- Skill runtime commands: `core/cmd/helm-ai-kernel/skills_cmd.go`
- Skill runtime packages: `core/pkg/skills/`
- Skill registry: `registry/skills/`
- Skill policy fixtures: `policies/skills/`
- Skill docs: `docs/skills/`

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        search["search registry"]
        scan["scan content and metadata"]
        install["repo-scoped install"]
        export["Codex plugin export"]
        revoke["disable or revoke"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        inspect["inspect skill"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipts["install/projection receipts"]
    end

    %% Operational Flow Edges
    search --> inspect
    inspect --> scan
    scan --> install
    install --> receipts
    scan --> export
    install --> revoke

    %% Premium Styling Rules
    style inspect fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style receipts fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## OSS Flows

### Search

`helm-ai-kernel skills search --json`

Loads the first-party skill registry and returns skills as `verified`, `experimental`, `blocked`, or `external`.

### Inspect

`helm-ai-kernel skills inspect helm/repo-auditor --json`

Shows manifest, requested projections, and the authority boundary: this skill does not grant tool permissions.

### Scan

`helm-ai-kernel skills scan <path_or_ref> --json`

Computes `skill_content_hash`, scans `SKILL.md`, metadata, scripts, symlinks, and MCP/tool requests, then emits `SKILL_SCAN_ATTESTATION`.

### Repo-Scoped Install

`helm-ai-kernel skills install helm/repo-auditor --agent codex --scope repo`

Runs scan, writes managed projection files atomically, and emits `SKILL_INSTALL_RECEIPT` plus `SKILL_PROJECTION_RECEIPT`.

### User Or Global Install

`helm-ai-kernel skills install helm/repo-auditor --agent codex --scope user`

Returns `ESCALATE` by default and writes no projection files.

### Export Codex Plugin

`helm-ai-kernel skills export helm/repo-auditor --format codex-plugin --output ./dist/repo-auditor`

Writes `.codex-plugin/plugin.json`, bundled skill files, pending/quarantined MCP metadata, and off-by-default hooks.

### Marketplace

`helm-ai-kernel skills marketplace init --scope repo`

Creates `.agents/plugins/marketplace.json`.

`helm-ai-kernel skills marketplace add <plugin_path>`

Adds only plugins inside the repo root and records policy/source hashes.

### Disable And Revoke

`helm-ai-kernel skills disable <skill_ref>`

Marks a HELM-managed install disabled and emits `SKILL_DISABLE_RECEIPT`.

`helm-ai-kernel skills revoke <skill_ref>`

Removes managed projection files, updates install state, and emits `SKILL_REVOKE_RECEIPT`.

## Negative Flows

- Policy bypass attempt -> `DENY`.
- Secret exfiltration attempt -> `DENY`.
- Global install request -> `ESCALATE`.
- MCP side-effect auto-enable -> `ESCALATE`.
- Plugin hook auto-approval -> `DENY`.
- Symlink escape -> `DENY`.
- Opaque binary payload -> `DENY` until provenance is available.

## Completion Gaps

Deferred: remote GitHub skill fetch, key-backed signature verification, full plugin marketplace e2e, and Enterprise global rollout approvals remain outside this MVP slice.

## Troubleshooting

| Condition | Response |
| --- | --- |
| Scan returns `DENY` | Inspect the attestation and remove unsafe file, symlink, or payload content before install. |
| User/global install escalates | Keep the install repo-scoped unless an operator approves the wider projection. |
| Marketplace add fails | Confirm the plugin path stays inside the repo root and has stable source hashes. |
| Revoke leaves files | Compare projection receipt paths with the working tree and remove only HELM-managed projections. |


---
title: "Developer Surface Map"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/source-map"
source: "helm-ai-kernel/docs/DEVELOPER_SURFACE_MAP.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/DEVELOPER_SURFACE_MAP.md"
section: "helm-ai-kernel"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:ca7b3160b9ebb07d9df69f148ce36079e0a809cefca18550f162eb705c13dd88"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM AI Kernel Developer Surface Map

This page is the public map of HELM AI Kernel developer surfaces. It complements the
quickstart and developer journey by showing where each source-backed capability
lives in the repository and which public docs page owns the explanation.

## Audience

This page is for developers who need the full HELM AI Kernel surface area without
reading the repository directory by directory.

## Outcome

You should be able to pick the correct page for installation, local execution,
language SDKs, framework integration, deployment, schemas, conformance,
verification, release integrity, and troubleshooting.

## Surface Flow

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        install["Install / build"]
        integrate["Integrate SDK or proxy"]
        deploy["Deploy or publish"]
        operate["Debug and conform"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        policy["Evaluate policy"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        boundary["Run HELM boundary"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["Capture receipt"]
        verify["Verify evidence"]
    end

    %% Operational Flow Edges
    install --> boundary
    boundary --> integrate
    integrate --> policy
    policy --> receipt
    receipt --> verify
    verify --> deploy
    deploy --> operate

    %% Premium Styling Rules
    style boundary fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style policy fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Developer Surfaces

| Need | Public page | Source truth |
| --- | --- | --- |
| Install on macOS, Linux, Windows/WSL, Docker, or source | `/helm-ai-kernel/developer-journey` | `docs/DEVELOPER_JOURNEY.md`, `docs/QUICKSTART.md`, `Makefile`, `.goreleaser.yml` |
| Run the first local boundary | `/helm-ai-kernel/developer-journey` | `core/cmd/helm-ai-kernel/server_cmd.go`, `core/cmd/helm-ai-kernel/proxy_cmd.go` |
| Point OpenAI-compatible clients at HELM | `/helm-ai-kernel/integrations/openai-compatible-proxy` | `docs/INTEGRATIONS/openai_baseurl.md`, `examples/python_openai_baseurl/`, `examples/ts_openai_baseurl/` |
| Use MCP | `/helm-ai-kernel/integrations/mcp` | `docs/INTEGRATIONS/mcp.md`, `examples/mcp_client/`, `mcp-bundle.json` |
| Use Python, TypeScript, JavaScript, Go, Rust, or Java | `/helm-ai-kernel/sdks` | `sdk/`, `examples/*_client/`, `examples/*openai_baseurl/` |
| Understand policy languages and bundles | `/helm-ai-kernel/reference/protocols-and-schemas`, `/helm-ai-kernel/compatibility` | `docs/architecture/policy-languages.md`, `protocols/bundles/`, `examples/policies/` |
| Validate conformance | `/helm-ai-kernel/conformance` | `docs/CONFORMANCE.md`, `protocols/conformance/v1/`, `tests/conformance/` |
| Verify receipts and evidence packs | `/helm-ai-kernel/verification`, `/helm-ai-kernel/developer-journey` | `docs/VERIFICATION.md`, `examples/receipt_verification/`, `protocols/spec/evidence-pack-v1.md` |
| Deploy with Docker or Kubernetes | `/helm-ai-kernel/deployment-and-examples` | `docker-compose.yml`, `deploy/`, `deploy/helm-chart/` |
| Verify release artifacts | `/helm-ai-kernel/security/release-security`, `/helm-ai-kernel/publishing` | `SECURITY.md`, `RELEASE.md`, `release/`, `.github/workflows/release.yml` |

## Source Truth

The coverage gate is `docs/developer-coverage.manifest.json`. The docs platform
loads public pages from `docs/public-docs.manifest.json`, then validates that
coverage-backed claims appear in public docs, search, Markdown exports,
`llms.txt`, `llms-full.txt`, and MCP responses.

## Troubleshooting

| Symptom | Use this page |
| --- | --- |
| You know the source path but not the public route | Match the source family in the table above. |
| You know the integration but not the proof command | Open `docs/developer-coverage.manifest.json` and inspect `validation_commands`. |
| A public page claims a capability but no example exists | Treat it as a docs bug unless the coverage manifest lists a live `example_paths` entry. |

<!-- docs-depth-final-pass -->

## Surface Ownership Rules

The surface map is the index a maintainer checks before creating new public docs. Every meaningful code family should have exactly one owning doc, one validation command, and a decision about whether it is public direct, public hub, source-owner, generated/config, or private/internal. When a new directory, schema, SDK, example, or CLI command appears, update this map before adding marketing copy. The public site should expose supported developer paths; source-owner docs can carry implementation detail; generated/config rows can stay classified without standalone prose when they do not affect external workflows.

<!-- docs-depth-final-pass-extra -->
 Treat missing ownership as a release blocker for high-value surfaces such as CLI commands, SDK packages, schemas, release artifacts, conformance fixtures, verifier paths, deployment examples, and policy bundles.

<!-- docs-depth-final-pass-extra-2 -->
 This map is also the first stop for deciding whether a new doc belongs in public IA or source-owner docs.


---
title: "TROUBLESHOOTING"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/troubleshooting"
source: "helm-ai-kernel/docs/TROUBLESHOOTING.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/TROUBLESHOOTING.md"
section: "supporting-material"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:9c4a3c9c6bf9f831f1767527b8bd3fe070110bb6550993cff96e0ecd5da665ab"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Troubleshooting

## Audience

Operators and contributors diagnosing local HELM AI Kernel startup, proxy, Console, receipt, and verification failures.

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `helm-ai-kernel/troubleshooting`
- Source document: `helm-ai-kernel/docs/TROUBLESHOOTING.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

This scheme maps the main sections of Troubleshooting in reading order.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["Troubleshooting"]
        A["First Diagnostic"]
        B["Auth Errors"]
        D["Timeouts"]
        E["Conformance Failures"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        C["Egress / Network"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C
    C --> D
    D --> E

    %% Premium Styling Rules
    style C fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
```


Common issues and solutions for HELM.

---

## First Diagnostic

Run `helm-ai-kernel doctor --json` before deeper debugging when the CLI is installed but the runtime path is unclear. The doctor command checks local initialization, trust material, data directories, and common environment mistakes.

```bash
helm-ai-kernel doctor --json
```

---

## Auth Errors

### `HELM_UNREACHABLE` in adapters

The adapter cannot reach the HELM server.

```bash
# Check HELM is running
curl http://127.0.0.1:7714/healthz

# Check the URL in your adapter config
export HELM_URL=http://127.0.0.1:7714
```

`helm-ai-kernel server` still defaults to `127.0.0.1:8080`. The public quickstart uses `helm-ai-kernel serve --policy ./release.high_risk.v3.toml`, which defaults to `127.0.0.1:7714`.
The separate `helm-ai-kernel server` health endpoint uses `HELM_HEALTH_PORT` or `8081`;
`helm-ai-kernel health` checks that health endpoint, not the main API port.

### `401 Unauthorized` from proxy

```bash
# Set your upstream API key
helm-ai-kernel proxy --upstream https://your-upstream.example/v1 --api-key $OPENAI_API_KEY

# Or via environment
export OPENAI_API_KEY=sk-...
helm-ai-kernel proxy --upstream https://your-upstream.example/v1
```

For release smoke or customer-data-free debugging, use the local fixture instead:

```bash
python3 scripts/launch/mock-openai-upstream.py --port 19090
helm-ai-kernel proxy --upstream http://127.0.0.1:19090/v1
```

---

## Egress / Network

### Sandbox exec fails with "PREFLIGHT_DENIED"

The sandbox provider's egress policy is too restrictive or the provider is not configured.

```bash
# Check preflight details
helm-ai-kernel sandbox exec --provider e2b --json -- echo test | jq .preflight

# Ensure provider credentials
export E2B_API_KEY=your-key
```

### MCP server unreachable over HTTP/SSE

```bash
# Start with explicit transport
helm-ai-kernel mcp serve --transport http --port 9100

# Check firewall allows the port
curl http://localhost:9100/mcp
```

---

## Timeouts

### Proxy request timeout

```bash
# Increase wallclock limit (default: 120s)
helm-ai-kernel proxy --upstream http://127.0.0.1:19090/v1 --max-wallclock 300s
```

### Sandbox execution timeout

```bash
# Increase timeout (default: 30s)
helm-ai-kernel sandbox exec --provider opensandbox --timeout 60s -- long-running-command
```

---

## Conformance Failures

### `G0_JCS_CANONICALIZATION` fails

JCS canonicalization requires valid JSON. Check your tool arguments:

```bash
echo '{"b":2,"a":1}' | jq -S .   # sorted keys
```

### `G1_PROOFGRAPH` fails

ProofGraph requires at least one receipt in the evidence directory:

```bash
ls data/evidence/   # Should contain .json receipt files
```

### `G2A_EVIDENCE_PACK` fails

EvidencePack requires deterministic tar with epoch mtime:

```bash
# Export with HELM (ensures determinism)
helm-ai-kernel export --evidence ./data/evidence --out evidence.tar

# Verify
helm-ai-kernel verify evidence.tar
```

### `helm-ai-kernel verify --online` fails but offline verification passes

`--online` requires a reachable public proof API and matching ledger metadata in the pack.

```bash
export HELM_LEDGER_URL=https://mindburn.org/api/proof/verify
helm-ai-kernel verify evidence.tar --online
```

If the pack has no public anchor, use offline verification or regenerate the pack from a release asset with public proof metadata.

### `helm-ai-kernel receipts tail` does not print events

Confirm the local boundary is running and that receipts are being emitted for the same agent id:

```bash
helm-ai-kernel serve --policy ./release.high_risk.v3.toml
helm-ai-kernel receipts tail --agent agent.helm.demo --server http://127.0.0.1:7714
```

### release smoke fails locally

Run `make release-smoke` from the repository root and inspect the first failing
phase: reproducible binaries, SBOM JSON, OpenVEX JSON, or optional Cosign
bundle verification. The command writes generated evidence under ignored
release/build artifact paths, so rerun after fixing the source failure. Missing
Cosign bundles are informational in local smoke runs unless
`REQUIRE_COSIGN_BUNDLES=1` is set.

### release asset staging fails in CI

Run the same tag-shaped command locally:

```bash
GITHUB_REF_TYPE=tag GITHUB_REF_NAME=v<version> RELEASE_ASSETS_DIR="$(mktemp -d)" make release-assets
```

If the failure reports a missing exact OpenVEX document, run `make vex` with the
same tag-derived version. If it fails while verifying `evidence-pack.tar`, check
that `helm-ai-kernel export --audit` preserved every file referenced by
`00_INDEX.json`.

### Kubernetes Helm validation uses the HELM AI Kernel CLI

The local `helm` binary in this repository may be the HELM AI Kernel CLI, not the
Kubernetes Helm v3 binary. Set `KUBE_HELM_CMD` to a Kubernetes Helm v3 binary or
run `make helm-chart-smoke`, which uses the pinned containerized chart runner
when needed.

---

## Common Errors

| Error                   | Cause                     | Fix                              |
| ----------------------- | ------------------------- | -------------------------------- |
| `DENY_TOOL_NOT_FOUND`   | Unknown tool URN          | Register tool in policy manifest |
| `DENY_SCHEMA_MISMATCH`  | Args don't match schema   | Check tool argument types        |
| `PROXY_ITERATION_LIMIT` | Too many tool call rounds | Increase `--max-iterations`      |
| `PROXY_WALLCLOCK_LIMIT` | Session too long          | Increase `--max-wallclock`       |
| `HELM_UNREACHABLE`      | Server down or wrong URL  | Check `helm-ai-kernel health`              |
| `ESCALATE`              | Human approval or more evidence needed | Stop dispatch and complete the required approval/evidence path |


---
title: "Verification"
canonical: "https://helm.docs.mindburn.org/helm-ai-kernel/verification"
source: "helm-ai-kernel/docs/VERIFICATION.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-kernel/edit/main/docs/VERIFICATION.md"
section: "start-here"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-20"
checksum_sha256: "sha256:23b302d12dbccf8b18806abc562ad8ec9696fe1e370a42e6af42ea0eb2d9f4a2"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Verification

Verification proves a HELM AI Kernel EvidencePack, boundary record, release artifact, or optional signature bundle from source-owned material instead of prose.

## Audience

This page is for release consumers, security reviewers, and integration owners who need to verify HELM AI Kernel outputs without trusting a hosted service or marketing claim.

## Outcome

You should be able to run local offline verification, distinguish release metadata from cryptographic evidence, and identify which release assets have enough material to verify before you execute or redistribute them.

## Source Truth

- Public route: `helm-ai-kernel/verification`
- Source document: `helm-ai-kernel/docs/VERIFICATION.md`
- Public manifest: `helm-ai-kernel/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-kernel/docs/source-inventory.manifest.json`
- Validation: `make docs-coverage`, `make docs-truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Published output is stale or incomplete | Run `npm run helm-public:accuracy` in `docs-platform`, then check the source path and public manifest row for this page. |
| A claim needs implementation backing | Check the Source Truth files above and update the implementation, manifest, source inventory, or page in the same change. |

## Diagram

This scheme maps the main sections of Verification in reading order.

```mermaid
flowchart TD
    subgraph Execution["3. Execution & Verdict Plane"]
        E["Run the Maintained Validation Targets"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Page["Verification"]
        A["Offline Verification"]
        B["Online Proof Check"]
        C["Export and Verify"]
        D["Release Asset Verification"]
        F["Optional Cosign / VEX Verification"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C
    C --> D
    D --> F
    F --> E

    %% Premium Styling Rules
    style Page fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style A fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style B fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style C fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style D fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style F fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style E fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
```


The verification path is local-first. `helm-ai-kernel verify <evidence-pack.tar|dir>`
performs offline checks by default; `--online` is optional and only runs after
offline checks pass.

Current source release target: `v0.5.6`:
<https://github.com/Mindburn-Labs/helm-ai-kernel/releases/tag/v0.5.6>. The
release is complete only when the page attaches platform binaries,
`SHA256SUMS.txt`, `sbom.json`, `v0.5.6.openvex.json`,
`release-attestation.json`, `evidence-pack.tar`,
`release.high_risk.v3.toml`, `sample-policy-material.tar`,
`helm-ai-kernel-launchpad-data.tar`, `helm-ai-kernel.mcpb`,
`helm-ai-kernel.rb`, `v0.5.6.json`, `version-status.json`, and matching
`*.cosign.bundle` files for each primary asset.

There is no public GitHub Release object for `v0.4.1`; use `v0.4.0` as the
actual baseline when auditing the `v0.5.0` delta.

## v0.5.6 Asset Contract

The `v0.5.6` release attaches these primary assets:

- `helm-ai-kernel-darwin-amd64`
- `helm-ai-kernel-darwin-arm64`
- `helm-ai-kernel-linux-amd64`
- `helm-ai-kernel-linux-arm64`
- `helm-ai-kernel-windows-amd64.exe`
- `SHA256SUMS.txt`
- `sbom.json`
- `v0.5.6.openvex.json`
- `release-attestation.json`
- `evidence-pack.tar`
- `release.high_risk.v3.toml`
- `sample-policy-material.tar`
- `helm-ai-kernel-launchpad-data.tar`
- `helm-ai-kernel.mcpb`
- `helm-ai-kernel.rb`

`sample-policy-material.tar` must include both
`release.high_risk.v3.toml` and
`reference_packs/eu_ai_act_high_risk.v1.json`. The release workflow signs each
primary asset, including `SHA256SUMS.txt`, with a matching
`*.cosign.bundle`.

## Offline Verification

```bash
helm-ai-kernel verify evidence-pack.tar
```

Compatibility form:

```bash
helm-ai-kernel verify --bundle evidence-pack.tar
```

Successful compact output includes the envelope id, signature count, anchor state, and sealed timestamp when those fields are embedded in the pack. If no anchor is embedded, the CLI reports `anchor offline`; it does not invent an anchor.

## Online Proof Check

```bash
helm-ai-kernel verify evidence-pack.tar --online
```

`--online` posts envelope/root metadata to `HELM_LEDGER_URL` or `https://mindburn.org/api/proof/verify`. Public proof verification is additive and must never use fixture-backed positive proof.

## Export and Verify

```bash
helm-ai-kernel export --evidence ./data/evidence --out evidence.tar
helm-ai-kernel verify evidence.tar
```

Audit exports preserve every file listed by `00_INDEX.json`, including
top-level sidecars such as `01_SCORE.json.sha256`. Verification fails when an
indexed file is missing or the exported archive contains an unexpected
canonical top-level entry.

## Local Tamper-Failure Demo

The launch proof demo exercises the public verification path without external
network calls:

```bash
./scripts/launch/demo-proof.sh
```

The script starts a localhost HELM boundary, creates a signed `DENY` receipt
for the dangerous shell fixture, verifies the receipt through `/api/demo/verify`,
then flips the verdict through `/api/demo/tamper`. The original receipt must
verify, and the tamper attempt must fail signature and ProofGraph hash checks.

## Boundary Records, Checkpoints, and Envelopes

The execution-boundary verifier checks HELM-native records first. External envelopes are wrappers over HELM roots, not independent authority.

```bash
helm-ai-kernel boundary records --json
helm-ai-kernel boundary checkpoint --create --receipt-count 1 --json
helm-ai-kernel boundary verify boundary-record-bootstrap --json
helm-ai-kernel evidence envelope create --envelope dsse --native-hash sha256:evidence --manifest-id demo --json
helm-ai-kernel evidence envelope verify --manifest-id demo --json
```

For API-backed verification, use:

```text
POST /api/v1/boundary/records/{record_id}/verify
POST /api/v1/evidence/envelopes/{manifest_id}/verify
POST /api/v1/evidence/verify
POST /api/v1/replay/verify
```

## Release Asset Verification

Download the binary and `SHA256SUMS.txt` from the same GitHub release, then
check the digest before executing the binary:

```bash
shasum -a 256 -c SHA256SUMS.txt --ignore-missing
```

Inspect the release metadata and SBOM:

```bash
jq . release-attestation.json
jq . sbom.json
```

`release-attestation.json` in `v0.4.0` is release metadata. Treat it as
descriptive unless a release also provides a cryptographically verifiable
provenance predicate and a documented verifier command.

Verify the bundled offline evidence pack:

```bash
helm-ai-kernel verify evidence-pack.tar
```

The release staging path runs the same offline verification before publishing
release checksums. If this step fails, the release must be treated as incomplete
and the exported EvidencePack must be repaired before attaching assets.

For `v0.5.6`, this command passes without network access. The verifier
accepts both the legacy `receipts/` layout and the canonical
`02_PROOFGRAPH/receipts/` layout.

For `v0.4.0`, the included EvidencePack also verifies offline and reports
`anchor offline`, but that release does not attach OpenVEX or Cosign bundles.

## Cosign Artifact Verification When Bundles Are Attached

Cosign verification requires a matching `*.cosign.bundle` file attached to the
release. When a release includes those files, verify a downloaded binary blob
with the bundled signature:

```bash
cosign verify-blob \
  --bundle helm-ai-kernel-linux-amd64.cosign.bundle \
  --certificate-identity-regexp "https://github.com/Mindburn-Labs/helm-ai-kernel" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  helm-ai-kernel-linux-amd64
```

Verify the published container image when one is published for the release:

```bash
cosign verify \
  --certificate-identity-regexp "Mindburn-Labs/helm-ai-kernel" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/mindburn-labs/helm-ai-kernel:<version>
```

Verify every artifact in a downloaded release directory in one command when the
directory contains matching `*.cosign.bundle` files:

```bash
bash scripts/release/verify_cosign.sh ./downloaded-release/
```

The script walks the directory, finds every `*.cosign.bundle`, and runs
`cosign verify-blob` against the matching artifact. A run with zero bundle
files proves no signature coverage; check that bundles exist before treating
Cosign as part of the release evidence. The `make verify-cosign` target runs
the same script against `dist/`. If the release has no bundle assets, use
checksum, SBOM, release metadata, offline EvidencePack, and reproducible-build
verification instead.

### VEX Consumption When A VEX File Is Attached

The repository retains OpenVEX policy source under `release/vex/`. When a
release attaches an OpenVEX file next to the SBOM, filter scanner output
through the published VEX statements:

```bash
vexctl filter --vex release/vex/v<version>.openvex.json sbom.json
```

CVEs marked `not_affected` in the VEX are removed from the scan output;
`under_investigation` and `affected` entries pass through unchanged so
the scanner can still surface them.

## Run the Maintained Validation Targets

```bash
make test
make test-console
make test-platform
make test-all
make crucible
make launch-smoke
make sdk-openapi-check
make sdk-examples-smoke
make launch-ready
make release-smoke
```

## Benchmarks

```bash
make bench
make bench-report
```

The benchmark report writes a local artifact under `benchmarks/results/`; benchmark output is generated locally or in CI and is not committed as a release-truth artifact in the repository tree.


---
title: "Microsoft Entra Agent ID Integration"
canonical: "https://helm.docs.mindburn.org/integrations/entra-agent-id"
source: "helm-ai-enterprise/docs/public/product/integrations/entra-agent-id.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/integrations/entra-agent-id.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-04-29"
checksum_sha256: "sha256:32d8cfd1876c443138cdbdefed9c4a1d7a63be73524221422efac2a044f6b7ea"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Integration: Microsoft Entra Agent ID

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `integrations/entra-agent-id`
- Source document: `helm-ai-enterprise/docs/public/product/integrations/entra-agent-id.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

HELM AI Enterprise can use Microsoft Entra Agent ID as an upstream identity provider for governed agent execution. The connector maps validated Entra agent token claims into HELM AI Enterprise principals and signed guardian decision context before an MCP or A2A side effect is permitted.

## Current Microsoft Surface

Microsoft Entra Agent ID is currently preview. Microsoft describes agent identities as service-principal-backed identities created from blueprints, without credentials on the agent identity itself. Resource servers that receive agent tokens are expected to validate OAuth claims, check agent facet claims, enforce permissions, and keep tenant boundaries intact.

Sources:

- [Agent identities in Microsoft Entra Agent ID](https://learn.microsoft.com/en-us/entra/agent-id/agent-identities)
- [Tokens in Microsoft agent identity platform](https://learn.microsoft.com/en-us/entra/agent-id/agent-tokens)
- [Best practices for Microsoft Entra Agent ID](https://learn.microsoft.com/en-us/entra/agent-id/best-practices-agent-id)

## HELM Binding

The commercial adapter lives at:

```text
commercial/integrations/entraagent
```

It accepts claims after JWT signature verification by the caller, then enforces:

- expected Entra tenant (`tid`)
- expected issuer and API audience
- token expiry
- agent identity presence from `xms_act_fct`, `azp`, `appid`, or agent-specific claim aliases
- optional blueprint and agent allowlists
- fail-closed rejection for high-privilege Microsoft Graph permissions such as `Directory.ReadWrite.All` and `RoleManagement.ReadWrite.Directory`

The normalized identity becomes:

- a commercial RBAC principal with provider `microsoft_entra_agent_id`
- a guardian subject such as `entra-agent:<tenant>:<agent>`
- signed decision context fields including `entra_agent_id`, `entra_agent_blueprint_id`, `entra_identity_type`, and `entra_agent_user_object_id` when delegated user context is present

The downstream `EffectPermit` remains the core kernel artifact. Entra identity is bound through the signed guardian verdict and decision context that the permit references.

## Console Connector Option

The enterprise connector catalog exposes:

```go
connectors.MicrosoftEntraAgentIDDefinition()
```

The definition is commercial-only and declares the `microsoft_entra_agent_id` family with required config for tenant ID, issuer, and allowed audiences. It is intentionally separate from `helm-ai-kernel` and protected core paths.

## Minimal Flow

1. Entra issues an agent token to the HELM resource audience.
2. The HELM edge verifies JWT signature and standard OAuth validity.
3. `entraagent.Validate` maps and validates claims against tenant policy.
4. HELM evaluates guardian policy with the returned subject and decision context.
5. If guardian allows the side effect, HELM issues the normal signed permit and receipt chain.

## Failure Behavior

The connector fails closed for missing claims, wrong tenant, wrong audience, wrong issuer, expired token, missing agent identity, untrusted blueprint, or blocked high-privilege permission.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        token["Entra agent token"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        validate["Validate OAuth claims"]
        normalize["Normalize HELM principal"]
        guardian["Guardian decision"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        permit["Effect permit"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["Signed receipt context"]
    end

    %% Operational Flow Edges
    token --> validate
    validate --> normalize
    normalize --> guardian
    guardian --> permit
    permit --> receipt

    %% Premium Styling Rules
    style validate fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style normalize fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style guardian fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style permit fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


---
title: "LangChain Integration"
canonical: "https://helm.docs.mindburn.org/integrations/langchain"
source: "helm-ai-enterprise/docs/public/product/integrations/langchain.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/integrations/langchain.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-04"
checksum_sha256: "sha256:2490bc0417230f6dff4e46eed4ba2d3ca5db2e4ef548e893ee76f34eb9af8f6a"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Integration: LangChain

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

Use HELM as the OpenAI-compatible boundary for LangChain when you want existing chains or agents to keep their framework shape while tool effects are governed, denied, or receipted by HELM.

## Basic Chat

```python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4",
    openai_api_base="http://localhost:9090/v1",
)

response = llm.invoke("Return the current policy status.")
print(response.content)
```

## With A Tool

```python
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI

@tool
def list_workspace_files(path: str) -> str:
    """List files under an allowed workspace path."""
    import os
    return "\n".join(os.listdir(path))

llm = ChatOpenAI(
    model="gpt-4",
    openai_api_base="http://localhost:9090/v1",
).bind_tools([list_workspace_files])

response = llm.invoke("List files in /tmp.")
print(response.content)
```

## Receipt Behavior

LangChain remains responsible for agent orchestration. HELM is responsible for the execution boundary. For governed tool calls, expect:

- input schema validation before execution;
- policy allow, deny, or escalation behavior;
- output validation where the manifest defines it;
- receipt metadata returned through headers, logs, or runtime receipt callbacks;
- a denial reason when the tool, path, budget, or identity is not allowed.

## Failure Modes

| Symptom | Cause | Fix |
| --- | --- | --- |
| LangChain calls the provider directly | `openai_api_base` is not set or a newer adapter option is required | inspect LangChain provider docs and log the request host |
| a Python tool runs locally before HELM sees it | framework executed the local callable in-process | expose tools through the governed gateway or MCP path instead |
| denied tool appears as model confusion | app catches and rewrites HELM denial | preserve denial status, reason code, and receipt ID |
| streaming callback misses receipt metadata | callback only observes text chunks | log final response metadata or runtime receipt callback |

## Source Truth

This page is a framework recipe. Keep endpoint and receipt claims aligned with the OpenAI base URL guide, MCP guide, and runtime tests. When LangChain changes provider option names, update the example rather than adding a custom HELM adapter.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Integration: LangChain"]
        s0["Basic Chat"]
        s1["With A Tool"]
        s3["Failure Modes"]
        output["Reader outcome"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        s2["Receipt Behavior"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> s3
    s3 --> output

    %% Premium Styling Rules
    style s2 fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Operational Readiness

Use this page as the public operating layer for **LangChain Integration**. The source of truth is `helm-ai-enterprise/docs/public/product/integrations/langchain.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "MCP Integration"
canonical: "https://helm.docs.mindburn.org/integrations/mcp"
source: "helm-ai-enterprise/docs/public/product/integrations/mcp.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/integrations/mcp.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-04"
checksum_sha256: "sha256:a9e5db503dbdfe510da36fbeef5f1402ca42b1402fc3f5d84c5706acf22293fc"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Integration: Model Context Protocol

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

HELM can sit in front of MCP-capable tools so agent clients discover tools normally while execution still passes through policy, schema, budget, and receipt controls.

## Discovery

```bash
curl -s http://localhost:8080/mcp/v1/capabilities | jq '.tools[].name'
```

Expected output is a list of governed tools exposed by the active bundle. If the list includes private tools you did not intend to expose, stop and fix the bundle before executing anything.

## Governed Tool Call

```bash
curl -s -X POST http://localhost:8080/mcp/v1/execute \
  -H 'Content-Type: application/json' \
  -d '{"method":"file_read","params":{"path":"/tmp/test.txt"}}' | jq .
```

Expected allowed shape:

```json
{
  "result": "...",
  "receipt_id": "rec_...",
  "reason_code": "ALLOW"
}
```

## Denied Tool Call

```bash
curl -s -X POST http://localhost:8080/mcp/v1/execute \
  -H 'Content-Type: application/json' \
  -d '{"method":"unknown_tool","params":{}}' | jq .
```

Expected denied shape:

```json
{
  "error": {
    "message": "Tool not found: unknown_tool",
    "reason_code": "DENY_TOOL_NOT_FOUND"
  }
}
```

## What HELM Adds

- schema validation for MCP inputs and outputs;
- policy decisions before execution;
- budget and effect-level checks;
- signed receipts and proof graph links;
- replayable evidence for audits;
- explicit deny or escalation semantics instead of silent framework fallback.

## Private MCP Tunnels

Claude Managed Agents private MCP tunnels are supported only when the tunnel
hostname routes to the HELM MCP Gateway. The gateway remains the policy point:
schema pinning, OAuth resource and scope checks, quarantine/rugpull controls,
tool visibility filtering, args hashing, receipt emission, and
`ExecutionBoundaryRecord` binding.

Direct tunnel targets to internal MCP servers are treated as bypass attempts and
must fail closed. Preview evidence for a tunneled call should include the tunnel
domain hash, upstream MCP server ID, OAuth resource, required scopes, protocol
version, CA or certificate reference hash, allowed upstream hostname or CIDR
hash, and the receipt ID for the allowed or denied tool call.

## Failure Modes

| Symptom | Cause | Fix |
| --- | --- | --- |
| capability list is empty | no bundle or MCP gateway not loaded | check runtime logs and active policy bundle |
| unknown tool is allowed | request bypassed HELM or policy is too broad | route through HELM MCP endpoint and tighten bundle |
| no receipt on allowed call | call is discovery-only or not governed | execute through `/mcp/v1/execute` and inspect runtime receipt logs |
| agent sees private tools | manifest exposes too much | reduce tool manifest and rerun discovery |
| managed-agent tunnel bypasses HELM | tunnel points at a raw MCP server | route the tunnel hostname to HELM MCP Gateway and pin the upstream profile |

## Source Truth

This page must stay aligned with the OSS MCP integration and OWASP MCP threat mapping. If MCP protocol details change, update the gateway, examples, and schema references together.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Integration: Model Context Protocol"]
        s0["Discovery"]
        s1["Governed Tool Call"]
        s2["Denied Tool Call"]
        s3["What HELM Adds"]
        output["Reader outcome"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> s3
    s3 --> output

    %% Premium Styling Rules
```


## Operational Readiness

Use this page as the public operating layer for **MCP Integration**. The source of truth is `helm-ai-enterprise/docs/public/product/integrations/mcp.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "OpenAI Base URL Integration"
canonical: "https://helm.docs.mindburn.org/integrations/openai-baseurl"
source: "helm-ai-enterprise/docs/public/product/integrations/openai-baseurl.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/integrations/openai-baseurl.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-04"
checksum_sha256: "sha256:b0328901a3f738f3414f49f74b4686f7e26f4dc844d482b984969280e65f9d27"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Integration: OpenAI Base URL

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

Use this path when an app already uses an OpenAI-compatible client and you want the smallest possible HELM integration. The app keeps the same client library and changes only the base URL so requests cross HELM before the upstream provider.

## Runnable Python Example

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:9090/v1")

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Return the active governance status."}],
)

print(response.choices[0].message.content)
print(response.response.headers.get("X-Helm-Receipt-ID"))
```

Expected response headers on the governed path:

```text
X-Helm-Receipt-ID: rec_...
X-Helm-Output-Hash: sha256:...
X-Helm-Lamport-Clock: ...
```

The exact values are runtime-specific. The required behavior is that the response is linked to a HELM decision and evidence path.

## Runnable TypeScript Example

```ts
import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "http://localhost:9090/v1",
});

const response = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Summarize the active policy." }],
});

console.log(response.choices[0]?.message?.content);
```

## Deny Check

Do not finish setup until you have tested one denied action. Use an unknown tool or a tool argument that the active policy bundle does not allow. A correct setup returns a denial response with a reason code and receipt or decision reference. An allow on an unknown tool means the policy bundle or route is wrong.

## Failure Modes

| Symptom | Cause | Fix |
| --- | --- | --- |
| no `X-Helm-*` headers | request bypassed HELM | log the request host and confirm the client points at HELM |
| provider key error | upstream key is configured on the wrong side of the boundary | follow your deployment model: sidecar-held upstream key or explicit pass-through |
| deny for all calls | identity, policy bundle, or budget gate is missing | inspect denial reason code and load the intended bundle |
| streaming stalls | proxy, client, or upstream does not preserve SSE | test non-streaming first, then check gateway timeout and buffering |

## Source Truth

This guide should stay aligned with `helm-ai-kernel/docs/INTEGRATIONS/openai_baseurl.md`, retained examples under `examples/*openai*baseurl*`, and the runtime proxy implementation. Do not document a header or endpoint here unless the runtime or test suite emits it.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Integration: OpenAI Base URL"]
        s3["Failure Modes"]
        output["Reader outcome"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        s0["Runnable Python Example"]
        s1["Runnable TypeScript Example"]
        s2["Deny Check"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> s3
    s3 --> output

    %% Premium Styling Rules
    style s0 fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style s1 fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style s2 fill:#e53e3e,stroke:#9b2c2c,stroke-width:2px,color:#fff
```


## Operational Readiness

Use this page as the public operating layer for **OpenAI Base URL Integration**. The source of truth is `helm-ai-enterprise/docs/public/product/integrations/openai-baseurl.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "Observability"
canonical: "https://helm.docs.mindburn.org/observability"
source: "helm-ai-enterprise/docs/public/observability/observability.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/observability/observability.md"
section: "helm-ai-enterprise"
access: "public"
sensitivity: "public"
last_reviewed: "2026-02-21"
checksum_sha256: "sha256:3a31079cb38d048c638a859591a39ee97f040bb638c2b088551f6ea7f28a2076"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Observability Templates

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `observability`
- Source document: `helm-ai-enterprise/docs/public/observability/observability.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

## OBS-001: Structured Logging with Trace Correlation

HELM uses Go's `log/slog` for structured logging with OpenTelemetry trace ID correlation.

### Configuration

```go
import (
    "log/slog"
    "go.opentelemetry.io/otel/trace"
)

// Create a handler that adds trace_id to every log entry
type TracedHandler struct {
    slog.Handler
}

func (h *TracedHandler) Handle(ctx context.Context, r slog.Record) error {
    span := trace.SpanFromContext(ctx)
    if span.SpanContext().IsValid() {
        r.AddAttrs(
            slog.String("trace_id", span.SpanContext().TraceID().String()),
            slog.String("span_id", span.SpanContext().SpanID().String()),
        )
    }
    return h.Handler.Handle(ctx, r)
}
```

### Log Fields Convention

| Field | Type | Description |
|-------|------|-------------|
| `trace_id` | string | OpenTelemetry trace ID (auto-injected) |
| `span_id` | string | Span ID within trace |
| `tenant_id` | string | Tenant isolation boundary |
| `decision_id` | string | Guardian decision identifier |
| `receipt_id` | string | Execution receipt reference |
| `tool_id` | string | Tool being executed |
| `latency_ms` | float64 | Operation latency in milliseconds |
| `error` | string | Error message if applicable |

---

## OBS-002: Grafana / Prometheus Overview Templates

### Prometheus Metrics (exposed at `:9090/metrics`)

```yaml
# Guardian decision metrics
helm_guardian_decisions_total{verdict="ALLOW|DENY|ESCALATE"}
helm_guardian_decision_duration_seconds{quantile="0.5|0.9|0.99"}

# Executor metrics
helm_executor_tool_calls_total{tool_id, status="ok|error"}
helm_executor_tool_duration_seconds{tool_id}

# ProofGraph metrics
helm_proofgraph_nodes_total{type="DECISION|EXECUTION|EVIDENCE"}
helm_proofgraph_chain_length

# Budget metrics
helm_budget_remaining{tenant_id}
helm_budget_consumed_total{tenant_id, tool_id}

# Evidence metrics
helm_evidence_packs_exported_total
helm_evidence_verification_total{result="pass|fail"}
```

### Grafana Overview JSON (import via Grafana UI)

Save as `grafana-helm-overview.json` and import:

```json
{
  "overview": {
    "title": "HELM Kernel Overview",
    "panels": [
      {
        "title": "Decision Throughput",
        "type": "timeseries",
        "targets": [{"expr": "rate(helm_guardian_decisions_total[5m])"}]
      },
      {
        "title": "Decision Latency (p99)",
        "type": "gauge",
        "targets": [{"expr": "histogram_quantile(0.99, helm_guardian_decision_duration_seconds)"}]
      },
      {
        "title": "Tool Call Rate by Tool",
        "type": "timeseries",
        "targets": [{"expr": "rate(helm_executor_tool_calls_total[5m])"}]
      },
      {
        "title": "Error Budget Remaining",
        "type": "gauge",
        "targets": [{"expr": "helm_budget_remaining"}]
      },
      {
        "title": "ProofGraph Growth",
        "type": "timeseries",
        "targets": [{"expr": "helm_proofgraph_nodes_total"}]
      },
      {
        "title": "Evidence Verification Success Rate",
        "type": "stat",
        "targets": [{"expr": "helm_evidence_verification_total{result='pass'} / helm_evidence_verification_total"}]
      }
    ]
  }
}
```

### AlertManager Rules

```yaml
groups:
  - name: helm-kernel
    rules:
      - alert: GuardianLatencyHigh
        expr: histogram_quantile(0.99, helm_guardian_decision_duration_seconds) > 0.005
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Guardian p99 latency exceeds 5ms SLA"

      - alert: BudgetExhausted
        expr: helm_budget_remaining < 20
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Error budget below 20% — builder/promotion gates activated"

      - alert: EvidenceVerificationFailure
        expr: rate(helm_evidence_verification_total{result="fail"}[5m]) > 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Evidence pack verification failures detected — potential tampering"
```

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Observability Templates"]
        s0["OBS-001: Structured Logging with Trace Correlation"]
        s1["OBS-002: Grafana / Prometheus Overview Templates"]
        output["Reader outcome"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> output

    %% Premium Styling Rules
```


## Operational Readiness

Use this page as the public operating layer for **Observability**. The source of truth is `helm-ai-enterprise/docs/public/observability/observability.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "HELM Operator Guide"
canonical: "https://helm.docs.mindburn.org/operations/operator-guide"
source: "helm-ai-enterprise/docs/public/operations/operator-guide.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/operations/operator-guide.md"
section: "helm-ai-enterprise"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:c3394d1736c9d25439ee53baeaac5bbd68a02b88687b8e4389d0e120d4817294"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM Operator Guide

This page summarizes the public-safe operational material for HELM AI Enterprise.
It links the public docs site to the source documents under `docs/operations/`
without publishing credentials, customer-specific inventory, or private incident
details.

## Audience

Use this page if you operate HELM, evaluate deployment readiness, review backup
and restore posture, or need to understand promotion, rollback, and SLO
mechanics.

## Outcome

You should know the operator workflow, which source docs own each procedure, and
which checks to run before promotion or recovery.

## Operator Flow

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        inventory["Deployment inventory"]
        baseline["Baseline infrastructure"]
        deploy["Deploy / migrate"]
        observe["SLOs and perf budgets"]
        recover["Backup, restore, rollback"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        verify["Production verification"]
    end

    %% Operational Flow Edges
    inventory --> baseline
    baseline --> deploy
    deploy --> verify
    verify --> observe
    observe --> recover

    %% Premium Styling Rules
    style verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Canonical Release Readiness

Use the repository root as the release gate entrypoint for the active backend:

```bash
make release-readiness
docker compose up -d postgres helm-ai-enterprise helm-ai-enterprise-console
curl -fsS http://localhost:8080/health/live
curl -fsS http://localhost:8080/health/ready
```

What this verifies:

- `make release-readiness` runs the canonical Go tests for `core`, `commercial`, and `apps/controlplane`, the JS workspace typecheck/lint/test/build set, boundary verification, and documentation truth checks.
- `docker compose up -d postgres helm-ai-enterprise helm-ai-enterprise-console` exercises the local controlplane runtime path only.
- `/health/live` confirms process liveness; `/health/ready` confirms readiness before promotion or rollback decisions.

## Operational Domains

| Domain | Source truth | Public purpose |
| --- | --- | --- |
| Deployment inventory | `docs/operations/DEPLOYMENT_INVENTORY.md` | Track services, dependencies, and ownership. |
| Baseline infrastructure | `docs/operations/DROPLET_BASELINE.md`, `docs/operations/TERRAFORM.md` | Explain infrastructure baseline and IaC expectations. |
| Deployment and chart | `docs/operations/DEPLOY_RUNBOOK.md`, `docs/operations/HELM_CHART.md` | Describe rollout prerequisites and Kubernetes chart operation. |
| Migration and versioning | `docs/operations/MIGRATIONS.md`, `docs/operations/VERSIONING.md` | Keep data and API changes ordered. |
| Promotion | `docs/operations/PROMOTION_RULES.md`, `docs/operations/PROD_VERIFICATION.md` | Define release promotion and verification checks. |
| Observability | `docs/operations/slos.md`, `docs/operations/PERF_BUDGETS.md`, `docs/public/observability/observability.md` | Explain service health and budget enforcement. |
| Recovery | `docs/operations/DR_RESTORE.md`, `docs/operations/RESTORE_DRILL.md`, `docs/operations/runbooks/ROLLBACK.md` | Prepare backup, restore, and rollback paths. |

## Public-Safe Boundary

The docs site exposes operational concepts, checks, and source links. It does
not publish secrets, private inventory values, customer-specific incident data,
or active credentials. When a source runbook contains environment-specific
material, the public page summarizes the invariant and points operators back to
their controlled repository access.

## Source Truth

- `docs/operations/README.md`
- `docs/operations/PROMOTION_RULES.md`
- `docs/operations/PROD_VERIFICATION.md`
- `docs/operations/DR_RESTORE.md`
- `docs/operations/runbooks/ROLLBACK.md`
- `docs/public/observability/observability.md`

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Release cannot promote | Confirm promotion rules, SLO state, and production verification results. |
| Migration order is unclear | Review `MIGRATIONS.md` and versioning policy before applying. |
| Restore path is uncertain | Run the restore drill against controlled non-production data first. |
| Runtime is healthy but evidence is missing | Check observability, tracing, and receipt index materialization. |
| A duplicate backend or standalone proof service reappears in CI or docs | Run `make docs-truth` and `bash scripts/ci/22_console_unification_guard.sh`; the gates block split Console surfaces. |

## Operational Readiness

Use this page as the public operating layer for **HELM Operator Guide**. The source of truth is `helm-ai-enterprise/docs/public/operations/operator-guide.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "Platform & DevOps"
canonical: "https://helm.docs.mindburn.org/platform"
source: "helm-ai-enterprise/docs/public/platform-landing.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/platform-landing.md"
section: "platform"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-13"
checksum_sha256: "sha256:aa44bfdedfd06b437a78b4731d4f49147e75180ad5ae529b97e062e11a98ad4a"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Platform & DevOps

This page gives the direct path to HELM deployment, operations, and runtime lifecycle references. The goal is to answer **what to change first: source docs, ops procedures, or boundary routing** before touching production behavior.

## Audience

- SRE and platform engineers operating HELM environments
- Developers planning deployment targets and CI/CD topology
- Release engineers maintaining release gates and rollout controls
- Product operators handling incidents and verification workflows
- Security reviewers checking observable evidence in production

## Outcome

After using this page you should be able to:

- find the correct operational playbooks for day-1 and day-2 activities,
- map deployment and observability guidance to source-owned docs,
- distinguish OSS deployment guidance from Commercial deployment and operational guidance,
- and resolve documentation gaps without guessing platform ownership.

## Mermaid

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Source["HELM Source Materials"]
        Build["Validation + CI/CD"]
        Deploy["Deployment Surfaces"]
        Incident["Incident Response"]
        OSS["HELM AI Kernel"]
        Commercial["HELM AI Enterprise"]
        Operator["Operator Guide"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Run["Runtime / Operations"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Observe["Observability + Evidence"]
    end

    %% Operational Flow Edges
    Source --> Build
    Build --> Deploy
    Deploy --> Run
    Run --> Observe
    Observe --> Incident
    OSS --> Build
    OSS --> Deploy
    Commercial --> Deploy
    Commercial --> Operator

    %% Premium Styling Rules
    style Run fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Observe fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Source Truth

- `docs/08_DEPLOYMENT.md`
- `docs/operations/**`
- `deploy/**`
- `infra/**`
- `docs/platform/**`
- `docs/release/**`

Update these source paths before changing route mapping in this landing page.

## Deployment and environment guidance

- Deployment guide source: `docs/08_DEPLOYMENT.md` — recommended deployment patterns and environment considerations.
- Commercial deployment source: `docs/COMMERCIAL_DEPLOY.md` — production deployment guidance for HELM AI Enterprise environments.
- Helm chart source: `deploy/helm-chart/` — Helm chart usage and chart-level configuration.
- [Kubernetes Deployment](/helm-ai-kernel/deployment/kubernetes) — Kernel Kubernetes manifests and topology.
- Deployment inventory source: `docs/operations/DEPLOYMENT_INVENTORY.md` — deployed service and port inventory.

## Operations and runtime operations

- Operations runbook source: `docs/operations/DEPLOY_RUNBOOK.md` — day-2 operations, health checks, and maintenance.
- Operator runbook source: `docs/operations/OPERATOR_RUNBOOK.md` — operator procedures and escalation paths.
- [Operator Guide](/operations/operator-guide) — enterprise operator-facing operational manual.
- [Observability](/observability) — logs, metrics, tracing, and alerts.
- [Tracing](/tracing) — trace setup and operational interpretation.

## Configuration, CI/CD, and release

- Configuration source: `docs/operations/CONFIGURATION.md` — runtime environment variables and feature flags.
- CI/CD pipeline source: `.github/workflows/` — continuous integration and deployment pipeline.
- Quality gates source: `Makefile` and `scripts/` — checks required before release.
- Release process source: `RELEASE_NOTES.md` and release workflow files — versioning, release coordination, and rollout practices.

## Kernel vs HELM AI Enterprise boundaries (explicit)

- Kernel documentation should carry canonical deployment semantics that remain portable across contexts and are used as base expectations for environment setup and validation.
- HELM AI Enterprise documentation should capture production packaging, entitlement-sensitive operations, and enterprise-level support flows.
- Use this rule when splitting a topic:
  - if a topic describes protocol-neutral deployment mechanics, keep it OSS,
  - if a topic encodes commercial operational policy or customer-specific process, classify it Commercial.
- Deployment target pages can still link to each other, but ownership should remain explicit and stable.

## Troubleshooting

- If a deployment question has no answer in OSS docs, check the corresponding Commercial deployment page before adding new behavior.
- If a CI/CD change is not reflected in release docs, align it first with `RELEASE_NOTES.md`, `Makefile`, and the relevant workflow.
- If an on-call issue appears in runtime but not in operators materials, start with `docs/operations/DEPLOY_RUNBOOK.md`, then `docs/operations/OPERATOR_RUNBOOK.md`.
- If source coverage checks report missing public mapping for deployment files, update the source mapping references used by this page before merging.
- If observability dashboards are inconsistent across environments, compare `/observability` and `/tracing` with the deployment topology for the exact environment.

## Adoption flow for production changes

1. Identify whether the change is OSS infrastructure semantics or Commercial operational policy.
2. Update the owning source file (`deploy/**`, `infra/**`, `docs/operations/**`, or `docs/08_DEPLOYMENT.md`) first.
3. Update this landing page routes to match the source classification immediately after review.
4. Confirm that troubleshooting paths still lead to the correct operator route and add missing cross-links if needed.


---
title: "HELM Console"
canonical: "https://helm.docs.mindburn.org/product/console"
source: "helm-ai-enterprise/docs/public/product/console.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/console.md"
section: "helm-ai-enterprise"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:75a9298af385af636aa5c4cd9ade82d961dd85cdb3bb1d3f10f9cca5ba17c0d8"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM Console

HELM Console is the commercial workspace surface for importing tool surfaces,
drafting and activating policy, reviewing governed runs, replaying evidence, and
exporting self-hostable bundles. This page is the public docs entry point for the
source material under `docs/console/`.

## Audience

Use this page if you are evaluating HELM AI Enterprise, designing a Console-backed
workflow, or operating the hosted/control-plane deployment.

## Outcome

You should understand the Console surfaces, the data flow from connector import
to policy activation, and the source documents that back each behavior.

## Console Lifecycle

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        import["Import MCP / OpenAPI surface"]
        graph["Build Tool Surface Graph"]
        draft["draft"]
        compile["Compile canonical bundle"]
        export["Export workspace bundle"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        run["Run governed workflow"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        replay["Replay receipts"]
    end

    %% Operational Flow Edges
    import --> graph
    draft --> compile
    compile --> run
    run --> replay
    replay --> export

    %% Premium Styling Rules
    style run fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style replay fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Public Console Surfaces

| Surface | Source truth | What to read |
| --- | --- | --- |
| Product boundary | `docs/console/PRODUCT_BOUNDARY.md` | What is OSS, hosted, public verification, and enterprise-only. |
| Run lifecycle | `docs/console/RUN_LIFECYCLE.md` | How a workspace moves through import, policy, run, receipt, replay, and export. |
| Replay and receipts | `docs/console/REPLAY_AND_RECEIPTS.md` | How Console exposes receipt review and replay evidence. |
| Workstation governance | `docs/console/WORKSTATION_GOVERNANCE.md` | How local agent receipts, denied effects, memory writes, and loops appear in Console. |
| Deployment architecture | `docs/console/DEPLOYMENT_ARCHITECTURE.md` | How Console fits into the enterprise control plane and deployment topology. |
| Export format | `docs/console/EXPORT_FORMAT.md` | What a self-host export contains. |
| Security model | `docs/console/SECURITY_MODEL.md` | Workspace isolation, evidence handling, and policy boundaries. |
| Execution scenarios | `docs/console/EXECUTION_SCENARIOS.md` | Production verification fixtures and evaluator flows. |
| OSS vs hosted | `docs/console/OSS_VS_HOSTED.md` | Boundary between the OSS kernel and hosted Console capability. |

## Control Plane Boundary

Console is not the policy kernel. The kernel remains responsible for governed
execution, receipts, verification, and evidence. Console provides workspace UX,
import surfaces, policy authoring, replay views, and export flows around that
kernel.

## Source Truth

- `docs/console/PRODUCT_BOUNDARY.md`
- `docs/console/RUN_LIFECYCLE.md`
- `docs/console/REPLAY_AND_RECEIPTS.md`
- `docs/console/WORKSTATION_GOVERNANCE.md`
- `docs/console/DEPLOYMENT_ARCHITECTURE.md`
- `docs/console/SECURITY_MODEL.md`
- `docs/COMMERCIAL_OVERVIEW.md`

## Troubleshooting

| Symptom | Check |
| --- | --- |
| A workspace import does not show expected tools | Review the Tool Surface Graph import path and connector manifest. |
| A policy draft cannot activate | Check compile diagnostics, bundle hash, and required approvals. |
| Replay evidence is missing | Check receipt index materialization and export-bundle storage. |
| An evaluator asks whether a feature is OSS or hosted | Use `docs/console/OSS_VS_HOSTED.md` and `docs/console/PRODUCT_BOUNDARY.md`. |

## Operational Readiness

Use this page as the public operating layer for **HELM Console**. The source of truth is `helm-ai-enterprise/docs/public/product/console.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "Console API"
canonical: "https://helm.docs.mindburn.org/product/console-api"
source: "helm-ai-enterprise/docs/public/product/console-api.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/console-api.md"
section: "teams"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:f8491998ec58ffc5682f7401cfef6e248799fe750cda3c46d1e4c5570a4a5d58"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Operator Console API

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `product/console-api`
- Source document: `helm-ai-enterprise/docs/public/product/console-api.md`
- Control-plane router: `apps/controlplane/internal/http/router.go`
- Console route registry: `apps/controlplane/internal/console/route_registry.go`
- Console handler mount: `apps/controlplane/internal/console/facade.go`
- OpenAPI source: `api/openapi/helm.openapi.yaml`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `go test ./apps/controlplane/internal/http ./apps/controlplane/internal/console`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

The HELM Operator Console uses `apps/controlplane` as its single browser API backend. All endpoints require authenticated session authority unless explicitly listed as public. The canonical Console route registry is `apps/controlplane/internal/console/route_registry.go`; this page is a public summary, not a second contract.

## Authentication

Session, refresh, reauth, and WebAuthn ceremony endpoints live under `/api/auth/*`. Workspace-scoped routes derive tenant and workspace authority on the server. Public proof routes bypass private session context only when they return redaction-safe metadata.

## Console/API Matrix

| Class | Route family | Source owner | Auth |
| --- | --- | --- | --- |
| Health | `/health`, `/health/live`, `/health/ready` | `internal/http/router.go` | Public |
| Auth and session | `/api/auth/*`, `/api/session` | `internal/auth`, `internal/platform` | Session, except WebAuthn login begin/finish |
| Bootstrap and workspaces | `/api/bootstrap*`, `/api/workspaces*`, `/api/entitlements` | `internal/platform` | Session |
| Console canonical API | `/api/v1/workspaces*`, `/api/v1/marketplace/connectors*` | `internal/console/route_registry.go` | Session |
| Public verification | `/api/v1/signing-key`, `/api/v1/verify`, `/api/v1/replays*`, `/api/public/*` | `internal/console`, `internal/platform`, `internal/runtime` | Public, redacted, read-only |
| Ops and connector drift | `/api/ops*`, `/api/connectors*` | `internal/ops` | Session |
| Billing and audit | `/api/billing*`, `/api/audit*` | `internal/billing`, `internal/audit` | Session; tenant path routes enforce tenant match |
| WebSocket hints | `/ws/console`, `/ws/telemetry` | `internal/ws` | Deployment/session dependent |

## Endpoint Reference

### Health And Session

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| GET | `/health` | Process health | Public |
| GET | `/health/live` | Liveness check | Public |
| GET | `/health/ready` | Readiness check including required dependencies | Public |
| GET | `/api/auth/session` | Current authenticated browser session | Session |
| POST | `/api/auth/refresh` | Rotate persisted session | Session |
| POST | `/api/auth/reauth` | Create a short-lived reauth grant | Session |
| POST | `/api/auth/webauthn/register/begin` | Begin WebAuthn registration ceremony | Session |
| POST | `/api/auth/webauthn/register/finish` | Finish WebAuthn registration ceremony | Session |
| POST | `/api/auth/webauthn/login/begin` | Begin WebAuthn login ceremony | Public |
| POST | `/api/auth/webauthn/login/finish` | Finish WebAuthn login ceremony | Public |

### Public Proof And Replay

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| GET | `/api/public/verify/{receiptId}` | Verify a public-safe receipt reference | Public |
| GET | `/api/public/evidence/{bundleId}` | Read redacted evidence bundle metadata | Public |
| GET | `/api/public/approval/{approvalId}` | Read public approval metadata | Public |
| GET | `/api/v1/signing-key` | Publish the receipt verification signing key | Public |
| POST | `/api/v1/verify` | Verify a receipt payload | Public |
| GET | `/api/v1/replays` | List published replay manifests | Public |
| GET | `/api/v1/replays/{id}` | Read one published replay manifest | Public |

### Workspace And Operator State

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| GET/POST | `/api/workspaces` | Control-plane workspace list/create used during bootstrap | Session |
| GET/POST | `/api/bootstrap/*` | Workspace bootstrap and activation progress | Session |
| GET | `/api/snapshot` | Authoritative Console snapshot | Session |
| GET/POST/DELETE | `/api/v1/workspaces*` | Console workspace CRUD, runs, approvals, tools, policy, tasks, actions, channels, skills, knowledge, evidence, legal holds, and jurisdictions | Session |

### Packs, Marketplace, Ops, And Billing

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| GET/POST/DELETE | `/api/packs*` | Pack listing, verification, install planning, install, and removal | Session |
| GET/POST | `/api/registry*` | Registry compatibility paths backed by controlplane pack handlers | Session |
| GET/POST | `/api/ops*` | Incidents, plans, blast radius, freeze, throttle, resume, quarantine, and resync | Session |
| GET/POST | `/api/connectors*` | Connector drift, shim list, and shim activation | Session |
| GET/POST | `/api/billing*` | Plans, usage, budget, and overview | Session with tenant path check |
| GET/POST | `/api/audit*` | Audit bundle, evidence pack, and verification endpoints | Session |
| GET/POST | `/api/v1/marketplace/connectors*` | Canonical connector marketplace routes | Session |

### Console Route Registry Areas

| Area | Routes | Notes |
| --- | --- | --- |
| `workspaces` | create, list, get, delete | Workspace IDs are path-scoped. |
| `runs` | submit, list, get | Run records include plan, policy, verdict, receipt, and evidence fields. |
| `approvals` | list, get, resolve | Approval records become evidence; they do not grant execution outside policy. |
| `tools` and `policy` | import tools, draft/compile/activate/read policy | Policy activation must remain auditable. |
| `workstation` | receipt import, run list, run detail, denied timeline, memory review, loop registry | Workstation routes store parsed receipts and selected-effect decisions, not raw chat history. |
| `tasks`, `actions`, `channels` | task control, action decisions, collaboration sessions | Operator workflow surfaces. |
| `skills` and `knowledge` | candidate review, promotion/rejection, claim review | Governance review surfaces. |
| `evidence`, `legal-holds`, `jurisdictions` | evidence packs, replay, legal holds, jurisdiction list | Retention and export-sensitive surfaces. |
| `marketplace` | connector read/install/disable | Activation remains authorization-protected. |

## Error Responses

Canonical Console `/api/v1/*` handlers return JSON errors with this shape:

```json
{
  "error": "detail",
  "message": "operator-safe summary",
  "code": 400
}
```

| Code | Meaning |
|------|---------|
| 400 | Bad Request — invalid parameters |
| 401 | Unauthorized — missing or invalid token |
| 403 | Forbidden — insufficient permissions |
| 404 | Not Found — resource does not exist |
| 405 | Method Not Allowed |
| 429 | Too Many Requests |
| 500 | Internal Server Error |

Some compatibility handlers still use Go `http.Error` until they are converted. Do not document a route as fully canonical unless it is covered by the controlplane route registry and route-contract tests.

## Redaction Boundary

Public Console API examples may include route names, sample IDs, receipt IDs, bundle IDs, hashes, public signing keys, and verification statuses. They must not include session cookies, customer payloads, provider credentials, private signing keys, raw evidence bundle contents, or production database URLs.

Public proof routes are read-only. Workspace, ops, billing, audit, and marketplace mutation routes require session authority and should not be presented as public integration endpoints.

## Contract Rule

New Console capability work must be added to `apps/controlplane`, reflected in `apps/controlplane/internal/console/route_registry.go` when it is part of the Console `/api/v1` surface, consumed through the canonical frontend API client layer, and covered by route-contract tests. Do not reintroduce a second browser backend or undocumented public proof surface.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Operator Console API"]
        auth["Session and WebAuthn"]
        snapshot["Authoritative Snapshot"]
        ops["Governed Ops"]
        controlplane["apps/controlplane"]
        registry["Route Registry and Contract Tests"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        proof["Public Proof"]
    end

    %% Operational Flow Edges
    source --> auth
    source --> snapshot
    source --> proof
    source --> ops
    auth --> controlplane
    snapshot --> controlplane
    proof --> controlplane
    ops --> controlplane
    controlplane --> registry

    %% Premium Styling Rules
    style proof fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


---
title: "HELM Design System"
canonical: "https://helm.docs.mindburn.org/product/design-system"
source: "helm-ai-enterprise/docs/public/product/design-system.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/design-system.md"
section: "helm-ai-enterprise"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:39d8e15aee058208102d2d9d829c6320e884b40dbace74e8ef79d579f0376cab"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM Design System

This page maps the HELM AI Enterprise design-system and UI package family to the
public docs site. It covers tokens, primitives, accessibility, package adoption,
and the handoff boundary between Console proof, operator, and product
surfaces.

## Audience

Use this page if you implement HELM UI, review accessibility or visual
regressions, adopt the design-system packages, or need to understand how UI
source material is documented publicly.

## Outcome

You should know which package owns each design-system surface, which source docs
back the public guidance, and how UI changes are validated before release.

## Package Flow

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        core["@mindburn/ui-core"]
        helm["@mindburn/helm-ai-enterprise-design-system"]
        apps["HELM Console"]
        tests["visual, a11y, package tests"]
        docs["Public docs and handoff"]
    end

    %% Operational Flow Edges
    core --> helm
    helm --> apps
    apps --> tests
    tests --> docs

    %% Premium Styling Rules
```


## Source Families

| Source family | Purpose | Public handling |
| --- | --- | --- |
| `../helm-ai-kernel/packages/design-system-core/` | Canonical OSS-safe tokens, shared components, forms, layout, data display, feedback, inspection, i18n, theme provider, and tests. | Covered by this page and `helm-ai-kernel/docs/design-system/`. |
| `packages/helm-ai-enterprise-design-system/` | HELM-specific policy routes, components, state, handoff readiness, and styles. | Covered by this page and Console/product docs. |
| `packages/design-tokens/` | Deprecated compatibility shim that imports core-owned token CSS for one migration window. | Inventory only; not a canonical source. |
| `docs/design-system-package/` | Architecture, theming, accessibility, release, semver, CI gates, primitive coverage, adoption, and decisions. | Summarized here; source remains the detailed reference. |
| `docs/ui/` | Product UI specifications, flows, evidence UX, operator guide, and IA. | Covered here and by Console/product pages. |

Active package names are `@mindburn/ui-core` and `@mindburn/helm-ai-enterprise-design-system`. `@mindburn/helm-ai-enterprise-design-tokens` is deprecated compatibility only; new code must not depend on it.

## Validation

Run the relevant package and browser checks for UI changes:

```bash
corepack pnpm run docs:coverage
corepack pnpm run docs:truth
corepack pnpm run test
corepack pnpm run test:e2e
```

For docs-site changes, run `npm run validate`, `npm run test:smoke`, and
`npm run test:a11y` in `docs-platform`.

## Source Truth

- `docs/design-system-package/README.md`
- `docs/design-system-package/accessibility.md`
- `docs/design-system-package/architecture.md`
- `docs/design-system-package/ci-gates.md`
- `docs/design-system-package/theming.md`
- `docs/ui/README.md`
- `../helm-ai-kernel/packages/design-system-core/README.md`
- `packages/helm-ai-enterprise-design-system/README.md`
- `packages/design-tokens/README.md`

## Troubleshooting

| Symptom | Check |
| --- | --- |
| UI package behavior changed but docs did not | Update this page or the relevant package README and rerun docs truth. |
| Accessibility behavior regresses | Check package tests plus `docs/design-system-package/accessibility.md`. |
| Token output differs between apps | Verify `@mindburn/ui-core` token source files and package export paths before changing app CSS. |
| Console proof UI looks undocumented | Map the route through `docs/ui/` and `docs/console/` before adding public copy. |

## Operational Readiness

Use this page as the public operating layer for **HELM Design System**. The source of truth is `helm-ai-enterprise/docs/public/product/design-system.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "EU AI Act High-Risk Readiness"
canonical: "https://helm.docs.mindburn.org/product/eu-ai-act-high-risk"
source: "helm-ai-enterprise/docs/public/product/eu-ai-act-high-risk.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/eu-ai-act-high-risk.md"
section: "helm-ai-enterprise"
access: "public"
sensitivity: "public"
last_reviewed: "2026-04-30"
checksum_sha256: "sha256:da502341761c415b85e86618b75efc9e2ef08270800d1527391d4583424c3824"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# EU AI Act High-Risk Readiness

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `product/eu-ai-act-high-risk`
- Source document: `helm-ai-enterprise/docs/public/product/eu-ai-act-high-risk.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

HELM AI Enterprise should lead compliance positioning with the EU AI Act high-risk timeline. The current European Commission Service Desk timeline lists 2026-08-02 for Annex III high-risk rules and Article 50 transparency rules to enter into application, with 2027-08-02 for high-risk systems embedded in regulated products. The Commission has proposed timeline adjustments tied to support tools and standards, so customer-facing copy should describe the 2026 date as the current application trajectory.

## Sales Message

HELM gives regulated AI operators a runtime receipt for every governed action:

- Article 9 risk management: policies encode action ceilings, escalation rules, and fail-closed controls before execution.
- Article 11 technical documentation: evidence exports describe which policy, principal, model, tool, and state snapshot governed an action.
- Article 12 record keeping: ProofGraph records the causal chain and receipt hash for agent decisions.
- Article 14 human oversight: approval ceremonies, override paths, and autonomy levels make human control visible.
- Article 50 transparency support: source and generation context can be attached to receipts when basic use HELM-proxied workflows.

## Discovery Questions

- Which AI workflows make or materially influence decisions in employment, credit, education, health, public services, migration, law enforcement, or critical infrastructure?
- Which actions can create external side effects, irreversible changes, or regulated communications?
- Where is human review required today, and where is it informal or undocumented?
- Which logs would an auditor need to replay a decision six months later?
- Which model, tool, connector, or policy changes should trigger a new approval route?

## Evidence HELM Can Produce

| Need | HELM artifact |
| --- | --- |
| Point-in-time action record | Receipt with principal, action, verdict, reason code, and hashes |
| Human oversight proof | Approval ceremony record and autonomy level |
| Risk management proof | Policy envelope, Guardian verdict, and escalation route |
| Technical documentation | Evidence bundle and compliance report export |
| Replay support | ProofGraph chain plus referenced state hashes |

## HELM AI Kernel Evidence Pack Dependency

This HCOM guide depends on the HELM AI Kernel EU AI Act reference pack and MCP governance implementation. The paired HELM AI Kernel lane verified the high-risk evidence pack shape and added MCP OAuth resource/scope enforcement so tool execution can be tied to a specific resource audience and required scopes before Guardian receives the decision request.

Sales use:

- Use the reference pack as the artifact checklist for regulated workflow discovery.
- Use MCP resource and scope enforcement as the technical proof point for action-level access control.
- Use ProofGraph and receipt exports as the customer-facing audit record.

Do not represent the pack as legal advice or as a complete conformity assessment. It is an evidence scaffold for counsel, compliance basic, and auditors.

## Colorado Positioning

Colorado remains worth monitoring, but it should not lead the HCOM urgency story. SB25B-004 moved SB24-205 requirements to 2026-06-30, and a March 2026 workgroup proposal would replace the law with an ADMT-focused framework effective 2027-01-01 if enacted. Use Colorado as a state-profile example for runtime records, human review, and ADMT audit support. Do not present the proposed ADMT framework as final law.

## Source Notes

- European Commission AI Act Service Desk timeline: <https://ai-act-service-desk.ec.europa.eu/en/ai-act/timeline/timeline-implementation-eu-ai-act>
- European Commission AI Act policy page: <https://digital-strategy.ec.europa.eu/en/policies/regulatory-framework-ai>
- Colorado General Assembly SB25B-004: <https://leg.colorado.gov/bills/sb25b-004>
- Cooley state AI laws update, 2026-04-24: <https://www.cooley.com/news/insight/2026/2026-04-24-state-ai-laws-where-are-they-now>
- HELM AI Kernel reference pack: `reference_packs/eu_ai_act_high_risk.v1.json`

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        usecase["High-risk use case"]
        control["Control mapping"]
        approval["Human oversight"]
        pack["Compliance pack"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        policy["Policy bundle"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["Receipt evidence"]
    end

    %% Operational Flow Edges
    usecase --> control
    control --> policy
    control --> approval
    control --> receipt
    receipt --> pack
    approval --> pack
    policy --> pack

    %% Premium Styling Rules
    style policy fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


---
title: "HELM Launchpad App Store"
canonical: "https://helm.docs.mindburn.org/product/launchpad"
source: "helm-ai-enterprise/docs/public/product/launchpad.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/launchpad.md"
section: "helm-ai-enterprise"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-19"
checksum_sha256: "sha256:a2bb24e9de90adad30ad1a4b7e29f7c2f8469fcb383c890d0135adaa0dd0ed1b"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM Launchpad App Store

HELM Launchpad is a workspace-scoped app store for governed app launches in the Enterprise Console.

## Audience

This page is for Enterprise operators, platform teams, and evaluators who need
to understand which Launchpad routes, approvals, policy packs, audit exports,
and EvidencePack exports back the Console app-store surface.

## Outcome

You should leave with the Enterprise Launchpad gate model, workspace API
surface, approval defaults, retention defaults, and promotion rule for moving
apps from catalog candidates to governed execution.

## Source Truth

- Console routes: `apps/controlplane/internal/console/launchpad_routes.go`
- Launch lifecycle service: `apps/controlplane/internal/console/launchpad_service.go`
- Durable run store: `apps/controlplane/internal/console/launchpad_store.go`
- Catalog migration: `apps/controlplane/migrations/006_launchpad_app_store.up.sql`
- Route/OpenAPI parity: `apps/controlplane/internal/console/route_registry.go` and `api/openapi/helm.openapi.yaml`
- Kernel evidence source: `helm-ai-kernel/docs/launchpad/final_report.json` and `helm-ai-kernel/docs/launchpad/v1_report.json`

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        catalog["Workspace catalog"]
        revoke["Revoke/delete"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        plan["Plan LaunchRun"]
        execute["Execute gate"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        approval["Approval receipt"]
        audit["Audit and EvidencePack refs"]
        teardown["Teardown receipt"]
        export["Tenant audit / EvidencePack export"]
    end

    %% Operational Flow Edges
    catalog --> plan
    plan --> approval
    approval --> execute
    execute --> audit
    execute --> revoke
    revoke --> teardown
    audit --> export

    %% Premium Styling Rules
    style plan fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style approval fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style execute fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style audit fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style teardown fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style export fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


Strict GA behavior is fail-closed:

- Planning creates a durable LaunchRun, GeneratedSpec, ActionProposal, approval request, retention ref, receipt refs, and EvidencePack refs.
- Execution requires an approved approval receipt, kernel `ALLOW`, certification refs, retention refs, provider readiness, and offline-verifiable EvidencePacks.
- DigitalOcean and Hetzner are dry-run by default. Live cloud mode requires explicit operator approval, provider secrets, idempotency reconciliation, and teardown receipts.
- OpenClaw, Hermes, OpenCode, and Kilo Code are kernel `oss_supported` for signed local-container Launchpad execution after workflow `26198407296` produced signed image refs, conformance evidence, teardown receipts, and offline-verifiable EvidencePacks.
- Codex, Claude Code, Cursor, and Junie are governed BYO adapters unless separate license/vendor/install/cloud certification passes.
- `local-container` is a Docker baseline for trusted developer workloads, not a hostile-code isolation claim. Hardened tiers are explicit: Docker rootless/userns, Docker ECI, gVisor, Kata/Firecracker, or dedicated VM.
- OpenRouter egress receipts prove CONNECT destination allowlisting. CONNECT payload contents are opaque unless a token-broker or model-gateway inspection mode is enabled.
- WebSocket MCP is not a supported Launchpad transport; advertised MCP paths must be covered by mediation proof tests before publication.

## API Surface

Workspace routes:

- `GET /api/v1/workspaces/{id}/launchpad/apps`
- `GET /api/v1/workspaces/{id}/launchpad/substrates`
- `GET /api/v1/workspaces/{id}/launchpad/matrix`
- `POST /api/v1/workspaces/{id}/launchpad/plan`
- `POST /api/v1/workspaces/{id}/launchpad/launch`
- `GET /api/v1/workspaces/{id}/launchpad/launches`
- `GET /api/v1/workspaces/{id}/launchpad/launches/{launch_id}`
- `POST /api/v1/workspaces/{id}/launchpad/launches/{launch_id}/execute`
- `POST /api/v1/workspaces/{id}/launchpad/launches/{launch_id}/repair`
- `POST /api/v1/workspaces/{id}/launchpad/launches/{launch_id}/delete`
- `POST /api/v1/workspaces/{id}/export`
- `POST /api/v1/workspaces/{id}/evidence/export`

Execute responses include approval refs, certification ref, retention ref, runtime handles, provider resource refs, redaction profile, and install mode when execution reaches `RUNNING`. Gate failures return `409` with blocked reasons and the updated launch state.

Audit export returns a redacted machine-readable launch record: workspace, app/substrate, state, policy verdict, approval refs, signed receipt refs, EvidencePack refs, retention ref, provider resource refs, and redaction profile. Evidence export returns receipt refs, EvidencePack refs, and the exact `helm-ai-kernel verify --bundle <pack>` command for offline proof.

## Approval Defaults

Launchpad maps app execution to an approval tier before any side effect runs:

- T0 plan, catalog, matrix, and evidence inspection routes are read-only and need no approval.
- T1 local-container launch requires a workspace operator approval receipt.
- T2 model egress, MCP side effects, or privileged local access require workspace admin approval.
- T3 cloud launch, public egress, or cost exposure requires tenant admin approval plus a cost ceiling receipt.
- T4 destructive repair, revoke, or force teardown requires dual control from tenant admin and security/admin roles.

Approval records carry tenant ID, workspace ID, requesting principal, approval principal, risk tier, app, substrate, policy verdict, receipt refs, EvidencePack refs, retention policy, and revoke/delete state.

## Admin Workflows

Operators must be able to approve pending launches, reject requests, revoke active launches, force teardown with a receipt, export tenant audit trails, export EvidencePacks, verify EvidencePacks offline, rotate provider/model secrets, and inspect unreconciled cloud resources.

## Retention Defaults

Launchpad keeps receipts for 400 days by default. EvidencePack manifests stay attached to audit records. Raw logs are excluded unless explicitly enabled, secrets are never retained, and tenant override may only increase retention or reduce raw-log capture.

## Incident Playbook

Runbooks must cover leaked secret suspicion, stuck cloud resources, failed teardown, compromised artifacts, bad MCP servers/tools, tenant audit disputes, and evidence verification failure. The first response is containment: revoke the launch, rotate affected secrets, export receipts/EvidencePack manifests, reconcile cloud resources, and record the operator decision trail.

## Production Promotion Rule

No app is cloud-installable because it appears in the catalog. Promotion requires:

- signed OCI manifest from the executed artifact workflow
- immutable GHCR digest reference
- cosign signature ref
- syft SBOM ref
- grype or trivy vulnerability scan ref
- license and redistribution proof
- live local/container e2e to `RUNNING`
- egress proxy receipt
- teardown proof
- offline EvidencePack verification from directory and tar
- cloud provider sandbox create/retry/reconcile/teardown tests
- secret-redacted logs
- public proof redaction review

Enterprise Launchpad remains approval-gated even for supported kernel apps: tenant launch state, retention refs, route/OpenAPI parity, receipts, and EvidencePack refs are the canonical commercial record.

## Troubleshooting

| Condition | Response |
| --- | --- |
| Plan returns blocked reasons | Inspect the LaunchRun state, policy verdict, certification refs, and provider readiness before retrying. |
| Execute lacks approval | Collect the required workspace, tenant, or dual-control approval receipt and retry through the same LaunchRun. |
| Evidence export is incomplete | Keep the launch non-promotable until audit rows and EvidencePack manifests verify offline. |
| Teardown fails | Revoke the launch, rotate affected secrets, reconcile provider resources, and attach the operator decision trail. |


---
title: "Policy Backends"
canonical: "https://helm.docs.mindburn.org/product/policy-backends"
source: "helm-ai-enterprise/docs/public/product/policy-backends.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/policy-backends.md"
section: "helm-ai-enterprise"
access: "public"
sensitivity: "public"
last_reviewed: "2026-02-21"
checksum_sha256: "sha256:d2ae9fcab976fae3b4044d39c1fee3973d014642cccf96bda2af4b3b5db7d01b"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Pluggable Policy Backends (PDP)

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `product/policy-backends`
- Source document: `helm-ai-enterprise/docs/public/product/policy-backends.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

HELM supports multiple Policy Decision Point (PDP) backends to integrate with existing enterprise policy infrastructure.

## Configuration
Use the following environment variables to configure the active PDP:

- `HELM_POLICY_BACKEND`: `helm` (default CEL), `opa`, or `cedar`.
- `HELM_POLICY_VERSION`: A human-readable identifier for the policy set (e.g., git hash).

### OPA (Open Policy Agent)
- `OPA_URL`: Base URL of the OPA server (e.g., `http://localhost:8181`).
- HELM dispatches requests to `/v1/data/helm-ai-enterprise/authz`.

### Cedar
- `CEDAR_URL`: Base URL of the Cedar sidecar (e.g., `http://localhost:8182`).
- HELM dispatches requests to `/decide`.

## Fail-Closed Semantics
All external PDP adapters implement strict fail-closed behavior. If the PDP is unreachable, returns a non-200 status, or provides a malformed response, the Kernel will DENY the action.

## Proof Binding
Every decision produced by a PDP is hashed via JCS and bound into the `DecisionRecord` and `ProofGraph`.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        s0["Configuration"]
        s1["Fail-Closed Semantics"]
        output["Reader outcome"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        source["Pluggable Policy Backends (PDP)"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        s2["Proof Binding"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> output

    %% Premium Styling Rules
    style source fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style s2 fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Operational Readiness

Use this page as the public operating layer for **Policy Backends**. The source of truth is `helm-ai-enterprise/docs/public/product/policy-backends.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "Policy Bundles"
canonical: "https://helm.docs.mindburn.org/product/policy-bundles"
source: "helm-ai-enterprise/docs/public/product/policy-bundles.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/policy-bundles.md"
section: "teams"
access: "public"
sensitivity: "public"
last_reviewed: "2026-02-21"
checksum_sha256: "sha256:1d035b12e5054eaedd4b2a8caa84d6d2183cc0f0a0980039cb55dfc915017bf6"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# External Policy Bundle Loading (GOV-002)

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `product/policy-bundles`
- Source document: `helm-ai-enterprise/docs/public/product/policy-bundles.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

## Overview

HELM's policy engine currently uses CEL rules defined inline in Go code. This guide describes the planned external policy bundle format for loading rules from files at runtime.

## Bundle Format

Policy bundles are YAML files with CEL expressions:

```yaml
# policy-bundle.yaml
apiVersion: helm.mindburn.run/v1
kind: PolicyBundle
metadata:
  name: production-policy
  version: "1.2.0"
  hash: "sha256:auto-computed-on-load"

rules:
  # Guardian-level rules (evaluated on every tool call)
  - id: require-approval-for-write
    action: "write.*"
    expression: |
      intent.risk_score < 0.7 || 
      has(artifacts, "type", "HUMAN_APPROVAL")
    verdict: DENY
    reason: "Write operations with risk > 0.7 require human approval"

  - id: budget-gate
    action: "*"
    expression: |
      state.budget_remaining > 10.0
    verdict: DENY
    reason: "Insufficient error budget"

  # PEP-level rules (post-execution validation)
  - id: output-size-limit
    action: "*"
    expression: |
      size(effect.output) < 1048576
    verdict: DENY
    reason: "Output exceeds 1MB limit"

  # Temporal rules
  - id: rate-limit
    action: "*"
    expression: |
      state.calls_per_minute < 100
    verdict: THROTTLE
    reason: "Rate limit exceeded"
```

## Loading

```go
import "github.com/Mindburn-Labs/helm-ai-enterprise/core/pkg/guardian"

// Load at startup
bundle, err := guardian.LoadPolicyBundle("policy-bundle.yaml")
if err != nil {
    log.Fatal("failed to load policy bundle:", err)
}

// Content-addressed version (GOV-001)
log.Printf("Policy version: %s", bundle.ContentHash())

// Apply to Guardian
g := guardian.NewGuardian(signer, prg, registry)
g.ApplyPolicyBundle(bundle)
```

## Validation

Bundles are validated on load:

1. **Schema check** — YAML structure matches expected format
2. **CEL compilation** — All expressions must compile without errors
3. **Content hash** — SHA-256 of canonical bundle content (for GOV-001)
4. **Signature verification** — Optional Cosign/Ed25519 signature on bundle file

## Roadmap

| Phase | Feature | Status |
|-------|---------|--------|
| 1 | YAML bundle format definition | ✅ Defined |
| 2 | Bundle loader with CEL compilation | Planned |
| 3 | Hot-reload on file change (fsnotify) | Planned |
| 4 | Bundle signing and verification | Planned |
| 5 | Remote bundle fetch (HTTP/Git) | Planned |

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        s0["Overview"]
        s1["Bundle Format"]
        s2["Loading"]
        s3["Validation"]
        output["Reader outcome"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        source["External Policy Bundle Loading (GOV-002)"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> s3
    s3 --> output

    %% Premium Styling Rules
    style source fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
```


## Operational Readiness

Use this page as the public operating layer for **Policy Bundles**. The source of truth is `helm-ai-enterprise/docs/public/product/policy-bundles.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "Procurement FAQ"
canonical: "https://helm.docs.mindburn.org/product/procurement"
source: "helm-ai-enterprise/docs/public/product/procurement.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/procurement.md"
section: "helm-ai-enterprise"
access: "public"
sensitivity: "public"
last_reviewed: "2026-04-29"
checksum_sha256: "sha256:345edd575dc103c957ad57632fa9d676fdd8e63dc1e0ab55bdbfba6705e18d37"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Procurement Guide: HELM Autonomous Labor Runtime

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `product/procurement`
- Source document: `helm-ai-enterprise/docs/public/product/procurement.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

This document provides guidance for organizations evaluating HELM for governing autonomous labor and agentic ecosystems.

## Core Value Proposition
HELM separates the **Cognitive Plane** (stochastic LLMs) from the **Truth Plane** (deterministic Go kernel). It ensures that no agentic action occurs without mathematical proof and policy compliance.

## Key Selection Criteria
1. **Mathematical Determinism**: HELM uses JCS (RFC 8785) and Merkle-DAGs to ensure execution is replayable and non-repudiable.
2. **Fail-Closed Governance**: The Kernel denies by default. If a policy check fails or a budget is exceeded, the action is blocked.
3. **Pluggable Policy**: HELM integrates with industry-standard policy engines like OPA and Cedar.
4. **Offline Verification**: EvidencePacks can be verified air-gapped, ensuring total high_assurance control over audit trails.

## RFP Compliance
HELM meets or exceeds requirements for:
- **Auditability**: Complete causal history via ProofGraph.
- **Traceability**: Attribution of every action to a human principal or agent.
- **Containment**: Enforced tool sandboxing and drift detection.
- **EU AI Act readiness**: High-risk workflow evidence for risk management,
  event logging, technical documentation, and human oversight on the current
  2026-08-02 Annex III application trajectory.
- **US state AI readiness**: Colorado SB24-205 and the proposed ADMT
  replacement are treated as monitored state overlays. HELM records runtime
  decisions and human-review evidence without depending on a single state
  deadline as the procurement driver.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Procurement Guide: HELM Autonomous Labor Runtime"]
        s0["Core Value Proposition"]
        s1["Key Selection Criteria"]
        s2["RFP Compliance"]
        output["Reader outcome"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> output

    %% Premium Styling Rules
```


## Operational Readiness

Use this page as the public operating layer for **Procurement FAQ**. The source of truth is `helm-ai-enterprise/docs/public/product/procurement.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "Regional Compatibility"
canonical: "https://helm.docs.mindburn.org/product/regional-compat"
source: "helm-ai-enterprise/docs/public/product/regional-compat.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/regional-compat.md"
section: "helm-ai-enterprise"
access: "public"
sensitivity: "public"
last_reviewed: "2026-04-29"
checksum_sha256: "sha256:1ad52b450a0a297505ecaf367cb670b58d5f1949137a1e484c310df54dc86d97"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM Regional Compatibility

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `product/regional-compat`
- Source document: `helm-ai-enterprise/docs/public/product/regional-compat.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

HELM supports regional deployment profiles that automatically configure governance
policies, data residency, encryption standards, and ceremony requirements.

## Supported Regions

| Region | Profile | Compliance | Encryption | Ceremony |
|--------|---------|------------|------------|----------|
| US     | `us`    | SOC2, NIST-800-53 | AES-256-GCM | Standard (2s timelock) |
| EU     | `eu`    | GDPR, SOC2, ISO-27001 | AES-256-GCM | Strict (5s timelock, challenge/response) |
| RU     | `ru`    | GOST-R-34.10, 152-FZ | GOST-28147-89 | Standard (3s timelock) |
| CN     | `cn`    | GB/T-35273, CSL | SM4 | Standard (3s timelock) |

## Configuration

Set the `HELM_REGION` environment variable:

```bash
export HELM_REGION=eu
```

Or in `helm.yaml`:

```yaml
region: eu
```

## EU-Specific Requirements

- **GDPR**: PII handling set to strict mode. All personal data processing
  requires explicit consent, logged as TRUST_EVENT in the ProofGraph.
- **EU AI Act**: Annex III high-risk obligations are on the current
  2026-08-02 application trajectory. The EU profile emphasizes risk
  management evidence, immutable event logs, technical documentation,
  human oversight ceremonies, and operator-visible override paths.
- **Right to Erasure**: Supported via cryptographic key rotation. Data
  encrypted with tenant keys can be rendered inaccessible by revoking
  the key in the Trust Registry.
- **Data Residency**: All data stored in `eu-west-1`. Cross-region
  replication disabled by default.

## US State AI Watch

Colorado is no longer the lead compliance deadline for HCOM positioning. The
current SB24-205 requirements were moved to 2026-06-30 by SB25B-004, and a
March 2026 workgroup proposal would replace the law with an ADMT-focused
framework effective 2027-01-01 if enacted.

HELM should position Colorado as a monitored state profile: runtime receipts,
decision logs, human-review records, and adverse-action context can support
ADMT audit and recordkeeping, but public copy should not claim the proposed
ADMT framework is final law.

## Ceremony Differences

The EU profile requires challenge/response verification for all
approval ceremonies, adding an extra layer of human verification.
This means the operator must type a confirmation phrase (e.g., "DELETE")
in addition to the standard timelock and hold requirements.

## Custom Profiles

Create a custom profile in `config/profiles/`:

```yaml
profiles:
  custom:
    name: "Custom Region"
    ceremony:
      min_timelock_ms: 10000
      min_hold_ms: 5000
      require_challenge: true
      domain_separation: "helm:approval:v1:custom"
    data_residency: "custom-dc-1"
    compliance:
      - "CUSTOM-STANDARD"
    encryption: "AES-256-GCM"
```

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["HELM Regional Compatibility"]
        s0["Supported Regions"]
        s1["Configuration"]
        s2["EU-Specific Requirements"]
        s3["US State AI Watch"]
        output["Reader outcome"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> s3
    s3 --> output

    %% Premium Styling Rules
```


---
title: "Responses API"
canonical: "https://helm.docs.mindburn.org/product/responses-api"
source: "helm-ai-enterprise/docs/public/product/responses-api.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/responses-api.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-02-21"
checksum_sha256: "sha256:064f4ef235c97daa2bd367ad610105250f030d7a0208ab28272ab0e6ac0b1ce6"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Responses API Migration Stance

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `product/responses-api`
- Source document: `helm-ai-enterprise/docs/public/product/responses-api.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

## Position

HELM currently implements the **OpenAI Chat Completions API** (`/v1/chat/completions`) as its proxy compatibility layer. This is the industry-standard API used by the majority of AI agent frameworks.

## Responses API (2025+)

OpenAI introduced the Responses API as a successor to Chat Completions, adding native tool orchestration, multi-turn state management, and built-in retrieval. 

### HELM's Stance

| Aspect | Position |
|--------|----------|
| Chat Completions API | **Fully supported** — indefinite support, no deprecation planned |
| Responses API | **Tracked** — monitoring adoption across the ecosystem |
| Migration timeline | **No near-term migration** — will implement when ecosystem adoption reaches critical mass |
| Breaking changes | **None** — Chat Completions compatibility is a core contract |

### Rationale

1. **HELM's value is orthogonal** — HELM's security layer (Guardian, receipts, ProofGraph) operates at a layer below the API surface. The same governance applies regardless of the API format.
2. **Ecosystem inertia** — As of early 2026, Chat Completions remains the dominant API across providers (Anthropic, Google, Mistral, Cohere).
3. **Clean separation** — When/if HELM adds Responses API support, it will be an additional endpoint, not a replacement for Chat Completions.

### What This Means for Integrators

- **No action required** — Continue using `/v1/chat/completions`
- **Tool use** — Pass `tools` array in the request body; HELM's Guardian validates and signs tool calls before execution
- **Future-proofing** — HELM will announce Responses API support with a minimum 6-month notice period

## Missing Parameters (Tracked)

The following Chat Completions parameters are not yet proxied by HELM:

| Parameter | Status | Priority |
|-----------|--------|----------|
| `tool_choice` | Planned | P1 |
| `parallel_tool_calls` | Planned | P1 |
| `response_format` | Planned | P1 |
| `logprobs` | Not planned | P2 |
| `top_logprobs` | Not planned | P2 |

These parameters are pass-through to upstream providers and do not affect HELM's security guarantees. Implementation is tracked in the API conformance backlog.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Responses API Migration Stance"]
        s0["Position"]
        s1["Responses API (2025+)"]
        s2["Missing Parameters (Tracked)"]
        output["Reader outcome"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> output

    %% Premium Styling Rules
```


---
title: "RFP Answers"
canonical: "https://helm.docs.mindburn.org/product/rfp-answers"
source: "helm-ai-enterprise/docs/public/product/rfp-answers.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/rfp-answers.md"
section: "helm-ai-enterprise"
access: "public"
sensitivity: "public"
last_reviewed: "2026-02-21"
checksum_sha256: "sha256:0e90d25b72a2dd89751e021030f9e0418e08a2753fdca0c907963791cbc3cd2c"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Standard RFP Answers: HELM

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `product/rfp-answers`
- Source document: `helm-ai-enterprise/docs/public/product/rfp-answers.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

This document contains standard responses for Risk, Compliance, and Technical RFP sections.

## 1. Security & Compliance
**Q: How does the system handle unauthorized agent actions?**
A: HELM uses a Policy Enforcement Point (PEP). Every side-effectful action must be authorized by a signed Kernel Verdict. Without this verdict, the Executor (SafeExecutor) cannot dispatch the action.

**Q: Can logs be tampered with?**
A: HELM produces a ProofGraph (Merkle-DAG). Any attempt to alter history invalidates the subsequent node hashes and signatures, making tampering mathematically detectable during verification.

## 2. Technical Architecture
**Q: What is the "7-Plane Model"?**
A: It is the HELM architectural standard that separates Identity, Policy, Truth, Record, Tools, Knowledge, and Surface into explicit trust boundaries.

**Q: Does it support OPA?**
A: Yes, HELM includes a native OPA adapter (`HELM_POLICY_BACKEND=opa`) that delegates decisions to a central OPA server while maintaining local proof binding.

## 3. Reliability
**Q: What happens if the policy engine is down?**
A: HELM implements fail-closed semantics. If the PDP is unreachable, all actions are denied until the connection is restored.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Standard RFP Answers: HELM"]
        s0["1. Security & Compliance"]
        s1["2. Technical Architecture"]
        s2["3. Reliability"]
        output["Reader outcome"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> output

    %% Premium Styling Rules
```


## Operational Readiness

Use this page as the public operating layer for **RFP Answers**. The source of truth is `helm-ai-enterprise/docs/public/product/rfp-answers.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "Workstation Governance"
canonical: "https://helm.docs.mindburn.org/product/workstation-governance"
source: "helm-ai-enterprise/docs/public/product/workstation-governance.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/workstation-governance.md"
section: "teams"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-20"
checksum_sha256: "sha256:9b5f0dc6358afdaafdbdd8b9724740065fddbb6969724e249c4ea3b7d71b1215"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Workstation Governance

HELM workstation governance records what local coding agents did, what selected
side effects were allowed or denied, and what evidence survived the run. It is
designed for Codex, Claude Code, and similar developer workflows where the first
adapter is manifest-first and local-wrapper based.

The current boundary is deliberately narrow: HELM governs artifacts and selected
effects that pass through its adapter or wrapper. It does not claim full desktop,
browser session, kernel-level, or proprietary hosted-agent control.

## Audience

Use this page if you are evaluating HELM for local coding-agent governance, operating the Enterprise Console workstation view, or deciding which adapter certification level is ready for a buyer-facing demo.

## Outcome

After reading this page, you should know what HELM governs for Codex or Claude Code-style runs, what remains outside scope, how receipts reach Console, and which release checks prove the adapter boundary.

## Flow

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        wrapper["Local wrapper"]
        importer["HELM importer"]
        console["Enterprise Console"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        decision{"Selected effect?"}
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        artifacts["Run artifacts"]
        allow["ALLOW receipt"]
        deny["DENY receipt"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["Signed Agent Run Receipt"]
        proof["ProofGraph and EvidencePack refs"]
    end

    %% Operational Flow Edges
    wrapper --> artifacts
    artifacts --> importer
    importer --> receipt
    receipt --> proof
    receipt --> console
    wrapper --> decision
    decision --> allow
    decision --> deny
    allow --> console
    deny --> console

    %% Premium Styling Rules
    style artifacts fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style proof fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style decision fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style allow fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style deny fill:#e53e3e,stroke:#9b2c2c,stroke-width:2px,color:#fff
```


## What HELM Governs

- A signed Agent Run Receipt for an imported local run.
- Deterministic ProofGraph mapping from manifest, tool events, diff summary,
  validation output, and receipt references.
- EvidencePack references that can be inspected offline.
- Workspace-scoped draft edits represented in the receipt.
- Selected operate-class effects sent through the enforcement bridge, including
  network egress, MCP mutation, memory write, recurring loop registration,
  shell operate, deploy/publish, secret read, and payment initiate requests.
- Memory writes as reviewable effects with TTL and sensitivity.
- Recurring loops as high-risk effects with schedule, max runtime, tool scope,
  and expiration.

## What HELM Does Not Govern

- Direct actions that bypass the HELM adapter or wrapper.
- Private Codex or Claude Code internals that are not exposed as artifacts.
- Raw chat history, private browser sessions, secrets, or local credential
  material.
- Every side effect on a workstation unless a future adapter proves that surface
  through conformance.
- Proprietary hosted-agent behavior unless there is an enforceable adapter for
  that hosted surface.

## Modes

| Mode | Meaning | Typical buyer question it answers |
| --- | --- | --- |
| Observe-only | HELM imports artifacts and emits a receipt after the run. | What happened, what changed, and what evidence survived? |
| Selected-effect enforceable | HELM can allow or deny declared effects routed through the wrapper. | Was this network, MCP, memory, loop, or publish action approved? |
| High-risk-effect capable | HELM has conformance fixtures for memory, recurring loop, taint, and other high-risk effect classes. | Can this adapter prove the effect classes we care about? |

## Operator Workflow

1. Run the local Codex or Claude Code wrapper.
2. Produce an artifact directory and signed Agent Run Receipt.
3. View the receipt with the local CLI.
4. Import the receipt or decision receipt into Enterprise Console.
5. Review the run list, receipt detail, denied timeline, memory queue, and loop
   registry.
6. Export or inspect the EvidencePack and ProofGraph references.
7. Run conformance certification for observe-only, enforceable, or
   high-risk-effect-capable mode.

## Console View

Enterprise Console exposes `/workspaces/:workspaceId/workstation` for the
operator read model. The view shows run summaries, receipt details, denied
effects, memory review items, and recurring loop registrations without rendering
raw transcripts.

## Source Truth

- Console route registry: `apps/controlplane/internal/console/route_registry.go`
- Workstation backend handlers: `apps/controlplane/internal/console/workstation_routes.go`
- OpenAPI contract: `api/openapi/helm.openapi.yaml`
- Console UI: `apps/console/src/features/workstation/`
- Kernel adapter and conformance: `helm-ai-kernel/core/pkg/workstation/`
- Adapter examples: `helm-ai-kernel/examples/workstation/`

Validation commands:

```bash
make openapi-route-parity
python3 scripts/check_documentation_truth.py
```

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A run is missing from Console | Confirm the signed receipt was imported through `/api/v1/workspaces/{id}/workstation/receipts/import`. |
| A denied action does not appear in the timeline | Confirm the wrapper wrote a decision receipt with the same run ID. |
| A memory write is not reviewable | Confirm the artifact models it as a memory effect with TTL and sensitivity. |
| A buyer assumes full workstation control | Re-state the adapter boundary: HELM governs artifacts and selected effects routed through the adapter or wrapper. |


---
title: "API Reference"
canonical: "https://helm.docs.mindburn.org/reference"
source: "helm-ai-enterprise/docs/11_API_REFERENCE.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/11_API_REFERENCE.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:f339b0209d8aa7a854d1d87b4af4831ad7aed67f3c9a0d04ed3bf70213c5d287"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM Reference Hub

This hub organizes HELM interfaces across the control plane, Console `/api/v1` surface, Basic/commercial API, generated OpenAPI contract, WebSocket telemetry, SDKs, and verification tooling. It is a map. Exact request and response fields belong to the owning source files, OpenAPI contract, schemas, and route tests.

## Audience

Use this page if you are integrating with HELM, generating a client, debugging a denied action, operating Console, or evaluating the commercial API boundary.

## Outcome

After this page you should know which public route family owns each integration path, which source file is authoritative, which routes are Console, Basic, commercial, proof, or generated OpenAPI surfaces, and which validation commands catch drift before docs are published.

## Source Truth

| Surface | Source truth | Public docs |
| --- | --- | --- |
| Control-plane router | `apps/controlplane/internal/http/router.go` | This page and `docs/audit/API_ENDPOINTS.md`. |
| Console `/api/v1` registry | `apps/controlplane/internal/console/route_registry.go` | `docs/public/product/console-api.md`. |
| Console handlers | `apps/controlplane/internal/console/facade.go`, `apps/controlplane/internal/console/*_routes.go` | `docs/public/product/console.md`. |
| Individual API | `commercial/basic/server.go`, mounted by `apps/helm-ai-enterprise/main.go` at `/api/basic/` | `docs/public/product/agent-skills-governance.md`. |
| Commercial gateway | `apps/helm-ai-enterprise/main.go`, `apps/helm-ai-enterprise/*.go` | `docs/COMMERCIAL_OVERVIEW.md`, `docs/COMMERCIAL_DEPLOY.md`. |
| OpenAPI source | `api/openapi/helm.openapi.yaml` | `docs/api/openapi.yaml` generated public mirror. |
| Schema registry | `protocols/json-schemas/SCHEMA_INDEX.md`, `docs/audit/CONTRACT_REGISTRY.md` | `docs/12_SCHEMA_REFERENCE.md`. |
| CLI and verifier | `packages/mindburn-helm-ai-enterprise-cli/src/**`, `core/cmd/helm-ai-enterprise-*` | `docs/13_CLI_REFERENCE.md`. |

If this page disagrees with a route registry, handler, OpenAPI source, or contract test, the source artifact wins.

## Interface Map

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        app["Application / SDK"]
        openapi["OpenAPI-backed HTTP contract"]
        operator["HELM Console"]
        cp["apps/controlplane router"]
        consoleRegistry["Console /api/v1 route registry"]
        basic["/api/basic router"]
        cli["CLI and verifier"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        commercial["HELM AI Enterprise gateway"]
        enterprise["billing, SCIM, provisioning, trial, audit"]
        ops["ops, billing, audit, packs"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        redacted["redaction-safe metadata"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        proof["public proof and replay routes"]
        receipts["audit and evidence links"]
        evidence["evidence bundles"]
    end

    %% Operational Flow Edges
    app --> openapi
    operator --> cp
    cp --> consoleRegistry
    commercial --> basic
    commercial --> enterprise
    cp --> proof
    cp --> ops
    basic --> receipts
    proof --> redacted
    cli --> evidence

    %% Premium Styling Rules
    style commercial fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style enterprise fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style proof fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style ops fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style receipts fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style redacted fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style evidence fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Console/API Matrix

| API family | Route shape | Owner | Auth boundary | Use when |
| --- | --- | --- | --- | --- |
| Health | `/health`, `/health/live`, `/health/ready` | `apps/controlplane/internal/http/router.go` | Public | Process and readiness probes. |
| Auth/session | `/api/auth/*`, `/api/session` | `internal/auth`, `internal/platform` | Session or ceremony-specific public login begin/finish | Browser session, refresh, reauth, and WebAuthn ceremonies. |
| Bootstrap/workspaces | `/api/bootstrap*`, `/api/workspaces*` | `internal/platform` | Session | Tenant/workspace bootstrap and member management. |
| Console canonical routes | `/api/v1/workspaces*`, `/api/v1/marketplace/connectors*`, `/api/v1/verify`, `/api/v1/replays*`, `/api/v1/signing-key` | `internal/console/route_registry.go` | Session except public signing key, verify, and replay reads | Console workspace operations, policy, approvals, receipts, evidence, legal holds, and connector marketplace flows. |
| Public proof | `/api/public/verify/{receiptId}`, `/api/public/evidence/{bundleId}`, `/api/public/approval/{approvalId}`, `/api/public/orgs/{org_id}/*` | `internal/platform`, `internal/runtime` | Public, redacted, read-only | External verification and evaluator-safe proof views. |
| Ops and connectors | `/api/ops*`, `/api/connectors*` | `internal/ops` | Session | Incidents, plans, blast radius, freeze/throttle/resume/quarantine/resync, drift, and shim activation. |
| Billing/entitlements | `/api/billing*`, `/api/entitlements*` | `internal/billing`, `internal/registry` | Session with tenant path checks where a tenant ID appears in the path | Plans, usage, budgets, and entitlement checks. |
| Audit/export | `/api/audit*`, `/api/evidence/{handle}` | `internal/audit`, `internal/evidence` | Session unless explicitly public | Audit bundles, pack build/export, verification, and evidence handles. |
| Runtime/research/genesis | `/api/org/runtime*`, `/api/org/research*`, `/api/org/genesis*` | `internal/runtime`, `internal/researchruntime`, `internal/genesis` | Mixed public read routes and session/private routes | Runtime state sync, public org status, research runtime, and genesis ceremony flows. |
| WebSocket hints | `/ws/console`, `/ws/telemetry` | `internal/ws` | Deployment/session dependent | Realtime hints; snapshot/API fetches remain authoritative. |
| Individual commercial API | protected `/api/basic` route family | `commercial/basic/server.go` | Commercial auth middleware | Individual workspaces, members, API keys, approvals, evidence, incidents, budgets, plans, blast radius, and notifications. Exact customer routes stay in authenticated customer docs. |
| Commercial admin/gateway | protected commercial route families | `apps/helm-ai-enterprise/main.go`, `apps/helm-ai-enterprise/provisioning.go`, `apps/helm-ai-enterprise/trial.go`, `apps/helm-ai-enterprise/scim_routes.go`, `apps/helm-ai-enterprise/activation.go`, `commercial/admin`, `commercial/billing`, `commercial/metering`, `commercial/retention`, `commercial/compliance` | Public only for explicitly allowlisted status/webhook routes; otherwise protected | Commercial activation, trial, identity provisioning, admin, compliance, and billing gateway flows. Exact operator and customer routes stay in authenticated customer or staff docs. |

Do not add new public docs for routes that are not registered by `apps/controlplane/internal/http/router.go`, `apps/controlplane/internal/console/route_registry.go`, `commercial/basic/server.go`, or `apps/helm-ai-enterprise/*.go`.

Treat the protected Basic route family as Basic-owned and keep billing,
provisioning, trial, identity provisioning, admin, and compliance routes in
the commercial gateway owner set above.
Compatibility aliases registered by `apps/controlplane/internal/http/router.go`
must be labeled as compatibility-only before they appear in public reference
tables.

## Generated OpenAPI

`api/openapi/helm.openapi.yaml` is the source OpenAPI contract. `docs/api/openapi.yaml` is the generated public mirror. Regenerate the mirror from the source; do not edit the mirror by hand.

The OpenAPI contract covers the public HTTP contract for proxying, approval, proof/evidence, conformance, org runtime, bootstrap/workspace, ops, and verification shapes. SDK docs and examples should link to the OpenAPI source or generated mirror when exact fields matter.

## Console `/api/v1` Registry

The Console route registry groups canonical routes by area:

| Area | Route examples | Notes |
| --- | --- | --- |
| Workspaces | `POST /api/v1/workspaces`, `GET /api/v1/workspaces/{id}` | Workspace CRUD. |
| Runs and receipts | `POST /api/v1/workspaces/{id}/runs`, `GET /api/v1/workspaces/{id}/runs/{run_id}`, `GET /api/v1/workspaces/{id}/runs/{run_id}/receipts` | Runs are receipted with policy and evidence metadata. |
| Approvals | `GET /api/v1/workspaces/{id}/approvals`, `POST /api/v1/workspaces/{id}/approvals/{approval_id}/resolve` | Approval records do not bypass kernel evaluation. |
| Tools and policy | `/tools`, `/policy/draft`, `/policy/compile`, `/policy/activate`, `/policy/active` | Policy activation must remain auditable. |
| Tasks/actions/channels | `/tasks*`, `/actions*`, `/channels*` | Operator action and collaboration surfaces. |
| Skills and knowledge | `/skills*`, `/knowledge/*` | Candidate promotion/rejection and knowledge claim review. |
| Evidence/legal/jurisdiction | `/evidence/*`, `/legal-holds*`, `/jurisdictions` | Export and retention-sensitive flows. |
| Public replay/verify | `/api/v1/replays*`, `/api/v1/verify`, `/api/v1/signing-key` | Public-safe verification surfaces. |
| Marketplace | `/api/v1/marketplace/connectors*` | Connector read, install, and disable flows behind authorization. |

## Individual API Classification

The Basic router is a commercial API mounted at `/api/basic/`. It is not the Console `/api/v1` registry.

| Class | Routes | Source |
| --- | --- | --- |
| Workspace administration | `/api/basic/workspaces`, `/api/basic/projects`, `/api/basic/environments`, `/api/basic/members` | `commercial/basic/server.go`, `workspace.go`, `rbac.go`. |
| Keys and approvals | `/api/basic/keys`, `/api/basic/approvals` | `apikey.go`, `approval.go`, `approval_audit.go`. |
| Evidence and health | `/api/basic/evidence`, `/api/basic/health` | `evidence_index.go`, `server.go`. |
| Incidents and budgets | `/api/basic/incidents`, `/api/basic/incidents/transition`, `/api/basic/budget/record`, `/api/basic/budget/summary` | `handler_incidents.go`, `handler_budget.go`. |
| Plans and blast radius | `/api/basic/plans`, `/api/basic/plans/approve`, `/api/basic/plans/commit`, `/api/basic/blastradius` | `handler_plans.go`, `handler_blastradius.go`. |
| Notifications | `/api/basic/notifications/subscribe`, `/api/basic/notifications/emit` | `handler_notifications.go`, `notifications.go`. |
| Runtime bridge | `/api/basic/runtime/start`, `/api/basic/runtime/stop`, `/api/basic/runtime/status` | `runtime_bridge.go`. |

## Redaction Boundary

Public examples may include route names, sample tenant/workspace IDs, receipt IDs, hash values, public signing keys, and redacted evidence metadata. They must not include session cookies, private tenant payloads, customer data, provider credentials, private signing keys, production database URLs, or raw evidence exports that contain private data.

Public proof routes should return verification status and metadata needed to validate a receipt. Workspace routes should require session authority and should not be described as public.

## Diagnostics Packet

When reporting an integration problem, collect:

- HELM version and deployment mode;
- endpoint, SDK method, or CLI command;
- request correlation ID;
- receipt ID or denial reason code;
- policy bundle ref or hash;
- sanitized request shape without secrets or private payloads;
- verifier output when an evidence pack exists.

## Versioning

HELM should preserve existing public integration paths unless a security fix requires a break. New fields should be additive where possible. Breaking changes need a migration note, compatibility section, changelog entry, and generated client update.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Route exists in code but not public docs | Route registry or endpoint registry changed without doc update | Update `docs/audit/API_ENDPOINTS.md`, this page, and the relevant public product page. |
| Generated client rejects a field | OpenAPI or SDK is older than runtime | Regenerate or pin to the matching HELM version. |
| Console page has stale data after WebSocket event | WebSocket messages are hints only | Refetch `/api/snapshot` or the owning API route. |
| Public proof exposes too much data | Redaction boundary was not applied | Treat it as a security bug; reduce response to verification metadata. |
| Individual route behavior is unclear | Console and Individual APIs were conflated | Check `commercial/basic/server.go` and the Individual governance page. |


---
title: "API and Audit Registries"
canonical: "https://helm.docs.mindburn.org/reference/api-and-audit-registries"
source: "helm-ai-enterprise/docs/public/reference/api-and-audit-registries.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/reference/api-and-audit-registries.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:daa9ed36408d848ac5e10836db3cbc563f5a3b32e94bac473b7485a60e3509e7"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# API and Audit Registries

This page maps the public reference docs to HELM's OpenAPI, endpoint registry,
config registry, contract registry, schema-version guide, and API lifecycle
material.

The active backend source for these registries is `apps/controlplane`.
HELM Console has one browser API backend and one route registry.

## Audience

Use this page if you build against HELM APIs, review control-plane contracts, or
audit whether route, config, and schema changes are tracked.

## Outcome

You should know which file owns each reference surface and which public export
or docs page to use for implementation.

## Registry Flow

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        router["Control-plane router"]
        endpoints["Endpoint registry"]
        config["Config sources"]
        configRegistry["Config registry"]
        contractRegistry["Contract registry"]
        schemas["Schema versions"]
        schemaGuide["Schema version guide"]
        openapi["openapi"]
        docs["Public reference docs"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        contracts["Runtime contracts"]
    end

    %% Operational Flow Edges
    router --> endpoints
    config --> configRegistry
    contracts --> contractRegistry
    schemas --> schemaGuide
    openapi --> docs
    configRegistry --> docs
    contractRegistry --> docs
    schemaGuide --> docs

    %% Premium Styling Rules
    style contracts fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
```


## Reference Surfaces

| Surface | Source truth | Public use |
| --- | --- | --- |
| OpenAPI | `api/openapi/helm.openapi.yaml` source, mirrored to `docs/api/openapi.yaml` | `/openapi.yaml` and `/reference` |
| API lifecycle | `docs/api/API_LIFECYCLE.md` | Versioning, compatibility, and deprecation expectations. |
| API changelog | `docs/api/CHANGELOG.md` | Public API change history. |
| Endpoint registry | `docs/audit/API_ENDPOINTS.md` | Generated route inventory for reviewer alignment. |
| Config registry | `docs/audit/CONFIG_REGISTRY.md` | Runtime and deployment configuration source map. |
| Contract registry | `docs/audit/CONTRACT_REGISTRY.md` | Contract ownership and compatibility map. |
| Schema version guide | `docs/audit/SCHEMA_VERSION_GUIDE.md` | Schema evolution and compatibility rules. |
| SDK docs | `docs/public/reference/sdks/` | SDK references and contract versioning. |
| CLI v3 evidence format | `docs/public/reference/cli-v3/format.md` | Evidence bundle and Merkle format. |
| CLI v3 keys | `docs/public/reference/cli-v3/keys.md` | Signing-key lifecycle and verification behavior. |

## Active Boundary

- Treat `apps/controlplane/internal/http/router.go`, the Console route registry, and `api/openapi/helm.openapi.yaml` as the canonical API inventory.
- Do not add a second browser API backend, standalone proof service, or duplicate route registry.

## Source Truth

- `docs/11_API_REFERENCE.md`
- `api/openapi/helm.openapi.yaml` (source)
- `docs/api/openapi.yaml` (generated public mirror)
- `docs/api/API_LIFECYCLE.md`
- `docs/audit/API_ENDPOINTS.md`
- `docs/audit/CONFIG_REGISTRY.md`
- `docs/audit/CONTRACT_REGISTRY.md`
- `docs/audit/SCHEMA_VERSION_GUIDE.md`

## Troubleshooting

| Problem | Check |
| --- | --- |
| Route exists in code but not docs | Regenerate or update `docs/audit/API_ENDPOINTS.md`, then update `/reference`. |
| API docs disagree with OpenAPI | Regenerate `docs/api/openapi.yaml` from `api/openapi/helm.openapi.yaml`; do not edit the mirror by hand. |
| SDK version behavior is unclear | Check `/reference/sdks` and `/reference/sdks/contract-versioning`. |
| Config behavior is ambiguous | Check `CONFIG_REGISTRY.md` and deployment docs before changing public docs. |

## Operational Readiness

Use this page as the public operating layer for **API and Audit Registries**. The source of truth is `helm-ai-enterprise/docs/public/reference/api-and-audit-registries.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "CLI v3 Output Format"
canonical: "https://helm.docs.mindburn.org/reference/cli-v3/format"
source: "helm-ai-enterprise/docs/public/reference/cli-v3/format.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/reference/cli-v3/format.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-02-21"
checksum_sha256: "sha256:e7727b334f97aa3b177679b819e64b93c71e2545285ed91ae2372bdd0c529878"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM v3 Evidence Bundle Format

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `reference/cli-v3/format`
- Source document: `helm-ai-enterprise/docs/public/reference/cli-v3/format.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

## Canonicalization

`00_INDEX.json` MUST be canonical JSON:
- Keys sorted lexicographically (recursive)
- No trailing whitespace
- UTF-8 encoded
- No BOM
- Single trailing newline

This matches [JCS (RFC 8785)](https://www.rfc-editor.org/rfc/rfc8785).

## Manifest Root Hash

```
manifest_root_hash = sha256(canonical_bytes(00_INDEX.json))
```

Identity of the bundle. Cache key. Single hash that pins the entire evidence tree.

## Merkle Tree

Leaves are the `sha256` hex strings from each `00_INDEX.json` entry, **sorted ascending by `path` string**. Each hex string is decoded to 32 bytes before hashing.

### Construction

```
leaf_hash    = sha256(0x00 || entry_sha256_bytes)     # domain separator: leaf
internal     = sha256(0x01 || left_hash || right_hash) # domain separator: node
odd_leaf     → duplicate last leaf
merkle_root  = root hash (hex)
```

### Ordering

Leaves are sorted by canonical `path` string (ascending, lexicographic). This prevents order drift across implementations.

### Verification Algorithm

```
1. Read 00_INDEX.json
2. Sort entries by path ascending
3. Decode each entry.sha256 from hex → 32 bytes
4. Hash each: leaf = sha256(0x00 || bytes)
5. Build tree bottom-up:
   a. If odd number of leaves, duplicate last
   b. Parent = sha256(0x01 || left || right)
6. Root = final hash (hex)
7. Compare to attestation merkle_root
```

## Attestation

```json
{
  "format":             "helm-attestation-v3",
  "release_tag":        "v0.9.1",
  "asset_name":         "helm-evidence-v0.9.1.tar.gz",
  "asset_sha256":       "abc123...",
  "manifest_root_hash": "def456...",
  "merkle_root":        "789abc...",
  "created_at":         "2026-02-21T12:00:00Z",
  "profiles_version":   "1.0.0"
}
```

Signed with Ed25519. Signature is over `sha256(canonical_bytes(attestation_json))`.

## Public Key

Shipped in CLI as pinned constant. Key rotation via versioned key list.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        index["00_INDEX.json"]
        canonical["Canonical JSON"]
        leaves["Sorted leaf hashes"]
        merkle["Merkle root"]
        attest["Attestation"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        verify["CLI verify"]
    end

    %% Operational Flow Edges
    index --> canonical
    canonical --> leaves
    leaves --> merkle
    merkle --> attest
    attest --> verify

    %% Premium Styling Rules
    style verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Operational Readiness

Use this page as the public operating layer for **CLI v3 Output Format**. The source of truth is `helm-ai-enterprise/docs/public/reference/cli-v3/format.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "CLI v3 Key Management"
canonical: "https://helm.docs.mindburn.org/reference/cli-v3/keys"
source: "helm-ai-enterprise/docs/public/reference/cli-v3/keys.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/reference/cli-v3/keys.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-02-21"
checksum_sha256: "sha256:ccb094c5e53974450ae7f61deb673a78179b0cf43962ee3ec73fd76e23202030"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM Signing Keys — Key Rotation Policy

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `reference/cli-v3/keys`
- Source document: `helm-ai-enterprise/docs/public/reference/cli-v3/keys.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

## Active Keys

| Key ID | Algorithm | Since | Status |
|--------|-----------|-------|--------|
| `helm-release-2026-v1` | Ed25519 | 2026-02-21 | **Active** |

## Key Lifecycle

1. **Generation**: Keys are generated offline using `openssl genpkey -algorithm Ed25519`.
2. **Pinning**: Public keys are embedded in the CLI source at `src/crypto.ts`.
3. **Rotation**: New keys are appended. Old keys remain for back-compat verification.
4. **Retirement**: Keys are marked inactive after 12 months. They continue to verify existing signatures.

## Verification

The CLI automatically tries all pinned keys in order when verifying an attestation signature.
No configuration is needed — the key list is shipped with each CLI release.

## Where Keys Live

| Location | Content |
|----------|---------|
| `packages/mindburn-helm-ai-enterprise-cli/src/crypto.ts` | Pinned public keys (PEM format) |
| GitHub Secrets (`HELM_SIGNING_KEY`) | Private key (never committed) |
| `scripts/release/build-evidence-bundle.sh` | Uses `HELM_SIGNING_KEY` env var for signing |

## Key Generation

```bash
# Generate Ed25519 keypair
openssl genpkey -algorithm Ed25519 -out private.pem
openssl pkey -in private.pem -pubout -out public.pem

# Extract the base64 line for pinning
grep -v "BEGIN\|END" public.pem
```

## Emergency Rotation

If a private key is compromised:

1. Generate new keypair
2. Append new public key to `PINNED_PUBLIC_KEYS` in `crypto.ts`
3. Update GitHub Secrets
4. Publish CLI patch release
5. Mark old key as `compromised` in this document
6. Re-sign any attestations created with the compromised key

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        generate["Generate keypair"]
        pin["Pin public key"]
        sign["Sign attestation"]
        compromise["Compromise event"]
        rotate["Emergency rotation"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        verify["Verify with shipped keys"]
    end

    %% Operational Flow Edges
    generate --> pin
    pin --> sign
    sign --> verify
    compromise --> rotate
    rotate --> pin

    %% Premium Styling Rules
    style verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Operational Readiness

Use this page as the public operating layer for **CLI v3 Key Management**. The source of truth is `helm-ai-enterprise/docs/public/reference/cli-v3/keys.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "SDK Documentation"
canonical: "https://helm.docs.mindburn.org/reference/sdks"
source: "helm-ai-enterprise/docs/public/reference/sdks/index.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/reference/sdks/index.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-02-21"
checksum_sha256: "sha256:1cf23acb69210db248ad55b8878032dac58a28d02a84b886683f3a805930377b"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM SDK Documentation

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `reference/sdks`
- Source document: `helm-ai-enterprise/docs/public/reference/sdks/index.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

## Architecture

```
api/openapi/helm.openapi.yaml    ← Single source of truth
         │
    scripts/sdk/gen.sh           ← Generates types_gen.* files
         │
    ┌────┴────┬────────┬─────────┬──────────┐
    ▼         ▼        ▼         ▼          ▼
sdk/ts/    sdk/python/ sdk/go/  sdk/rust/  sdk/java/
 types.gen.ts  types_gen.py  types_gen.go  types_gen.rs  TypesGen.java
 client.ts     client.py     client.go     lib.rs        HelmClient.java
    │         │        │         │          │
    ▼         ▼        ▼         ▼          ▼
examples/  examples/  examples/ examples/  examples/
```

## Contract → Code → Wrapper → Example

| Layer | Purpose | Location |
|-------|---------|----------|
| **OpenAPI spec** | Single truth source | `api/openapi/helm.openapi.yaml` |
| **Generated types** | Typed models | `sdk/*/types_gen.*` (AUTO-GENERATED) |
| **Ergonomic wrapper** | HTTP client with error handling | `sdk/*/client.*` (hand-written) |
| **Examples** | Runnable demos | `examples/` |

## SDKs

| Language | Package | Install |
|----------|---------|---------|
| TypeScript | `@mindburn/helm-ai-enterprise-sdk` | `npm install @mindburn/helm-ai-enterprise-sdk` |
| Python | `helm-ai-kernel-sdk` | `pip install helm-ai-kernel-sdk` |
| Go | `github.com/Mindburn-Labs/helm-ai-enterprise/sdk/go` | `go get ...` |
| Rust | `helm-ai-kernel-sdk` | `cargo add helm-ai-kernel-sdk` |
| Java | `ai.mindburn.helm:helm-ai-kernel-sdk` | Maven |

## CI Gates

| Gate | Script | What it checks |
|------|--------|---------------|
| SDK drift | `scripts/ci/sdk_drift_check.sh` | Regenerate → diff = fail |
| SDK build/test | `scripts/ci/sdk_build_test.sh` | Build + test all 5 SDKs |
| OpenAPI lint | `.github/workflows/sdk_gates.yml` | Redocly lint |

## Per-SDK READMEs

- TypeScript (protected staff doc)
- Python (protected staff doc)
- Go (protected staff doc)
- Rust (protected staff doc)
- Java (protected staff doc)

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["HELM SDK Documentation"]
        s0["Architecture"]
        s1["Contract → Code → Wrapper → Example"]
        s2["SDKs"]
        output["Reader outcome"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        s3["CI Gates"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> s3
    s3 --> output

    %% Premium Styling Rules
    style s3 fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
```


## Operational Readiness

Use this page as the public operating layer for **SDK Documentation**. The source of truth is `helm-ai-enterprise/docs/public/reference/sdks/index.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "Contract Versioning"
canonical: "https://helm.docs.mindburn.org/reference/sdks/contract-versioning"
source: "helm-ai-enterprise/docs/public/reference/sdks/contract-versioning.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/reference/sdks/contract-versioning.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-02-21"
checksum_sha256: "sha256:a221e3154bb3f188e0abddd44ef6051b5bada5b5a97e6aee2875329988a2b5be"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM API Contract Versioning

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `reference/sdks/contract-versioning`
- Source document: `helm-ai-enterprise/docs/public/reference/sdks/contract-versioning.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

## Version Format

HELM uses semantic versioning for the API contract:
- **Major** (breaking): endpoint removal, required field addition, error shape change
- **Minor** (additive): new endpoint, optional field, new reason code
- **Patch** (fix): documentation, example correction

## Current Version

`0.1.0` — Initial Kernel release.

## Version Sources

| Location | What it governs |
|----------|----------------|
| `api/openapi/helm.openapi.yaml` -> `info.version` | Canonical contract version |
| `sdk/*/package.json` / `pyproject.toml` / etc. | SDK package version (tracks contract) |
| `apps/controlplane/cmd/controlplane` build metadata | Server binary version |

## Stability Guarantees

### Stable (v0.1+)
- Error envelope shape: `{ error: { message, type, code, reason_code, details? } }`
- Reason code set (additive only — codes are never removed)
- Endpoint paths for: proxy, approval, proofgraph, evidence, conformance, health

### Unstable (may change in v0.2)
- Response field additions (additive, won't break)
- New endpoints (additive)
- `details` object contents

## Drift Prevention

Generated types in `sdk/*/types_gen.*` are regenerated by `scripts/sdk/gen.sh`.
CI runs `scripts/ci/sdk_drift_check.sh` on every PR — fails if diff exists.

## Adding a New Endpoint

1. Add to `api/openapi/helm.openapi.yaml`
2. Run `bash scripts/sdk/gen.sh`
3. Update wrapper clients in `sdk/*/client.*`
4. Add examples to `examples/`
5. CI will validate drift + build

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        schema["Contract schema"]
        codegen["SDK codegen"]
        sdk["SDK package"]
        tests["SDK contract tests"]
        docs["Public SDK docs"]
        lifecycle["Compatibility window"]
    end

    %% Operational Flow Edges
    schema --> codegen
    codegen --> sdk
    sdk --> tests
    tests --> docs
    schema --> lifecycle

    %% Premium Styling Rules
```


## Operational Readiness

Use this page as the public operating layer for **Contract Versioning**. The source of truth is `helm-ai-enterprise/docs/public/reference/sdks/contract-versioning.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "Specs, Research, and Source Families"
canonical: "https://helm.docs.mindburn.org/reference/specs-research-and-source-families"
source: "helm-ai-enterprise/docs/public/reference/specs-research-and-source-families.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/reference/specs-research-and-source-families.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:d3c99af1d088500b16c6b66614b888e6303d64d273a67f63f513057f147dc62f"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Specs, Research, and Source Families

This page closes the public coverage gap between the HELM docs site and the
large internal source families in the HELM repo. It does not publish every
internal note as a standalone public page; it documents the owner route for each
active family and points to the public surface that carries the source truth.

## Audience

Use this page if you are auditing source coverage, building against advanced
HELM internals, reviewing specs/research material, or trying to find the public
route for a repo family that is not a top-level navigation item.

## Outcome

You should know how `apps`, `core`, `modules`, `packs`, `protocols`, `schemas`,
`infra`, `scripts`, `services`, `docs/specs`, `docs/research`, and UI/design
system material map into public docs, LLM exports, MCP, and validation gates.

## Coverage Topology

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        families["Source-family rules"]
        direct["Direct public pages"]
        hubs["Public hub pages"]
        internal["Internal/source-only classifications"]
        exports["Markdown / LLM / MCP"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        ledger["documentation-coverage.csv"]
        audit["Audit ledger with rationale"]
    end

    %% Operational Flow Edges
    ledger --> families
    families --> direct
    families --> hubs
    families --> internal
    direct --> exports
    hubs --> exports
    internal --> audit

    %% Premium Styling Rules
    style ledger fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style audit fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## HELM Source Families

| Source family | Active rows | Public route or classification |
| --- | ---: | --- |
| `apps/` | 43 | `/enterprise`, `/product/console`, `/operations/operator-guide` |
| `core/` | 132 | `/reference`, `/proof`, `/reference/verify`, `/operations/operator-guide` |
| `examples/` | 19 | `/integrations/openai-baseurl`, `/integrations/vercel-ai-sdk`, `/integrations/langchain`, `/integrations/mcp`, `/reference/sdks` |
| `modules/` | 23 | `/product/console` and this page |
| `packs/` | 16 | `/product/policy-bundles`, `/reference`, `/product/eu-ai-act-high-risk` |
| `protocols/` | 160 | `/helm-ai-kernel/reference/protocols-and-schemas`, `/reference` |
| `schemas/` | 28 | `/helm-ai-kernel/reference/protocols-and-schemas`, `/reference/api-and-audit-registries` |
| `sdk/` | 16 | `/reference/sdks`, `/helm-ai-kernel/sdks` |
| `packages/` | 25 | `/product/design-system`, `/reference/sdks`, `/reference/cli-v3/format` |
| `infra/`, `deploy/`, `ops/` | 21 | `/operations/operator-guide` |
| `scripts/`, `tools/`, `qa/`, `tests/`, `e2e/` | 40 | `/coverage`, `/operations/operator-guide`, and source-only validation ledgers |
| `services/` | 3 | `/integrations/mcp`, `/product/console`, high-risk-loop bridge source docs |
| `docs/specs/`, `docs/research/` | Source-led docs | This page, `/reference`, `/proof`, `/enterprise` |
| `docs/ui/`, design-system package docs | Source-led docs | `/product/design-system`, `/product/console` |

## Public versus Source-Only

Some source rows are intentionally not standalone public pages:

- generated ownership READMEs
- migration files where the public contract is the deployment or schema guide
- CI workflow implementation details where the public contract is release,
  supply-chain, or validation behavior
- test fixtures where the public contract is conformance, verification, or
  example behavior
- private deployment inventory values and customer-specific runbooks

Those rows still need a coverage rule. The source-coverage gate fails when a row
does not match a public route or an explicit classification.

## Source Truth

- `helm-ai-enterprise/docs/documentation-coverage.csv`
- `helm-ai-enterprise/scripts/check_documentation_coverage.py`
- `helm-ai-enterprise/scripts/check_documentation_truth.py`
- `helm-ai-enterprise/docs/public-docs.manifest.json`
- `helm-ai-kernel/docs/public-docs.manifest.json`
- `docs-platform/scripts/check-helm-source-coverage.ts`

## Troubleshooting

| Symptom | Check |
| --- | --- |
| A source path is not findable from public docs | Run `npm run helm-source:check` and inspect the unmatched row. |
| A hub page claims a family that no longer exists | The source-coverage gate checks repo paths and will fail. |
| A public docs page misses a diagram | `npm run diagrams:check` fails with the exact slug and source path. |
| A source-only classification feels too broad | Split the family into a direct public page and update the rule. |


---
title: "Verify"
canonical: "https://helm.docs.mindburn.org/reference/verify"
source: "helm-ai-enterprise/docs/public/reference/verify.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/reference/verify.md"
section: "trust"
access: "public"
sensitivity: "public"
last_reviewed: "2026-02-21"
checksum_sha256: "sha256:28586ce7cf7281e5309d6678590447ca72c894301b534efe798bd45b4e6820ab"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Verify HELM Conformance

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `reference/verify`
- Source document: `helm-ai-enterprise/docs/public/reference/verify.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

Verify any HELM release in one command. No configuration needed.

## Quick Start

```bash
npx @mindburn/helm-ai-enterprise
```

This launches the **interactive flow**:
1. Choose artifact source (latest release or local bundle)
2. Select conformance level (L1 or L2)
3. View verification results
4. Optionally drill down into gate details or generate an HTML report

## CI / Automation

```bash
# Verify local bundle — JSON on stdout, human summary on stderr
npx @mindburn/helm-ai-enterprise --ci --bundle ./evidence 2>/dev/null

# Exit code: 0 = pass, 1 = fail, 2 = error, 3 = no bundle
echo $?

# Pipe to jq for specific fields
npx @mindburn/helm-ai-enterprise --ci --bundle ./evidence 2>/dev/null | jq .verdict
# "PASS"
```

## Options

| Flag | Description | Default |
|------|-------------|---------|
| `--bundle PATH` | Local evidence bundle directory | — |
| `--level L1\|L2` | Conformance level | L2 |
| `--ci` | CI mode (JSON stdout, exit code) | — |
| `--json` | Alias for `--ci` | — |
| `--depth 0-3` | Output verbosity | 1 |
| `--report PATH` | Generate HTML evidence report | — |
| `--no-cache` | Skip download cache | — |
| `--cache-dir DIR` | Custom cache directory | `~/.helm-ai-enterprise/cache` |

## Output Depth

| Depth | Content |
|-------|---------|
| 0 | Badge + short hash |
| 1 | Summary table (structure, hash chain, signature, gates, roots) |
| 2 | Per-gate details with failure reasons |
| 3 | Full tree stats with leaf counts |

## What Gets Verified

1. **Structure** — §3.1 mandatory directories and files
2. **Hash chain** — every INDEX entry hash matches file contents
3. **Manifest root hash** — `sha256(00_INDEX.json)` for bundle identity
4. **Merkle root** — real Merkle tree over entry hashes (domain-separated)
5. **Signature** — conformance report signature (when present)
6. **Gates** — L1/L2 gate pass/fail against 01_SCORE.json
7. **Attestation** — Ed25519 signature over release attestation (when downloading)

## Examples

```bash
# Verify a specific bundle with detailed gate output
npx @mindburn/helm-ai-enterprise --bundle ./artifacts/conformance --level L2 --depth 2

# Generate an HTML evidence report
npx @mindburn/helm-ai-enterprise --bundle ./evidence --report ./report.html

# Verify at minimal level
npx @mindburn/helm-ai-enterprise --bundle ./evidence --level L1 --depth 0
```

## HTML Report

The `--report` flag generates a single-file HTML evidence report suitable for embedding in audit documentation:

```bash
npx @mindburn/helm-ai-enterprise --bundle ./evidence --report ./helm-ai-enterprise-report.html
open ./helm-ai-enterprise-report.html
```

## Programmatic API

```typescript
import { verifyBundle, computeMerkleRoot, LEVELS } from "@mindburn/helm-ai-enterprise";

const result = await verifyBundle("./evidence", "L2");
console.log(result.verdict);          // "PASS" or "FAIL"
console.log(result.roots.merkle_root); // real Merkle root
```

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        s0["Quick Start"]
        s1["CI / Automation"]
        s2["Options"]
        s3["Output Depth"]
        output["Reader outcome"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        source["Verify HELM Conformance"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> s3
    s3 --> output

    %% Premium Styling Rules
    style source fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Operational Readiness

Use this page as the public operating layer for **Verify**. The source of truth is `helm-ai-enterprise/docs/public/reference/verify.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "Security & Trust"
canonical: "https://helm.docs.mindburn.org/security"
source: "helm-ai-enterprise/docs/public/security-landing.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/security-landing.md"
section: "security"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-13"
checksum_sha256: "sha256:841c7f05eafc019a5b8f602b59f8cedd19ecd21641bb7d0476a842d68a66f005"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Security & Trust

The security route is the public map for HELM security documentation. It points readers to the trust model, verifier model, credential handling, TCB policy, and threat model without duplicating the `/trust` source page.

## Audience

This page is for security reviewers, platform teams, procurement reviewers, and engineers who need to decide which HELM security document answers a concrete question.

## Outcome

After this page you should know where to inspect fail-closed execution behavior, signed receipt verification, credential boundaries, and trusted-computing-base assumptions. Use `/trust` for the main security model and the linked subpages for narrower review.

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Security["Security route"]
        Trust["/trust security model"]
        Credentials["Credential security"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        Threat["Threat model"]
        TCB["TCB policy"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Verify["Verifier trust model"]
        Evidence["Receipts and evidence packs"]
    end

    %% Operational Flow Edges
    Security --> Trust
    Security --> Threat
    Security --> TCB
    Security --> Credentials
    Security --> Verify
    Trust --> Evidence
    Verify --> Evidence

    %% Premium Styling Rules
    style Threat fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style TCB fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Evidence fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Source Truth

- `docs/public/security-and-trust/security-model.md`
- `docs/public/security-and-trust/threat-model.md`
- `docs/public/security-and-trust/tcb-policy.md`
- `docs/public/security-and-trust/key-management.md`
- `docs/public/security-and-trust/verifier-trust-model.md`
- `docs/public/reference/verify.md`
- `core/pkg/guardian/`
- `core/pkg/proofgraph/`
- `core/pkg/conform/`

## Review Path

| Question | Canonical page |
| --- | --- |
| What does HELM enforce before dispatch? | `/trust` |
| What is inside the TCB? | `/security/tcb-policy` |
| How are credentials scoped? | `/security/key-management` |
| How does the verifier avoid trusting prose? | `/security/verifier-trust-model` |
| What threat assumptions are in scope? | `/security/threat-model` |

## Boundary Notes

The `/security` route is intentionally a map, not a second security model. It
exists because the public navigation needs a stable security entry point while
the canonical model remains `/trust`. Keep the route narrow: link to the exact
security page that owns a claim, name the implementation path that proves it,
and avoid restating route tables, compliance mappings, or release promises that
belong elsewhere.

Security documentation must distinguish three classes of evidence:

- **Runtime controls:** policy evaluation, fail-closed behavior, credential
  scoping, verifier logic, and receipt emission implemented in code.
- **Operator procedures:** deployment, key handling, incident response, and
  runbooks that depend on the operator environment.
- **Release evidence:** checksums, SBOMs, attestations, signatures, and
  evidence bundles attached to a specific release.

Do not collapse those classes into a generic assurance claim. A reviewer should
be able to follow a security statement from this map to a source file, route,
test, release artifact, or narrower public page without relying on private
sales material.

## What This Route Does Not Claim

This route does not claim that every deployment is certified, audit-ready, or
fully compliant. HELM can provide verifiable execution evidence only for the
paths that are wired through its boundary and retained in receipts, proof
records, or release artifacts. Customer-specific controls such as cloud IAM,
network policy, key custody, log retention, and incident response remain the
operator's responsibility unless a narrower HELM document names the exact
managed surface. Keep public security copy precise: describe the control, point
to the implementation or verifier, then state the evidence a reviewer can
collect.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A security claim points only to this landing page | Move the claim to a specific source-backed security page. |
| `/security` and `/trust` drift | Keep `/security` as the map and `/trust` as the model. |
| A verifier claim lacks a command | Link it to `docs/public/reference/verify.md` or remove it. |
| A private deployment detail appears here | Move it to an authenticated operations page. |


---
title: "Chaos Testing"
canonical: "https://helm.docs.mindburn.org/security/chaos-testing"
source: "helm-ai-enterprise/docs/public/security-and-trust/chaos-testing.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/security-and-trust/chaos-testing.md"
section: "trust"
access: "public"
sensitivity: "public"
last_reviewed: "2026-04-30"
checksum_sha256: "sha256:0c2a412772851476d8cccff1fea238bcdc42339a71190f9591d4cf0e928e8703"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Chaos Engineering & Testing Scenarios (TEST-004)

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `security/chaos-testing`
- Source document: `helm-ai-enterprise/docs/public/security-and-trust/chaos-testing.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

## Overview

HELM chaos testing validates that the kernel degrades gracefully under adversarial conditions, maintaining security invariants (fail-closed, receipt generation, budget enforcement).

## Scenarios

### 1. Error Budget Exhaustion

**Goal**: Verify that builder/promotion endpoints return 429 when budget drops below 20%.

```bash
# Inject chaos (burns 30% budget per call)
curl -X POST http://localhost:8080/api/ops/chaos/inject \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Repeat until budget < 20%
curl -X POST http://localhost:8080/api/ops/chaos/inject \
  -H "Authorization: Bearer $ADMIN_TOKEN"
curl -X POST http://localhost:8080/api/ops/chaos/inject \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Verify generated-spec creation is gated
curl -X POST http://localhost:8080/api/v1/workspaces/$WORKSPACE_ID/generated-specs \
  -H "Content-Type: application/json" \
  -d '{"goal":"test governed generated-spec flow"}'
# Expected: 429 Too Many Requests with X-Gate-Enforced: BudgetExhausted
```

### 2. Signer Unavailable

**Goal**: Verify Guardian returns DENY verdict when signer is unavailable.

```go
// Test with nil signer
g := guardian.NewGuardian(nil, prg, registry)
decision, err := g.EvaluateDecision(ctx, req)
// Expected: err != nil (fail-closed)
```

### 3. Clock Drift

**Goal**: Verify that expired intents are rejected even with clock manipulation.

```go
// Inject a clock that returns past time
exec := NewSafeExecutor(dispatchers, guardian, proofgraph)
exec = exec.WithClock(func() time.Time {
    return time.Now().Add(-2 * time.Hour) // 2 hours in the past
})

// Execute with a valid intent — should detect expiration
result, err := exec.Execute(ctx, intent)
// Expected: err contains "expired"
```

### 4. Concurrent Storm

**Goal**: Verify kernel handles 1000 concurrent tool calls without race conditions.

```bash
# Run race detector with concurrent access
cd core && go test ./pkg/guardian/... -race -count=1 -timeout 120s
cd core && go test ./pkg/executor/... -race -count=1 -timeout 120s
cd core && go test ./pkg/firewall/... -race -count=1 -timeout 120s
```

### 5. Policy Graph Mutation

**Goal**: Verify that mutating the PRG after Guardian creation doesn't affect in-flight decisions.

```go
g := guardian.NewGuardian(signer, prg, registry)
// Modify PRG after creation
prg.AddRule("dangerous-tool", RequirementSet{...})
// Guardian should still use original snapshot
```

### 6. Malformed Input

**Goal**: Verify kernel rejects malformed JSON, oversized payloads, and invalid schemas.

```bash
# Malformed JSON
curl -X POST http://localhost:9090/v1/tools/execute \
  -H "Content-Type: application/json" \
  -d '{invalid json'
# Expected: 400 Bad Request

# Oversized payload (>1MB)
python3 -c "print('{\"data\":\"' + 'A'*2000000 + '\"}')" | \
  curl -X POST http://localhost:9090/v1/tools/execute \
  -H "Content-Type: application/json" \
  -d @-
# Expected: 400 or 413
```

## Automation

All chaos scenarios are automated via the race detector (`go test -race`) and the `TestPolicyFirewall_ConcurrentAccess` test in the firewall package.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        inject["Inject fault"]
        observe["Observe signal"]
        report["Update drill report"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        invariant["Check invariant"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        block["Block release"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["Capture evidence"]
    end

    %% Operational Flow Edges
    inject --> observe
    observe --> invariant
    invariant --> receipt
    receipt --> report
    invariant -->|fails| block

    %% Premium Styling Rules
    style invariant fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style block fill:#e53e3e,stroke:#9b2c2c,stroke-width:2px,color:#fff
```


## Operational Readiness

Use this page as the public operating layer for **Chaos Testing**. The source of truth is `helm-ai-enterprise/docs/public/security-and-trust/chaos-testing.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "Key Management"
canonical: "https://helm.docs.mindburn.org/security/key-management"
source: "helm-ai-enterprise/docs/public/security-and-trust/key-management.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/security-and-trust/key-management.md"
section: "trust"
access: "public"
sensitivity: "public"
last_reviewed: "2026-04-30"
checksum_sha256: "sha256:e9746bfeaca8de774fb6b38ad01a9489a66f33cb3dded68da3e02b9f6d564193"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Key Management

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `security/key-management`
- Source document: `helm-ai-enterprise/docs/public/security-and-trust/key-management.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

HELM uses layered credential protection with AES-256-GCM at-rest encryption and strict access controls.

## Current Architecture

| Layer | Mechanism |
|-------|-----------|
| At-rest encryption | AES-256-GCM with 256-bit derived key |
| Key derivation | PBKDF2-HMAC-SHA256, 600 000 iterations |
| Memory | Credentials zeroed after use via `memguard` |
| Access | Environment variable `HELM_CREDENTIAL_KEY` (bootstrap) |
| Rotation | `RotationManager` with configurable TTL and grace period |

## Key Storage

The credential encryption key is currently stored as an environment variable (`HELM_CREDENTIAL_KEY`). For production deployments, operators **SHOULD** use an external KMS:

### HSM / KMS Integration Path

| Provider | Integration | Status |
|----------|-------------|--------|
| AWS KMS | `aws-sdk-go-v2/service/kms` — use `GenerateDataKey` for envelope encryption | Planned |
| GCP Cloud KMS | `cloud.google.com/go/kms` — use `Encrypt`/`Decrypt` with symmetric keys | Planned |
| Azure Key Vault | `azkeys` SDK — use `WrapKey`/`UnwrapKey` for key wrapping | Planned |
| HashiCorp Vault | Transit secrets engine — use `encrypt`/`decrypt` endpoints | Planned |
| PKCS#11 HSM | `miekg/pkcs11` — direct HSM integration for hardware-backed keys | Planned |

**Envelope encryption pattern**: KMS encrypts a Data Encryption Key (DEK); the DEK encrypts credentials locally. Only the encrypted DEK is stored alongside the ciphertext.

## Key Rotation

The `RotationManager` (in `core/pkg/credentials/rotation.go`) supports:

1. **Automatic rotation** — configurable TTL (default: 90 days)
2. **Grace period** — old key remains valid for decryption during transition (default: 24 hours)
3. **Re-encryption** — all credentials are re-encrypted with the new key during rotation
4. **Audit trail** — rotation events are logged to the Guardian audit log

### Rotation Procedure

```bash
# 1. Generate new key
export HELM_CREDENTIAL_KEY_NEW=$(openssl rand -hex 32)

# 2. Trigger rotation (re-encrypts all stored credentials)
helm credentials rotate --new-key-env HELM_CREDENTIAL_KEY_NEW

# 3. Update environment
export HELM_CREDENTIAL_KEY=$HELM_CREDENTIAL_KEY_NEW
unset HELM_CREDENTIAL_KEY_NEW
```

## Recommendations

> [!IMPORTANT]
> For production deployments handling sensitive data, use an external KMS rather than environment variables for the master encryption key.

- **Development**: Environment variable is acceptable
- **Staging**: Use cloud KMS with IAM-scoped access
- **Production**: Use cloud KMS or HSM with audit logging and automatic rotation

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Key Management"]
        s0["Current Architecture"]
        s1["Key Storage"]
        s2["Key Rotation"]
        s3["Recommendations"]
        output["Reader outcome"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> s3
    s3 --> output

    %% Premium Styling Rules
```


---
title: "TCB Policy"
canonical: "https://helm.docs.mindburn.org/security/tcb-policy"
source: "helm-ai-enterprise/docs/public/security-and-trust/tcb-policy.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/security-and-trust/tcb-policy.md"
section: "trust"
access: "public"
sensitivity: "public"
last_reviewed: "2026-04-30"
checksum_sha256: "sha256:7d7826d98549311736c57e414f749140b5610ff586c87114c6e97b5a7b8b94b8"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM TCB Policy

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `security/tcb-policy`
- Source document: `helm-ai-enterprise/docs/public/security-and-trust/tcb-policy.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

## Trust Computing Base Principles

1. **Minimal Surface**: Only code that directly handles tool execution authorization,
   cryptographic signing, and policy enforcement lives in the TCB.

2. **Fail-Closed**: All PEP (Policy Enforcement Point) boundaries default to deny.
   Unknown tools, unvalidated args, drifted outputs are all blocked.

3. **Deterministic**: All canonicalization uses RFC 8785 JCS. All hashes are SHA-256.
   All signing uses Ed25519. No randomness in the decision path.

4. **Auditable**: Every action produces a ProofGraph node with Lamport-clock ordering.
   Evidence packs can be exported and independently verified.

## TCB Boundaries

```
                    ┌──────────────────────┐
   Untrusted        │     TCB Boundary     │      Trusted
                    │                      │
   LLM Output ────► │  PEP: Tool Args      │
                    │  Validation +        │──── Guardian PRG
   Connector   ◄─── │  Output Drift        │
   Response         │  Detection           │──── SafeExecutor
                    │                      │
   Human Input ────►│  Ceremony            │──── Crypto Signer
                    │  Validation          │
                    └──────────────────────┘
```

## Adding Code to TCB

Any code addition to TCB packages requires:
1. Deterministic behavior (no goroutines, no time-dependent logic in decision path)
2. Test coverage > 80%
3. No external network calls
4. No dynamic loading (no plugins, no reflection-based dispatch)
5. Reviewed via `helm-ai-kernel verify pack` evidence export

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        s0["Trust Computing Base Principles"]
        s1["TCB Boundaries"]
        s2["Adding Code to TCB"]
        output["Reader outcome"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        source["HELM TCB Policy"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> output

    %% Premium Styling Rules
    style source fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
```


## Operational Readiness

Use this page as the public operating layer for **TCB Policy**. The source of truth is `helm-ai-enterprise/docs/public/security-and-trust/tcb-policy.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "Threat Model"
canonical: "https://helm.docs.mindburn.org/security/threat-model"
source: "helm-ai-enterprise/docs/public/security-and-trust/threat-model.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/security-and-trust/threat-model.md"
section: "trust"
access: "public"
sensitivity: "public"
last_reviewed: "2026-04-30"
checksum_sha256: "sha256:90a8b1a6291d9efd28c1b5b0db725e800fb27066b4c77b05d28ccad83011b859"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Threat Model

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `security/threat-model`
- Source document: `helm-ai-enterprise/docs/public/security-and-trust/threat-model.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

## Trust Boundaries

```
┌─────────────────────────────────────────────────────┐
│                    UNTRUSTED                        │
│  LLM Provider · User Prompts · Connector Outputs    │
└───────────────────────┬─────────────────────────────┘
                        │
                  ┌─────▼─────┐
                  │ HELM      │  ← PEP boundary (schema + hash)
                  │ Kernel    │  ← Guardian (policy engine)
                  │           │  ← SafeExecutor (signed receipts)
                  └─────┬─────┘
                        │
┌───────────────────────▼─────────────────────────────┐
│                    TRUSTED                          │
│  Signed Receipt Store · ProofGraph DAG · Trust Reg  │
└─────────────────────────────────────────────────────┘
```

## Threat Categories

### T1: Unauthorized Tool Execution

**Attack:** Model generates a tool call not sanctioned by the current policy.

**Defense:** Guardian policy engine maintains an explicit allowlist. Undeclared tools are blocked before reaching the executor. Default-deny.

**Residual risk:** Runtime coverage must prove every advertised tool transport
is mediated before dispatch. Launchpad MCP mediation tests cover stdio in the
kernel CLI, HTTP JSON-RPC, `/mcp/v1/execute`, generated client configs, MCPB
packaging, and unsupported WebSocket fail-closed behavior.

### T2: Argument Tampering

**Attack:** Malicious input crafts tool arguments that bypass validation or alter semantics.

**Defense:**
1. Schema validation against pinned JSON Schema (fail-closed)
2. JCS canonicalization (RFC 8785) eliminates encoding ambiguity
3. SHA-256 hash of canonical args (`ArgsHash`) bound into signed receipt

**Residual risk:** Schema must be correct. HELM enforces the schema, not its semantic correctness.

### T3: Output Spoofing

**Attack:** Malicious connector returns data that doesn't match the declared output schema.

**Defense:** Output validation against pinned schema. Contract drift produces `ERR_CONNECTOR_CONTRACT_DRIFT` and halts execution.

**Residual risk:** Connector could return semantically wrong but schema-valid data.

### T4: Resource Exhaustion (WASI)

**Attack:** Uploaded WASM module consumes unbounded CPU, memory, or time.

**Defense:**
- Gas metering: hard budget per invocation
- Wall-clock timeout: configurable per-tool
- Memory cap: WASM linear memory bounded
- Deterministic trap codes on budget exhaustion

**Residual risk:** None for compute resources. Side-channels at the host OS level are out of scope.

### T5: Receipt Forgery

**Attack:** Attacker creates fake receipts to claim executions that didn't happen.

**Defense:** Ed25519 signatures on canonical payloads. Verification requires the signer's public key.

**Residual risk:** Key compromise. Mitigated by Trust Registry key rotation.

### T6: Replay Attacks

**Attack:** Attacker replays a valid receipt to re-execute an effect.

**Defense:**
- Lamport clock monotonicity per session
- Causal `PrevHash` chain (each receipt signs over previous receipt's signature)
- Idempotency cache in executor

**Residual risk:** None within a single session. Cross-session replay mitigated by session scoping.

### T7: Approval Bypass

**Attack:** Model or operator bypasses human approval for high-risk operations.

**Defense:**
- Timelock: approval window must elapse before execution
- Deliberate confirmation: approver must produce a hash derived from the original intent
- Domain separation: approval keys are distinct from execution keys
- Challenge/response ceremony for disputes

**Residual risk:** Social engineering of the human approver is out of scope.

### T8: Trust Registry Manipulation

**Attack:** Attacker adds a rogue key or revokes a legitimate one.

**Defense:** Event-sourced trust registry. Every key lifecycle event (add/revoke/rotate) is a signed, immutable event with Lamport ordering. Registry state is replayable from genesis.

**Residual risk:** Compromise of the registry admin key. Mitigated by ceremony-based key management.

### T9: Proxy Sidecar Attacks

**Attack vectors:**

1. **MITM between client and proxy:** Attacker intercepts traffic between the app and the local HELM proxy, injecting tool calls or modifying responses.

2. **Budget bypass:** Attacker circumvents budget enforcement by directly hitting the upstream API, bypassing the proxy entirely.

3. **Receipt store tampering:** Attacker modifies the JSONL receipt store on disk to cover traces or inject fake receipts.

4. **Session fixation:** Attacker reuses a session-scoped Lamport counter to replay receipts from a previous session.

5. **SSE stream poisoning:** In streaming mode, attacker injects partial tool_call fragments into the SSE stream to trigger unintended executions.

**Defense:**
1. Proxy binds to localhost only; TLS is recommended for remote deployments.
2. Budget enforcement is advisory in OSS sidecar mode. For hard enforcement, use `--island-mode` or deploy as a network gateway.
3. Receipts are Ed25519-signed. Tampered receipts fail `helm-ai-kernel pack verify`. ProofGraph DAG nodes have causal chain integrity (prevHash linking).
4. Session-scoped Lamport clocks with atomic increments. Cross-session replay detected by `helm-ai-kernel replay --verify`.
5. Streaming responses are buffered and validated before governance checks. Partial tool_calls are held until the complete SSE stream is received.

**Residual risk:**
- Local attacker with filesystem access can bypass the sidecar. This is inherent to sidecar architectures and mitigated by island mode for high-security environments.
- SSE streaming governance is eventual (validated after full buffering), not inline.
- Launchpad CONNECT proxy receipts prove destination allowlisting only. Payload
  contents remain encrypted and opaque without a token broker or model-gateway
  inspection path.

### T10: Launchpad Container Isolation Overclaim

**Attack:** A hostile local app or agent abuses Docker daemon, kernel, namespace,
or filesystem boundaries while the product claim implies stronger isolation than
the selected substrate provides.

**Defense:** Launchpad records an explicit isolation tier in substrate specs,
policy packs, runtime evidence, and start receipts. `docker-default` is a
baseline developer substrate. Hardened claims require Docker rootless/userns,
Docker ECI, gVisor, Kata/Firecracker, or dedicated VM evidence.

**Residual risk:** Baseline Docker remains inappropriate for hostile-code
claims. Unsupported or unconfigured hardened modes fail closed before launch.

## Out of Scope

- Content safety / prompt injection within the text domain
- Vulnerabilities in upstream LLM providers
- Host OS / hardware side channels
- Network-level attacks (TLS is assumed)
- Social engineering of human approvers

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Threat Model"]
        s0["Trust Boundaries"]
        s2["Out of Scope"]
        output["Reader outcome"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        s1["Threat Categories"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> output

    %% Premium Styling Rules
    style s1 fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
```


---
title: "Verifier Trust Model"
canonical: "https://helm.docs.mindburn.org/security/verifier-trust-model"
source: "helm-ai-enterprise/docs/public/security-and-trust/verifier-trust-model.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/security-and-trust/verifier-trust-model.md"
section: "trust"
access: "public"
sensitivity: "public"
last_reviewed: "2026-04-30"
checksum_sha256: "sha256:0aeb8d00e7eb308dea6799a85167620d3f07cdfb9e3bd2dd0ea979ac5b4b1a94"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Offline Verifier Trust Model

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `security/verifier-trust-model`
- Source document: `helm-ai-enterprise/docs/public/security-and-trust/verifier-trust-model.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

The HELM Offline Verifier is a standalone tool designed for high-assurance audits and air-gapped verification of EvidencePacks.

## Trust Assumptions
1. **Cryptographic Primitives**: The verifier trusts the mathematical correctness of Ed25519 signatures, SHA-256 hashes, and JCS (RFC 8785) canonicalization.
2. **Standard Compliance**: The verifier assumes the EvidencePack format adheres to the UCS v1.3 specification.
3. **No Network Trust**: The verifier does NOT require network access and does NOT trust results from the HELM server or any proxy.

## Verification Layers
1. **Structural Integrity**: Ensures the bundle contains required indices and manifests.
2. **Content Integrity**: Verifies that every file matches its hash in the signed manifest.
3. **Chain Integrity**: Validates the causal DAG (ProofGraph) and prevents reordering or deletion of events.
4. **Temporal Integrity**: Checks Lamport clock monotonicity across the event stream.
5. **Policy Binding**: Recomputes policy hashes to ensure the Kernel applied the correct rules.

## Auditor Mode
Using the `--json` flag, the verifier produces a machine-readable report containing every check performed, suitable for inclusion in formal compliance artifacts.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Offline Verifier Trust Model"]
        s0["Trust Assumptions"]
        output["Reader outcome"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        s2["Auditor Mode"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        s1["Verification Layers"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> output

    %% Premium Styling Rules
    style s1 fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style s2 fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
```


## Operational Readiness

Use this page as the public operating layer for **Verifier Trust Model**. The source of truth is `helm-ai-enterprise/docs/public/security-and-trust/verifier-trust-model.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "Integrate HELM in 10 Minutes"
canonical: "https://helm.docs.mindburn.org/start"
source: "helm-ai-enterprise/docs/public/getting-started/integrate-in-5-min.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/getting-started/integrate-in-5-min.md"
section: "start"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-04"
checksum_sha256: "sha256:fcf61af43fb4c1e84844c8fdc338c3d49457e5033eaddab30e0318795f66cc72"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Integrate HELM in 10 Minutes

This path gets a developer from a normal AI call to a governed call with a receipt that can be inspected and verified. The goal is not to read the architecture first. The goal is to see the boundary work.

## Audience

Use this guide if you are adding HELM to an application, evaluating the proxy path for an internal platform, or proving to a security reviewer that tool calls can be allowed, denied, receipted, and replayed without trusting the model provider.

## Outcome

At the end you will have:

- a local HELM boundary accepting OpenAI-compatible requests;
- one AI request routed through HELM instead of directly to the provider;
- one denied tool action with a reason code;
- one receipt or evidence bundle reference;
- a verifier command that returns deterministic pass/fail output;
- a short troubleshooting path for the common first-run failures.

## Request Lifecycle

```mermaid
sequenceDiagram
  participant App as Application
  participant Helm as HELM proxy
  participant Policy as Policy bundle
  participant Provider as Upstream model
  participant Proof as Receipt and evidence
  App->>Helm: OpenAI-compatible request
  Helm->>Policy: Evaluate identity, tool, args, egress, delegation
  alt allowed
    Helm->>Provider: Forward governed request
    Provider-->>Helm: Model response
    Helm->>Proof: Write receipt headers and evidence
    Helm-->>App: Response with X-Helm-* headers
  else denied or escalated
    Helm->>Proof: Write denial receipt
    Helm-->>App: 403 with reason code
  end
```

## Source Truth

The public docs route is backed by this file. Implementation truth is in the HELM runtime and the OSS verifier surfaces:

- `docs/public/product/integrations/openai-baseurl.md`
- `docs/public/reference/verify.md`
- `docs/public/product/integrations/mcp.md`
- `../helm-ai-kernel/docs/QUICKSTART.md`
- `../helm-ai-kernel/docs/VERIFICATION.md`
- `../helm-ai-kernel/docs/INTEGRATIONS/openai_baseurl.md`

If a command here disagrees with the implementation, the source files and verifier output win.

## 1. Start HELM

From the HELM repo:

```bash
docker compose up -d
curl -fsS http://localhost:8080/health
```

Expected output is an HTTP 200 health response. If your deployment exposes a separate health port, use the health URL shown by your compose or operator config.

## 2. Point One Client at HELM

HELM intentionally uses an OpenAI-compatible edge so most clients only change `base_url`.

```diff
- client = openai.OpenAI()
+ client = openai.OpenAI(base_url="http://localhost:9090/v1")
```

Full Python request:

```python
import openai

client = openai.OpenAI(base_url="http://localhost:9090/v1")

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Return the current policy status."}],
)

print(response.choices[0].message.content)
```

For Node.js:

```ts
import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "http://localhost:9090/v1",
});
```

## 3. Confirm Receipt Headers

Allowed requests should return HELM headers when the proxy path is active:

```text
X-Helm-Receipt-ID: rec_...
X-Helm-Output-Hash: sha256:...
X-Helm-Lamport-Clock: ...
```

The exact receipt ID and hash are runtime values. The important property is that the response is linked to a decision record, not just to a model completion.

## 4. Trigger a Deny

Use a tool name or argument shape that is not in the active policy bundle:

```bash
curl -sS http://localhost:9090/v1/tools/execute \
  -H 'Content-Type: application/json' \
  -d '{"tool":"unknown_tool","args":{"bad_field":true}}' | jq .
```

Expected shape:

```json
{
  "status": "DENIED",
  "reason_code": "DENY_TOOL_NOT_FOUND",
  "receipt_hash": "sha256:..."
}
```

The exact reason code depends on the active bundle and runtime adapter. Treat any allow on an unknown tool as a failed setup.

## 5. Verify the Evidence

Use the maintained verifier path for bundles produced by local runtime, CI, or release artifacts:

```bash
npx @mindburn/helm-ai-enterprise --bundle ./path/to/evidence --level L2 --depth 1
```

Expected result is a deterministic pass/fail summary. The verifier should not need the upstream model provider. It needs the bundle, policy/evidence material, and trust inputs required by the selected verification level.

## 6. Move From Verification to App

Before using HELM in a real app:

1. Pin the upstream URL and policy bundle.
2. Decide which effects require approval rather than automatic allow.
3. Store receipt IDs with the application action they governed.
4. Add a CI job that verifies representative bundles.
5. Expose receipt or proof links in your operator UI.

## Troubleshooting

| Symptom | Likely Cause | Fix |
| --- | --- | --- |
| Client still talks directly to OpenAI | `base_url` or `baseURL` was not changed | Log the request host and confirm it is `port 3000` or your HELM host. |
| Response has no `X-Helm-*` headers | Request bypassed HELM or proxy/header emission is disabled | Use the OpenAI base URL guide and check proxy logs. |
| Unknown tool is allowed | Wrong policy bundle or permissive dev policy | Load the intended bundle and rerun the deny step. |
| Verifier cannot find bundle material | Evidence export path is wrong | Use the receipt/evidence export produced by your runtime or CI job. |
| First request is denied | Identity, tool, or egress policy is missing | Inspect the denial receipt and add the smallest required grant. |

## Next Pages

- [OpenAI base URL integration](/integrations/openai-baseurl)
- [MCP integration](/integrations/mcp)
- [Verify HELM conformance](/reference/verify)
- [SDK documentation](/reference/sdks)


---
title: "Agent Skills Governance"
canonical: "https://helm.docs.mindburn.org/teams"
source: "helm-ai-enterprise/docs/public/product/agent-skills-governance.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/agent-skills-governance.md"
section: "teams"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-04"
checksum_sha256: "sha256:6105e219781bf625fea989e41737159d5b2bc56195008975fad05286ea0b4a4d"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Agent Skills Governance

HELM AI Enterprise turns the OSS execution boundary into a shared operating surface for groups that run AI agents, internal tools, and approval workflows together. The product goal is simple: every consequential action has an owner, a policy, a decision, and a receipt.

## Audience

Use this page if you administer a team workspace, design an approval flow, issue API keys, or evaluate whether autonomous work can be governed without forcing every developer to become a policy expert.

## Outcome

After reading this page you should be able to design a team rollout with:

- workspaces mapped to products, environments, or business units;
- API keys scoped to agents, services, and environments;
- role models for developers, approvers, auditors, and admins;
- policy bundles that define allowed, denied, and escalated actions;
- audit trails that connect every action to a receipt;
- team administration practices that preserve least privilege.

## Governance Lifecycle

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Workspace["Create workspace"]
        Roles["Assign roles"]
        Keys["Issue scoped API keys"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        Bundle["Attach policy bundle"]
        Review["Review, export, and refine policy"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Runtime["Route agent/tool calls"]
        Decision{"Allow, deny, or escalate"}
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Receipt["Receipt and audit trail"]
    end

    %% Operational Flow Edges
    Workspace --> Roles
    Roles --> Keys
    Keys --> Bundle
    Bundle --> Runtime
    Runtime --> Decision
    Decision --> Receipt
    Receipt --> Review
    Review --> Bundle

    %% Premium Styling Rules
    style Bundle fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Runtime fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Decision fill:#e53e3e,stroke:#9b2c2c,stroke-width:2px,color:#fff
    style Receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Review fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
```


## Source Truth

The public Individual route is backed by HELM product docs, the commercial `/api/basic` router, and the operator API surface:

- `commercial/basic/server.go`
- `commercial/basic/workspace.go`
- `commercial/basic/rbac.go`
- `commercial/basic/apikey.go`
- `commercial/basic/approval.go`
- `commercial/basic/evidence_index.go`
- `commercial/basic/runtime_bridge.go`
- `apps/helm-ai-enterprise/main.go`
- `docs/public/product/console-api.md`
- `docs/public/product/policy-bundles.md`
- `docs/public/product/policy-backends.md`
- `docs/public/security-and-trust/security-model.md`
- `docs/11_API_REFERENCE.md`

Use those references for exact endpoint names, payloads, and policy syntax.
Non-`/api/basic/*` commercial routes are not Individual API surface area. Billing,
trial, provisioning, admin, SCIM, and compliance endpoints are owned by the
commercial gateway and classified in `docs/11_API_REFERENCE.md`.

## Individual API Classification

The Individual API is mounted at `/api/basic/` by the commercial server. It is separate from the Console `/api/v1` route registry.

| Class | Routes | Use |
| --- | --- | --- |
| Workspace administration | `/api/basic/workspaces`, `/api/basic/projects`, `/api/basic/environments`, `/api/basic/members` | Create workspaces, project scopes, environments, and role assignments. |
| Keys and approvals | `/api/basic/keys`, `/api/basic/approvals` | Issue scoped API keys and request or inspect approval gates. |
| Evidence | `/api/basic/evidence` | Search evidence by workspace, project, run, decision, or principal. |
| Incidents and budgets | `/api/basic/incidents`, `/api/basic/incidents/transition`, `/api/basic/budget/record`, `/api/basic/budget/summary` | Track operational incidents and budget posture. |
| Plans and blast radius | `/api/basic/plans`, `/api/basic/plans/approve`, `/api/basic/plans/commit`, `/api/basic/blastradius` | Review, approve, commit, and estimate governed operational changes. |
| Notifications | `/api/basic/notifications/subscribe`, `/api/basic/notifications/emit` | Subscribe to or emit team notifications. |
| Runtime bridge | `/api/basic/runtime/start`, `/api/basic/runtime/stop`, `/api/basic/runtime/status` | Start, stop, or inspect workspace runtime state. |

## Workspace Model

A workspace is the administrative unit for a governed execution context. Most teams use one of three patterns:

| Pattern | Use When | Notes |
| --- | --- | --- |
| Product workspace | A product team owns agents and approvals end to end. | Good default for application teams. |
| Environment workspace | Staging and production need different policies. | Useful when production requires stricter escalation. |
| Business-unit workspace | Different units need separate auditors and retention. | Useful for regulated teams or internal platforms. |

Keep workspace boundaries aligned with who can approve an effect. Avoid a single shared workspace for unrelated applications.

## Roles

| Role | Typical Permissions | What They Should Not Do |
| --- | --- | --- |
| Developer | Create test agents, inspect denied receipts, request policy changes. | Approve their own production side effects. |
| Approver | Review escalations, approve bounded actions, add notes. | Modify policy bundles without review. |
| Auditor | Export receipts, verify evidence, inspect policy versions. | Execute tools or create new keys. |
| Admin | Manage workspaces, roles, keys, retention, and integrations. | Bypass policy evaluation. |

## API Keys

Keys should be scoped by workspace, environment, and agent class. A useful key name includes the owning service, environment, and purpose, for example `checkout-agent-prod-governed-tools`.

Minimum practice:

1. Create separate keys for local development, CI, staging, and production.
2. Rotate keys when a service owner changes.
3. Bind production keys to stricter policy bundles.
4. Store key issuance and rotation events in the audit trail.
5. Never use a human admin key inside an autonomous agent.

## Policy Bundles

Teams should treat policy bundles as versioned operational code. A bundle answers:

- which tools can be called;
- which argument shapes are allowed;
- which identities can act;
- which effects require approval;
- which egress destinations are blocked;
- what evidence must be retained.

Use the policy bundles reference for exact syntax. In a team rollout, start with a deny-by-default bundle, add one allowed workflow, then expand based on receipts rather than guesses.

## Approval Flows

Escalation should be reserved for actions where a human decision is meaningful:

- production deploys;
- outbound customer communication;
- financial or billing changes;
- data export;
- policy changes;
- destructive operations.

An approval event should record the requested action, policy version, approver identity, decision, timestamp, and receipt reference. Approval does not replace HELM evaluation; it becomes part of the evidence chain.

## Audit Trails

The audit trail is useful only if it can answer concrete questions:

- Who or what requested the action?
- Which workspace and policy bundle were active?
- What was allowed, denied, or escalated?
- Which receipt proves the decision?
- What changed after the decision?
- Can the receipt be exported and verified?

Teams should review denied and escalated receipts weekly during rollout. Denies reveal missing grants, unsafe tool shapes, and agents attempting actions beyond their intended scope.

## Redaction Boundary

Individual docs may show sample tenant, workspace, project, and environment IDs. They may describe key scopes and approval payload shapes. They must not show live API keys, raw customer evidence, session cookies, private tenant payloads, production webhook secrets, or unredacted SIEM export samples.

## Troubleshooting

| Symptom | Likely Cause | Fix |
| --- | --- | --- |
| Developers cannot reproduce production decisions | Dev and prod use different bundles without recorded versions | Pin bundle versions and show them in receipt metadata. |
| Too many escalations | Bundle is overly broad in effect classification | Split high-risk effects from routine allowed effects. |
| Receipts have unknown actors | Shared API key or missing agent identity | Issue per-agent keys and require identity claims. |
| Auditors cannot answer why a call was allowed | Missing policy version or source link | Require bundle hash and edit-source link in exports. |
| Policy changes are risky | No review workflow | Require a policy PR plus an approver before production attach. |

## Next Pages

- [Operator Console API](/product/console-api)
- [Policy Bundles](/product/policy-bundles)
- [Policy Backends](/product/policy-backends)
- [Security Model](/trust)


---
title: "Distributed Tracing"
canonical: "https://helm.docs.mindburn.org/tracing"
source: "helm-ai-enterprise/docs/public/tracing.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/tracing.md"
section: "helm-ai-enterprise"
access: "public"
sensitivity: "public"
last_reviewed: "2026-03-04"
checksum_sha256: "sha256:3f31d7737808bf464f715ed8a30e58527b58ec821d24787f5481b5235e85e3ba"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Distributed Tracing with OpenTelemetry

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `tracing`
- Source document: `helm-ai-enterprise/docs/public/tracing.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

HELM Kernel supports OpenTelemetry (OTEL) distributed tracing out-of-the-box. This capability allows you to visualize the full lifecycle of an AI agent's execution intent as it securely passes through the HELM architecture.

## Architecture

HELM instruments the critical path using `go.opentelemetry.io/otel`:

1. **API Gateway / Proxy**: Traces incoming external tool calls.
2. **Guardian (PEP)**: Records policy evaluations, temporal interventions, and context bounds.
3. **Safe Executor**: Traces the actual tool dispatch, cryptographic signature validation, and ProofGraph receipt generation.

## Running Jaeger Locally

To visualize these traces locally during development, HELM includes a Jaeger all-in-one Compose file:

```bash
cd deploy/
docker-compose -f jaeger-docker-compose.yml up -d
```

Jaeger's UI will be available at [http://localhost:16686](http://localhost:16686).

## Configuring the Kernel

To run the HELM server with tracing enabled, set the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable. By default, it will fall back to `localhost:4317` (the default Jaeger gRPC receiver port).

```bash
export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317
helm server
```

As the HELM server processes tasks, traces are batched and exported via gRPC to the configured collector.

## Integration

If you deploy HELM in a Kubernetes cluster, you can point the OTLP exporter to your OpenTelemetry Collector DaemonSet, which can route traces to Datadog, Honeycomb, New Relic, or AWS X-Ray.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        request["Governed request"]
        executor["Executor span"]
        collector["OTLP collector"]
        backend["Tracing backend"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        gateway["Gateway / proxy span"]
        guardian["Guardian decision span"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["Receipt span"]
    end

    %% Operational Flow Edges
    request --> gateway
    gateway --> guardian
    guardian --> executor
    executor --> receipt
    receipt --> collector
    collector --> backend

    %% Premium Styling Rules
    style gateway fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style guardian fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Operational Readiness

Use this page as the public operating layer for **Distributed Tracing**. The source of truth is `helm-ai-enterprise/docs/public/tracing.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.


---
title: "Security Model"
canonical: "https://helm.docs.mindburn.org/trust"
source: "helm-ai-enterprise/docs/public/security-and-trust/security-model.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/security-and-trust/security-model.md"
section: "trust"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-04"
checksum_sha256: "sha256:3eaa9480edd34c207405dbb87ef942d8e25346f01967f86986533e64f5bb48bb"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Security Model

HELM is a fail-closed execution boundary for AI agents, tools, connectors, and operator workflows. Its public security model is intentionally narrow: a request is either evaluated against a known policy and receipted, or the request does not execute.

## Audience

Use this page if you are reviewing HELM for a platform team, security team, enterprise evaluation, or audit-prep workflow. It explains what HELM tries to prove, what lives inside the trusted computing base, what evidence can be exported, and where to go for deeper threat-model and verifier details.

## Outcome

After reading this page you should be able to:

- identify the policy enforcement point for a governed action;
- explain why missing policy, schema, identity, budget, or evidence data fails closed;
- trace a receipt from request input to output hash and evidence pack;
- separate HELM kernel trust from upstream model-provider trust;
- give an auditor a concrete list of artifacts they can verify without reading private application code.

## Security Boundary

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        App["Application or agent"]
        Schema["Input and output schema checks"]
        Driver["Connector, tool, or model driver"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        PEP["HELM policy enforcement point"]
        Identity["Identity and session checks"]
        Policy["Policy bundle and budget gates"]
        Threat["Threat and egress checks"]
        Validate["Output validation"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Decision["ALLOW, DENY, or ESCALATE"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Receipt["Signed receipt"]
        Evidence["Evidence pack and proof graph"]
        Verify["Offline verifier"]
    end

    %% Operational Flow Edges
    App --> PEP
    PEP --> Identity
    PEP --> Schema
    PEP --> Policy
    PEP --> Threat
    Identity --> Decision
    Schema --> Decision
    Policy --> Decision
    Threat --> Decision
    Decision -->|ALLOW| Driver
    Decision -->|DENY or ESCALATE| Receipt
    Driver --> Validate
    Validate --> Receipt
    Receipt --> Evidence
    Evidence --> Verify

    %% Premium Styling Rules
    style PEP fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Identity fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Policy fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Threat fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Decision fill:#e53e3e,stroke:#9b2c2c,stroke-width:2px,color:#fff
    style Receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Validate fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style Evidence fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Verify fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Source Truth

This public page is the top-level trust entry. It is backed by:

- `docs/public/security-and-trust/tcb-policy.md`
- `docs/public/security-and-trust/threat-model.md`
- `docs/public/security-and-trust/key-management.md`
- `docs/public/security-and-trust/verifier-trust-model.md`
- `docs/public/reference/verify.md`
- `../core/pkg/guardian/`
- `../core/pkg/proofgraph/`
- `../core/pkg/conform/`
- `../core/pkg/identity/`

If a claim here conflicts with code, verifier output, or the more specific trust subpage, the specific artifact wins.

## Design Principle: Fail Closed, Proof First

HELM assumes the model, tool input, connector output, and external system can all be wrong or adversarial. The execution boundary therefore treats missing state as a denial condition. Examples:

| Missing or Invalid Material | Expected HELM Behavior |
| --- | --- |
| no policy bundle | deny or refuse startup, depending on deployment mode |
| malformed tool args | deny before driver execution |
| unknown tool or connector | deny with a reason code |
| budget lock cannot be acquired | deny rather than spend speculatively |
| upstream model fails | return an error path with no fabricated success receipt |
| receipt material cannot be written | fail the governed action rather than execute without evidence |

## Trusted Computing Base

The TCB is the smallest set of code and configuration a reviewer must trust for a HELM decision:

| Area | Responsibility |
| --- | --- |
| `guardian` | policy evaluation, privilege checks, threat gates, and fail-closed decision behavior |
| `identity` | principals, session binding, DID/verifiable credential helpers, and isolation checks |
| `manifest` and contracts | tool schemas, protocol shapes, and compatibility surfaces |
| `executor` and runtime boundary | the execution path that is allowed to call drivers |
| `proofgraph` and receipt code | decision DAG, causal hashes, receipt records, and verification material |
| `conform` | L1/L2/L3 conformance reason codes and validation behavior |
| deployment policy | bundle, environment, signing, retention, and approval configuration |

See [TCB Policy](/security/tcb-policy) for expansion rules. The short version is that a new TCB dependency needs explicit justification, tests, and maintainer review.

## Receipt And Evidence Chain

Every governed action should bind input, decision, output, and policy context. A normal receipt flow is:

1. canonicalize the request and tool arguments;
2. evaluate identity, policy, budget, egress, and schema gates;
3. execute only when the decision is `ALLOW`;
4. validate output shape and hash output material;
5. write a signed receipt and append it to the proof graph;
6. export an evidence pack when CI, compliance, or an auditor needs offline verification.

Auditors can verify receipt integrity, decision ordering, policy references, schema versions, and evidence-pack completeness. They cannot infer that an upstream model was correct; HELM proves what was governed, what was allowed or denied, and which evidence supports that decision.

## Threat Model Summary

HELM primarily defends against:

- prompt injection that tries to make a model misuse allowed tools;
- unauthorized tool use and connector scope escalation;
- schema drift between framework adapters and runtime tools;
- missing audit trails for autonomous actions;
- replay disputes where a later party claims a different output or policy was used;
- identity or credential reuse across principals;
- unbounded spend, egress, or privilege escalation.

For detailed threat categories and mitigations, use [Threat Model](/security/threat-model), [Key Management](/security/key-management), and the OSS OWASP mappings.

## Compliance And Supply Chain Evidence

HELM docs expose compliance mapping as evidence support, not as a blanket certification statement. Public reviewers should look for:

| Reviewer Question | HELM Evidence |
| --- | --- |
| What was the boundary? | TCB policy, threat model, deployment model, and policy bundle |
| Which action executed? | receipt ID, decision ID, output hash, and proof graph node |
| Which policy applied? | policy ref, bundle hash, schema version, and reason code |
| Can it be replayed? | evidence pack and verifier command |
| Was the build trusted? | SBOM, SLSA/provenance, Cosign signature, and release artifact checks where available |
| Which controls map to OWASP or AI RMF concerns? | OWASP mapping, NIST/ISO crosswalk, and compliance packs |

## Troubleshooting

| Symptom | Likely Cause | Fix |
| --- | --- | --- |
| an action executes without a receipt | the request bypassed HELM or receipt writing is misconfigured | check the OpenAI base URL or MCP integration path and runtime logs |
| every action is denied | policy bundle, identity, or fail-closed dependency is missing | inspect denial reason codes, load the intended bundle, and retry one low-risk action |
| verifier rejects a bundle | evidence export is incomplete or trust inputs do not match | regenerate the evidence pack from the source runtime and verify the bundle path |
| security reviewer asks for a certification claim | public docs overstate what HELM proves | point to evidence artifacts and remove any unsupported claim |
| upstream provider behavior differs | provider output is outside HELM's proof claim | verify decision and output hashes, then debug provider behavior separately |