Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLI
Assigneesstack72

Relationships

#910 Add how-to guides for core operations and operational tasks

Opened by stack72 · 7/1/2026· Shipped 7/1/2026

Problem

The how-to section (content/manual/how-to/) has strong coverage for extensions, AI agents, vaults, giga-swamp, and swamp serve. But the three most common day-to-day operations — creating/running models, creating/running workflows, and querying data — have no how-to guides. A user who has read the explanation pages and reference docs still has nowhere to go for task-oriented "how do I do X?" guidance on these core operations.

Additional operational tasks (webhooks, extension trust, shell completions, audit, issues, activity overview, OpenTelemetry, scheduled workflows) also lack how-to guides despite having reference documentation.

Scope

This issue covers how-to documentation only (diataxis type: how-to). Every page must follow the how-to rules: goal-oriented, assumes the reader knows what they want to do, provides the steps to accomplish it, does not teach concepts (that's tutorial) or explain design decisions (that's explanation).

CRITICAL: Do Not Fabricate CLI Output

Previous documentation PRs (#783, #785) shipped errors because CLI command syntax, flag names, and default-trusted collectives were written from memory rather than verified against the actual CLI. Every how-to guide in this issue contains CLI commands and their output. All of it must be real.

Mandatory Verification Process

For every command shown in a how-to guide:

  1. Create a sandbox repo first:

    SWAMP_SANDBOX=$(mktemp -d) && cd "$SWAMP_SANDBOX" && swamp repo init

  2. Run the exact command you intend to document and capture the real output.

  3. Use the real output verbatim in the guide. Truncate long output with ... but never edit, paraphrase, or guess what the output looks like.

  4. Verify flag names and syntax by running swamp help <command path> before writing any flag table or command example. Do NOT write flags from memory.

  5. For interactive commands (TUI, editor-based), use a non-interactive alternative (--json, --title, --body flags) and document both paths.

  6. Clean up: rm -rf "$SWAMP_SANDBOX"

What Counts as Fabrication (Do NOT Do These)

  • Writing a command example without running it first
  • Inventing flag names that sound right (e.g., --webhook-secret instead of --webhook)
  • Guessing CLI output format or field names
  • Showing a command syntax that differs from swamp help output (e.g., wrong argument order)
  • Claiming a feature exists (e.g., @si default trust) without verifying it
  • Copy-pasting output from a reference page instead of re-running the command

How to Handle Commands That Need Infrastructure

Some commands require infrastructure (S3, cloud credentials, a running server). For these:

  • swamp serve commands: Start a local server in the sandbox, run the client commands against it, capture real output
  • Vault commands with cloud backends: Use the local_encryption vault type for examples, note that cloud backends follow the same pattern
  • Webhook commands: Document the server-side flag syntax (verifiable via swamp help serve) and show a curl test against localhost
  • OpenTelemetry: Show the env var configuration (verifiable via swamp help and the reference docs) and a swamp model method run with OTEL_TRACES_EXPORTER=console to capture real span output

The how-to section currently has these top-level tiles:

  1. Extensions (6 sub-pages)
  2. AI Agents (7 sub-pages)
  3. Vaults (5 sub-pages)
  4. swamp serve (7 sub-pages)
  5. Giga-Swamp (7 sub-pages)
  6. Remote Execution
  7. Set Up TLS for swamp serve
  8. Set Up Background Autoupdating
  9. Authenticate with API Keys
  10. Troubleshoot Your Swamp Repo
  11. Gate a Workflow with Manual Approval
  12. Cancel a Stuck Run
  13. Reuse a Model with the Factory Pattern

That's 13 top-level tiles. This issue adds 11 new how-to pages. To avoid tile overload, group related guides under index pages where it makes sense:

Grouping Strategy

New index page: "Core Operations" (how-to/core-operations.md, order 1)

Groups the three foundational how-to guides under one tile:

  • how-to/core-operations/create-and-run-a-model.md (order 1)
  • how-to/core-operations/create-and-run-a-workflow.md (order 2)
  • how-to/core-operations/query-and-manage-data.md (order 3)

New index page: "Operational Tasks" (how-to/operational-tasks.md, order 9)

Groups smaller operational guides under one tile:

  • how-to/operational-tasks/set-up-shell-completions.md (order 1)
  • how-to/operational-tasks/use-the-audit-timeline.md (order 2)
  • how-to/operational-tasks/file-issues-from-the-cli.md (order 3)
  • how-to/operational-tasks/inspect-repo-activity.md (order 4)

Standalone pages (no grouping needed):

  • how-to/set-up-webhooks.md (order 7) — sits near swamp serve guides
  • how-to/set-up-extension-trust.md (order 6) — sits near extension guides
  • how-to/set-up-opentelemetry.md (order 10) — standalone
  • how-to/run-workflows-on-a-schedule.md (order 11) — standalone

Net tile change: +6 tiles (13 → 19: 2 new index tiles + 4 standalone). The sub-pages nest under their index tiles in the nav, same as the existing Extensions/AI Agents/Vaults/etc. pattern.

Detailed Plan

Index Page 1: "Core Operations" (how-to/core-operations.md)

---
title: "Core Operations"
description: "<150-160 chars describing the group>"
type: how-to
order: 1
---

Brief intro paragraph explaining these guides cover the most common day-to-day swamp operations. Link to each sub-page.

Guide 1.1: "Create and Run a Model" (how-to/core-operations/create-and-run-a-model.md)

Prerequisites: Swamp installed, a repo initialized (swamp repo init)

What to cover, in order:

  1. Search for available model types: swamp model type search — show real output
  2. Inspect a type before using it: swamp model type describe command/shell --json — show real output (truncated)
  3. Create a model definition: swamp model create command/shell my-greeter — show what files it creates
  4. Edit the definition to set global arguments — show the YAML content
  5. Validate the definition: swamp model validate my-greeter — show real output
  6. Run a method: swamp model method run my-greeter execute — show real output
  7. Inspect the output: swamp model output my-greeter — show real output
  8. View method run history: swamp model method history my-greeter — show real output
  9. Quick path: auto-create with swamp model method run @command/shell execute my-quick-model — show how auto-definitions work

Do NOT cover: What models conceptually are (link to explanation/models-types-and-methods), the full YAML schema (link to reference/model-definitions), or extension model development (link to how-to/extensions/create-and-publish).

Guide 1.2: "Create and Run a Workflow" (how-to/core-operations/create-and-run-a-workflow.md)

Prerequisites: Swamp installed, a repo with at least one model (link to guide 1.1)

What to cover, in order:

  1. Create a workflow: swamp workflow create deploy-pipeline — show what files it creates
  2. Edit the workflow YAML — show a minimal example with two steps that reference the model from guide 1.1
  3. Validate the workflow: swamp workflow validate deploy-pipeline — show real output
  4. Run the workflow: swamp workflow run deploy-pipeline — show real output (the interactive tree)
  5. Run with --json for scripted use — show JSON output shape
  6. Pass inputs: swamp workflow run deploy-pipeline --input env=staging — show how inputs work
  7. View run history: swamp workflow history deploy-pipeline — show real output
  8. View logs: swamp workflow history logs deploy-pipeline — show real output
  9. Search past runs: swamp workflow history search --status succeeded — show real output

Do NOT cover: The DAG execution model (link to explanation/the-workflow-execution-model), manual approval gates (link to existing how-to/gate-a-workflow-with-manual-approval), or the full YAML schema (link to reference/workflows).

Guide 1.3: "Query and Manage Data" (how-to/core-operations/query-and-manage-data.md)

Prerequisites: Swamp installed, a repo with at least one model that has produced data (link to guide 1.1)

What to cover, in order:

  1. List data for a model: swamp data list my-greeter — show real output
  2. Get a specific data artifact: swamp data get my-greeter stdout — show real output
  3. View versions: swamp data versions my-greeter stdout — show real output
  4. Query across models with CEL: swamp data query 'modelName == "my-greeter"' — show real output
  5. Query with projections: swamp data query 'true' --select 'modelName + ": " + dataName' — show real output
  6. Launch the interactive TUI: swamp data query (no predicate) — describe what the TUI shows (screenshot if possible, otherwise describe the interface)
  7. Search by tag: swamp data search --tag env=staging — show real output
  8. Rename data: swamp data rename my-greeter old-name new-name — explain forwarding
  9. Delete data: swamp data delete my-greeter stdout — show real output with --dry-run first
  10. Run garbage collection: swamp data gc --dry-run — show real output

Do NOT cover: How the data layer works conceptually (link to explanation/the-data-layer), data output specs in YAML (link to reference/data), or CEL expression syntax (link to reference/cel-expressions).

Guide 2: "Set Up Extension Trust" (how-to/set-up-extension-trust.md)

Prerequisites: Swamp installed, authenticated (swamp auth login)

What to cover, in order:

  1. Check current trust list: swamp extension trust list — show real output (should show swamp as default)
  2. Add a trusted collective: swamp extension trust add @myorg — show real output
  3. Verify it's added: swamp extension trust list — show updated output
  4. Enable auto-trust for membership collectives: swamp extension trust auto-trust true — show real output
  5. Explain when to use auto-trust vs explicit trust (team repos vs CI repos)
  6. Remove a collective: swamp extension trust rm @myorg — show real output
  7. How trust affects swamp extension install — show what happens when an untrusted extension is referenced

IMPORTANT: Verify what is actually default-trusted by running swamp extension trust list in a fresh repo. Do NOT claim @si or any other collective is default-trusted without verifying.

Guide 3: "Set Up Webhooks" (how-to/set-up-webhooks.md)

Prerequisites: Swamp installed, a repo with a workflow, familiarity with swamp serve

What to cover, in order:

  1. Create a workflow that the webhook will trigger
  2. Start swamp serve with a GitHub webhook: swamp serve --webhook '/hooks/github:my-workflow:mysecret' — show real startup output
  3. Test locally with curl: curl -X POST http://localhost:9090/hooks/github -H 'X-Hub-Signature-256: ...' -d '{"ref":"refs/heads/main"}' — show how to compute the HMAC for testing
  4. Use env var for the secret: swamp serve --webhook '/hooks/github:my-workflow:@env=WEBHOOK_SECRET'
  5. Use file-based secret: swamp serve --webhook '/hooks/github:my-workflow:@file=/run/secrets/webhook'
  6. Set up a Linear webhook: show the linear scheme variant
  7. Set up a Stripe webhook: show the stripe scheme variant
  8. Set up a generic webhook: show the generic scheme with custom header
  9. Access webhook payload in workflow CEL: show webhook.headers, webhook.body, webhook.params

Verify flag syntax by running swamp help serve and checking the --webhook flag spec before writing any examples.

Guide 4: "Run Workflows on a Schedule" (how-to/run-workflows-on-a-schedule.md)

Prerequisites: Swamp installed, a repo with a workflow, swamp serve running

What to cover, in order:

  1. Add a trigger block to a workflow YAML with a cron schedule — show the YAML
  2. Validate the workflow: swamp workflow validate — show it accepts the trigger
  3. Start swamp serve (triggers only execute when the server is running)
  4. Verify the schedule is registered — show relevant server log output
  5. Disable scheduling: swamp serve --no-schedule
  6. Common cron patterns (every hour, daily at midnight, weekdays only)

Verify the trigger YAML schema by running swamp workflow schema get --json and checking the trigger fields.

Guide 5: "Set Up OpenTelemetry" (how-to/set-up-opentelemetry.md)

Prerequisites: Swamp installed

What to cover, in order:

  1. Enable console tracing for local debugging:
    OTEL_TRACES_EXPORTER=console swamp model method run my-model execute
    Show real span output.
  2. Send traces to a collector:
    OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 swamp model method run my-model execute
  3. Configure service name: OTEL_SERVICE_NAME=my-infra
  4. Add custom headers for vendors (Honeycomb, Axiom):
    OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=your-key"
  5. Verify spans are being exported — check the collector/vendor UI
  6. Disable tracing: --no-telemetry flag or SWAMP_NO_TELEMETRY=true

Verify all env var names against swamp help and the existing reference/opentelemetry page. Do NOT invent env var names.

Index Page 2: "Operational Tasks" (how-to/operational-tasks.md)

---
title: "Operational Tasks"
description: "<150-160 chars describing the group>"
type: how-to
order: 9
---

Brief intro paragraph. Link to each sub-page.

Guide 6.1: "Set Up Shell Completions" (how-to/operational-tasks/set-up-shell-completions.md)

What to cover, in order:

  1. Generate bash completions: swamp completions bash — show output and where to save it
  2. Generate zsh completions: swamp completions zsh — show output and where to save it
  3. Generate fish completions: swamp completions fish — show output and where to save it
  4. Reload the shell to activate completions

Verify by running each swamp completions <shell> command and confirming the output format.

Guide 6.2: "Use the Audit Timeline" (how-to/operational-tasks/use-the-audit-timeline.md)

What to cover, in order:

  1. View the default timeline (last 24h): swamp audit — show real output
  2. Change the time window: swamp audit --hours 4
  3. Include all commands (including noise): swamp audit --all
  4. Filter by session: swamp audit --session <id>
  5. JSON output for scripting: swamp audit --json
  6. Check the audit hook health: swamp doctor audit — show real output

Guide 6.3: "File Issues from the CLI" (how-to/operational-tasks/file-issues-from-the-cli.md)

What to cover, in order:

  1. Search existing issues: swamp issue search vault — show real output
  2. View an issue: swamp issue get <number> — show real output
  3. File a bug report: swamp issue bug --title "..." --body "..." — show real output
  4. File a feature request: swamp issue feature --title "..." --body "..." — show real output
  5. File a security report: swamp issue security --title "..." --body "..." — note visibility (author and admins only)
  6. Comment on an issue: swamp issue ripple <number> --body "..." — show real output
  7. Close an issue with a comment: swamp issue ripple <number> --body "Fixed" --close
  8. Edit an issue: swamp issue edit <number> --title "Updated title"

Requires authentication. Note that swamp auth login is needed first.

Guide 6.4: "Inspect Repo Activity" (how-to/operational-tasks/inspect-repo-activity.md)

What to cover, in order:

  1. Show recent activity: swamp summarise — show real output
  2. Change the time window: swamp summarise --since 1d
  3. Cap output on large repos: swamp summarise --limit 10
  4. JSON output for scripting: swamp summarise --json
  5. Remote repo activity: swamp summarise --server ws://... --token ...

Renumbering Existing How-to Pages

The new guides need to slot into the existing order. Current order values and proposed changes:

Page Current order New order
Core Operations (NEW index) — 1
Extensions 1 2
AI Agents 2 3
Vaults 2 4
swamp serve 3 5
Set Up Extension Trust (NEW) — 6
Set Up Webhooks (NEW) — 7
Giga-Swamp 8 8
Operational Tasks (NEW index) — 9
Set Up OpenTelemetry (NEW) — 10
Run Workflows on a Schedule (NEW) — 11
Remote Execution 8 12
Set Up TLS for swamp serve 9 13
Set Up Background Autoupdating 10 14
Authenticate with API Keys 11 15
Troubleshoot Your Swamp Repo 12 16
Gate a Workflow with Manual Approval 13 17
Cancel a Stuck Run 14 18
Reuse a Model with the Factory Pattern 14 19

Implementation Notes

Meta descriptions

Per CLAUDE.md SEO rules, frontmatter description fields must be 150-160 characters. Verify character count for every new and modified page. Previous PRs (#783, #785) both shipped with descriptions outside this range.

Terminology

Per CLAUDE.md:

  • "Swamp" capitalized in prose, swamp lowercase in command invocations
  • "operative" not "operator" for users
  • "collective" not "organization"
  • "agent" lowercase in running prose

Diataxis how-to rules

  • Goal-oriented: each guide answers "how do I do X?"
  • Assumes knowledge: the reader knows what they want, they just need the steps
  • No conceptual explanation: link to explanation pages for the "why"
  • No teaching: link to tutorials for learning journeys
  • Minimal context: a brief prerequisites section, then straight to the steps
  • Working examples: every command shown must work when copied

Acceptance Criteria

  • All 11 new how-to pages created with correct frontmatter (title, description 150-160 chars, type: how-to, order)
  • 2 new index pages created (Core Operations, Operational Tasks)
  • Every CLI command in every guide has been run in a sandbox repo and the output is real
  • Every flag name verified against swamp help <command path> — no fabricated flags
  • No claims about default values, trusted collectives, or behavior that haven't been verified against the actual CLI
  • Existing how-to pages renumbered per the table above
  • Cross-references to explanation and reference pages are valid
  • deno task check passes
  • Terminology rules followed (Swamp capitalization, operative, collective)
  • No conceptual explanation or tutorial-style teaching in how-to pages
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 4 MOREPR_MERGED+ 1 MORENOTIFICATION_SKIPPED

Shipped

7/1/2026, 10:01:43 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack727/1/2026, 9:22:23 PM
Editable. Press Enter to edit.

evrardjp commented 7/2/2026, 4:41:10 PM

FYI this is far better! Love it.

Sign in to post a ripple.