Platform Reference

The public, agent-consumable surface of the nanohype stack. If you’re building an AI client — a Bedrock agent, a Claude Code session, a custom orchestrator, an OpenAI Assistant, anything that produces software — and you want it to deliver shipped k8s-native applications, start here.

This page is the front door. Everything else (catalog manifest, standards, per-repo agent docs, the SDK, the MCP server) is one link away.

Who this is for

You’re building an AI client that needs to:

Discover what templates and composites are available (catalog.json, the SDK, or @nanohype/mcp)
Understand the production bar every build is measured against (standards/)
Know the shape of the deploy substrate (AGENTS.md in each supporting repo)
Render templates programmatically without re-implementing the scaffolding contract (@nanohype/sdk)
Optionally, expose all of the above as MCP tools to its own LLM (@nanohype/mcp)

If you’re a human reading this looking for “how do I use the templates,” skip down to Quickstart. If you’re an agent author looking for “what’s the architecture,” start with The stack below.

The stack

Nine public repos form the system: the catalog you’re reading, the deploy substrate it targets, the tooling that operates that substrate, and fab — the reference factory client, open-source so you can clone it, configure your skills overlay, and run your own factory.

Each one ships an AGENTS.md at its root. The machine-readable list is the SDK’s CONTRACT_REPOS, and loadContract(repo) fetches any of them.

Repo	Role	Agent entry point
`nanohype/nanohype`	Template catalog + SDK + the public Platform Reference itself (this file)	`AGENTS.md`
`nanohype/landing-zone`	OpenTofu/Terragrunt monorepo. Cloud substrate: VPC, base IAM, KMS, observability, and the generic `tenant-substrate` module that provisions a tenant’s datastores from `Platform.spec.datastores`	`landing-zone/AGENTS.md`
`nanohype/eks-gitops`	ArgoCD addon catalog for EKS clusters (App-of-Apps pattern)	`eks-gitops/AGENTS.md`
`nanohype/eks-agent-platform`	k8s-native control plane. Owns the `Platform` / `AgentFleet` / `ModelGateway` / `BudgetPolicy` / `EvalSuite` CRDs	`eks-agent-platform/AGENTS.md`
`nanohype/eks-fleet`	Cluster factory. Vends EKS clusters via Crossplane from a `Cluster` API	`eks-fleet/AGENTS.md`
`nanohype/kx`	Local kind workspace that mirrors `eks-gitops`. Run the same charts locally before deploying	`kx/AGENTS.md`
`nanohype/cloudgov`	AWS security & cost governance CLI. IAM least-privilege, cost, infrastructure hygiene, security posture, plus a Platform-tenant conformance auditor	`cloudgov/AGENTS.md`
`nanohype/portal`	Self-hosted operations portal. Go API + React SPA that runs the cloud substrate from one UI with one audit trail	`portal/AGENTS.md`
`nanohype/fab`	Reference factory client. Orchestrates 80 Claude agents across Discovery → Design → Build → Verify → Ship. Four transports, selected by `FAB_RUNTIME`. Ships the quality-check rubric and per-role curation and engineering baselines in `skills/`; overlay your personal recipe via `~/.fab/skills/`	`fab/skills/README.md`

The boundary between layers:

Slow-moving cloud infra (VPC, base IAM, KMS keys, cost pipeline, EventBridge, WAF) → landing-zone
Per-tenant identity + access (the tenant IAM role, its scoped datastore-access policy generated from spec.datastores, its capability-access policy generated from spec.identity.capabilities, KMS grants, Bedrock model-access) → eks-agent-platform operator reconciles via AWS SDK
Model path — inference is Bedrock in the tenant’s own account, including open-weight models via Bedrock Custom Model Import (routed by a ModelGateway modelSource: imported route referencing the imported-model ARN). Embeddings stay on Bedrock foundation embedding models — Custom Model Import does not support embedding models. In-cluster model serving is not a supported shape, and GPU nodes are not part of the model story: open-weight flexibility comes through the ordinary Bedrock runtime with no accelerators
Per-tenant stateful substrate (databases, buckets, queues, caches, streams) → declared in Platform.spec.datastores, provisioned by the generic tenant-substrate landing-zone module — no per-app component
Per-tenant managed capabilities (SES send, EventBridge Scheduler) → declared in Platform.spec.identity.capabilities, the operator generates the scoped grants (and mints the scheduler-invoke role) — no per-app policy
Per-tenant secret reads → secrets projected into the pod by the chart’s ExternalSecret are read by the External Secrets controller’s own identity (no tenant-role grant); the few a pod reads itself via the SDK are declared in Platform.spec.identity.directSecretReads, and the operator grants read on exactly those
Cluster addons (cert-manager, external-secrets, Kyverno, observability) → eks-gitops
Local development → kx (kind cluster mirroring eks-gitops)
Application logic → templates from nanohype/templates/ scaffolded into an <app>/chart/ + <app>/platform.yaml

If you find yourself producing cloud resources inside an application chart, you’re in the wrong layer.

Catalog

The machine-readable index of every template and composite is committed at the repo root as catalog.json. Stable GitHub raw URL for fetch-from-anywhere consumers:

https://raw.githubusercontent.com/nanohype/nanohype/main/catalog.json

Validated against schemas/catalog.schema.json on every PR. Re-generated deterministically by npm run generate:catalog.

Templates (templates/<name>/) scaffold files directly. The full contract is in docs/spec/template-contract.md; the rendering algorithm is in docs/spec/consumer-guide.md. Categories: ai-systems, applications, infrastructure, composable-modules, plus non-engineering personas (design, qa, product, marketing, sales, operations, customer-success).

Composites (composites/*.yaml) are pre-baked multi-template stacks for common engagement shapes (agent-team, ai-chatbot, enterprise-ai, etc.). The composite contract is in docs/spec/composite-contract.md.

Standards

The production bar every build meets, in machine-readable JSON under standards/:

File	What it declares
`language-toolchain.json`	Per-language `{install, build, lint, test, docs}` command sets + manifest, lockfile, registry, version-lookup
`version-currency.json`	EOL policy, version floor, accepted `@pin` reasons, per-language registries
`platform-tenant-contract.json`	The required artifacts (chart, ApplicationSet entry, Platform CR), the minimum Platform CR shape, OTel resource attrs, and the chart rules with their severities (no in-chart IAM role, no chart-owned ServiceAccount, no role-arn annotation)
`llm-policy.json`	Bedrock-primary, gateway-first auth (on the substrate the app holds no model credential and calls its Platform’s `ModelGateway`; off it, an assumed IAM role such as GitHub OIDC on a CI runner; no provider API key anywhere), model tiers (sonnet default / opus escalation / haiku light), the deploy region, prompt-caching requirement
`quality-rubric-dimensions.json`	The ten quality dimensions every build is graded against, and the ids every other standard’s `grades` field draws from. Dimension names + summaries only — reviewer assignments and merge-gate enforcement live in the reference client
`testing-rubric.json`	The testing-strategy bar — per-language coverage floors enforced in-config, the testing-trophy shape, and `security-critical-100` (100% on audit ledgers, auth, and approval gates)
`resource-tagging.json`	The org-wide tag/label taxonomy every cloud resource and k8s object carries — vendor-neutral dimensions, per-surface rendering (AWS tags, k8s labels, OTel attributes), casing transforms, required tiers
`resource-naming.json`	The naming grammar for cloud and k8s resources — the env-first cloud vs. environment-token-free k8s split, the cluster-identity model, reserved environment values, collision + length guards
`observability-slo.json`	RED for services, USE for resources, the four golden signals, and at least one SLO with a multi-window multi-burn-rate error budget. Fixes the dashboard a system ships to represent itself, plus the fleet-alerting contract — severity tiers, standard alarm dimensions, and per-cluster composite rollups so a hard-down cluster pages once
`telemetry-pipeline.json`	How telemetry travels — the OTLP collection contract every workload emits against one collector-agnostic endpoint, the `floor`\|`full` cluster tier that changes only where signals land, the events the platform publishes when telemetry makes it act, and the SSM paths a client discovers those resources from
`seo-baseline.json`	The discovery surface every public site the factory ships presents — canonical-host rule, required files (robots.txt, sitemap.xml, llms.txt, og.png), required head tags
`documentation-voice.json`	How prose is written on every surface a human reads — markdown, code comments, schema descriptions, CLI help, error strings — citing the Google developer documentation style guide and OKF, plus the four rules neither covers
`agent-access.json`	The AI agents and search crawlers every public deliverable admits — the fetcher roster by token, operator and class, and the robots.txt, edge and live-probe rules that keep search-index and user-initiated fetchers reachable while a site opts out of training

Each file is validated against schemas/standards.schema.json, and declares applies_to (the deliverables it governs, with any stack scoping) and grades (the quality dimensions a violation is graded on); every rule carries a reject or warn severity. standards/README.md is the human-readable normative form.

What’s intentionally not in this directory: the merge-gate choreography, the per-reviewer dimension assignments, the agent roster, the factory preamble prompt, and the orchestration code that produces consistent output against this bar. Those live in the reference client. The cut is deliberate — publishing the guardrails everyone has to meet, keeping the choreography that consistently hits them.

Deploy contracts

Each repo in the stack has an AGENTS.md at its root — short, agent-facing, answers “what does this repo give me and how do I add a new thing here.” Read these in order if you’re learning the stack cold:

nanohype/AGENTS.md — templates + SDK + catalog. The starting point.
eks-agent-platform/AGENTS.md — the CRD surface. Platform / AgentFleet / ModelGateway / BudgetPolicy / EvalSuite. How to declare a tenant.
landing-zone/AGENTS.md — cloud substrate. The tenant-substrate module driven by Platform.spec.datastores. Pod Identity setup.
eks-gitops/AGENTS.md — addon catalog. ApplicationSet entry shape. Sync waves.
eks-fleet/AGENTS.md — the Cluster API. How a cluster gets vended.
kx/AGENTS.md — local kind mirror. When to use it.
cloudgov/AGENTS.md — the governance checks your output is audited against.
portal/AGENTS.md — the operations surface over the substrate.
fab/AGENTS.md — the reference factory client, if you’re studying how one consumes all of the above.

If you’re skipping straight to delivery, only eks-agent-platform/AGENTS.md is mandatory — its Platform CR is what your output must conform to.

SDK

@nanohype/sdk is the reference TypeScript implementation of the catalog + standards consumption pattern. One runtime dependency (a YAML parser).

import {
  LocalSource,
  loadCatalog,
  loadStandards,
  renderTemplate,
} from "@nanohype/sdk";

// Discovery — LocalSource takes { rootDir }, not a bare path string
const source = new LocalSource({ rootDir: "/path/to/nanohype-repo" });
const catalog = await loadCatalog(source);
const standards = await loadStandards(source);

// Selection (your client decides which template fits)
const templateName = catalog.templates.find(
  (t) => t.category === "ai-systems" && t.tags.includes("rag"),
)?.name; // e.g. "rag-pipeline"

// Fetch skeleton, then render — renderTemplate is sync and writes nothing to disk
const { manifest, files } = await source.fetchTemplate(templateName!);
const result = renderTemplate(manifest, files, {
  ProjectName: "my-rag-bot",
  LlmProvider: "gateway",
});
// result.files — SkeletonFile[] with rendered paths and content
// consumer writes them (and runs hooks) however it likes

For agents running remotely without a checkout, use GitHubSource instead (new GitHubSource({ repo: "nanohype/nanohype" })) — same CatalogSource API, fetches manifests from the GitHub API.

loadStandards() returns a typed bundle covering every standards file. loadContract(source, repo) fetches the corresponding AGENTS.md so your agent can present the deploy contract for any specific repo. See docs/spec/consumer-guide.md for the full rendering algorithm.

MCP server

For agents running inside Claude Desktop, Claude API tool-use, or an MCP-capable runtime (some Bedrock agent configurations), @nanohype/mcp exposes the whole reference as MCP resources and tools.

// Claude Desktop config snippet (claude_desktop_config.json)
{
  "mcpServers": {
    "nanohype": {
      "command": "npx",
      "args": ["-y", "@nanohype/mcp"],
    },
  },
}

Resources: nanohype://catalog, nanohype://standards, nanohype://standards/{name}, nanohype://contracts/{repo}, nanohype://template/{name}, nanohype://composite/{name}.

Tools: search_templates(query, category?, persona?), get_template(name), get_composite(name), list_standards(), get_standard(name), get_contract(repo).

Full integration snippets for Claude Desktop, Claude API tool-use, and AWS Bedrock agent registration live in the MCP package’s own README.

Reference client

fab is the open-source reference implementation of “AI client consuming this Platform Reference to produce shipped software.” Clone it to study, fork it to extend, or — most likely — install it and configure a personal skill overlay to layer your opinions on top without forking.

Fab runs the same workflows against four transports:

managed-agents (default) — Anthropic-hosted REST API. Sessions + sandboxes live on Anthropic infrastructure.
sdk — @anthropic-ai/claude-agent-sdk running the agent loop in fab’s own process.
sdk-k8s — the sdk loop, each role-session dispatched as its own isolated pod on the eks-agent-platform substrate.
claude-cli — a claude -p subprocess per role-session, billed against your Claude subscription.

Pick by setting FAB_RUNTIME=managed-agents | sdk | sdk-k8s | claude-cli. All four are behaviorally 1:1 for the application-level workflow flow; transport-level trade-offs (durability, sandboxing, deploy step, threading) are documented in fab/docs/transports.md.

The overlay system. Fab bundles the quality-check rubric and per-role curation and engineering baselines as markdown files in fab/skills/. When loading a skill, fab walks four locations in priority order — $FAB_SKILLS_DIR → ~/.fab/skills/ → <cwd>/.fab/skills/ → bundled — and the first match wins as the base. <skill>.append.md files from every layer get concatenated for additive overlays. Result: anyone can clone fab and run a competent factory; your personal overlay at ~/.fab/skills/ produces your factory.

What fab does, broadly:

Accepts an intake brief conforming to fab.schema.json
Loads the public standards via the SDK (and adds private review-process layers on top)
Selects templates from the catalog based on the brief
Renders the selected templates + plans the multi-template composition
Orchestrates 78 Claude agents across Discovery → Design → Build → Verify → Ship phases
Produces a PR that meets the production bar, with evidence

Your client doesn’t have to be 78 agents. A single Claude session that reads the catalog, picks one template, renders it, and meets the bar is a conformant client. The reference exists to show the upper bound, not set the minimum.

Quickstart: build your own client

The minimum-viable client:

Fetch the catalog: curl https://raw.githubusercontent.com/nanohype/nanohype/main/catalog.json. Parse it to get the list of available templates and composites.
Load the standards: same URL pattern for standards/*.json. Each file’s applies_to says whether it governs your deliverable, and its grades which quality dimension a violation lands on.
Pick a template: choose by category, persona, or tags. For most AI workloads, start with a composite like ai-chatbot or agent-team from composites/.
Render via the SDK: import { renderTemplate, GitHubSource } from "@nanohype/sdk". Or implement the consumer-guide algorithm in your language of choice — it’s ~150 lines of string-replacement, no template engine needed.
Conform to the platform-tenant contract: produce a Helm chart in <app>/chart/ + ApplicationSet entry + Platform CR. The shape is in standards/platform-tenant-contract.json.
Hit the bar: ensure the rendered output exposes the four phases (build/lint/test/docs), uses current-stable versions, ships with OTel resource attrs, and passes the ten quality-rubric dimensions.

That’s the conformant client. Everything fab does on top — multi-agent orchestration, merge-gate enforcement, evidence-bound verdicts — is the choreography that makes the bar consistently reachable, not a separate bar.

Versioning

Every public artifact carries a version field (positive integer = major version). Bump on any breaking shape change. Backwards-compatible additions don’t bump. Pin your client to a major version range; minor evolution is non-breaking by construction.

Current versions:

catalog.json: v1
standards/*.json: the version field in each file
@nanohype/sdk: see sdk/package.json
@nanohype/mcp: see mcp-server/package.json

Reusing this pattern

The structure described here (top-level reference doc + machine-readable manifests + per-repo AGENTS.md + SDK + MCP server) is portable. If you want to publish a similar Platform Reference for your own org or project, docs/platform-reference-pattern.md describes how.