Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .gitleaks.toml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
title = "Zombie Docs Gitleaks Config"
title = "Agent Docs Gitleaks Config"

[allowlist]
description = "Allow placeholder tokens used in documentation examples"
Expand Down
4 changes: 2 additions & 2 deletions .mlc-config.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
"ignorePatterns": [
{ "pattern": "^/" },
{ "pattern": "^https://discord.gg" },
{ "pattern": "^https://usezombie.com" },
{ "pattern": "^https://app.usezombie.com" },
{ "pattern": "^https://agentsfleet.net" },
{ "pattern": "^https://app.agentsfleet.net" },
{ "pattern": "^mailto:" }
],
"retryOn429": true,
Expand Down
18 changes: 9 additions & 9 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## About this project

- This is the usezombie documentation site built on [Mintlify](https://mintlify.com)
- This is the agentsfleet documentation site built on [Mintlify](https://mintlify.com)
- Pages are MDX files with YAML frontmatter
- Configuration lives in `docs.json`
- Run `mint dev` to preview locally on port 3000
Expand All @@ -12,7 +12,7 @@

## Terminology

- Use "agent" (lowercase) for the product noun — the always-on agent process. "zombie" is legacy terminology; do not use it in new prose (brand/code tokens like `usezombie`, `zombiectl`, `zombied`, `zmb_`, `zombie_id`, and `/zombies/` paths stay)
- Use "agent" (lowercase) for the product noun — the always-on agent process. "agent" is legacy terminology; do not use it in new prose (brand/code tokens like `agentsfleet`, `agentsfleet`, `agentsfleetd`, `zmb_`, `agent_id`, and `/agents/` paths stay)
- Use "workspace" not "project"
- Use "skill" for a named capability an agent can invoke (agentmail, slack, github, ...)
- Use "trigger" for how an agent receives events (today: webhook)
Expand All @@ -25,9 +25,9 @@
- Use "runner" for the execution-plane process that sandboxes and runs an agent — not "executor"
- Use "agent" not "bot" or "AI"
- Use "PR" not "pull request" (except on first mention per page)
- Use `zombiectl` in code formatting when referring to CLI commands
- Use `zombied` in code formatting when referring to server processes
- Use "Dashboard" (capitalized in headings, lowercase "dashboard" in body prose) for the web app at `app.usezombie.com`. The earlier aspirational name for this surface is retired — do not reintroduce it.
- Use `agentsfleet` in code formatting when referring to CLI commands
- Use `agentsfleetd` in code formatting when referring to server processes
- Use "Dashboard" (capitalized in headings, lowercase "dashboard" in body prose) for the web app at `app.agentsfleet.net`. The earlier aspirational name for this surface is retired — do not reintroduce it.

Forbidden terminology: `spec`, `stage`, `gate loop`, `scorecard`. These refer to a v1 product surface that has been removed. Do not introduce them into new pages. (`run`/`runs` are now the v2 execution unit — see Terminology above.)

Expand All @@ -51,10 +51,10 @@ Forbidden terminology: `spec`, `stage`, `gate loop`, `scorecard`. These refer to

## When closing out a feature PR in the lead repo (companion docs flow)

A landing PR in any lead repo (`usezombie`, `zombiectl`, the website, the app) almost always drifts the docs site. Before the lead-repo PR flips ready-for-review:
A landing PR in any lead repo (`agentsfleet`, `agentsfleet`, the website, the app) almost always drifts the docs site. Before the lead-repo PR flips ready-for-review:

1. **Review the lead PR's changed files.** Every public-surface change is a candidate doc edit — HTTP request/response shape, CLI subcommand or flag, frontmatter schema, error code, env var, default value, response field, pricing / billing copy, dashboard flow.
2. **Identify the `.mdx` pages that drift.** Grep this docs repo for the old field name, old YAML shape, old subcommand, old copy. Common candidates: `quickstart.mdx`, `cli/*.mdx`, `zombies/*.mdx` (especially `authoring.mdx`, `webhooks.mdx`, `install.mdx`, `running.mdx`), `api-reference/*.mdx`, `billing/*.mdx`, `snippets/rates.mdx`, `concepts/*.mdx`.
2. **Identify the `.mdx` pages that drift.** Grep this docs repo for the old field name, old YAML shape, old subcommand, old copy. Common candidates: `quickstart.mdx`, `cli/*.mdx`, `agents/*.mdx` (especially `authoring.mdx`, `webhooks.mdx`, `install.mdx`, `running.mdx`), `api-reference/*.mdx`, `billing/*.mdx`, `snippets/rates.mdx`, `concepts/*.mdx`.
3. **Update the relevant pages.** Fix examples, tables, and prose. Preserve load-bearing detail (`UZ-XXX-NNN` error codes, endpoint paths, env var names, schema column names, money amounts). Don't rewrite past entries; only touch pages that no longer describe what shipped.
4. **Add a `changelog.mdx` `<Update>` block** at the top, after the leading `<Tip>`. Section order is fixed: Upgrading → What's new → API reference → Bug fixes → CLI. Voice rules: lead with the change, no marketing words, no milestone IDs / spec filenames / `RULE XXX` references. Date label `MMM DD, YYYY`, no semver prefix. Two entries on the same date get distinct titles (no disambiguator suffix needed) or a merged block.
5. **All four steps land on a dedicated docs-repo branch** — `chore/m{N}-{slug}-changelog` off `main`. Do not commit docs changes on the lead-repo feature branch (it's a separate repository) and do not commit on `main` directly. Open the docs PR alongside the lead PR so reviewers can cross-link the two.
Expand All @@ -63,10 +63,10 @@ The rule applies to every milestone PR, not just trigger/CLI ones — schema mig

## Design system colors

{/* SYNC SOURCE: ~/Projects/usezombie/ui/packages/design-system/src/tokens.css
{/* SYNC SOURCE: ~/Projects/agentsfleet/ui/packages/design-system/src/tokens.css
When touching colors in this repo (docs.json, logos, custom CSS), always
verify values against the canonical design-system tokens first.
Run: grep -E "^ --(pulse|bg|surface|text|success|warn|error|info|evidence)" ~/Projects/usezombie/ui/packages/design-system/src/tokens.css
Run: grep -E "^ --(pulse|bg|surface|text|success|warn|error|info|evidence)" ~/Projects/agentsfleet/ui/packages/design-system/src/tokens.css

Heritage `--z-orange` palette retired in M64 (Operational Restraint
rollout). Anything still referencing `#d96b2b` / `--z-orange` is stale. */}
Expand Down
2 changes: 1 addition & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ SHELL := /bin/bash

.PHONY: dev lint test _lint-openapi-drift

OPENAPI_URL ?= https://raw.githubusercontent.com/usezombie/usezombie/main/public/openapi.json
OPENAPI_URL ?= https://raw.githubusercontent.com/agentsfleet/agentsfleet/main/public/openapi.json

dev:
npx mintlify dev
Expand Down
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
<picture>
<source media="(prefers-color-scheme: dark)" srcset="logo/dark.svg" />
<source media="(prefers-color-scheme: light)" srcset="logo/light.svg" />
<img src="logo/dark.svg" width="200" alt="usezombie" />
<img src="logo/dark.svg" width="200" alt="agentsfleet" />
</picture>

**Your deploy failed. The agent already knows why.**
Expand All @@ -12,8 +12,8 @@ A long-lived runtime that owns one operational outcome end to end.
Wakes on your events. Runs against a durable, replayable log.
Posts evidenced answers — never chats.

[![Docs](https://img.shields.io/badge/usezombie-Docs-5EEAD4?style=for-the-badge)](https://docs.usezombie.com)
[![Get early access](https://img.shields.io/badge/usezombie-Get_early_access-5EEAD4?style=for-the-badge)](https://usezombie.com)
[![Docs](https://img.shields.io/badge/agentsfleet-Docs-5EEAD4?style=for-the-badge)](https://docs.agentsfleet.net)
[![Get early access](https://img.shields.io/badge/agentsfleet-Get_early_access-5EEAD4?style=for-the-badge)](https://agentsfleet.net)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)

</div>
Expand All @@ -37,4 +37,4 @@ Changes pushed to the default branch are deployed automatically via the [Mintlif

## License

MIT — Copyright (c) 2026 usezombie
MIT — Copyright (c) 2026 agentsfleet
40 changes: 20 additions & 20 deletions zombies/authoring.mdx → agents/authoring.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ my-agent/
└── TRIGGER.md # machine-readable config + deployment metadata
```

`zombiectl install <template>` scaffolds both. This page is the reference for authoring your own.
`agentsfleet install <template>` scaffolds both. This page is the reference for authoring your own.

## `SKILL.md` — agent instructions

Expand All @@ -28,7 +28,7 @@ description: Diagnoses platform health from fly.io and upstash, posts to Slack.
version: 0.1.0 # required, semver
when_to_use: ... # optional
tags: [platform-ops, diagnostics] # optional
author: usezombie # optional
author: agentsfleet # optional
model: claude-sonnet-4-6 # optional, hint
---
```
Expand Down Expand Up @@ -87,7 +87,7 @@ always frame as "leading hypothesis" and let the human decide.
---
name: platform-ops-agent # top level — must match SKILL.md `name:`

x-usezombie: # all runtime config nests under this key
x-agentsfleet: # all runtime config nests under this key
triggers: # array, 1–8 entries; one agent can wake on many sources
- type: api # operator chats via /steer; events arrive as event_type: chat
tools:
Expand Down Expand Up @@ -120,22 +120,22 @@ x-usezombie: # all runtime config nests under this key
| Field | Required | Purpose |
|---|---|---|
| `name` | yes | Identity. Must equal `SKILL.md` `name:`. |
| `x-usezombie` | yes | Runtime config block. Required subkeys below. |
| `x-agentsfleet` | yes | Runtime config block. Required subkeys below. |

Top-level keys other than `name`/`x-*` are accepted silently. Runtime keys (`tools`, `credentials`, `network`, `budget`, `trigger`) **must not** appear at the top level — they belong inside `x-usezombie:`.
Top-level keys other than `name`/`x-*` are accepted silently. Runtime keys (`tools`, `credentials`, `network`, `budget`, `trigger`) **must not** appear at the top level — they belong inside `x-agentsfleet:`.

### `x-usezombie:` subkeys
### `x-agentsfleet:` subkeys

Validation under this block is rigid: an unknown subkey is rejected with a typo hint. All listed subkeys are required unless marked optional.

| Subkey | Required | Purpose |
|---|---|---|
| `triggers[]` | yes | Array of 1–8 trigger entries. The singular `trigger:` shape is rejected at install (`ERR_ZOMBIE_INVALID_CONFIG: use "triggers:" (array)`). Entries are unique on the `(type, source)` tuple; at most one `cron` entry. |
| `triggers[]` | yes | Array of 1–8 trigger entries. The singular `trigger:` shape is rejected at install (`ERR_AGENTSFLEET_INVALID_CONFIG: use "triggers:" (array)`). Entries are unique on the `(type, source)` tuple; at most one `cron` entry. |
| `triggers[].type` | yes | One of `webhook` \| `cron` \| `api`. See the table below. |
| `triggers[].source` | per type | Required for `webhook`. Carries the upstream label (e.g. `github`, `slack`, `linear`) and selects the per-trigger URL `…/v1/webhooks/{zombie_id}/{source}` — see [Webhooks](/zombies/webhooks). |
| `triggers[].source` | per type | Required for `webhook`. Carries the upstream label (e.g. `github`, `slack`, `linear`) and selects the per-trigger URL `…/v1/webhooks/{agent_id}/{source}` — see [Webhooks](/agents/webhooks). |
| `triggers[].events` | optional | Per-webhook event whitelist (1–16 entries, ≤64 chars each). Omit to accept every event the source delivers. |
| `triggers[].signature.secret_ref` | optional | Vault key whose value verifies webhook signatures (first-class providers). |
| `tools` | yes | Non-empty list of tool names from the [Tools catalogue](/zombies/tools). |
| `tools` | yes | Non-empty list of tool names from the [Tools catalogue](/agents/tools). |
| `credentials` | optional | Vault key names the agent reads at event time. |
| `network.allow` | yes | Outbound hostname allowlist enforced by the sandbox. |
| `budget.daily_dollars` | yes | Rolling 24-hour dollar ceiling. |
Expand All @@ -145,23 +145,23 @@ Validation under this block is rigid: an unknown subkey is rejected with a typo

| YAML value | Wakes from | Use when | Companion fields |
|---|---|---|---|
| `webhook` | An external HTTP `POST` to `https://api.usezombie.com/v1/webhooks/{zombie_id}/{source}` with a signed body. | Most production agents — anything driven by a third-party event (GitHub, Slack, Linear, Jira, etc.). | `source` (label, also selects the URL) + `events` (optional whitelist) + `signature` (HMAC config). See [Webhooks](/zombies/webhooks). |
| `webhook` | An external HTTP `POST` to `https://api.agentsfleet.net/v1/webhooks/{agent_id}/{source}` with a signed body. | Most production agents — anything driven by a third-party event (GitHub, Slack, Linear, Jira, etc.). | `source` (label, also selects the URL) + `events` (optional whitelist) + `signature` (HMAC config). See [Webhooks](/agents/webhooks). |
| `cron` | A self-scheduled timer the agent sets via the `cron_add` tool. | Periodic health checks, drift sweeps, scheduled cleanups. | None at the trigger level — schedules live inside the reasoning loop. At most one `cron` entry per agent. |
| `api` | A `zombiectl steer` invocation or a `POST /v1/.../zombies/{id}/messages` API call. | Steerable, operator-driven agents — manual investigation, on-demand workflows, the install-time smoke test. | None. |
| `api` | A `agentsfleet steer` invocation or a `POST /v1/.../agents/{id}/messages` API call. | Steerable, operator-driven agents — manual investigation, on-demand workflows, the install-time smoke test. | None. |

An agent can declare up to eight triggers and wake on any of them — e.g. one webhook from GitHub plus a cron sweep every 30 minutes. Any agent can also be steered via `zombiectl steer` regardless of declared triggers — steer always works. The `api` type is for agents whose *primary* surface is steer (no inbound webhook).
An agent can declare up to eight triggers and wake on any of them — e.g. one webhook from GitHub plus a cron sweep every 30 minutes. Any agent can also be steered via `agentsfleet steer` regardless of declared triggers — steer always works. The `api` type is for agents whose *primary* surface is steer (no inbound webhook).

<Note>**Long-run continuations are not a trigger type.** When a run exhausts its context, the runtime re-enqueues the same event with `actor=continuation:<original_actor>` automatically. You don't declare this in `TRIGGER.md`; it happens regardless of which trigger type woke the original run. See [Context lifecycle](/concepts/context-lifecycle).</Note>

### Tools

The `tools:` list is the explicit allowlist of tools the agent may invoke. A compromised or jailbroken agent cannot reach outside this list.

23 tools are user-callable today, grouped by category — network (`http_request`, `web_search`, `web_fetch`), memory (`memory_store`/`recall`/`list`/`forget`), cron (`cron_add`/`list`/`remove`/`update`/`run`/`runs`), agent orchestration (`delegate`, `spawn`, `schedule`), browser, git, file edits, and stateless utilities. **See [Tools catalogue](/zombies/tools) for every tool with its purpose and use cases.**
23 tools are user-callable today, grouped by category — network (`http_request`, `web_search`, `web_fetch`), memory (`memory_store`/`recall`/`list`/`forget`), cron (`cron_add`/`list`/`remove`/`update`/`run`/`runs`), agent orchestration (`delegate`, `spawn`, `schedule`), browser, git, file edits, and stateless utilities. **See [Tools catalogue](/agents/tools) for every tool with its purpose and use cases.**

### Credentials

Each entry under `credentials:` is a **bare vault key name** referencing a JSON-shaped secret in the workspace vault (e.g. `github` carrying `{api_token, webhook_secret}`, `slack` carrying `{bot_token}`). Names like `github`, `slack`, `linear`, `jira` are credential references — **not** tool names. The tool bridge resolves the named credential at `http_request` time and substitutes its fields into outbound calls; the agent sees the response, never the raw secret. Add and rotate via [Credentials](/zombies/credentials).
Each entry under `credentials:` is a **bare vault key name** referencing a JSON-shaped secret in the workspace vault (e.g. `github` carrying `{api_token, webhook_secret}`, `slack` carrying `{bot_token}`). Names like `github`, `slack`, `linear`, `jira` are credential references — **not** tool names. The tool bridge resolves the named credential at `http_request` time and substitutes its fields into outbound calls; the agent sees the response, never the raw secret. Add and rotate via [Credentials](/agents/credentials).

### Network allowlist

Expand All @@ -180,17 +180,17 @@ A breach terminates the in-flight event cleanly and records a `budget_breach` en

| Symptom | Cause | Fix |
|---|---|---|
| `RuntimeKeysOutsideBlock` at install | `tools:`, `credentials:`, etc. at the top of TRIGGER.md | Indent them under `x-usezombie:`. |
| `UnknownRuntimeKey` at install | Typo in a runtime subkey (e.g. `crendentials:` instead of `credentials:`) | Fix the spelling, or remove the key. Validation under `x-usezombie:` is strict. |
| `RuntimeKeysOutsideBlock` at install | `tools:`, `credentials:`, etc. at the top of TRIGGER.md | Indent them under `x-agentsfleet:`. |
| `UnknownRuntimeKey` at install | Typo in a runtime subkey (e.g. `crendentials:` instead of `credentials:`) | Fix the spelling, or remove the key. Validation under `x-agentsfleet:` is strict. |
| `name_mismatch` at install | SKILL.md and TRIGGER.md disagree on `name:` | One identity per bundle. Make both top-level `name:` values equal. |
| `MissingRequiredField` for SKILL.md | `name`, `description`, or `version` missing from SKILL.md frontmatter | All three are required at the top level. |

## Validation

`zombiectl install --from <dir>` reads both files and posts them to the server, which runs the same parser the runtime uses. Errors are returned with the field at fault.
`agentsfleet install --from <dir>` reads both files and posts them to the server, which runs the same parser the runtime uses. Errors are returned with the field at fault.

```bash
zombiectl install --from ./my-agent
agentsfleet install --from ./my-agent
```

```
Expand All @@ -202,10 +202,10 @@ zombiectl install --from ./my-agent
## Next

<CardGroup cols={2}>
<Card title="Bundled templates" icon="layer-group" href="/zombies/templates">
<Card title="Bundled templates" icon="layer-group" href="/agents/templates">
See the anatomy of the flagship `platform-ops` sample.
</Card>
<Card title="Webhooks" icon="webhook" href="/zombies/webhooks">
<Card title="Webhooks" icon="webhook" href="/agents/webhooks">
Authentication modes and approval gates in depth.
</Card>
</CardGroup>
Loading
Loading