From 1d44db5cf85cefad830299f5bba2c14aa82da9d9 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Tue, 26 May 2026 13:33:23 +0530 Subject: [PATCH 1/6] docs: trim landing + concepts, sync two-command install, link contributing to repo - index.mdx: new pitch headline ("Your deploy failed. The agent already knows why."); remove "How a stage works" and "Three pillars"; tighten Get started to the real two-command flow; Explore 8 -> 4 cards - quickstart.mdx, cli/install.mdx, zombies/install.mdx: drop the stale `npx skills add` step (the npm install of zombiectl now adds the host skill, per the live site); keep the curl one-liner as fallback - quickstart.mdx, concepts.mdx: replace inline credit/$5 detail with the "free until July 31, 2026" trial framing + link to usezombie.com/pricing - concepts.mdx: de-duplicate Zombie/Tool between the four-nouns cards and the glossary; Tool accordion becomes the tool catalog - docs.json: add Contributing anchor -> github.com/usezombie/usezombie#contributing - remove 4 orphaned contributing/*.mdx pages (live by URL but absent from nav and llms.txt); contributor docs now live in the repo README Co-Authored-By: Claude Opus 4.7 (1M context) --- cli/install.mdx | 23 ++--------- concepts.mdx | 30 +++++--------- contributing/architecture.mdx | 53 ------------------------ contributing/development.mdx | 71 -------------------------------- contributing/overview.mdx | 41 ------------------- contributing/testing.mdx | 66 ------------------------------ docs.json | 5 +++ index.mdx | 77 +++++++++-------------------------- quickstart.mdx | 35 ++++------------ zombies/install.mdx | 27 +++--------- 10 files changed, 52 insertions(+), 376 deletions(-) delete mode 100644 contributing/architecture.mdx delete mode 100644 contributing/development.mdx delete mode 100644 contributing/overview.mdx delete mode 100644 contributing/testing.mdx diff --git a/cli/install.mdx b/cli/install.mdx index 3205c2d..93a6e65 100644 --- a/cli/install.mdx +++ b/cli/install.mdx @@ -27,26 +27,11 @@ description: "Install the zombiectl CLI." ## Agent Skills -The `usezombie-install-platform-ops` skill is the guided install UX driven from a host agent (Claude Code, Amp, Codex CLI, OpenCode). Two ways to install it — pick whichever fits your environment. +The `usezombie-install-platform-ops` skill is the guided install UX driven from a host agent (Claude Code, Amp, Codex CLI, OpenCode). The `npm install -g @usezombie/zombiectl` above already symlinks the `/usezombie-*` slash commands into every supported host's skill directory it detects on your machine — invoke `/usezombie-install-platform-ops` in your agent and you're set. - - - One-liner. Symlinks the `/usezombie-*` slash commands into every supported host's skill directory the package can detect on your machine: - - ```bash - npx skills add usezombie/skills - ``` - - Pass `--host=` to pin a specific host instead of letting the package decide. - - - Prefer a single command? This installs `zombiectl` and the skill together. Requires Node (it runs npm under the hood). Want to read it first? `curl -fsSL https://usezombie.sh` without `| bash` prints the script. - - ```bash - curl -fsSL https://usezombie.sh | bash - ``` - - + + **No global install?** `curl -fsSL https://usezombie.sh | bash` installs `zombiectl` and the skill together in one command (requires Node — it runs npm under the hood). Run `curl -fsSL https://usezombie.sh` without `| bash` to read it first. + The skill drives `zombiectl install --from`, `zombiectl credential`, `zombiectl steer`, `zombiectl logs`, and the doctor preflight under the hood. See [Quickstart](/quickstart) for the end-to-end flow. diff --git a/concepts.mdx b/concepts.mdx index 71a10d3..66d85f7 100644 --- a/concepts.mdx +++ b/concepts.mdx @@ -3,8 +3,6 @@ title: "Key concepts" description: "The four nouns, the tool bridge, and how a stage works." --- -import { STARTER_CREDIT } from "/snippets/rates.mdx"; - This page introduces the operator-facing model. For the canonical technical reference — system topology, data flow, billing internals, security boundary, post-ship reflection — read [`docs/architecture/`](https://github.com/usezombie/usezombie/tree/main/docs/architecture) on GitHub. @@ -15,13 +13,13 @@ usezombie has four primary objects. Everything else is infrastructure. - Your top-level billing and identity boundary. Created automatically on first Clerk sign-in. Carries the **credit balance** ({STARTER_CREDIT} starter credit, never expires) and your default Stripe customer. + Your top-level billing and identity boundary. Created automatically on first Clerk sign-in. Carries your default Stripe customer — hosted execution is [free until July 31, 2026](https://usezombie.com/pricing). - A container for zombies and credentials. One tenant can have many workspaces (team, project, environment). Credits are **not** fragmented per workspace — every workspace debits the same tenant wallet. + A container for zombies and credentials. One tenant can have many workspaces (team, project, environment). Billing and identity live at the tenant — a workspace is purely an organizational boundary. - A persistent, durable agent process scoped to one operational outcome. One zombie has one `SKILL.md` + `TRIGGER.md`, a set of triggers (webhook, cron, steer), and a set of workspace credentials it uses but never sees raw bytes for. Lives inside a workspace. + A persistent, durable agent process scoped to one operational outcome. One zombie has one `SKILL.md` + `TRIGGER.md`, a set of triggers (webhook, cron, steer), and a set of workspace credentials it uses but never sees raw bytes for. Lives inside a workspace; crashes and restarts are transparent — the platform survives them. A named primitive the zombie's agent can invoke — `http_request`, `memory_store`, `cron_add`. Tools are declared in `TRIGGER.md` and **enforced** by the executor sandbox; the agent literally cannot call a tool that isn't on the list. The companion file `SKILL.md` is **advisory** — natural-language prose the model reads as its system prompt to decide *when* to reach for which tool and what counts as "done." Enforcement comes from `TRIGGER.md`; behavior comes from `SKILL.md`. @@ -31,7 +29,7 @@ usezombie has four primary objects. Everything else is infrastructure. ### How they relate ``` -Tenant (wallet: $5.00, provider: anthropic) +Tenant (billing + identity, provider: anthropic) │ ├── Workspace: "platform-ops" │ │ @@ -48,17 +46,13 @@ Tenant (wallet: $5.00, provider: anthropic) └── Triggers: webhook (Zendesk), steer ``` -Every stage debits the same tenant balance regardless of which workspace the zombie lives in. This is the **single-wallet, multi-workspace** model — no per-workspace credit pools, no workspace-scoped top-ups. - -## Credits and your model provider +## Cost: free during the trial, bring your own model -New tenants start with **{STARTER_CREDIT}** seeded at signup — never expires. +Hosted execution — every event receipt and stage — is **free until July 31, 2026**. No credit card to start. -- **Hosted execution is metered.** usezombie debits credits on event receipt and per-stage execution. That's what the credit pool pays for. -- **You bring your provider and model.** Pick the provider (Anthropic, OpenAI, Fireworks, Together, Groq, Moonshot), attach the key, and pay them directly. usezombie marks up zero on inference. The executor resolves your credential at the tool bridge. -- **Debits happen on completed work only.** A stage that fails before producing output does not debit. +**You bring your provider and model.** Pick the provider (Anthropic, OpenAI, Fireworks, Together, Groq, Moonshot), attach the key, and pay them directly — usezombie marks up zero on inference. The executor resolves your credential at the tool bridge, so the agent never sees the raw key. -See [Billing and cost control](/billing/plans). +For the metered rates that apply after the trial, see [pricing on usezombie.com](https://usezombie.com/pricing). ## How a stage runs @@ -78,10 +72,6 @@ A trigger lands on the event stream. A stage opens. The agent calls tools allow- ## Core terminology - - A persistent, always-on agent scoped to one operational outcome. A zombie has two markdown files (`SKILL.md` + `TRIGGER.md`), a trigger that wakes it, a list of tools it can call, and the workspace credentials it needs. Crashes and restarts are transparent — the platform survives them. - - One end-to-end execution of the agent on one trigger: webhook arrives → agent reasons → tool calls → result. Most zombies finish a stage in a few seconds. See [How long does a stage take?](/concepts/context-lifecycle). @@ -96,8 +86,8 @@ A trigger lands on the event stream. A stage opens. The agent calls tools allow- `SKILL.md` decides what to do based on the event payload. - - A named verb the agent can invoke, declared in `TRIGGER.md`: + + The named verbs an agent can invoke, declared in `TRIGGER.md`: - `http_request` — outbound HTTP. Slack posts, GitHub calls, your provider — all go through this. - `memory_store` / `memory_recall` / `memory_list` / `memory_forget` — durable cross-event learning. See [Memory](/memory). - `cron_add` / `cron_list` / `cron_remove` — schedule future stages. diff --git a/contributing/architecture.mdx b/contributing/architecture.mdx deleted file mode 100644 index d014e47..0000000 --- a/contributing/architecture.mdx +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: "Source tree" -description: "Codebase structure and module organization." ---- - -## Module map - -```mermaid -graph TD - subgraph "zombied (Zig)" - Main[src/main.zig] --> CMD[src/cmd/] - CMD --> Serve[serve.zig] - CMD --> WorkerCmd[worker.zig] - CMD --> Doctor[doctor.zig] - CMD --> Migrate[migrate.zig] - Main --> HTTP[src/http/] - Main --> Pipeline[src/pipeline/] - Main --> Executor[src/executor/] - Main --> DB[src/db/] - Main --> Queue[src/queue/] - Main --> Auth[src/auth/] - Main --> Config[src/config/] - Main --> Observability[src/observability/] - end - subgraph "zombiectl (TypeScript)" - CLI[zombiectl/src/cli.js] --> Commands[src/commands/] - CLI --> Program[src/program/] - end - subgraph "UI (React/TypeScript)" - Website[ui/packages/website/] - App[ui/packages/app/] - DesignSystem[ui/packages/design-system/] - end -``` - -## Top-level directories - -| Directory | Language | Description | -|-----------|----------|-------------| -| `src/` | Zig | zombied server and worker. The core of the platform. | -| `src/cmd/` | Zig | CLI subcommands for zombied (`serve`, `worker`, `doctor`, `migrate`). | -| `src/http/` | Zig | HTTP route handlers for the REST API. | -| `src/pipeline/` | Zig | Spec parsing, gate evaluation, and scorecard generation. | -| `src/executor/` | Zig | Run execution engine. Manages sandbox lifecycle and agent orchestration. | -| `src/db/` | Zig | Database layer. Migrations, queries, and connection pooling (Postgres). | -| `src/queue/` | Zig | Job queue backed by Redis. Handles run scheduling and worker dispatch. | -| `src/auth/` | Zig | Authentication and authorization. Clerk token validation, workspace-scoped access. | -| `src/config/` | Zig | Configuration loading from environment, files, and defaults. | -| `src/observability/` | Zig | Structured logging, metrics, and tracing. | -| `zombiectl/` | TypeScript | CLI tool for developers. Wraps the REST API with ergonomic commands. | -| `ui/packages/website/` | React/TS | Marketing website and documentation. | -| `ui/packages/app/` | React/TS | Dashboard application for workspace and run management. | -| `ui/packages/design-system/` | React/TS | Shared component library across UI packages. | diff --git a/contributing/development.mdx b/contributing/development.mdx deleted file mode 100644 index a38a389..0000000 --- a/contributing/development.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: "Development setup" -description: "Set up your local development environment." ---- - -## Prerequisites - -| Tool | Version | Purpose | -|------|---------|---------| -| Zig | Latest stable | zombied server and worker | -| Node.js | 18+ | zombiectl CLI | -| Docker | Latest | Postgres and Redis for local dev | -| Make | Any | Task runner for all components | - -## Start services - -Bring up Postgres and Redis in Docker: - -```bash -make up -``` - -## Run zombied in dev mode - -```bash -make dev -``` - -This starts the server with hot reload, connected to the local Postgres and Redis instances. - -## Lint - -```bash -make lint -``` - -Runs all linters and type checks across the full codebase (Zig, TypeScript, and UI). - -## Test - -```bash -make test -``` - -Runs the full unit test suite. Requires no external services. - -## Build - -```bash -make build -``` - -Compiles production binaries for zombied and runs the TypeScript build for zombiectl. - -## zombiectl development - -The CLI lives in its own directory with a separate dependency tree: - -```bash -cd zombiectl -npm install -npm run dev -``` - -## Stop services - -```bash -make down -``` - -Stops and removes the Docker containers started by `make up`. diff --git a/contributing/overview.mdx b/contributing/overview.mdx deleted file mode 100644 index 1d21afd..0000000 --- a/contributing/overview.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "Contributing" -description: "How to contribute to usezombie." ---- - -usezombie is open source under the [MIT License](https://github.com/usezombie/usezombie/blob/main/LICENSE). - -## What we welcome - -- Bug reports with reproduction steps. -- Feature requests with a clear use case. -- Documentation improvements. -- Performance optimizations with benchmarks. -- New gate implementations for the pipeline. -- CLI improvements and new commands. - -## Pull request process - -1. Fork the repository. -2. Create a feature branch from `main`. -3. Make your changes. Follow the existing code style. -4. Run `make lint` and `make test` -- both must pass. -5. Open a PR against `main` with a clear description of what and why. - -## Code of conduct - -We follow the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). Be respectful, constructive, and inclusive. - -## Commit style - -Use [Conventional Commits](https://www.conventionalcommits.org/): - -``` -feat(pipeline): add retry logic for transient gate failures -fix(cli): correct workspace list output alignment -docs(api): update error code reference -``` - -## Questions - -Open a GitHub Discussion or reach out on Discord for questions that are not bug reports or feature requests. diff --git a/contributing/testing.mdx b/contributing/testing.mdx deleted file mode 100644 index 9afc5be..0000000 --- a/contributing/testing.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "Testing" -description: "Test strategy and commands." ---- - -## Unit tests - -```bash -make test -``` - -Runs all unit tests. No external services required. These tests cover pure logic: parsers, state machines, serialization, and utility functions. - -## Integration tests - -```bash -make test-integration -``` - -Requires Postgres and Redis running locally (start them with `make up`). Integration tests exercise the full request path: HTTP handler to database to queue and back. - -## Memory leak tests - -On Linux, run the Valgrind-based memory leak detector: - -```bash -make test-memleak -``` - -This compiles a debug build and runs the test suite under Valgrind. Any leaked allocation fails the test. - -## Cross-compilation check - -Verify that the build succeeds for all target platforms: - -```bash -make build-cross -``` - -This runs the Zig cross-compilation matrix (Linux x86_64, Linux aarch64, macOS x86_64, macOS aarch64). - -## Code conventions - -### Module size - -Every module must stay under **500 lines**. If a module grows past this limit, split it. Smaller modules are easier to test and review. - -### Zig database conventions - -When writing or reviewing Zig code that interacts with the database: - -- **Always call `.drain()` before `.deinit()`** on `conn.query()` results. This prevents connection pool corruption. -- **Prefer `conn.exec()`** when no result rows are needed. It handles cleanup automatically. - -```zig -// Good: drain before deinit -var result = try conn.query("SELECT id FROM runs WHERE status = $1", .{"QUEUED"}); -defer result.deinit(); -// ... process rows ... -result.drain(); - -// Better when no rows needed: use exec -try conn.exec("UPDATE runs SET status = $1 WHERE id = $2", .{ "RUNNING", run_id }); -``` - -Run `make check-pg-drain` to verify all query call sites follow this convention. diff --git a/docs.json b/docs.json index 2adaa83..abe2cc3 100644 --- a/docs.json +++ b/docs.json @@ -248,6 +248,11 @@ "anchor": "GitHub", "href": "https://github.com/usezombie/usezombie", "icon": "github" + }, + { + "anchor": "Contributing", + "href": "https://github.com/usezombie/usezombie#contributing", + "icon": "code-pull-request" } ] } diff --git a/index.mdx b/index.mdx index c203f12..7b486d5 100644 --- a/index.mdx +++ b/index.mdx @@ -1,10 +1,8 @@ --- -title: "Operational outcomes don't fall into limbo" -description: "A deploy fails at 2am. Your senior engineer is asleep. usezombie owns the outcome — wakes on your events, gathers evidence against your infra, posts an evidenced diagnosis to Slack." +title: "Your deploy failed. The agent already knows why." +description: "usezombie is an open runtime that owns operational outcomes — a zombie wakes on your events, gathers evidence from your own systems, posts a diagnosis with proof, and keeps a replayable log of every move it made." --- -import { STARTER_CREDIT } from "/snippets/rates.mdx"; - **Stealth-mode testing.** usezombie is in private alpha — APIs and agent behavior may change without long deprecation windows. Want a hand calibrating a zombie or to join as a design partner? Email [usezombie@agentmail.to](mailto:usezombie@agentmail.to). @@ -13,78 +11,43 @@ import { STARTER_CREDIT } from "/snippets/rates.mdx"; A deploy fails at 2am. Your senior on-call engineer is asleep. You guess at the cause from a stack trace, ship a patch, hope. The next morning, half the context is gone — no one remembers what was already tried, the evidence is scattered across CI, logs, dashboards, and chat, and the audit trail is whatever someone thought to paste into a thread. -usezombie owns the outcome instead. A **zombie** is a durable runtime described in two markdown files — `SKILL.md` (the senior engineer's playbook in prose) plus `TRIGGER.md` (which tools the agent can reach and which events wake it). When a trigger fires, the zombie gathers evidence, reasons over it, and posts an evidenced diagnosis to your Slack channel. The flagship `platform-ops` wakes on a GitHub Actions deploy failure, pulls workflow logs + your hosting provider's app state + your data-plane's health, and posts a one-paragraph diagnosis with a leading hypothesis. The same zombie is reachable via `zombiectl steer` for a manual investigation. - -## Three pillars +usezombie owns the outcome instead. A **zombie** is a durable runtime described in two markdown files — `SKILL.md` (the senior engineer's playbook in prose) plus `TRIGGER.md` (which tools the agent can reach and which events wake it). When a trigger fires, the zombie gathers the evidence, reasons over it, posts an evidenced diagnosis to your Slack channel, and keeps a replayable log of every move it made. - - - The runtime that holds your credentials and runs against your infrastructure is code you can read. Apache-2.0. - - - Pick the provider — Anthropic, OpenAI, Fireworks (Kimi K2), Together, Groq, Moonshot — attach the key, and pay them directly. Zero markup on inference. - - - Behaviour lives in `SKILL.md` + `TRIGGER.md`. Iterate on prose, not redeploys. No YAML allowlists, no DAG editors. - - +The flagship `platform-ops` wakes on a GitHub Actions deploy failure, pulls workflow logs + your hosting provider's app state + your data-plane's health, and posts a one-paragraph diagnosis with a leading hypothesis. The same zombie is reachable via `zombiectl steer` for a manual investigation. The runtime is open source, you bring your own model and pay your provider directly, and the agent never sees your raw keys — only `${secrets.NAME}` placeholders, swapped for real values outside the sandbox. ## Get started - - `npm install -g @usezombie/zombiectl`, then `npx skills add usezombie/skills`, then `/usezombie-install-platform-ops` inside Claude Code, Amp, Codex CLI, or OpenCode. - +`platform-ops` goes from a cold machine to a real diagnosis in Slack in about ten minutes. Install the CLI: -## How a stage works +```bash +npm install -g @usezombie/zombiectl +``` -A zombie does its work in **stages** — one stage is one end-to-end execution on one trigger: event arrives → agent reasons → tool calls → result. Most zombies finish a stage in seconds. +Then invoke the install skill inside your agent — Claude Code, Amp, Codex CLI, or OpenCode: - - - Webhooks, scheduled cron jobs the zombie sets up itself, and `zombiectl steer` messages all flow through the same reasoning loop. - - - The model never sees raw API keys or tokens — only `${secrets.NAME.FIELD}` placeholders. The **tool bridge** substitutes the real value outside the sandbox when the agent calls a tool. A prompt-injection attack recovers only the placeholder. More → - - - If one stage hits the model's context window, the platform restarts it on a fresh prompt with prior findings recovered. How long does a stage take? → - - - Risky actions block until a human clicks Approve in the dashboard or Slack. The wait survives worker restarts. - - - Per-day and per-month dollar caps. {STARTER_CREDIT} starter credit that never expires. Inference cost is yours, paid to your provider directly. - - - `zombiectl stop` pauses the zombie cleanly; resume with `zombiectl resume`. `zombiectl kill` is terminal — re-install to bring it back. - - +``` +/usezombie-install-platform-ops +``` + +The skill signs you in, registers the GitHub webhook, and writes `SKILL.md` + `TRIGGER.md` into your repo. From there, behaviour iterates on prose, not redeploys. + + + Sign in, install `platform-ops`, and trigger a real diagnosis — step by step from a cold machine. + ## Explore - - Install `zombiectl`, run the install skill, see a real diagnosis. - - - The `SKILL.md` + `TRIGGER.md` reference for writing your own. - Tenants, workspaces, zombies, tools — the four nouns. - - Three knobs, defaults that work, when to override. + + Write your own `SKILL.md` + `TRIGGER.md`. Every `zombiectl` command, with examples. - - The canonical technical reference — capabilities, data flow, billing + model providers, path to bastion, post-ship reflection. - Source, issues, design partners welcome. - - Live help from design partners and the core team. Drop in for quick sanity-checks and unreleased-feature questions. - diff --git a/quickstart.mdx b/quickstart.mdx index 0e68bae..a9acc19 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -3,8 +3,6 @@ title: Quickstart description: "Install zombiectl, run /usezombie-install-platform-ops, see a real diagnosis in Slack." --- -import { STARTER_CREDIT } from "/snippets/rates.mdx"; - This walks through installing the flagship `platform-ops` zombie on one of your repositories. Total time: about ten minutes from a cold machine. At the end, a deploy failure on the repo lands an evidenced diagnosis in your Slack channel. @@ -31,7 +29,7 @@ This walks through installing the flagship `platform-ops` zombie on one of your zombiectl --version ``` - `zombiectl` is the only binary you install on your machine. It ships the `/usezombie-*` skill samples under `~/.config/usezombie/samples/` so the install skill (next step) can drive `zombiectl install --from` against a known-good source. + `zombiectl` is the only binary you install on your machine. The same install also drops the `/usezombie-*` host skills into every supported agent it detects — so `/usezombie-install-platform-ops` is ready to invoke in the next step — and ships the matching skill samples under `~/.config/usezombie/samples/` so the install skill can drive `zombiectl install --from` against a known-good source. @@ -39,7 +37,7 @@ This walks through installing the flagship `platform-ops` zombie on one of your zombiectl login ``` - Opens a Clerk-backed approval page in your browser. After you click **Approve**, the page shows a 6-digit verification code — type it back into the CLI to complete login. The code binds the browser approver to the terminal you're typing from. New accounts come with a {STARTER_CREDIT} starter credit pool — never expires, covers hosted execution (event receipts + stages). You bring your provider and model — pay them directly. usezombie marks up zero on inference. + Opens a Clerk-backed approval page in your browser. After you click **Approve**, the page shows a 6-digit verification code — type it back into the CLI to complete login. The code binds the browser approver to the terminal you're typing from. Hosted execution (event receipts + stages) is **free until July 31, 2026** — no credit card to start; see [pricing](https://usezombie.com/pricing) for the metered rates after the trial. You bring your provider and model — pay them directly. usezombie marks up zero on inference. Login also fetches your tenant's workspaces and selects the first one as active locally. Signup auto-provisions a default workspace, so your CLI is ready to install zombies immediately — no `workspace add` required. @@ -54,29 +52,8 @@ This walks through installing the flagship `platform-ops` zombie on one of your Skip this step if the signup-provisioned default workspace is fine. Run it only when you want a second workspace or a custom name. Workspaces are the boundary for credentials, access control, and webhook namespaces — every zombie lives in exactly one. Switch later with `zombiectl workspace use `. See [Command reference → workspaces](/cli/zombiectl#workspaces). - - Two ways to drop the `usezombie-install-platform-ops` skill into your host's skills folder. Pick one. - - - - One-liner. The `skills` package symlinks `/usezombie-*` into every supported host's skill directory it can detect: - - ```bash - npx skills add usezombie/skills - ``` - - Pass `--host=` to pin a specific host. - - - Installs `zombiectl` and the skill in one shot (requires Node — it runs npm under the hood). If you skipped the steps above and ran this on a fresh machine, you still need `zombiectl login` (Step 3) before the skill works. Want to read it first? `curl -fsSL https://usezombie.sh` without `| bash` prints the script. - - ```bash - curl -fsSL https://usezombie.sh | bash - ``` - - - - Then, in your host agent, invoke: + + The `npm install` in Step 2 already added the `/usezombie-install-platform-ops` skill to your agent. Invoke it: ``` /usezombie-install-platform-ops @@ -84,6 +61,10 @@ This walks through installing the flagship `platform-ops` zombie on one of your The skill drives `zombiectl install --from ~/.config/usezombie/samples/platform-ops` under the hood. Power users can run that directly; everyone else gets the guided flow. + + **Fresh machine?** `curl -fsSL https://usezombie.sh | bash` installs `zombiectl` and the skill in one shot (it runs npm under the hood) — a one-command replacement for Step 2. You still need `zombiectl login` (Step 3) before the skill works. Run `curl -fsSL https://usezombie.sh` without `| bash` to read it first. + + The skill asks three gating questions: - **Slack channel** — where diagnoses post (e.g. `#platform-ops`). diff --git a/zombies/install.mdx b/zombies/install.mdx index 107c8ef..1f1dc19 100644 --- a/zombies/install.mdx +++ b/zombies/install.mdx @@ -22,33 +22,16 @@ Re-running against the same workspace is safe — running it twice has the same ## Two ways to invoke -Most users don't run `zombiectl install --from` directly. They drive the install from a host agent (Claude Code, Amp, Codex CLI, OpenCode) via the `/usezombie-install-platform-ops` slash command. Set up the skill once per machine using either install path: - - - - One-liner. Symlinks `/usezombie-*` into every supported host's skill directory the package can detect: - - ```bash - npx skills add usezombie/skills - ``` - - Pass `--host=` to pin a specific host. - - - Prefer a single command? This installs `zombiectl` and the skill together. Requires Node (it runs npm under the hood). Want to read it first? `curl -fsSL https://usezombie.sh` without `| bash` prints the script. - - ```bash - curl -fsSL https://usezombie.sh | bash - ``` - - - -Then invoke the slash command in your host agent: +Most users don't run `zombiectl install --from` directly. They drive the install from a host agent (Claude Code, Amp, Codex CLI, OpenCode) via the `/usezombie-install-platform-ops` slash command. Installing the CLI sets the skill up for you — `npm install -g @usezombie/zombiectl` symlinks `/usezombie-*` into every supported host's skill directory it detects. Then invoke the slash command in your host agent: ``` /usezombie-install-platform-ops ``` + + **No global install?** `curl -fsSL https://usezombie.sh | bash` installs `zombiectl` and the skill together in one command (requires Node — it runs npm under the hood). Run `curl -fsSL https://usezombie.sh` without `| bash` to read it first. + + The slash command asks three gating questions (Slack channel, production branch glob, optional cron schedule), registers the webhook via your existing `gh` CLI, and prints a per-trigger registration summary at the end. See [Quickstart](/quickstart) for the full walkthrough. Power users and scripted setups call `zombiectl install --from ` directly — the same flow as the slash command, minus the gating questions and the auto-registration. From 237d5c749f8d188cf4e55e9db3f99917add1d216 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Tue, 26 May 2026 13:39:17 +0530 Subject: [PATCH 2/6] docs: fix review findings on install copy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - index.mdx: drop "signs you in" from Get started — the install skill does not handle login (`zombiectl login` is a separate step); it only registers the webhook and writes SKILL.md + TRIGGER.md - cli/install.mdx, zombies/install.mdx, quickstart.mdx: replace the unverified "symlinks"/"drops" wording with "installs" for the host-skill step, harmonized across all three pages Co-Authored-By: Claude Opus 4.7 (1M context) --- cli/install.mdx | 2 +- index.mdx | 2 +- quickstart.mdx | 2 +- zombies/install.mdx | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/cli/install.mdx b/cli/install.mdx index 93a6e65..00d5aca 100644 --- a/cli/install.mdx +++ b/cli/install.mdx @@ -27,7 +27,7 @@ description: "Install the zombiectl CLI." ## Agent Skills -The `usezombie-install-platform-ops` skill is the guided install UX driven from a host agent (Claude Code, Amp, Codex CLI, OpenCode). The `npm install -g @usezombie/zombiectl` above already symlinks the `/usezombie-*` slash commands into every supported host's skill directory it detects on your machine — invoke `/usezombie-install-platform-ops` in your agent and you're set. +The `usezombie-install-platform-ops` skill is the guided install UX driven from a host agent (Claude Code, Amp, Codex CLI, OpenCode). The `npm install -g @usezombie/zombiectl` above already installs the `/usezombie-*` slash commands into every supported host's skill directory it detects on your machine — invoke `/usezombie-install-platform-ops` in your agent and you're set. **No global install?** `curl -fsSL https://usezombie.sh | bash` installs `zombiectl` and the skill together in one command (requires Node — it runs npm under the hood). Run `curl -fsSL https://usezombie.sh` without `| bash` to read it first. diff --git a/index.mdx b/index.mdx index 7b486d5..1457c2b 100644 --- a/index.mdx +++ b/index.mdx @@ -29,7 +29,7 @@ Then invoke the install skill inside your agent — Claude Code, Amp, Codex CLI, /usezombie-install-platform-ops ``` -The skill signs you in, registers the GitHub webhook, and writes `SKILL.md` + `TRIGGER.md` into your repo. From there, behaviour iterates on prose, not redeploys. +The skill registers the GitHub webhook and writes `SKILL.md` + `TRIGGER.md` into your repo. From there, behaviour iterates on prose, not redeploys. Sign in, install `platform-ops`, and trigger a real diagnosis — step by step from a cold machine. diff --git a/quickstart.mdx b/quickstart.mdx index a9acc19..0986f5d 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -29,7 +29,7 @@ This walks through installing the flagship `platform-ops` zombie on one of your zombiectl --version ``` - `zombiectl` is the only binary you install on your machine. The same install also drops the `/usezombie-*` host skills into every supported agent it detects — so `/usezombie-install-platform-ops` is ready to invoke in the next step — and ships the matching skill samples under `~/.config/usezombie/samples/` so the install skill can drive `zombiectl install --from` against a known-good source. + `zombiectl` is the only binary you install on your machine. It also installs the `/usezombie-*` host skills into every supported agent it detects — so `/usezombie-install-platform-ops` is ready to invoke in the next step — and ships the matching skill samples under `~/.config/usezombie/samples/` so the install skill can drive `zombiectl install --from` against a known-good source. diff --git a/zombies/install.mdx b/zombies/install.mdx index 1f1dc19..b7f075d 100644 --- a/zombies/install.mdx +++ b/zombies/install.mdx @@ -22,7 +22,7 @@ Re-running against the same workspace is safe — running it twice has the same ## Two ways to invoke -Most users don't run `zombiectl install --from` directly. They drive the install from a host agent (Claude Code, Amp, Codex CLI, OpenCode) via the `/usezombie-install-platform-ops` slash command. Installing the CLI sets the skill up for you — `npm install -g @usezombie/zombiectl` symlinks `/usezombie-*` into every supported host's skill directory it detects. Then invoke the slash command in your host agent: +Most users don't run `zombiectl install --from` directly. They drive the install from a host agent (Claude Code, Amp, Codex CLI, OpenCode) via the `/usezombie-install-platform-ops` slash command. Installing the CLI sets the skill up for you — `npm install -g @usezombie/zombiectl` installs `/usezombie-*` into every supported host's skill directory it detects. Then invoke the slash command in your host agent: ``` /usezombie-install-platform-ops From ad018f3e9cff2626fb374d77db7f5c85989d75eb Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Tue, 26 May 2026 13:43:19 +0530 Subject: [PATCH 3/6] docs(quickstart): document non-interactive (no-TTY) login for agents/CI The Sign in step only showed the interactive browser + 6-digit-code flow, which an agent driving the CLI (no TTY) can't complete. Add a note covering the token path: `ZOMBIE_TOKEN` env var (preferred), `--token`, or stdin, resolved in that order, plus `--no-input` to fail fast. Links to the full precedence in cli/zombiectl#zombiectl-login. Co-Authored-By: Claude Opus 4.7 (1M context) --- quickstart.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/quickstart.mdx b/quickstart.mdx index 0986f5d..158ac62 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -42,6 +42,10 @@ This walks through installing the flagship `platform-ops` zombie on one of your Login also fetches your tenant's workspaces and selects the first one as active locally. Signup auto-provisions a default workspace, so your CLI is ready to install zombies immediately — no `workspace add` required. Pass `--token-name "your-device-label"` to label this install so it's easy to recognize on the approval page and in `zombiectl auth status` later. Defaults to your platform family otherwise. + + + **No terminal — CI, or an agent driving the CLI?** Skip the browser entirely: supply a token via the `ZOMBIE_TOKEN` environment variable (preferred — keeps it out of shell history), the `--token ` flag, or piped on stdin, resolved in that order. Add `--no-input` to fail fast instead of waiting for the code — a no-TTY shell with no token exits with an error. Full precedence in [`zombiectl login`](/cli/zombiectl#zombiectl-login). + From f260bce577f706039fde35a0d7eac271b7e1487f Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Tue, 26 May 2026 14:55:38 +0530 Subject: [PATCH 4/6] =?UTF-8?q?docs:=20post-release=20audit=20=E2=80=94=20?= =?UTF-8?q?fix=20stale=20CLI/auth/webhook/billing=20facts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Audited every .mdx page against the zombiectl/server source and live product. Tier 1 (confirmed factual): - quickstart: correct login token order (--token -> ZOMBIE_TOKEN -> stdin) - zombies/overview: drop dead /concepts#credits anchor; tenant-level billing - zombies/troubleshooting: webhook 404 path gains /{source}; fix dead /quickstart#wire-the-github-webhook anchor - zombies/credentials: TRIGGER.md example uses triggers: array (singular trigger: is rejected at install) Tier 2 (resolved against source): - credentials path is ~/.config/zombiectl/credentials.json (was wrong dir in cli/zombiectl logout, missing .json in cli/configuration) - cli/configuration: rewrite auth precedence — TTY-aware command resolution; --token is login-only, not global - cli/install: doctor runs 3 checks and needs no auth (was 5 + auth short-circuit; that table had drifted from source) - api-reference/introduction: error envelope is flat RFC 7807 application/problem+json (matches error-codes.mdx); IDs are UUIDv7 Tier 3 (free-trial framing, credit model kept): - billing/plans, billing/budgets: add "free until July 31, 2026" banner + pricing link; post-trial credit/wallet model retained - workspaces/overview: webhook URL gains /{source}; soften wallet wording Deferred: zombiectl workspace credentials body section (redirect stub; the command table already lists it) — noted for follow-up. Co-Authored-By: Claude Opus 4.7 (1M context) --- api-reference/introduction.mdx | 14 +++++++------- billing/budgets.mdx | 4 ++++ billing/plans.mdx | 4 ++++ cli/configuration.mdx | 16 +++++++++++----- cli/install.mdx | 8 +++----- cli/zombiectl.mdx | 2 +- quickstart.mdx | 2 +- workspaces/overview.mdx | 6 +++--- zombies/credentials.mdx | 14 +++++++------- zombies/overview.mdx | 2 +- zombies/troubleshooting.mdx | 4 ++-- 11 files changed, 44 insertions(+), 32 deletions(-) diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index 345e2a3..d966529 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -25,23 +25,23 @@ Two kinds of bearer token are accepted: ## Errors -All errors follow a consistent format: +All errors use RFC 7807 problem detail (`Content-Type: application/problem+json`): ```json { - "error": { - "code": "UZ-WORKSPACE-001", - "message": "No workspace with the given ID exists." - }, + "docs_uri": "https://docs.usezombie.com/api-reference/error-codes#UZ-WORKSPACE-001", + "title": "Workspace not found", + "detail": "No workspace with the given ID exists.", + "error_code": "UZ-WORKSPACE-001", "request_id": "req_01JQ7K..." } ``` -Error codes follow the `UZ--NNN` scheme. Every response includes a `request_id` for tracing. See [Error codes](/api-reference/error-codes) for the full registry. +Error codes follow the `UZ--NNN` scheme in the `error_code` field. Every response includes a `request_id` for tracing. See [Error codes](/api-reference/error-codes) for the full registry. ## Conventions -- **IDs** are UUIDs. +- **IDs** are UUIDv7. - **Timestamps** are Unix milliseconds. - **State transitions** are partial updates on the parent resource (e.g., `PATCH /v1/workspaces/{workspace_id}/zombies/{zombie_id}` with body `{status: "stopped"}`). Sub-resources (e.g., `/messages`, `/events`, `/events/stream`) handle data-flow operations. - **Streaming endpoints** (activity stream) return Server-Sent Events. diff --git a/billing/budgets.mdx b/billing/budgets.mdx index bd45070..16c5422 100644 --- a/billing/budgets.mdx +++ b/billing/budgets.mdx @@ -5,6 +5,10 @@ description: "Per-zombie dollar ceilings, tenant-wide spend caps, and how debits usezombie enforces budgets at two levels: per-zombie ceilings declared in `TRIGGER.md`, and a tenant-wide balance that every stage debits against. + + **Free until July 31, 2026.** During the launch trial, hosted execution is free — the tenant-wallet mechanics below apply **after** the trial. See [pricing](https://usezombie.com/pricing). + + ## Per-zombie ceilings (`daily_dollars` / `monthly_dollars`) Every zombie declares its own dollar ceilings in `TRIGGER.md`: diff --git a/billing/plans.mdx b/billing/plans.mdx index 47eef5e..3584e60 100644 --- a/billing/plans.mdx +++ b/billing/plans.mdx @@ -5,6 +5,10 @@ description: "Hobby and Scale — what you get and how credits work." usezombie has two plans. Both include the full platform — always-on agent hosting, the tool bridge, activity stream, webhook ingestion, kill switch. The difference is scale and support. + + **Free until July 31, 2026.** During the launch trial, hosted execution — every event receipt and stage — is free. The plan details below describe billing **after** the trial. See [pricing](https://usezombie.com/pricing). + + ## Hobby (Free) New tenants start here. The first sign-in seeds the tenant balance with **$5 (500¢)** automatically — there are no tokens to enter or gates to clear. The balance is waiting for you the moment Clerk completes auth. diff --git a/cli/configuration.mdx b/cli/configuration.mdx index 50bc5fb..3225534 100644 --- a/cli/configuration.mdx +++ b/cli/configuration.mdx @@ -5,13 +5,19 @@ description: "Configuration precedence and environment variables." ## Auth precedence -Authentication is resolved in this order, highest priority first: +`zombiectl login` decides which token to **store**, highest priority first: -1. **CLI flag** -- `--token ` on any command -2. **Environment variable** -- `ZOMBIE_TOKEN` -3. **Stored credentials** -- written by `zombiectl login` to `~/.config/zombiectl/credentials` +1. **`--token `** — login-only flag +2. **`ZOMBIE_TOKEN`** environment variable +3. **Piped stdin** — token read from a pipe +4. **Browser device flow** — interactive terminals only -A value at a higher level always wins. Use `ZOMBIE_TOKEN` in CI so no interactive login is needed. Use `--token` for one-off overrides without touching stored credentials. +Every **other command** then resolves its token, and the order is TTY-aware: + +- **Interactive terminal** — `ZOMBIE_TOKEN` wins over stored credentials, so an env var you just exported overrides a possibly-stale file. +- **Non-interactive (CI, cron, pipes)** — stored credentials (written by `zombiectl login` to `~/.config/zombiectl/credentials.json`) win, falling back to `ZOMBIE_TOKEN` only when no file exists. + +`--token` is not accepted on commands other than `login`; use the `ZOMBIE_TOKEN` env var for one-off overrides in scripts. ## API URL precedence diff --git a/cli/install.mdx b/cli/install.mdx index 00d5aca..3460734 100644 --- a/cli/install.mdx +++ b/cli/install.mdx @@ -49,14 +49,12 @@ Run the built-in diagnostics command to verify API connectivity, auth status, an zombiectl doctor ``` -`doctor` runs five checks and exits non-zero if any fails: +`doctor` runs three checks and exits non-zero if any fails. It does **not** require authentication and never short-circuits — every check runs and reports: | Check | Verifies | |---|---| -| `auth_token_present` | The local config has a valid auth token from `zombiectl login`. Short-circuits the rest — every check downstream needs auth. | | `server_reachable` | `GET /healthz` against the configured API URL returns `{ "status": "ok" }` within 5s. | | `workspace_selected` | The local config has a `current_workspace_id`. Auto-populated by `zombiectl login` from your signup-provisioned default workspace; can also be set or replaced by `zombiectl workspace add` / `workspace use`. | -| `workspace_binding_valid` | The auth token can read the selected workspace's zombies — i.e. it is bound to the right tenant. | -| `tenant_provider` | Returns the active inference posture for the tenant: `{ mode, model, context_cap_tokens, free_trial }`. `mode` is `platform` (you pay credits, we route to a default model) or `self_managed` (you attached your own provider key via `zombiectl tenant provider set`). `free_trial` carries `{ active, ends_at_ms }` while the launch trial window is open. | +| `workspace_binding_valid` | The resolved auth token can read the selected workspace's zombies — i.e. it is bound to the right tenant. Reports a failed check (rather than aborting) when no token is present. | -Pass `--json` for the structured `{ ok, api_url, checks: [...] }` envelope. Run it before any install — host-agent skills depend on this preflight. +Pass `--json` for the structured `{ ok, api_url, checks: [...] }` envelope. Run it before any install — host-agent skills depend on this preflight. For the tenant's inference posture and free-trial window, use [`zombiectl tenant provider show`](/cli/zombiectl#tenant-provider). diff --git a/cli/zombiectl.mdx b/cli/zombiectl.mdx index 5fd8de2..127471b 100644 --- a/cli/zombiectl.mdx +++ b/cli/zombiectl.mdx @@ -58,7 +58,7 @@ The login session lives 5 minutes; an unfinished approval expires automatically. ### `zombiectl logout` -Removes local credentials (`~/.config/usezombie/credentials.json`) and aborts any in-flight `zombiectl login` flows you have pending. +Removes local credentials (`~/.config/zombiectl/credentials.json`) and aborts any in-flight `zombiectl login` flows you have pending. ```bash zombiectl logout diff --git a/quickstart.mdx b/quickstart.mdx index 158ac62..99076e2 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -44,7 +44,7 @@ This walks through installing the flagship `platform-ops` zombie on one of your Pass `--token-name "your-device-label"` to label this install so it's easy to recognize on the approval page and in `zombiectl auth status` later. Defaults to your platform family otherwise. - **No terminal — CI, or an agent driving the CLI?** Skip the browser entirely: supply a token via the `ZOMBIE_TOKEN` environment variable (preferred — keeps it out of shell history), the `--token ` flag, or piped on stdin, resolved in that order. Add `--no-input` to fail fast instead of waiting for the code — a no-TTY shell with no token exits with an error. Full precedence in [`zombiectl login`](/cli/zombiectl#zombiectl-login). + **No terminal — CI, or an agent driving the CLI?** Skip the browser entirely: supply a token via the `--token ` flag, the `ZOMBIE_TOKEN` environment variable, or piped on stdin — resolved in that order (prefer the env var or stdin to keep it out of shell history). Add `--no-input` to fail fast instead of waiting for the code — a no-TTY shell with no token exits with an error. Full precedence in [`zombiectl login`](/cli/zombiectl#zombiectl-login). diff --git a/workspaces/overview.mdx b/workspaces/overview.mdx index f7ac669..012d953 100644 --- a/workspaces/overview.mdx +++ b/workspaces/overview.mdx @@ -3,7 +3,7 @@ title: "Workspaces" description: "What a workspace is and how it relates to your tenant." --- -A **workspace** is a tenant-scoped container for zombies, their credentials, and their webhooks. Workspaces are not bound to a GitHub repo — repos enter the picture per-zombie, when you wire an upstream webhook to a `zombie_id` (see [Webhooks](/zombies/webhooks)). Multiple workspaces under one tenant let you separate environments (staging vs. production) or domains (platform-ops vs. customer-success) without giving up the shared tenant wallet. +A **workspace** is a tenant-scoped container for zombies, their credentials, and their webhooks. Workspaces are not bound to a GitHub repo — repos enter the picture per-zombie, when you wire an upstream webhook to a `zombie_id` (see [Webhooks](/zombies/webhooks)). Multiple workspaces under one tenant let you separate environments (staging vs. production) or domains (platform-ops vs. customer-success) without splitting billing, which stays at the tenant level. ## What a workspace contains @@ -11,12 +11,12 @@ Each workspace has its own: - **Zombies** — the configured agents that live and run here. - **Credentials** — the vault keys zombies in this workspace can read. Workspace-scoped on purpose: credentials do not leak across workspaces. -- **Webhook namespace** — every zombie in a workspace gets its own unique URL under `https://api.usezombie.com/v1/webhooks/{zombie_id}`. +- **Webhook namespace** — every zombie in a workspace gets its own unique URL under `https://api.usezombie.com/v1/webhooks/{zombie_id}/{source}`. - **Access control** — teammates invited to a workspace can see, start, and kill its zombies; they cannot see zombies in other workspaces. ## What a workspace does NOT contain -- **Billing.** Credits, plan tier, and Stripe subscription all live on the **tenant**, not the workspace. Creating a second workspace does not give you a second $5 credit; every stage in every workspace debits the same tenant wallet. See [Billing and cost control](/billing/plans). +- **Billing.** Plan tier and Stripe subscription all live on the **tenant**, not the workspace. Creating a second workspace does not change billing — every stage in every workspace draws on the same tenant account. See [Billing and cost control](/billing/plans). - **Per-workspace spend caps.** Monthly spend caps live at the tenant level in v2. ## Plan limits diff --git a/zombies/credentials.mdx b/zombies/credentials.mdx index 1c789ea..3ea18bb 100644 --- a/zombies/credentials.mdx +++ b/zombies/credentials.mdx @@ -74,13 +74,13 @@ A zombie declares the credentials it needs as a **list of bare key names** in it name: platform-ops-zombie x-usezombie: - trigger: - type: webhook - source: github - signature: - secret_ref: github_secret - header: x-hub-signature-256 - prefix: "sha256=" + triggers: + - type: webhook + source: github + signature: + secret_ref: github_secret + header: x-hub-signature-256 + prefix: "sha256=" credentials: - github diff --git a/zombies/overview.mdx b/zombies/overview.mdx index c61d8e0..32e3c41 100644 --- a/zombies/overview.mdx +++ b/zombies/overview.mdx @@ -47,7 +47,7 @@ Every zombie belongs to exactly one **workspace**. The workspace is the boundary - **Access control** — teammates invited to a workspace can see, start, and kill its zombies; they cannot see zombies in other workspaces. - **Webhook namespace** — every zombie in a workspace gets one unique URL per declared trigger under `https://api.usezombie.com/v1/webhooks/{zombie_id}/{source}` (one entry per `triggers[].source` in `TRIGGER.md`). -Billing is **not** workspace-scoped. Every stage — no matter which workspace it lives in — debits the same tenant wallet. See [Key concepts](/concepts#credits) for the single-wallet model. +Billing is **not** workspace-scoped — every workspace draws on the same tenant-level billing. See [Billing](/billing/plans) for the model. `zombiectl workspace add [name]` creates a new workspace and sets it as active. Switch between existing ones with `zombiectl workspace use ` (run `zombiectl workspace list` first to see the IDs). The dashboard's active-workspace selection is independent — switching there does not affect the CLI and vice versa. diff --git a/zombies/troubleshooting.mdx b/zombies/troubleshooting.mdx index 0934b38..8e8dd5b 100644 --- a/zombies/troubleshooting.mdx +++ b/zombies/troubleshooting.mdx @@ -61,10 +61,10 @@ If the upstream itself shows a non-2xx response, the body carries one of: | Wire code | HTTP | What to check | |---|---|---| -| `UZ-WH-001` | 404 | URL is wrong. The path is `https://api.usezombie.com/v1/webhooks/{zombie_id}` — verify the ID matches `zombiectl status`. | +| `UZ-WH-001` | 404 | URL is wrong. The path is `https://api.usezombie.com/v1/webhooks/{zombie_id}/{source}` — verify the ID matches `zombiectl status`. | | `UZ-WH-002` | 400 | Request body is malformed JSON or empty. | | `UZ-WH-003` | 403 | Zombie is paused or killed. `zombiectl status` will show the state; re-install with `zombiectl install --from `. | -| `UZ-WH-010` | 401 | HMAC signature verification failed. The shared secret in your vault doesn't match the one configured at the upstream. Rotate per [Quickstart → Wire the GitHub webhook](/quickstart#wire-the-github-webhook). | +| `UZ-WH-010` | 401 | HMAC signature verification failed. The shared secret in your vault doesn't match the one configured at the upstream. Rotate per [Quickstart → Verify the registered webhook](/quickstart#verify-the-registered-webhook). | | `UZ-WH-011` | 401 | Replay-window violation — request timestamp is older than 5 minutes. Sender clock skew is the usual culprit. | | `UZ-WH-020` | 401 | No webhook credential configured for this zombie's source. The `secret_ref` in `TRIGGER.md` either isn't set or points at a vault key that doesn't exist. Run `zombiectl credential list` to confirm; add with `zombiectl credential add --data=@-`. | | `UZ-WH-030` | 413 | Payload exceeds the 1 MiB ingest limit. The upstream is sending too much; filter or trim the event body before forwarding. | From 74a9fa629216a0457d4cb60d9579e6b829d7be52 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Tue, 26 May 2026 15:02:10 +0530 Subject: [PATCH 5/6] =?UTF-8?q?docs(index):=20address=20greptile=20P1s=20?= =?UTF-8?q?=E2=80=94=20full=20secrets=20placeholder=20+=20login=20step?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Restore `${secrets.NAME.FIELD}` (was simplified to `${secrets.NAME}`; the .FIELD component is required — a single credential can hold multiple fields, e.g. a GitHub credential carries both a token and a webhook secret) - Add `zombiectl login` to the Get started flow so the landing page no longer implies the install skill signs you in (login is a separate prerequisite) Co-Authored-By: Claude Opus 4.7 (1M context) --- index.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/index.mdx b/index.mdx index 1457c2b..fafa84a 100644 --- a/index.mdx +++ b/index.mdx @@ -13,14 +13,15 @@ A deploy fails at 2am. Your senior on-call engineer is asleep. You guess at the usezombie owns the outcome instead. A **zombie** is a durable runtime described in two markdown files — `SKILL.md` (the senior engineer's playbook in prose) plus `TRIGGER.md` (which tools the agent can reach and which events wake it). When a trigger fires, the zombie gathers the evidence, reasons over it, posts an evidenced diagnosis to your Slack channel, and keeps a replayable log of every move it made. -The flagship `platform-ops` wakes on a GitHub Actions deploy failure, pulls workflow logs + your hosting provider's app state + your data-plane's health, and posts a one-paragraph diagnosis with a leading hypothesis. The same zombie is reachable via `zombiectl steer` for a manual investigation. The runtime is open source, you bring your own model and pay your provider directly, and the agent never sees your raw keys — only `${secrets.NAME}` placeholders, swapped for real values outside the sandbox. +The flagship `platform-ops` wakes on a GitHub Actions deploy failure, pulls workflow logs + your hosting provider's app state + your data-plane's health, and posts a one-paragraph diagnosis with a leading hypothesis. The same zombie is reachable via `zombiectl steer` for a manual investigation. The runtime is open source, you bring your own model and pay your provider directly, and the agent never sees your raw keys — only `${secrets.NAME.FIELD}` placeholders, swapped for real values outside the sandbox. ## Get started -`platform-ops` goes from a cold machine to a real diagnosis in Slack in about ten minutes. Install the CLI: +`platform-ops` goes from a cold machine to a real diagnosis in Slack in about ten minutes. Install the CLI and sign in: ```bash npm install -g @usezombie/zombiectl +zombiectl login ``` Then invoke the install skill inside your agent — Claude Code, Amp, Codex CLI, or OpenCode: From e3871f2a24e3ee5d2d5098942418daef128f4806 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Tue, 26 May 2026 15:13:37 +0530 Subject: [PATCH 6/6] docs(concepts): clarify budget ceilings vs free trial MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit greptile flagged that the Budget accordion didn't relate the dollar ceilings to the free-trial framing above it. Source confirms computeStageCharge returns $0 while the trial is active (tenant_billing.zig FREE_TRIAL_STAGE_NANOS), so a daily/monthly ceiling won't stop a zombie for trial usage — the caps apply to the metered rate after July 31, 2026. Stated that explicitly. Co-Authored-By: Claude Opus 4.7 (1M context) --- concepts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts.mdx b/concepts.mdx index 66d85f7..e40a023 100644 --- a/concepts.mdx +++ b/concepts.mdx @@ -100,6 +100,6 @@ A trigger lands on the event stream. A stage opens. The agent calls tools allow- - Dollar ceilings on hosted execution (the platform compute that runs your zombie — separate from your model provider's bill) declared in `TRIGGER.md`. `daily_dollars` caps spend over a rolling 24-hour window; `monthly_dollars` caps the calendar month. Hitting either ceiling stops new stages from opening. Inference is on your model provider's bill, not on your usezombie invoice — your provider's own caps apply there. + Dollar ceilings on hosted execution (the platform compute that runs your zombie — separate from your model provider's bill) declared in `TRIGGER.md`. `daily_dollars` caps spend over a rolling 24-hour window; `monthly_dollars` caps the calendar month. Hitting either ceiling stops new stages from opening. During the launch free trial (through July 31, 2026) hosted-execution stages are billed at **$0**, so a budget ceiling won't stop a zombie for trial usage — these caps apply to the metered rate after the trial (see [pricing](https://usezombie.com/pricing)). Inference is on your model provider's bill, not on your usezombie invoice — your provider's own caps apply there.