Add Blaxel providers, examples, and docs

.agents/skills/docs-current-state/SKILL.md

@@ -1,21 +1,43 @@
 ---
 name: docs-current-state
 description: >-
-  Update project READMEs and Markdown guides as current-state truth only.
-  Use when writing or revising README.md, docs/, examples/**/README.md, or any
-  project guide after API, layout, architecture, or dependency changes; when
-  removing stale docs; or when the user asks to refine documentation.
+  Update project READMEs and Markdown/MDX guides as current-state truth for
+  end users and SDK callers (not SDK builders). Use when writing or revising
+  README.md, docs/, examples/**/README.md, sdks/**/README.md,
+  website/content/docs/**, or any product guide after API, layout,
+  architecture, or dependency changes; when removing stale docs; or when the
+  user asks to refine documentation.
 ---
 
-# Docs: current state only
+# Docs: current state, SDK-user audience
 
-Write documentation that matches the repository **as it exists now**. Pair with
-`crafting-effective-readmes` for README structure, `writing-clearly-and-concisely`
-for prose, and `golang-documentation` for Go/doc-comment work. Use
-`baoyu-format-markdown` only when the user asks to format or beautify markdown
-layout without rewriting meaning.
+Write documentation that matches the repository **as it exists now**, for
+**people who call the SDK**. Pair with `crafting-effective-readmes` for README
+structure, `writing-clearly-and-concisely` for prose, and
+`golang-documentation` for Go/doc-comment work. Use `baoyu-format-markdown`
+only when the user asks to format or beautify markdown layout without
+rewriting meaning.
 
-This skill aligns with `.cursor/rules/docs-current-state.mdc` and `AGENTS.md`.
+This skill aligns with `.cursor/rules/docs-current-state.mdc`,
+`.cursor/rules/docs-sdk-user-audience.mdc`, and `AGENTS.md`.
+
+## Audience
+
+Primary readers are application developers integrating `@sandbox-kit/*` or the
+Go sandbox modules. Write like a technical documentation engineer for that
+audience.
+
+| For SDK users                       | Not for SDK builders                                      |
+| ----------------------------------- | --------------------------------------------------------- |
+| What to call, pass, and expect back | Mapping layers, wire shapes, adapter internals            |
+| Provider-specific usage differences | Inventory YAML, proto regen, contributor workflows        |
+| Outcomes on the handle (`state`, …) | “Unified metadata”, ignored-option plumbing               |
+| Unsupported → say so + alternative  | Negated field catalogs unless they prevent a real mistake |
+
+Omit options the provider does not use from examples. If you must mention an
+unused option, say the provider does not use it—do not say it is “accepted and
+ignored.” Prefer listing fields the caller receives over listing fields that
+stay empty.
 
 ## Rules
 
@@ -26,27 +48,31 @@ This skill aligns with `.cursor/rules/docs-current-state.mdc` and `AGENTS.md`.
 3. **Replace stale content.** Delete outdated sections, examples, commands, and
    claims. Do not keep deprecated paths "for context."
 4. **Update with the code change.** When APIs, layout, architecture, examples,
-   or dependencies change, edit the relevant Markdown in the same task.
+   or dependencies change, edit the relevant Markdown/MDX in the same task.
 5. **Stay silent in chat.** Do not announce "I also updated the README" unless
    the user asked about docs. PR/commit summaries may mention docs when that is
    part of the deliverable.
 6. **Verify.** Check links and commands against the repo. Match examples to the
    implemented API. Prefer one catalog of truth (`examples/README.md`) over
    duplicated incomplete tables.
+7. **Provider- and language-specific.** When behavior differs, say so under the
+   right provider/language section—do not paper over with generic wording.
 
 ## Scope
 
 | Include                                       | Exclude                                       |
 | --------------------------------------------- | --------------------------------------------- |
 | Root/`docs/`/`examples/**` READMEs and guides | CHANGELOG, commit/PR history                  |
-| SDK and tooling READMEs that describe usage   | Skill packages under `.agents/skills/`        |
+| SDK package READMEs that describe usage       | Skill packages under `.agents/skills/`        |
+| `website/content/docs/**` product + SDK pages | Contributor-only architecture unless asked    |
 | Out-of-scope notes stated as present facts    | Roadmap or "planned / future work" narratives |
 
 ## Workflow
 
-1. Identify which Markdown files describe the changed behavior.
-2. Read those files and the matching code/examples.
-3. Rewrite so each file is a clean current description; remove contradictions.
+1. Identify which Markdown/MDX files describe the changed behavior.
+2. Read those files and the matching public API / examples.
+3. Rewrite so each file is a clean current description for an SDK caller;
+   remove contradictions and builder-only detail.
 4. For README structure or audience fit, follow `crafting-effective-readmes`.
 5. For sentence-level clarity, follow `writing-clearly-and-concisely`.
 6. Do not prompt about incidental README edits after feature work unless

.cursor/rules/docs-current-state.mdc

@@ -1,5 +1,5 @@
 ---
-description: Keep docs and READMEs as current-state truth; update silently; remove outdated content
+description: Keep docs and READMEs as current-state truth for SDK users; update silently; remove outdated content
 alwaysApply: true
 ---
 
@@ -8,6 +8,9 @@ alwaysApply: true
 When APIs, layout, architecture, examples, or dependencies change, update the
 relevant README and project Markdown as part of the same work.
 
+Audience for product and SDK docs is **end users and SDK callers**, not SDK
+builders. Follow `.cursor/rules/docs-sdk-user-audience.mdc` for voice.
+
 ## Write what is true now
 
 - Describe the project as it exists **today**. Present tense.
@@ -30,6 +33,7 @@ relevant README and project Markdown as part of the same work.
 
 ## Scope
 
-- Applies to `README.md`, `docs/`, `examples/**/README.md`, and other project
-  Markdown that describes current behavior.
+- Applies to `README.md`, `docs/`, `examples/**/README.md`,
+  `website/content/docs/**`, SDK package READMEs, and other project Markdown
+  that describes current behavior.
 - Does not replace CHANGELOG or commit/PR history; keep those elsewhere.

.cursor/rules/docs-sdk-user-audience.mdc

@@ -0,0 +1,51 @@
+---
+description: Write product and SDK docs for end users and SDK callers, not SDK builders
+alwaysApply: true
+---
+
+# Docs audience: SDK users, not builders
+
+Write README, guides, website docs, and SDK reference as a technical
+documentation engineer for **people who call the SDK** (application
+developers). Not for people who implement providers or maintain this repo.
+
+## Voice
+
+- Lead with what to call, what to pass, and what you get back.
+- Prefer short how-to prose and working snippets over internal design notes.
+- Keep provider- and language-specific behavior explicit when it differs.
+- Present tense. Current behavior only (see `docs-current-state`).
+
+## Do
+
+- Name the public method and show a realistic call.
+- Describe outcomes the caller can use (`state`, `terminal`, `exitCode`, …).
+- Say what the caller must supply (credentials, name, image, region).
+- Note unsupported operations as “not available” / “not supported” for that
+  provider, with the alternative when there is one.
+
+## Do not
+
+- Explain Kit internals, wire formats, mapping layers, or “unified” plumbing.
+- Document ignored options as acceptance theater (“`wait` is accepted and
+  ignored”). Omit unused options from examples; if needed, say the provider
+  does not wait / does not use that option.
+- Surface native `providerState` strings unless the caller must read them.
+- Negate field catalogs (“does not fill `mode`”) unless that prevents a
+  real mistake; prefer listing what the caller actually receives.
+- Write for SDK maintainers (inventory YAML, proto regeneration, adapter
+  shapes) in user-facing docs. Keep that in `AGENTS.md` / contributor docs.
+
+## Examples
+
+```md
+<!-- Bad: builder voice -->
+
+Deletes and returns unified Deleted metadata (`providerState: "TERMINATED"`).
+`wait` is accepted and ignored.
+
+<!-- Good: SDK-user voice -->
+
+Deletes the sandbox. On success, `info.state` is `deleted` and `terminal` is
+true. Pass `wait: true` to wait until removal finishes.
+```

AGENTS.md

@@ -82,9 +82,13 @@ Keep examples aligned with the implemented API. Label test doubles and local
 verification limits clearly. Verify changed examples before handoff and update
 `examples/README.md` when adding a language.
 
-Update project Markdown whenever APIs, layout, architecture, or dependencies
-change. Write docs as current-state truth: present tense, remove outdated
-sections, and verify links and commands against the repository.
+Update project Markdown and `website/content/docs/` whenever APIs, layout,
+architecture, or dependencies change. Write docs as current-state truth for
+**end users and SDK callers** (not SDK builders): present tense, what to call
+and what you get back, provider- and language-specific when behavior differs.
+Remove outdated sections, and verify links and commands against the
+repository. See `.cursor/rules/docs-sdk-user-audience.mdc` and
+`.cursor/skills/docs-current-state/`.
 
 ## Development tooling