skill: ship idlefy-deploy wizard

A new SKILL.md that turns any AI agent (Claude Code, Cursor, Cline, etc.)
into a guided wizard for producing a validated values.yaml for the
idlefy-universal chart.

Five phases, 23 questions across 8 blocks (Identity, Exposure,
Resources, Storage, Security, Observability, Repo & multi-env, Secrets).
Auto-discovers from docker-compose / Dockerfile / k8s manifests / helm /
Procfile / CI files; drafts with provenance-annotated YAML; validates
with helm template (JSON-Pointer error parser, 5-fix loop bound); hands
off without running helm install.

Distribution: a single canonical URL the user pastes into their agent —
  https://raw.githubusercontent.com/idlefy/idlefy-universal/main/skills/idlefy-deploy/SKILL.md

Audience reminder: the chart is for autonomous agents; this wizard is
for the HUMAN who happens to be using an agent as the interface.

Wires the wizard into the site (How-To nav, homepage promo replaces the
verbose paste-this-prompt block, README install pointer). mkdocs build
--strict is clean.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: wowsel

README.md

@@ -29,6 +29,9 @@ helm install demo oci://ghcr.io/idlefy/idlefy-universal \
   -f values.yaml
 ```
 
+Prefer a guided experience? Hand the [deploy wizard](https://idlefy.github.io/idlefy-universal/how-to/wizard/)
+to an AI agent and it'll author a validated `values.yaml` for you.
+
 A minimal `values.yaml`:
 
 ```yaml

docs/how-to/wizard.md

@@ -0,0 +1,53 @@
+# Use the deploy wizard
+
+`idlefy-deploy` is a SKILL.md that walks a human (you) through producing
+a validated `values.yaml` for the `idlefy-universal` Helm chart, with
+the AI agent of your choice handling the conversation. It scans your
+project, drafts a values.yaml from what it finds, asks only the
+gap-filling questions that can't be inferred, validates with
+`helm template`, and hands off — stopping short of `helm install` so
+you review the diff yourself.
+
+## Invoke it
+
+Paste a sentence like this into Claude Code, Cursor, Cline, or any other
+agent that can fetch a URL and run shell commands:
+
+> Using <https://raw.githubusercontent.com/idlefy/idlefy-universal/main/skills/idlefy-deploy/SKILL.md>, help me deploy this project to Kubernetes via idlefy-universal.
+
+The agent fetches the file and follows it. No install step, no `curl`,
+no `~/.claude/skills/` directory required.
+
+## What you'll be asked
+
+23 questions total, grouped into 8 blocks. Each one explains WHY and
+gives a sensible default — most you can accept and move on:
+
+- **Identity** — workload kind, namespace, image tag, imagePullSecrets, replicas.
+- **Exposure** — Service, Ingress, cert-manager TLS (with a precondition gate).
+- **Resources** — CPU / memory presets (starter / web / heavy).
+- **Storage** — PVC size and class (only for stateful workloads).
+- **Security** — RBAC, ServiceAccount, NetworkPolicy.
+- **Observability** — ServiceMonitor, PodDisruptionBudget, HPA.
+- **Repo & multi-env** — save path, single- vs multi-env layout.
+- **Secrets** — `secretRefs` for sensitive env vars (never written into values.yaml).
+
+The agent skips any question already answered by the scan.
+
+## Failure modes
+
+- **HTTP 429 from `raw.githubusercontent.com`.** Unauthenticated reads
+  are rate-limited per IP (~60/hr). A single human user never hits this;
+  multi-tenant CI does. Mirror the file to your own bucket, or fall
+  back to the `git clone` path below.
+- **Air-gapped / offline.** `git clone https://github.com/idlefy/idlefy-universal`
+  and point the agent at the local file path.
+- **Agent without `WebFetch` / equivalent.** Paste the SKILL.md contents
+  directly into the conversation as a one-time message. Functionally
+  identical, just verbose.
+
+## Related
+
+- [Verify the chart's supply chain](verify-supply-chain.md) — recommended before any `helm install`.
+- [Your first app](../tutorials/your-first-app.md) — manual walk-through if you'd rather not use an agent.
+- [Reference → Values](../reference/values.md) — the full schema surface the wizard navigates.

docs/index.md

@@ -16,58 +16,26 @@ hide:
 
 ## Deploy with an AI agent
 
-`idlefy-universal` is built for AI-driven deployment. The chart bundles
-[`agent-index.json`](reference/agent-metadata.md#agent-indexjson) — a flat,
-machine-readable description of every value with `whenToUse`,
+`idlefy-universal` ships [`agent-index.json`](reference/agent-metadata.md#agent-indexjson)
+— a flat, machine-readable description of every value with `whenToUse`,
 `relatedFields`, `commonMistakes`, and `exampleUseCase`. Every release is
 signed (cosign keyless), SBOM-attached, and carries SLSA L3 provenance,
 so an agent can self-verify the artifact before installing it.
 
-Paste the prompt below into any agent that can run shell commands
-(Claude Code, Cursor, Cline, an MCP-equipped harness, a custom runner — all
-work; the chart ships data, not an integration). Replace `<DESCRIBE YOUR
-WORKLOAD>` with what you actually want deployed.
-
-````text
-You are deploying idlefy-universal for the following workload:
-  <DESCRIBE YOUR WORKLOAD>
-
-Use VERSION=1.0.0 throughout this prompt. Every command below that
-references a chart version MUST use that same value.
-
-1. Verify the chart's supply chain before pulling it. Run the three
-   commands documented at
-   https://idlefy.github.io/idlefy-universal/how-to/verify-supply-chain/#three-command-verification
-   with CHART_REF="oci://ghcr.io/idlefy/idlefy-universal:${VERSION}".
-   Refuse to proceed if any command exits non-zero.
-
-2. After verification passes, pull the chart locally so you can read
-   its agent metadata:
-     helm pull oci://ghcr.io/idlefy/idlefy-universal --version "${VERSION}" --untar
-   Read idlefy-universal/agent-index.json — that file is your
-   authoritative list of fields, with whenToUse, relatedFields,
-   commonMistakes, and exampleUseCase for each.
-
-3. Build a minimal values.yaml for the workload above. Honor every
-   commonMistakes warning. Enable autoCreate* flags only for resources
-   the workload actually needs (Service, Ingress, Certificate, RBAC,
-   ServiceMonitor, NetworkPolicy, PodDisruptionBudget, ServiceAccount).
-
-4. Validate locally before touching the cluster:
-     helm template demo ./idlefy-universal -f values.yaml
-   The chart ships values.schema.json (JSON Schema 2020-12). Typos and
-   cross-field violations fail with a JSON Pointer path. Fix and retry
-   until the template renders cleanly.
-
-5. Install:
-     helm install demo oci://ghcr.io/idlefy/idlefy-universal \
-       --version "${VERSION}" -f values.yaml
-````
+The fastest way to deploy: hand your favourite AI agent the
+[`idlefy-deploy` wizard](how-to/wizard.md). One sentence in your agent's
+chat:
+
+> Using <https://raw.githubusercontent.com/idlefy/idlefy-universal/main/skills/idlefy-deploy/SKILL.md>, help me deploy this project to Kubernetes via idlefy-universal.
+
+The wizard scans your repo, drafts a `values.yaml`, asks only the
+questions the scan couldn't answer, and validates with `helm template`.
+See [Use the deploy wizard](how-to/wizard.md) for details and failure-mode notes.
 
 Further reading:
 
-- [How-To → Verify the chart's supply chain](how-to/verify-supply-chain.md) — the three-command gate, plus a single-script autonomous form
-- [Concepts → Agent-native](concepts/agent-native.md) — why the metadata lives inside the schema, not in a sidecar
+- [How-To → Verify the chart's supply chain](how-to/verify-supply-chain.md) — three-command gate
+- [Concepts → Agent-native](concepts/agent-native.md) — why the metadata lives inside the schema
 - [Reference → Agent metadata](reference/agent-metadata.md) — the `x-agent-*` keyword spec and `agent-index.json` shape
 
 ## Why idlefy-universal

mkdocs.yml

@@ -84,6 +84,7 @@ nav:
       - Add metrics: tutorials/add-metrics.md
       - Gateway API: tutorials/gateway-api.md
   - How-To:
+      - Use the deploy wizard: how-to/wizard.md
       - Monitoring: how-to/monitoring.md
       - RBAC: how-to/rbac.md
       - Network policy: how-to/network-policy.md