Summary
The docs don't make cloudemu's full capability surface easy to discover or understand — a newcomer (or an AI coding agent pointed at the repo) can't quickly answer "what can cloudemu do, what can't it, and how do I use each part?" without reading source. The information exists but is scattered across docs/*.md, per-package doc comments, and tribal knowledge. This issue proposes restructuring the docs so all capabilities are discoverable in one place and unambiguous, and so an agent can act on them without guessing.
Why this matters
- Agents/LLMs are increasingly the ones reading these docs to wire cloudemu into tests. They need explicit, structured, single-source-of-truth statements — not prose that assumes context.
- The emulator boundary is the single most misunderstood thing (e.g. the Kubernetes data plane emulates the API + controllers but does not run containers — no real
kubectl logs/exec, no real networking). This "what it is / isn't" needs to be front-and-center per surface, or users hit it as a surprise.
- Capability info is currently spread across
services.md, sdk-server.md, standalone-server.md, architecture.md and package comments, with no single index.
Proposed docs work
1. A top-level "What cloudemu is / isn't"
A short, explicit section (README + docs home) stating the boundary once, clearly:
- ✅ Emulates cloud APIs / control surfaces for fast, deterministic, Docker-free testing (Go API, SDK-compat HTTP server, standalone
serve, Kubernetes API + built-in controllers).
- ❌ Does not run real workloads/containers, does not serve real traffic, does not enforce IAM/quota/policy, does not persist state across restarts, and does not validate credentials/signatures. Name the top non-goals up front.
2. A single capability index — generated from source
One page listing every service and every supported operation, with a per-entry works / partial / non-goal status. Generate it from the driver interfaces (e.g. a go generate step that walks the drivers and emits docs/capabilities.md) so it can't drift from the code — hand-maintained tables are the root cause of the contradictions this issue is about. The generator is the durable fix; the table is the artifact.
3. A machine-readable capability manifest (for agents)
Alongside the human table, emit a structured docs/capabilities.json (service → operations → status) from the same generator, plus an AGENTS.md / llms.txt at the repo root pointing agents at it. This mirrors the existing --endpoints-file JSON convention and gives tools something to parse instead of scraping markdown. This is what actually delivers the "agent-understandable" goal in the title.
4. Per-surface quickstarts, copy-pasteable
One minimal, runnable example each for: Go API, SDK-compat server (per provider), standalone serve, and Kubernetes/kubectl (create cluster via SDK → kubeconfig → kubectl apply). The kubectl path especially is a headline capability with no standalone quickstart today.
5. Explicit per-service non-goals
Each service section should end with a short "Not in scope" list (the Kubernetes section already does this well — replicate the pattern everywhere) so behavior gaps are documented, not discovered. This dovetails with the scope decisions in #312.
6. Make it agent-friendly / keep it honest
- Prefer structured tables/lists over narrative where a capability is being stated.
- No claims the code doesn't back. The project already enforces this at the code level (k8s discovery is derived from what
ServeHTTP actually dispatches, so it "can never promise a resource the emulator does not serve") — the docs should inherit that principle.
- Keep docs that describe the same thing (
services.md ↔ sdk-server.md) in sync, or cross-link so one is authoritative.
Draft available
I have a working draft of items 2–4 to seed this: a browsable capability matrix across AWS/Azure/GCP, a "when to use / non-goals" section, and three runnable examples (direct Go API, SDK-compat httptest test, and a standalone-server program that points real aws-sdk-go-v2 clients at :4566 to create + list resources). Happy to open it as a PR against development if the direction is agreeable.
Acceptance
A newcomer or agent can, from the docs alone: (a) understand what cloudemu can and can't do, (b) find every service + supported operation in one place, and (c) copy-paste a working example for each entry point — without reading the source.
Summary
The docs don't make cloudemu's full capability surface easy to discover or understand — a newcomer (or an AI coding agent pointed at the repo) can't quickly answer "what can cloudemu do, what can't it, and how do I use each part?" without reading source. The information exists but is scattered across
docs/*.md, per-package doc comments, and tribal knowledge. This issue proposes restructuring the docs so all capabilities are discoverable in one place and unambiguous, and so an agent can act on them without guessing.Why this matters
kubectl logs/exec, no real networking). This "what it is / isn't" needs to be front-and-center per surface, or users hit it as a surprise.services.md,sdk-server.md,standalone-server.md,architecture.mdand package comments, with no single index.Proposed docs work
1. A top-level "What cloudemu is / isn't"
A short, explicit section (README + docs home) stating the boundary once, clearly:
serve, Kubernetes API + built-in controllers).2. A single capability index — generated from source
One page listing every service and every supported operation, with a per-entry
works / partial / non-goalstatus. Generate it from the driver interfaces (e.g. ago generatestep that walks the drivers and emitsdocs/capabilities.md) so it can't drift from the code — hand-maintained tables are the root cause of the contradictions this issue is about. The generator is the durable fix; the table is the artifact.3. A machine-readable capability manifest (for agents)
Alongside the human table, emit a structured
docs/capabilities.json(service → operations → status) from the same generator, plus anAGENTS.md/llms.txtat the repo root pointing agents at it. This mirrors the existing--endpoints-fileJSON convention and gives tools something to parse instead of scraping markdown. This is what actually delivers the "agent-understandable" goal in the title.4. Per-surface quickstarts, copy-pasteable
One minimal, runnable example each for: Go API, SDK-compat server (per provider), standalone
serve, and Kubernetes/kubectl (create cluster via SDK → kubeconfig →kubectl apply). The kubectl path especially is a headline capability with no standalone quickstart today.5. Explicit per-service non-goals
Each service section should end with a short "Not in scope" list (the Kubernetes section already does this well — replicate the pattern everywhere) so behavior gaps are documented, not discovered. This dovetails with the scope decisions in #312.
6. Make it agent-friendly / keep it honest
ServeHTTPactually dispatches, so it "can never promise a resource the emulator does not serve") — the docs should inherit that principle.services.md↔sdk-server.md) in sync, or cross-link so one is authoritative.Draft available
I have a working draft of items 2–4 to seed this: a browsable capability matrix across AWS/Azure/GCP, a "when to use / non-goals" section, and three runnable examples (direct Go API, SDK-compat
httptesttest, and a standalone-server program that points realaws-sdk-go-v2clients at:4566to create + list resources). Happy to open it as a PR againstdevelopmentif the direction is agreeable.Acceptance
A newcomer or agent can, from the docs alone: (a) understand what cloudemu can and can't do, (b) find every service + supported operation in one place, and (c) copy-paste a working example for each entry point — without reading the source.