swamp git:20261013.dcc3099A

Immutable. This exact content never changes and is served at /api/v1/blob/73bc3d6a6d516af3.

---
name: swamp
description: >
  Swamp CLI — create and run behaviors (formerly models), build and validate
  workflows, query and manage data, store and retrieve vault secrets, develop
  and publish extensions, initialize repos, run reports, file issues, and
  troubleshoot errors. Triggers on swamp commands (swamp behavior, swamp
  behavior run, swamp model, swamp workflow, swamp vault, swamp data),
  extension development, repo setup, or diagnostic questions. Do NOT use for
  getting started / onboarding (use swamp-getting-started), pull requests, git
  operations, worktree management, cron/agent scheduling, or general coding
  tasks unrelated to swamp.
---

# Swamp

## Core Concepts

- **Behaviors** (formerly models) — typed resource definitions exposing methods
  (create, stop, destroy, sync). `swamp behavior` is the preferred spelling;
  every `swamp model` spelling still works (see
  [references/behavior/reference.md#compatibility](references/behavior/reference.md#compatibility)).
- **Data** — versioned state snapshots produced by method runs; referenced via
  CEL expressions.
- **Workflows** — declarative DAGs chaining behavior methods with guard
  expressions for idempotent execution and assert steps for validation.
- **Vaults** — secret storage referenced by behaviors at runtime.
- **Extensions** — TypeScript packages adding behavior types, vault backends,
  datastores, reports, and webhook handlers.
- **Grants** — authorization rules for swamp serve access control.
- **Serve** — exposes the repo over the network with TLS and authentication.

## Routing Table

Route to the right guide based on what the user needs.

| User intent                                                      | Guide                                                                          |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Behaviors — create, run, edit, delete, search types              | [references/behavior/guide.md](references/behavior/guide.md)                   |
| Workflows — create, run, validate, DAG, history                  | [references/workflow/guide.md](references/workflow/guide.md)                   |
| Data — list, query, versions, GC, delete                         | [references/data/guide.md](references/data/guide.md)                           |
| Vaults — create, store/read secrets, expressions                 | [references/vault/guide.md](references/vault/guide.md)                         |
| Reports — run, configure, view, filter                           | [references/report/guide.md](references/report/guide.md)                       |
| Repository — init, upgrade, datastores, sources                  | [references/repo/guide.md](references/repo/guide.md)                           |
| Extensions — create behaviors/vaults/datastores/reports/webhooks | [references/extension/guide.md](references/extension/guide.md)                 |
| Publishing — push extensions to registry, deprecate              | [references/extension-publish/guide.md](references/extension-publish/guide.md) |
| Issues — file bugs, features, security reports                   | [references/issue/guide.md](references/issue/guide.md)                         |
| Run tracking — active runs, stale detection, diagnostics         | [references/behavior/guide.md](references/behavior/guide.md)                   |
| Architecture — which primitive to use, design trade-offs         | [references/architecture/guide.md](references/architecture/guide.md)           |
| Sharing — promote solo repo to team, datastore + vault setup     | [references/share/guide.md](references/share/guide.md)                         |
| Serve — auth, grants, access control, tokens, OAuth              | [references/serve/guide.md](references/serve/guide.md)                         |
| Troubleshooting — errors, health checks, diagnostics             | [references/troubleshooting/guide.md](references/troubleshooting/guide.md)     |

## Common Commands

```bash
# Behaviors
swamp behavior create <type> <name>            # create a behavior definition
swamp behavior run @<type> <method> <name>     # run a method on a behavior
swamp behavior get <name> --json               # inspect current behavior state
swamp behavior type search [query]             # find available behavior types
swamp behavior list                            # list all behaviors in the repo

# Data
swamp data list <name>                         # list data versions for a behavior
swamp data query '<CEL predicate>'             # query data with CEL expressions
# read one item's latest content (`swamp data get` is deprecated)
swamp data query 'model("<model>") && name == "<data>"' --select content

# Workflows
swamp workflow create <name>                   # create a new workflow
swamp workflow validate <name>                 # validate DAG before running
swamp workflow run <name>                      # execute a workflow
swamp workflow run <name> --input key=value    # execute with inputs
swamp workflow resume <name>                   # resume a suspended workflow
swamp workflow resume <name> --run <id>        # retry a failed run's failed steps
swamp workflow resume <name> --from <step>     # re-enter failed run at step
swamp workflow history search --json           # search run history

# Run tracking
swamp run history                              # recent runs (last 24h)
swamp run history --active                     # what's running right now?
swamp run doctor                               # diagnose stale/orphaned runs
swamp run doctor --fix                         # auto-reap stale runs

# Vaults, Reports, Extensions
swamp vault create <type> <name>               # create a vault for secrets
swamp report run <name>                        # run a report
swamp extension init <name>                    # scaffold a new extension
```

## Workflow

1. **Route** — match intent to a guide in the routing table.
2. **Load** — read the guide; load its `reference.md` if needed, deeper
   `references/` only when the guide says to.
3. **Validate** — before running any workflow: `swamp workflow validate <name>`.
   Before destructive methods (delete, stop, destroy):
   `swamp behavior get <name> --json` to confirm the target exists and is in the
   expected state. Proceed only when validation passes.
4. **Verify args** — run `swamp help <subcommand>` (e.g.
   `swamp help behavior run`) to confirm exact flags and arguments before
   executing. The output is structured JSON — the canonical CLI schema.
5. **Execute** — run the command.
6. **On failure** — load
   [references/troubleshooting/guide.md](references/troubleshooting/guide.md)
   and diagnose before retrying or changing definitions.

## Rules

1. **Use the routing table, not memory.** Don't answer from cached knowledge
   about swamp commands — always load the current guide.
2. **Consult the architecture guide for design decisions.** Before choosing
   between primitives (behavior vs. workflow vs. extension vs. report) or
   explaining a design trade-off, load
   [references/architecture/guide.md](references/architecture/guide.md) and cite
   the design doc you relied on.
3. **Use swamp commands, don't go around them.** Query data with
   `swamp data query`, not by grepping `.swamp/` files. Interact with resources
   through behavior methods, not raw CLI tools when a behavior type already
   wraps the API — check with `swamp behavior type search`. Composing with
   `--json` output (e.g. piping through `jq`) is fine — the anti-pattern is
   bypassing swamp entirely.
4. **Verify flags with `swamp help` before executing.** `swamp help <command>`
   outputs the full CLI schema as structured JSON — every subcommand, argument,
   and option. Always run it to confirm exact flags before executing a swamp
   command (workflow step 4). Do not guess flags from memory.