Status: companion to the Workshop plan. Anonymised for the public repo. Where there is a real fork, the options are listed; the choice is the maintainer's.
1. The premise: the user is AI-first
The people building AI systems increasingly work through agents, or drive them all day. A developer in Claude Code does not open our website; their agent fetches, runs, and reports. The doctrine already says it: the visitor's AI is a seventh user, a first-class user rather than a feature. For this segment the agent interface is the product and the human page is the brochure.
The agent is both the maker and the buyer. It searches for the right configuration, forks a template, composes a stack from a goal, checks it, certifies it, and keeps it. Every one of those is an API call or a command. So "the site needs an API for AI use cases" is not a feature request; for this user it is the whole product surface.
"This" is the full range, not just Helm charts. The entry question is "find or help me build the right configuration or system for my goal; show me what it contains, what it needs, what has been checked, and what remains uncertain." The user might start with one chart, bring an existing application, adapt a stack, or ask their AI to assemble a platform. So the common machine interface must be designed for configs, charts, addons, apps, stacks, and platforms alike. Helm is an evidence-rich first case (the tables and records below are richest there), not the product's ceiling, and the choice of which system size to prove first is an open decision, not a claim that a chart is the entry.
The guiding principle, from the working record of August: an agent is correct in proportion to how much of the system can describe itself to the agent, and refuse the agent when it is wrong. The catalog is the encoded expertise. The records are the self-description. The composition verdict and the approval gate are the refusal. Everything below is in service of those three.
The persona for this document is a developer at work who uses Claude Code all day, starts from zero with nothing of ours installed, and has a real question. Section 8 walks their ladder.
2. What the agent needs to do
Nine steps, from a goal to a governed system. The last column is where the capability lives, and it is the architecture of the API.
| The agent needs to... | What answers it | Where it lives |
|---|---|---|
| Discover what fits (GPU, cloud, format, what it needs and provides) | search over machine-readable listings | the static hub |
| Resolve to exact versions and digests | canonical addressing: component, version, base, digest | the static hub |
| Compose a system from a goal | goal into a stack manifest (the composer) | local cub |
| Validate before anything runs | cub stack certify: CERTIFIED or REJECTED with reasons | local cub (the gate) |
| Fork for this environment | a derived variant with an upstream link | ConfigHub |
| Place: which of my clusters fits this? | placement as a query over the live fleet graph | ConfigHub SaaS |
| Land it (the button, many clusters) | cub fleet up | ConfigHub SaaS |
| Operate | release, promote, gate, roll back, watch drift | ConfigHub SaaS |
| Prove it to its operator | receipts, digests, evidence URLs | the static hub and SaaS |
Rows one and two are the hub: static, free, crawl-free. Rows three and four are the gate: local, free. Rows five to nine are ConfigHub. Rows four and six are the ones no one else offers to an agent: certification of a composition before it runs, and placement across clouds as a query.
3. The surface that exists today
Shipped, not planned. All static files are served with CORS * and strong ETags, which is what makes browser-side and agent-side consumption with zero server egress possible.
| Surface | What it gives an agent | Status |
|---|---|---|
site/llms.txt | the curated index of every machine and human surface, plus a machine contract: resolve the exact chart and version through changes.json and its schema_version; read coverage before citing a verdict, because missing coverage means not checked; use the canonical chart URL and cite the evidence URLs, because page copy is a guide and receipts hold the evidence; a breaking change uses a new major version; when an entry is absent, render locally and ask before filing a public issue | shipped |
site/catalog.json | the machine-readable catalog: components, retained versions, packaged configurations, counts, rendered_yaml_paths and rendered_yaml_sha256s per base, the repo data paths they come from; schema_version: "1" | shipped |
site/changes.json and changes.schema.json | the compact change feed: exact chart versions, aliases, package digests, declared coverage, canonical pages, evidence URLs; the versioned JSON Schema | shipped |
site/base-variant-records.json | source-neutral records joining each maintained base to its exact source, objects, OCI package, prerequisites, lifecycle routes, policy, and evidence status | shipped |
| six record schemas | review, workshop-result, workshop-ci-report, promotion-review, configuration-decision, changes: the versioned shapes for a reviewed result, a CI report, a promotion comparison, and an accepted decision | shipped |
site/.well-known/agent-skills/config-workshop/SKILL.md (v0.1.1) with references/processing-model.md and references/task-playbook.md, and index.json | an installable agent skill: four tasks (find a known answer, check my config, promote my config, keep the result); working rules (pin versions and digests, records over page copy, missing coverage is not checked, never print Secret values, preview before mutation); how to resolve, materialize, compare, and produce a reviewed result; the CI report | shipped |
site/ai.html | the human and agent entry page | shipped |
docs/agent/ (README, tasks, recovery, verification, catalog, human-agent doctrine, terms) | in-repo agent instructions, linked from the site's Docs | shipped |
the cub CLI and the workshop plugin | the action surface: check, compose, vary, render, publish, verify, certify, sandbox, upload, release, promote, fleet | shipped |
What this already is, and is not. Three things are shipped: a complete, read-only static API; a local action surface (the cub verbs, each of which runs today); and a skill that teaches an agent to use both. What is not shipped is the orchestrated search-to-fork-to-build-to-certify loop as one capability: the composer, the one-line pull, the placement-query surface, per-listing JSON, and the discovery and publish edges are all still to build (section 4). So a coding agent with a shell can run the individual steps today by fetching the corpus and calling cub, and stitch them itself; the loop as a single agent-callable orchestration is the target, not a shipped feature. When using this inventory to scope work or write agent instructions, keep three things apart: the available primitives (shipped), the demonstrated workflows (proved on specific examples), and the proposed orchestration (the loop, still to build).
4. The gaps
Concrete, verified against the shipped files.
| Gap | Why it matters | What it blocks |
|---|---|---|
No per-listing JSON at predictable URLs. Zero today; only the monolithic catalog.json, changes.json, and base-variant-records.json. | an agent must download the whole record set to answer one chart question, and cannot construct an address without crawling | rung 1 of the developer's ladder; every motion that starts from the catalog |
The skill is a task skill, not a ladder. It does the four tasks well but does not route zero-install first, does not offer the one-line install of cub and the plugin as the escalation, does not teach the doorway (cub server, upload) or the ConfigHub verbs, and carries no rung structure or wins-as-prompts. | the agent cannot guide a zero-install user up the ladder; it assumes tools are present | rungs 2 to 4 of the developer's ladder; progressive disclosure |
No one-line pull. There is no cub stack pull <listing>@<digest> --into <org> that pulls a certified system into an org in one command. | the from_pretrained moment for systems does not exist; pulling is several steps | the marketplace's "press a button" |
| Placement as a query is not a product surface. ConfigHub Where, labels, and triggers exist, but there is no agent-callable "which of my clusters fits this stack" call returning the fit, the plan, and the gaps. | the mission's stated differentiator is not exposed to the agent | the Place step; the paid edge |
| No composer. Nothing turns a goal into a candidate config, app, addon, or stack manifest, born as ConfigHub data. | the make half of the flywheel is manual | Compose; the generative hub |
No machine card per listing. The fields exist in base-variant-records.json (needs, provides, verdict, receipt, constraints) but not as a first-class per-listing document. | agents decide fit from a card; today they parse a record set | Discover |
| The read-only documentation MCP is deferred. The plan says: do not add a public MCP command until a real endpoint exists and is maintained. | agents without a shell have no action surface | reach beyond coding agents |
The marketplace's discover and publish edges. Three of five parts exist (variant is the listing, manifest is the template, cub fleet up is the button); discovery and vendor publishing do not. | the supply side is manual | the second ladder |
5. Static or SaaS: the split
Not a choice between them; a split along the boundary the doctrine already enforces.
| Layer | What it holds | Why there | Examples |
|---|---|---|---|
| Static, predictable URLs (the Moat's read side) | the public, anonymous, read catalog: listings, machine cards, evidence, receipts, the skill | crawl-free, cacheable, CORS *, no auth, zero egress; the encoded expertise the hyperscaler cluster tools do not have; commodity-resistant because the value is the evidence, not the tool-calling | llms.txt, catalog.json, changes.json, per-listing JSON, SKILL.md |
Local cub (the Moat's tools) | compose, check, certify, render, publish OCI | free, no account, private input stays local; the gate runs where the user is | cub config check, cub stack certify, cub stack sandbox |
| ConfigHub SaaS (the Castle) | per-org state: where a fork lands, placement over the live graph, release, promote, gate, roll back, fleet | placement is a query over your live fleet graph, which only ConfigHub holds; custody and governance are per-org and authenticated | cub variant create, cub variant upload, cub release publish, cub fleet up, Where and labels |
The agent interface spans three independent axes; do not collapse them into one line.
- Data locality: public, anonymous reads (the static corpus) versus private, per-org state (your Units, Spaces, and live fleet graph).
- Execution locality: local computation (
cubfor compose, check, certify;cub serverfor a local ConfigHub) versus hosted computation (ConfigHub SaaS). - Entitlement: free versus paid.
These are separate decisions. Compose, check, and certify are local and free. The doorway itself can be local and free: cub server runs ConfigHub on your own machine, so private per-org state does not by itself require paid SaaS or a hosted service. Hosted-versus-self-hosted deployment and free-versus-paid entitlement are additional decisions layered on top, not the same boundary as the read/action split.
On the standing objection that config is not enough and there has to be code behind it: the code behind it is the engine over config-as-data (section 7 of the umbrella). It runs locally through cub and cub server and at scale through ConfigHub SaaS. The place a hosted service earns is the placement query over a large, live, multi-cluster fleet graph, and shared governance across a team, not every stateful action.
6. ConfigHub as the foundation: every motion maps to a primitive
The AI-led marketplace is a thin agent-facing façade over primitives that already exist. Almost every motion has a ConfigHub home.
| Marketplace or AI-led motion | ConfigHub foundation | cub verb |
|---|---|---|
| Search or find the right config, addon, or stack | the public catalog for read; your components and Units for org state | browse the catalog; query Units |
| Fork a template or listing | a derived variant on a base, in a Space, upstream-linked | cub variant create |
| Build or compose a system from a goal | a stack (manifest) of components, then certify | cub stack certify, then cub stack upload |
| A listing (the marketplace item) | a base variant, or a released OCI | cub variant upload, cub release publish |
| Publish (a maintainer participates) | upload a base variant and release it as OCI | cub config check --out oci://..., cub release publish |
| The button (land in my org, many clusters) | Spaces, targets, fleet placement | cub fleet up |
| Placement query ("this cluster has the right GPU") | ConfigHub Where, labels, triggers over the live graph | where-clauses, cub fleet status |
| Govern | ConfigHub governance | release, promote, gate, roll back |
Two consequences. The API layer builds almost no new backend: it translates a goal into these operations and lets the composition verdict refuse a bad one. Fork is not a new object; it is a derived variant. Build is not a new object; it is a stack plus certify. And the delta is nameable: the composer (goal into a candidate), the marketplace's discover and publish edges, and richer agent-facing read (per-listing JSON, machine cards).
7. The AI-first flywheel: what AI makes, and where
People, with their AI, will make more configs, apps, addons, and stacks. The question is where. Made as loose files in a repo, AI output is untrusted code with no lineage. Made in ConfigHub, it is data, certified, traceable, governable, publishable.
| Someone, with AI, makes a... | It is, in ConfigHub | Born via | Hugging Face analogue |
|---|---|---|---|
| config | a base or derived variant | cub variant create, cub config check | fine-tune |
| app | a workload with its needs declared, placed on a stack | cub app check | |
| addon | a component composed into a stack | manifest edit, cub stack certify | adapter |
| stack | a stack manifest, a platform once governed | cub stack certify, cub stack upload | a new model |
| ...published back | a listing: a base variant or released OCI | cub variant upload, cub release publish, cub stack publish | push_to_hub |
Lineage is the trust feature of AI-made config. Upstream links, digests, and receipts answer where it came from, what changed, and whether it is safe.
**Config as data is what makes AI creation checkable, and it is checkability, not a universal guarantee, that we claim.** Being stored as data does not by itself certify a configuration or prove it is safe. What data buys is that the AI's proposal is something the engine can read and refuse rather than something that must be run to be understood. Keep three distinct things apart, each with its own scope:
- an advisory local check (
cub check) inspects rendered objects; the skill states plainly that it does not authorize an apply or prove destination acceptance, runtime health, upgrade, or rollback; - composition certification (
cub stack certify) refuses a stack whose parts conflict before it renders; this is proved on specific examples (eks-inferencecertified,metrics-doublerefused), and one deterministic agent-authored change is recorded rejected with Kubernetes apply not run (data/ai-change-review/summary.md); - release authorization is a separate, revision-bound ConfigHub apply gate (for example
vet-approvedby): a release is refused until an approval clears for exactly that revision, and the next change is gated again.
"Nothing runs until certified" is the design intent of that revision-bound gate, not a property that flattening confers on its own. Where the gate is enforced is ConfigHub's apply path, not the local check.
8. The developer's ladder: progressive disclosure from inside the agent
The rule: the question determines the rung, the skill routes, and nothing is gated behind an install or a sign-up when a lower rung can answer it. Every rung delivers a win before the ask.
| Rung | The developer's Claude does | The win | What pulls them up | What we need |
|---|---|---|---|---|
| 0. Discovery | asks a config question; Claude knows to look at us | a tested answer exists | a real question | be in the model's knowledge and the registries; llms.txt |
| 1. Public API, zero install | fetches a predictable URL | a cited, exact answer about a tested chart (objects, hooks, CRDs, receipt), nothing installed, nothing signed up for | a chart we lack, or their own values | per-listing JSON at predictable URLs |
| 2. The skill | loads SKILL.md | multi-step tasks done right (resolve, read coverage, cite); knows when to escalate | their question needs local computation | the skill as the ladder's controller; wins as prompts |
3. Install cub + the workshop | one line, no account | exact answers about their config; CERTIFIED or REJECTED; a verified OCI their Flux or Argo can pull | they want to keep, share, or place it | the skill's one-line install and escalation; "entry absent, render locally" as the on-ramp |
| 4. The doorway | cub server in twenty seconds, then upload to their org | kept as data with lineage; vary, promote, place | the team, then the fleet | the skill teaches the doorway and the ConfigHub verbs |
| 5. Make more, publish back | composes a variant, addon, or stack; certifies; publishes | their derivative is a listing others' agents pull | the composer; the publish-back loop |
Principles the ladder forces: the skill is the protagonist for a Claude Code user (it is the first thing to get, it knows the API, and it is the progressive-disclosure controller); failure is the on-ramp (the machine contract already says: when an entry is absent, render locally, which is rung 3); private input stays local through rung 3 and only rung 4 moves data, into the developer's own org; the doorway is a reward, not a toll; instrument every rung (API hits, skill installs, plugin installs, first certify, first cub server, first upload, first release, first publish back).
9. Machine cards: the per-listing format
A proposal for the missing per-listing document, building on base-variant-records.json. Every listing (a base variant, a stack) gets one card at a predictable URL.
| Field | What it says | Source today |
|---|---|---|
| identity | component, version, base, digest, canonical URL | changes.json, records |
| what it needs | CRDs, Secrets, controllers, hardware (GPU class), cloud, namespaces that must exist | records: prerequisites, lifecycle requirements, target facts |
| what it provides | the objects, the services, the CRDs it installs | records: object inventory |
| verdict | flattening lane; certify result where it is a stack | records: flattening verdict; composition verdict |
| receipt | what was checked, what did not run, evidence URLs | receipts |
| placement constraints | plane, order, route intents, where it can and cannot land | records: routes; the manifest |
| lineage | upstream base, derived variants known, publisher | ConfigHub links; OCI provenance |
Agents read the card to decide fit; humans see it rendered as the listing page.
10. Delivery options
Listed as options. The considerations under each are the ones raised in the record and in discussion.
Option 1. Skill-first, no new server. Make SKILL.md the ladder's controller, ship per-listing JSON, and treat cub as the action surface. Optimises for: the coding-agent user (Claude Code, Codex, Cursor), who already has a shell and web fetch; zero hosting; plays to the moat (the corpus and the gate) rather than the protocol. Leaves out: agents without a shell.
Option 2. The static-plus-SaaS split with an org-scoped SaaS API. Keep the public catalog static; expose fork-into-org, placement-as-query, and govern as ConfigHub's own authenticated API for agents. Optimises for: the paid edge; the differentiator (placement by query) as a product surface; custody stays in ConfigHub. Leaves out: nothing on the read side; it is the Castle's API.
Option 3. MCP. Three positions have been argued:
- (a) lead with an MCP server as the agent interface;
- (b) treat it as distribution, built later, exposing catalog, tools, and doorway, local for the free path and hosted and org-scoped for the SaaS path, listed in the registries for one-click install into Claude, Cursor, and Codex;
- (c) skip it: the skill plus
cubplus the static catalog is the interface.
Considerations: for a be-the-default mission the channel into the agent toolchain matters, the way pip install transformers did for Hugging Face; the moat is what the tools expose, not the protocol; hyperscaler MCPs (EKS, GKE, AKS, OpenShift) will own "operate my cluster," a layer the Workshop should not compete on; the earlier plan says do not add a public MCP until a real endpoint exists and is maintained; MCP is the only route to agents without a shell; a protocol boundary can make the refusal structural (the agent cannot mutate without passing the gate).
Option 4. The one-line pull as the hero. cub stack pull <listing>@<digest> --into <org> --where '<placement>': the from_pretrained moment for systems, with certify in the path. Optimises for: the mission's "press a button"; a single memorable surface. Leaves out: it presumes the doorway and the org.
Option 5. The refusal gate as the trust product. Position certify not as a check but as agent-safe infrastructure: let your agent build the system, and the engine refuses the ones that will not hold together. Optimises for: a CISO and platform-team sentence no one else can say; the AI-era argument for the Castle. Leaves out: it is positioning, not a surface.
| Option | What it optimises for | Cost | Risk |
|---|---|---|---|
| 1 Skill-first | coding agents; zero hosting; the moat | low | no reach to non-shell agents |
| 2 Static + SaaS API | the paid edge; placement by query | medium (SaaS API design, auth for agents) | none on read; scope creep on write |
| 3a MCP first | toolchain distribution | high (build, host, version, secure) | competing on a commoditising protocol before the corpus is complete |
| 3b MCP later | distribution when the corpus is ready | medium | timing |
| 3c No MCP | simplicity | none | missing the registries and non-shell agents |
| 4 One-line pull | the mission's button | medium (a new verb) | presumes the doorway |
| 5 Refusal gate | positioning | none | claims must stay honest about limits |
Options 1, 2, 4, and 5 combine. Option 3 is the fork.
11. A proposed sequence, for decision
Steps that do not depend on the open decisions first.
- Per-listing JSON at predictable URLs. Needed by every option.
- Machine cards as the per-listing format (section 9).
- The skill as the ladder's controller (zero-install first; one-line install as escalation; the doorway and the ConfigHub verbs; wins as prompts).
- Make the doorway frictionless and measure it (
cub server, one-command upload; time from a certified result to the first Space). - Instrument the rungs.
- Prove the loop on the cohort and on the developer's ladder with fetch and
cub, no new server. - Decide option 3 (MCP) and option 4 (the one-line pull), then build what is chosen.
- Placement as a query as an agent-callable surface (option 2).
- The composer, born in ConfigHub, gated by certify. A basic composer over the public catalog; a composer that learns from an org's derivation graph as the Castle's edge.
12. Open decisions, with their options
- MCP: 3a, 3b, or 3c.
- The hero surface: the one-line pull, the skill, or the machine card.
- Per-listing granularity: one card per base variant, per version, or per component with versions inside.
- How an agent authenticates at the doorway: the user's
cublogin; a scoped agent token; the SaaS API's own auth. - The composer's free and paid line: open over the public catalog; learning from an org's derivation graph; both.
- Which ladder framing leads (the umbrella plan, section 4), because it decides what the skill routes first.