# Syntropic137 — Complete Documentation

> Agentic Engineering platform. Orchestrate AI agents with event-sourced workflows.

---

## Overview
> Syntropic137 — orchestrate AI agents with event-sourced workflows

## What is Syntropic137?

**Syntropic137** is an event-sourced platform for orchestrating AI coding agents. It provides workflow execution, real-time observability, workspace isolation, and cost tracking — everything you need to run AI agents in production with confidence.

<SystemArchitectureFlow />

## Core Concepts

| Concept | Description |
|---------|-------------|
| **Workflow** | A YAML definition of work to be done — steps, inputs, outputs, triggers |
| **Execution** | A running instance of a workflow in an isolated workspace |
| **Session** | An agent's working session within an execution (conversation, tool calls, tokens) |
| **Artifact** | Output produced by an agent (code, files, reports) stored in object storage |
| **Event** | An immutable record of state change — the single source of truth |
| **Trigger** | A GitHub event or webhook that automatically starts a workflow |

## Architecture at a Glance

Syntropic137 is built on four bounded contexts:

<DomainModelFlow />

- **Orchestration** — Workflow definitions, execution lifecycle, workspace management
- **Agent Sessions** — Agent conversation tracking, token metrics, tool timelines
- **GitHub Integration** — App installations, webhook triggers, automated workflows
- **Artifacts** — Output storage and retrieval with metadata

## Quick Links

**Get Started**
- [Getting Started](/docs/guide/getting-started) — install and run your first workflow in 5 minutes
- [Core Concepts](/docs/guide/core-concepts) — understand events, workspaces, and the mental model

**Build**
- [Workflows](/docs/guide/workflows) — create and distribute workflow packages
- [Claude Code Plugin](/docs/guide/claude-code-plugin) — manage Syntropic137 from inside Claude Code
- [GitHub Integration](/docs/guide/github-integration) — trigger workflows from GitHub events

**Operate**
- [Tunnels](/docs/guide/tunnels) — expose the platform for webhooks and remote access
- [Secrets Management](/docs/guide/secrets) — file-based secrets and 1Password integration
- [Setup CLI](/docs/guide/setup-cli) — manage the running platform
- [Self-Hosting](/docs/guide/self-hosting) — deploy and scale on your infrastructure

**Reference**
- [API Reference](/docs/api) — 45+ REST endpoints with interactive docs
- [CLI Reference](/docs/cli) — `syn` command-line interface
- [Architecture](/docs/guide/architecture) — event sourcing, CQRS, and system internals
- [LLM Docs](/llms) — machine-readable documentation for AI agents

---

## Architecture
> Event sourcing, CQRS, workspace isolation, and the internals of Syntropic137

## Event Sourcing

Syntropic137 uses **event sourcing** as its core persistence pattern. Instead of storing current state, every state change is recorded as an immutable event. The current state is derived by replaying events.

<EventSourcingFlow />

### Two Event Types

Syntropic137 distinguishes between two kinds of events, each optimized for its use case:

| | Domain Events | Observability Events |
|---|---|---|
| **Purpose** | Business logic, state transitions | Telemetry, metrics, audit logs |
| **Storage** | TimescaleDB (append-only, replay-safe) | TimescaleDB (hypertable, time-series optimized) |
| **Pipeline** | Command → Aggregate → Event → Projection | Agent stdout → Collector → EventBuffer → TimescaleDB |
| **Validation** | Aggregate invariants, can be rejected | Schema validation only, append-only |
| **Examples** | `WorkflowCreated`, `ExecutionStarted` | `ToolExecuted`, `TokensUsed` |

<TwoEventTypesFlow />

## CQRS

Commands and queries are strictly separated. Commands modify state through aggregates; queries read from pre-built projections cached in Redis.

**Commands (12):** `CreateWorkflow`, `StartExecution`, `PauseExecution`, `ResumeExecution`, `CancelExecution`, `RegisterTrigger`, `UpdateTrigger`, `DeleteTrigger`, and more.

**Events (31):** Every command produces one or more events: `WorkflowCreated`, `ExecutionStarted`, `ExecutionPaused`, `ExecutionResumed`, `ExecutionCompleted`, `TriggerRegistered`, etc.

**Projections (14):** Pre-computed read models updated by event processors, cached in Redis or PostgreSQL for sub-millisecond query response times. Includes a `repo_correlation` projection that maps repositories to workflow executions for cross-context insight queries.

<CQRSFlow />

## Domain Model

Syntropic137 is organized into five bounded contexts with nine aggregates:

<DomainModelFlow />

## Real-Time Communication

Syntropic137 uses **Server-Sent Events (SSE)** for real-time monitoring of executions — progress updates, tool events, token metrics, and state changes all stream over a single connection:

```
GET /api/executions/{execution_id}/stream
```

Control commands (pause, resume, cancel) are sent via standard REST API calls rather than a persistent connection.

### Execution State Machine

<div className="not-prose my-6 overflow-x-auto rounded-lg border border-fd-border bg-fd-card p-6">
  <div className="flex flex-col gap-3 text-sm font-mono">
    <div className="flex items-center gap-2">
      <span className="inline-block w-28 rounded-md bg-fd-muted px-3 py-1.5 text-center text-fd-muted-foreground">NOT_STARTED</span>
      <span className="text-fd-muted-foreground">→ start →</span>
      <span className="inline-block w-24 rounded-md bg-fd-primary/20 px-3 py-1.5 text-center text-fd-primary font-semibold">RUNNING</span>
      <span className="text-fd-muted-foreground">→ finish →</span>
      <span className="inline-block w-28 rounded-md bg-emerald-500/20 px-3 py-1.5 text-center text-emerald-400">COMPLETED</span>
    </div>
    <div className="flex items-center gap-2 pl-[calc(7rem+2.5rem+0.5rem)]">
      <span className="inline-block w-24 rounded-md bg-fd-primary/20 px-3 py-1.5 text-center text-fd-primary font-semibold opacity-0">RUNNING</span>
      <span className="text-fd-muted-foreground">→ error →</span>
      <span className="inline-block w-28 rounded-md bg-red-500/20 px-3 py-1.5 text-center text-red-400">FAILED</span>
    </div>
    <div className="flex items-center gap-2 pl-[calc(7rem+2.5rem+0.5rem)]">
      <span className="inline-block w-24 rounded-md bg-fd-primary/20 px-3 py-1.5 text-center text-fd-primary font-semibold opacity-0">RUNNING</span>
      <span className="text-fd-muted-foreground">→ pause →</span>
      <span className="inline-block w-28 rounded-md bg-amber-500/20 px-3 py-1.5 text-center text-amber-400">PAUSED</span>
      <span className="text-fd-muted-foreground">→ resume →</span>
      <span className="inline-block w-24 rounded-md bg-fd-primary/20 px-3 py-1.5 text-center text-fd-primary">RUNNING</span>
    </div>
    <div className="flex items-center gap-2 pl-[calc(7rem+2.5rem+0.5rem)]">
      <span className="inline-block w-24 rounded-md bg-fd-primary/20 px-3 py-1.5 text-center text-fd-primary font-semibold opacity-0">RUNNING</span>
      <span className="text-fd-muted-foreground">→ interrupt →</span>
      <span className="inline-block w-28 rounded-md bg-orange-500/20 px-3 py-1.5 text-center text-orange-400">INTERRUPTED</span>
      <span className="text-fd-muted-foreground">→ retry →</span>
      <span className="inline-block w-24 rounded-md bg-fd-primary/20 px-3 py-1.5 text-center text-fd-primary">RUNNING</span>
    </div>
    <div className="flex items-center gap-2 pl-[calc(7rem+2.5rem+0.5rem+6rem+3.5rem+0.5rem)]">
      <span className="inline-block w-28 rounded-md bg-amber-500/20 px-3 py-1.5 text-center text-amber-400 opacity-0">PAUSED</span>
      <span className="text-fd-muted-foreground">→ cancel →</span>
      <span className="inline-block w-28 rounded-md bg-zinc-500/20 px-3 py-1.5 text-center text-zinc-400">CANCELLED</span>
    </div>
  </div>
</div>

**Yield Points** — The agent can only be paused at safe points: before each workflow phase, after each tool execution, and after each LLM call.

## Performance

Both event pipelines are optimized for their access patterns. Domain events use append-only writes with aggregate-level consistency. Observability events use TimescaleDB hypertables with automatic partitioning for high-throughput ingestion. Read models are cached in Redis for fast dashboard and API queries.

---

## Claude Code Integration
> Monitor and manage Syntropic137 from inside Claude Code with slash commands and domain skills.

The [Syntropic137 Claude Code plugin](https://github.com/syntropic137/syntropic137-claude-plugin)
adds slash commands and domain knowledge to Claude Code, turning it into a Syntropic137
orchestrator — create workflows, kick off executions, monitor costs, and troubleshoot
issues without leaving your editor.

<Callout type="info">
This is a **Claude Code plugin** — it teaches Claude Code how to operate Syntropic137.
It is not a [Syntropic137 plugin](/docs/guide/plugins) (workflow package). See
[Plugin Ecosystem](/docs/guide/plugins#two-plugin-boundaries) for how these two concepts
differ.
</Callout>

## Installation

The recommended way to install the plugin is through the setup system, which handles
everything automatically:

```bash
npx @syntropic137/setup
```

The setup wizard detects the `claude` CLI and offers to install the plugin for you. You
can also install the plugin step specifically:

```bash
npx @syntropic137/setup plugin
```

### Manual Installation

If you prefer to install directly from the Claude Code marketplace:

```bash
claude plugin marketplace add syntropic137/syntropic137-claude-plugin
claude plugin install syntropic137
```

Or from a local clone (for development):

```bash
claude plugin install ./lib/syntropic137-claude-plugin --scope project
```

## Slash Commands

The plugin provides 7 commands for quick platform interaction:

| Command | Purpose | Example |
|---------|---------|---------|
| `/syn-setup` | Open the setup wizard | `/syn-setup` |
| `/syn-status` | Platform health — containers, API, recent activity | `/syn-status` |
| `/syn-health` | Deep API diagnostics | `/syn-health` |
| `/syn-costs` | Cost tracking and breakdown | `/syn-costs summary` |
| `/syn-sessions` | Session listing and details | `/syn-sessions list` |
| `/syn-metrics` | Aggregated metrics across executions | `/syn-metrics --workflow <id>` |
| `/syn-observe` | Debug a specific agent session | `/syn-observe <session-id> tools` |

Commands resolve the API URL automatically — from `SYN_API_URL` env var, your `~/.syntropic137/.env` config, or the default `http://localhost:8137`.

## Domain Skills

The plugin includes 7 domain skills that Claude loads contextually based on your questions:

| Skill | Activates When You Ask About |
|-------|------------------------------|
| **workflow-management** | Creating workflows, YAML schema, prompt files, `$ARGUMENTS` substitution |
| **execution-control** | Running workflows, monitoring progress, pause/resume/cancel, debugging failures |
| **observability** | Sessions, tool timelines, token metrics, cost breakdowns, two-lane architecture |
| **organization** | Org/System/Repo hierarchy, cost rollup, contribution tracking |
| **github-automation** | GitHub App setup, webhook triggers, safety limits, input mapping |
| **setup** | `npx @syntropic137/setup`, Docker stack, secrets, troubleshooting |
| **platform-ops** | Service map, workspace lifecycle, token injection, QA commands |

Skills are not invoked directly — Claude uses them automatically when your question matches their domain. For example, asking "create a workflow that reviews PRs" activates both **workflow-management** and **github-automation** skills.

## Session Start Hook

The plugin runs a health check every time Claude Code starts a new session. It pings your Syntropic137 API and silently confirms it's reachable. If the platform is down, you'll see a notification suggesting `/syn-setup` or `/syn-status`.

## Updating

```bash
claude plugin update syntropic137
```

## Source

The plugin source is in the [`syntropic137-claude-plugin`](https://github.com/syntropic137/syntropic137-claude-plugin)
repository, also available as a submodule at `lib/syntropic137-claude-plugin` in the
monorepo.

---

## Configuration
> Environment variables, settings, and GitHub App setup for Syntropic137.

Syntropic137 uses environment variables for configuration. Copy `.env.example` to `.env`
and customize as needed.

## Core Settings

| Variable | Default | Description |
|----------|---------|-------------|
| `APP_ENVIRONMENT` | `development` | Runtime environment (`development`, `staging`, `production`) |
| `DATABASE_URL` | — | PostgreSQL connection string |
| `REDIS_URL` | — | Redis connection string |
| `API_HOST` | `0.0.0.0` | API server bind address |
| `API_PORT` | `8000` | API server port |

## GitHub App

Syntropic137 integrates with GitHub through a GitHub App for receiving webhook events
and managing repositories.

### Setup

Run the GitHub App setup via the CLI:

```bash
npx @syntropic137/setup github-app
```

See [GitHub Integration](/docs/guide/github-integration) for the full setup guide including trigger rules and webhook configuration. For secret storage details, see [Secrets Management](/docs/guide/secrets).

### Environment Variables

| Variable | Description |
|----------|-------------|
| `GITHUB_APP_ID` | GitHub App ID |
| `GITHUB_APP_PRIVATE_KEY` | PEM-encoded private key |
| `GITHUB_WEBHOOK_SECRET` | Webhook verification secret |

## Agent Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `AGENT_WORKSPACE_DIR` | `/tmp/syn-workspaces` | Base directory for agent workspaces |
| `AGENT_TIMEOUT` | `3600` | Maximum agent execution time (seconds) |
| `AGENT_MAX_CONCURRENT` | `4` | Maximum concurrent agent sessions |

## Event Polling

Syntropic137 polls the GitHub Events API as a zero-config fallback when webhooks
are unavailable. Polling is **enabled by default** — no tunnel setup required.
See [Event Ingestion](/docs/guide/event-ingestion) for how the hybrid approach works.

| Variable | Default | Description |
|----------|---------|-------------|
| `SYN_POLLING_DISABLED` | `false` | Disable Events API polling entirely |
| `SYN_POLLING_POLL_INTERVAL_SECONDS` | `60.0` | Active polling interval (seconds) |
| `SYN_POLLING_SAFETY_NET_INTERVAL_SECONDS` | `300.0` | Safety net polling interval (seconds) |
| `SYN_POLLING_WEBHOOK_STALE_THRESHOLD_SECONDS` | `1800.0` | Seconds before switching to active polling |
| `SYN_POLLING_DEDUP_TTL_SECONDS` | `86400` | Redis dedup key TTL (seconds) |

See `.env.example` in the repository for the complete list of configuration
options.

---

## Core Concepts
> The mental model behind Syntropic137 — events, workspaces, workflows, and observability.

<Callout type="info">
You don't need to understand event sourcing to use Syntropic137. This page gives you the mental model — the "why" behind what you see in the dashboard and CLI.
</Callout>

## Two Kinds of Events

Syntropic137 separates all data into two lanes, each optimized for its purpose:

| | Domain Events | Observability Events |
|---|---|---|
| **Purpose** | Source of truth for business logic and state transitions | High-throughput telemetry for dashboards and debugging |
| **Storage** | TimescaleDB (append-only, replay-safe) | TimescaleDB (hypertable, time-series optimized) |
| **Pipeline** | Command → Aggregate → Event → Projection | Agent stdout → Collector → EventBuffer → TimescaleDB |
| **Examples** | `WorkflowCreated`, `ExecutionCompleted`, `TriggerFired` | `ToolExecuted`, `TokensUsed`, `StreamChunk` |

**Domain events** are the source of truth for what happened. The current state of any workflow or execution is derived by replaying its events — there's no mutable database row to corrupt.

**Observability events** are append-only telemetry. They power the dashboard metrics, cost tracking, and session timelines. They never affect business logic.

## Workspaces

Every agent execution runs inside an **isolated Docker container** — a workspace. Workspaces use a two-phase security model:

1. **Setup Phase** — Secrets (API keys, Git credentials) are briefly available to configure credential helpers. Raw tokens are cleared before the agent starts.
2. **Agent Phase** — The agent runs with only `ANTHROPIC_API_KEY` in its environment. Git operations use cached credentials from the setup phase. Network egress goes through an Envoy sidecar proxy.

This means the agent never sees raw GitHub tokens or other secrets. Even if an agent is compromised, credentials are already gone.

## Workflows

A **workflow** is a YAML definition of work to be done. It consists of one or more **phases**, where each phase is a task for an AI agent:

```yaml
id: research-v1
name: Research Workflow
phases:
  - id: discovery
    prompt_file: phases/discovery.md
    model: sonnet
  - id: synthesis
    prompt_file: phases/synthesis.md
    model: opus
```

Phases execute sequentially. Each phase can reference the output of previous phases using `{{phase-id}}` substitution. The `$ARGUMENTS` variable passes user input into the prompt.

Workflows can be packaged and distributed — see [Workflow Packages](/docs/guide/workflows).

## Executions

An **execution** is a running instance of a workflow. It progresses through a state machine:

<div className="not-prose my-6 overflow-x-auto rounded-lg border border-fd-border bg-fd-card p-6">
  <div className="flex flex-col gap-3 text-sm font-mono">
    <div className="flex items-center gap-2">
      <span className="inline-block w-28 rounded-md bg-fd-muted px-3 py-1.5 text-center text-fd-muted-foreground">NOT_STARTED</span>
      <span className="text-fd-muted-foreground">→ start →</span>
      <span className="inline-block w-24 rounded-md bg-fd-primary/20 px-3 py-1.5 text-center text-fd-primary font-semibold">RUNNING</span>
      <span className="text-fd-muted-foreground">→ finish →</span>
      <span className="inline-block w-28 rounded-md bg-emerald-500/20 px-3 py-1.5 text-center text-emerald-400">COMPLETED</span>
    </div>
    <div className="flex items-center gap-2 pl-[calc(7rem+2.5rem+0.5rem)]">
      <span className="inline-block w-24 rounded-md bg-fd-primary/20 px-3 py-1.5 text-center text-fd-primary font-semibold opacity-0">RUNNING</span>
      <span className="text-fd-muted-foreground">→ error →</span>
      <span className="inline-block w-28 rounded-md bg-red-500/20 px-3 py-1.5 text-center text-red-400">FAILED</span>
    </div>
    <div className="flex items-center gap-2 pl-[calc(7rem+2.5rem+0.5rem)]">
      <span className="inline-block w-24 rounded-md bg-fd-primary/20 px-3 py-1.5 text-center text-fd-primary font-semibold opacity-0">RUNNING</span>
      <span className="text-fd-muted-foreground">→ pause →</span>
      <span className="inline-block w-28 rounded-md bg-amber-500/20 px-3 py-1.5 text-center text-amber-400">PAUSED</span>
      <span className="text-fd-muted-foreground">→ resume →</span>
      <span className="inline-block w-24 rounded-md bg-fd-primary/20 px-3 py-1.5 text-center text-fd-primary">RUNNING</span>
    </div>
    <div className="flex items-center gap-2 pl-[calc(7rem+2.5rem+0.5rem)]">
      <span className="inline-block w-24 rounded-md bg-fd-primary/20 px-3 py-1.5 text-center text-fd-primary font-semibold opacity-0">RUNNING</span>
      <span className="text-fd-muted-foreground">→ interrupt →</span>
      <span className="inline-block w-28 rounded-md bg-orange-500/20 px-3 py-1.5 text-center text-orange-400">INTERRUPTED</span>
      <span className="text-fd-muted-foreground">→ retry →</span>
      <span className="inline-block w-24 rounded-md bg-fd-primary/20 px-3 py-1.5 text-center text-fd-primary">RUNNING</span>
    </div>
    <div className="flex items-center gap-2 pl-[calc(7rem+2.5rem+0.5rem+6rem+3.5rem+0.5rem)]">
      <span className="inline-block w-28 rounded-md bg-amber-500/20 px-3 py-1.5 text-center text-amber-400 opacity-0">PAUSED</span>
      <span className="text-fd-muted-foreground">→ cancel →</span>
      <span className="inline-block w-28 rounded-md bg-zinc-500/20 px-3 py-1.5 text-center text-zinc-400">CANCELLED</span>
    </div>
  </div>
</div>

You can **pause**, **resume**, and **cancel** executions in real time via the REST API or the CLI. The agent can only be paused at safe yield points — between phases, after tool calls, or after LLM responses.

## Sessions

A **session** is an agent's working period within an execution. It captures:

- **Conversation** — the full message history
- **Tool timeline** — every tool call with input, output, and duration
- **Token metrics** — input/output tokens per model
- **Cost** — calculated from token usage and model pricing

Sessions are the primary unit of observability. When you debug a failed execution or analyze costs, you're looking at session data.

## Artifacts

**Artifacts** are outputs produced by agents — code files, reports, design documents, test results. They're stored in MinIO (S3-compatible object storage) and linked to their source execution.

## Triggers

A **trigger** connects a GitHub event to a workflow. When a matching event arrives (PR opened, push to main, issue labeled), the trigger automatically starts a workflow execution.

Triggers have built-in safety limits:

| Guard | Purpose |
|-------|---------|
| `daily_limit` | Maximum executions per day |
| `cooldown` | Minimum seconds between executions |
| `budget` | Maximum spend before pausing |

See [GitHub Integration](/docs/guide/github-integration) for setup details.

---

## Event Ingestion
> How Syntropic137 receives GitHub events through webhooks and polling.

Syntropic137 uses a **hybrid approach** to receive GitHub events: webhooks for
real-time delivery, and Events API polling as a zero-config fallback. Both
sources feed into a unified pipeline with content-based deduplication — the same
event is never processed twice, regardless of how it arrives.

## How It Works

<div className="not-prose my-6 overflow-x-auto rounded-lg border border-fd-border bg-fd-card p-6">
  <div className="flex flex-col items-center gap-4 text-sm font-mono">
    <div className="flex items-center gap-4">
      <div className="flex flex-col gap-2">
        <span className="rounded-md bg-fd-primary/20 px-4 py-2 text-center text-fd-primary font-medium">GitHub Webhook</span>
        <span className="rounded-md bg-fd-primary/10 px-4 py-2 text-center text-fd-primary/70">Events API Poller</span>
      </div>
      <span className="text-fd-muted-foreground text-lg">→</span>
      <span className="rounded-md bg-fd-secondary px-4 py-2 text-center text-fd-secondary-foreground">NormalizedEvent</span>
      <span className="text-fd-muted-foreground text-lg">→</span>
      <span className="rounded-md bg-amber-500/20 px-4 py-2 text-center text-amber-400">Dedup (Redis)</span>
      <span className="text-fd-muted-foreground text-lg">→</span>
      <span className="rounded-md bg-emerald-500/20 px-4 py-2 text-center text-emerald-400 font-medium">Trigger Evaluation</span>
    </div>
  </div>
</div>

1. **Webhook endpoint** receives GitHub webhook deliveries in real time
2. **Events API poller** runs as a background task, polling GitHub's Events API
   for repositories that have active triggers
3. Both sources normalize their payloads into a common `NormalizedEvent` format
4. The **EventPipeline** checks each event against a dedup store (Redis) using
   content-based keys — if the event was already processed, it's skipped
5. New events are routed to trigger evaluation, which fires matching workflows

## Polling Modes

The poller adapts its behavior based on whether webhooks are arriving:

| Mode | Interval | When it activates |
|------|----------|-------------------|
| **Active Polling** | 60 seconds | No webhook received in 30 minutes (or never) |
| **Safety Net** | 300 seconds | Webhooks arriving normally |

When you first start Syntropic137 without a webhook URL configured, the poller
operates in **Active Polling** mode — checking for new events every 60 seconds.
Once webhooks start arriving (after configuring a tunnel or public URL), the
poller automatically backs off to **Safety Net** mode, polling every 5 minutes
as a catch-up mechanism.

If webhooks stop arriving (tunnel goes down, GitHub outage), the poller detects
the gap after 30 minutes and switches back to active polling.

## Deduplication

When both webhooks and polling are active, the same event may arrive from both
sources. Syntropic137 prevents double-processing using **content-based dedup keys**.

Each event type has a dedicated key extractor that uses stable identifiers present
in both webhook and Events API payloads:

- **Push events:** repository + commit SHA (`after` field)
- **Pull requests:** repository + PR number + action + `updated_at` timestamp
- **Check runs:** repository + check run ID + action
- **Issue comments:** repository + comment ID + action

Keys are stored in Redis with a 24-hour TTL using atomic `SETNX` — the first
source to deliver an event "wins," and the duplicate from the other source is
silently skipped.

### Fail-open behavior

If Redis is temporarily unavailable, events are **processed anyway** rather than
dropped. Trigger safety guards (fire counts, cooldown periods) provide
second-layer protection against duplicate workflows.

## GitHub API Quota

The Events API has a rate limit of 60 conditional requests per hour per
installation. Syntropic137 minimizes quota usage through several mechanisms:

- **ETag caching:** Uses `If-None-Match` headers for conditional requests.
  304 Not Modified responses still count against the limit but return no data.
- **Selective polling:** Only repositories with active triggers are polled.
  Repos without triggers consume zero API calls.
- **Adaptive intervals:** In Safety Net mode (webhooks healthy), polling drops
  to every 5 minutes — roughly 12 requests per hour per repo.
- **X-Poll-Interval:** The poller respects GitHub's recommended minimum interval
  from the `X-Poll-Interval` response header.

### Quota estimates

| Mode | Polls/hour/repo | With 5 repos |
|------|-----------------|--------------|
| Active Polling (60s) | ~60 | ~300 |
| Safety Net (300s) | ~12 | ~60 |

## Configuration

All polling settings use the `SYN_POLLING_` environment variable prefix:

| Variable | Default | Description |
|----------|---------|-------------|
| `SYN_POLLING_DISABLED` | `false` | Disable polling entirely |
| `SYN_POLLING_POLL_INTERVAL_SECONDS` | `60.0` | Active polling interval (min: 10s) |
| `SYN_POLLING_SAFETY_NET_INTERVAL_SECONDS` | `300.0` | Safety net interval (min: 60s) |
| `SYN_POLLING_WEBHOOK_STALE_THRESHOLD_SECONDS` | `1800.0` | Seconds without webhook before active polling (min: 60s) |
| `SYN_POLLING_DEDUP_TTL_SECONDS` | `86400` | Redis dedup key TTL (min: 3600s) |

## Disabling Polling

If you have reliable webhook delivery and want zero Events API quota usage:

```bash
SYN_POLLING_DISABLED=true
```

This is recommended for production deployments with a stable public webhook URL
or Cloudflare Tunnel. The webhook endpoint continues to work normally regardless
of this setting.

---

## Getting Started
> Install Syntropic137 and run your first AI agent workflow in under 5 minutes.

Syntropic137 orchestrates **Claude Code sessions inside isolated Docker workspaces** — giving you scalable, observable, trigger-driven AI agent execution. Each workflow phase runs in its own container with injected credentials, captured output, and full token/cost tracking. Claude Code is currently the only supported agent provider; [OpenCode](https://github.com/opencode-ai/opencode) support is planned next.

<Callout type="info">
Get up and running in a single command — no config files, no YAML, no manual setup.
</Callout>

```bash title="Terminal"
npx @syntropic137/setup
```

This opens an **interactive terminal** with arrow-key navigation, styled prompts, and progress tracking. Choose from available commands or jump straight to a full install with `init`.

## Available Commands

```bash title="Setup CLI"
npx @syntropic137/setup init        # Full interactive install wizard
npx @syntropic137/setup status      # Show running services
npx @syntropic137/setup start       # Start the stack
npx @syntropic137/setup stop        # Stop the stack
npx @syntropic137/setup logs        # Tail service logs
npx @syntropic137/setup update      # Pull latest images and restart
npx @syntropic137/setup github-app  # Configure GitHub App integration
npx @syntropic137/setup plugin      # Install Claude Code plugin
```

## Prerequisites

You need three things installed on your machine:

- **Node.js 18+** — for running the setup CLI
- **Docker** — for isolated agent workspaces
- **Docker Compose v2.20+** — for orchestrating the service stack

<Callout type="warn">
Syntropic137 requires Docker Compose v2 (the `docker compose` plugin), not the legacy v1 (`docker-compose`). Check with `docker compose version`.
</Callout>

## Install

```bash title="Terminal"
npx @syntropic137/setup init
```

The `init` wizard walks you through the full setup step-by-step:

1. **Docker check** — verifies Docker and Compose are available
2. **Directory setup** — creates `~/.syntropic137/` with config, secrets, and workspace directories
3. **Secret generation** — creates cryptographically random passwords for Postgres, Redis, and MinIO (stored as `chmod 600` files)
4. **API key** — prompts for your `ANTHROPIC_API_KEY`
5. **GitHub App** — opens your browser to create a GitHub App via manifest flow for webhook-triggered workflows
6. **Claude Code plugin** *(optional)* — installs the Syntropic137 plugin for Claude Code if the `claude` CLI is detected
7. **Pull & start** — downloads container images and starts the full stack

<Callout type="info">
The Claude Code plugin step is optional — skip it during setup and add later with `npx @syntropic137/setup plugin`. The GitHub App is required for webhook-triggered workflows.
</Callout>

Once complete, the dashboard is live at **http://localhost:8137**.

## Run Your First Workflow

Install the example research workflow package and run it:

```bash title="Terminal"
# Install the starter research workflow from GitHub
syn workflow install syntropic137/syntropic137 --ref main --path workflows/examples/research-package

# Run it with a task
syn workflow run research-package-v1 \
  --task "Investigate event sourcing patterns for building reliable agent systems"
```

The workflow executes in an isolated Docker workspace. Watch it in real time on the dashboard or via SSE:

```bash title="Terminal"
# Stream execution events
curl -N http://localhost:8137/api/executions/{execution-id}/stream
```

## What's Running

After setup, your `~/.syntropic137/` directory contains a Docker Compose stack with these services:

| Service | Port | Purpose |
|---------|------|---------|
| `gateway` | 8137 | nginx reverse proxy + dashboard UI |
| `api` | 8000 | FastAPI — REST API, SSE |
| `event-store` | 50051 | gRPC event sourcing server |
| `collector` | 8080 | Agent event ingestion |
| `timescaledb` | 5432 | PostgreSQL + TimescaleDB |
| `redis` | 6379 | Caching and pub/sub |
| `minio` | 9000 | S3-compatible artifact storage |

## Next Steps

- [Core Concepts](/docs/guide/core-concepts) — understand the mental model: events, workspaces, workflows
- [Workflows](/docs/guide/workflows) — create and distribute workflow packages
- [Claude Code Plugin](/docs/guide/claude-code-plugin) — manage Syntropic137 from inside Claude Code
- [GitHub Integration](/docs/guide/github-integration) — trigger workflows from GitHub events
- [Setup CLI Reference](/docs/guide/setup-cli) — all `npx @syntropic137/setup` commands

---

## GitHub Integration
> Connect GitHub repositories to trigger automated agent workflows from events.

Syntropic137 integrates with GitHub through a GitHub App. This enables webhook-driven workflow automation — PRs opened, pushes to branches, issues labeled, and more can automatically trigger agent workflows.

## Setting Up the GitHub App

The setup wizard handles GitHub App creation:

```bash
npx @syntropic137/setup github-app
```

This opens your browser to GitHub's App manifest flow:

1. You confirm the app creation on GitHub
2. GitHub redirects back with credentials
3. The CLI saves the App ID, private key (PEM), and webhook secret to `~/.syntropic137/secrets/`
4. You choose which repositories the app can access

The entire flow takes about 30 seconds.

<Callout type="info">
If you already ran `npx @syntropic137/setup init`, the GitHub App step was offered during initial setup. You can re-run it anytime with `npx @syntropic137/setup github-app`.
</Callout>

## Trigger Rules

A **trigger rule** connects a GitHub event to a workflow. When a matching event arrives, Syntropic137 starts a workflow execution automatically.

```bash
# Create a trigger via CLI
syn trigger create \
  --repo owner/my-repo \
  --event pull_request.opened \
  --workflow pr-review-v1 \
  --daily-limit 20 \
  --cooldown 60
```

### Safety Limits

Every trigger has built-in guards to prevent runaway execution:

| Guard | Default | Purpose |
|-------|---------|---------|
| `daily_limit` | 50 | Maximum executions per day per trigger |
| `cooldown` | 30s | Minimum seconds between executions |
| `budget` | — | Maximum spend before pausing (optional) |

These are enforced server-side and cannot be bypassed by webhook payloads.

### Supported Events

Triggers can fire on any GitHub webhook event type:

- `push` — commits pushed to a branch
- `pull_request.opened`, `pull_request.synchronize` — PR activity
- `issues.labeled` — issue triage
- `check_run.completed` — CI results
- `workflow_run.completed` — GitHub Actions completion
- And any other [GitHub webhook event](https://docs.github.com/en/webhooks/webhook-events-and-payloads)

## Event Delivery: Webhooks + Polling

Syntropic137 uses a hybrid approach for receiving GitHub events:

**Webhooks** are the primary path — real-time delivery from GitHub when your App has a reachable URL (via [tunnel](/docs/guide/tunnels) or public server).

**Events API polling** is the fallback — a background task polls GitHub's Events API on an adaptive interval. This enables zero-config onboarding without a tunnel.

<Callout type="warn">
GitHub's Events API does **not** include GitHub Actions webhook events (`workflow_run`, `check_run`, etc.). If you need to trigger workflows from Actions events, you must set up a [tunnel](/docs/guide/tunnels) for webhook delivery.
</Callout>

The system automatically deduplicates events using content-based keys (commit SHA, PR number, check run ID), so the same logical event is processed exactly once regardless of whether it arrived via webhook, polling, or both.

For a deep dive into the event pipeline, deduplication strategy, and polling configuration, see [Event Ingestion](/docs/guide/event-ingestion).

## Repository Installation

After creating the GitHub App, install it on your repositories:

1. Go to your GitHub App settings → **Install App**
2. Select the organization or personal account
3. Choose **All repositories** or select specific ones
4. Syntropic137 dynamically resolves installation IDs per repository — no reconfiguration needed when you add new repos

---

## Documentation
> Guides, architecture, and deployment documentation for Syntropic137

Welcome to the Syntropic137 documentation. Use the sidebar to navigate between guides.

- [Getting Started](/docs/guide/getting-started) — Install and run your first workflow
- [Workflow Packages](/docs/guide/workflows) — Install, create, and distribute workflows via the marketplace
- [Architecture](/docs/guide/architecture) — Event sourcing, CQRS, and system internals
- [Configuration](/docs/guide/configuration) — Settings and GitHub App setup
- [Self-Hosting](/docs/guide/self-hosting) — Deploy on your own infrastructure

---

## Plugin Ecosystem
> Discover, install, and share agent workflows for the Syntropic137 platform.

import { Files, Folder, File } from 'fumadocs-ui/components/files';

Syntropic137 plugins are distributable bundles of workflows for the Syntropic137 platform.
Install pre-built plugins from GitHub-hosted marketplaces, or create your own and share
them with the community.

```bash
# Register a marketplace
syn marketplace add syntropic137/workflow-library

# Search for plugins
syn workflow search "research"

# Install by name
syn workflow install research-toolkit

# Run it
syn workflow run deep-research --task "Analyze our authentication architecture"
```

## Two Plugin Boundaries

Syntropic137 has two distinct plugin concepts. The diagram below shows how they relate:

<PluginEcosystemFlow />

### Syntropic137 Plugins

Bundles of **workflows** (and eventually triggers) that are ingested into the Syntropic137
platform. These are what you install from marketplaces, export from running workflows,
and share with your team. They define *what work gets done* — the multi-phase execution
plans that agents follow inside isolated Docker workspaces.

- Distributed via GitHub-based marketplaces
- Manifest: `syntropic137-plugin.json`
- Content: `workflow.yaml` + phase `.md` files
- Install: `syn workflow install <name>`

### Claude Code Plugin

A separate project ([`syntropic137-claude-plugin`](https://github.com/syntropic137/syntropic137-claude-plugin))
that gives Claude Code the context to **operate** Syntropic137. It provides slash commands
(`/syn-status`, `/syn-workflow`, etc.) and domain skills that teach Claude Code how to
create workflows, kick off executions, query metrics, and manage the platform.

The Claude Code plugin is *not* a Syntropic137 plugin — it's a Claude Code plugin *for*
using Syntropic137. See [Claude Code Integration](/docs/guide/claude-code-plugin) for details.

## Phase Prompt Format

Phase prompts use `.md` files with optional YAML frontmatter — a convention inspired by
Claude Code's custom command format. If you've written Claude Code commands, the format
is familiar:

```markdown
---
model: sonnet
argument-hint: "[topic]"
allowed-tools: Read,Glob,Grep,Bash
max-tokens: 4096
timeout-seconds: 300
---

You are a research assistant investigating: $ARGUMENTS

Use {{discovery}} to reference output from a previous phase.
```

| Frontmatter Key | Description |
|-----------------|-------------|
| `model` | Claude model (`sonnet`, `opus`, `haiku`) |
| `argument-hint` | Shown to users when prompted for input |
| `allowed-tools` | Comma-separated list of permitted tools |
| `max-tokens` | Maximum output tokens for the phase |
| `timeout-seconds` | Phase execution timeout |

## Exporting Plugins

Any workflow running in Syntropic137 can be exported as a distributable plugin:

```bash
# Export as a package (workflow.yaml + phase .md files)
syn workflow export <workflow-id> --output ./my-plugin/

# Export as a plugin with a Claude Code command wrapper
syn workflow export <workflow-id> --format plugin --output ./my-plugin/
```

The `plugin` format adds a `commands/syn-*.md` wrapper that calls `syn workflow run`,
so the exported workflow can also be invoked as a slash command in Claude Code. The
package itself remains a Syntropic137 plugin — the CC command is a convenience bridge.

<Files>
  <Folder name="my-plugin" defaultOpen>
    <File name="syntropic137-plugin.json" />
    <Folder name="commands" defaultOpen>
      <File name="syn-deep-research.md" />
    </Folder>
    <Folder name="workflows" defaultOpen>
      <Folder name="deep-research" defaultOpen>
        <File name="workflow.yaml" />
        <Folder name="phases">
          <File name="discovery.md" />
          <File name="synthesis.md" />
        </Folder>
      </Folder>
    </Folder>
    <File name="README.md" />
  </Folder>
</Files>

## Marketplace

The marketplace is a decentralized network of GitHub repositories that serve as plugin
registries. Any GitHub repo with a `marketplace.json` at the root can be a marketplace.

### How It Works

1. **Register** a marketplace: `syn marketplace add org/repo`
2. **Search** across all registries: `syn workflow search "code review"`
3. **Install** by name: `syn workflow install pr-review` — the CLI resolves the name
   from registered marketplaces, clones the repo, and installs the workflows
4. **Update** when new versions are available: `syn workflow update pr-review`
5. **Uninstall** when you're done: `syn workflow uninstall pr-review`

### Registry Management

```bash
syn marketplace add syntropic137/workflow-library     # Register
syn marketplace add myorg/internal --name my-company  # Custom name
syn marketplace list                                  # List registries
syn marketplace refresh                               # Force cache refresh
syn marketplace remove my-company                     # Remove
```

Marketplace indexes are cached locally for 4 hours. The CLI refreshes automatically
when the cache expires, or you can force it with `syn marketplace refresh`.

### Discovery

```bash
# Search by keyword (matches name, description, category, tags)
syn workflow search "research"

# Filter by category or tag
syn workflow search --category research
syn workflow search --tag multi-phase

# Get full details on a specific plugin
syn workflow info research-toolkit
```

### Install, Update, Uninstall

```bash
# Install from marketplace by name
syn workflow install research-toolkit

# Check for updates
syn workflow update research-toolkit --dry-run

# Update to latest
syn workflow update research-toolkit

# Uninstall (removes workflows from platform)
syn workflow uninstall research-toolkit

# Uninstall but keep workflows running
syn workflow uninstall research-toolkit --keep-workflows
```

Updates compare the remote git commit SHA against the installed SHA — if they match,
the package is already up to date.

## Trigger Support

<Callout type="info">
Trigger bundling in plugins is not yet implemented. Plugins currently contain workflows
only. Track progress: [#430](https://github.com/syntropic137/syntropic137/issues/430)
</Callout>

The vision is that plugins will include trigger configurations alongside workflows — for
example, a "PR Review" plugin that bundles a code review workflow *and* a trigger that
fires it when a pull request is opened. Since triggers need to be attached to specific
repos (which vary across setups), the CLI would prompt during install to select target
repos.

Triggers exist today as a [separate system](/docs/cli/triggers) (`syn triggers register/list/pause/resume/delete`)
but aren't yet part of the plugin package format.

## Creating Plugins

Plugins follow a standard package format. See [Workflow Packages](/docs/guide/workflows)
for the full guide on:

- [Package formats](/docs/guide/workflows#package-formats) — single workflow vs. multi-workflow plugin
- [Scaffolding](/docs/guide/workflows#scaffold-from-template) — `syn workflow init` to bootstrap a new plugin
- [Plugin manifests](/docs/guide/workflows#plugin-manifest) — `syntropic137-plugin.json` metadata
- [Creating a marketplace](/docs/guide/workflows#creating-a-marketplace-repository) — host your own registry
- [Private marketplaces](/docs/guide/workflows#private-marketplaces) — use private GitHub repos

## Learn More

- [Workflow Packages](/docs/guide/workflows) — detailed package creation, distribution, and marketplace setup
- [CLI Reference](/docs/cli) — all `syn workflow` and `syn marketplace` commands
- [Claude Code Integration](/docs/guide/claude-code-plugin) — the Claude Code plugin for operating Syntropic137 (slash commands and domain skills)

---

## Secrets Management
> How Syntropic137 handles secrets — file-based storage, Docker secrets, and 1Password integration.

Syntropic137 stores infrastructure secrets (database, Redis, and MinIO credentials) as file-based secrets with strict permissions, mounted into containers via Docker Compose's secrets mechanism. Application-level API keys (such as `ANTHROPIC_API_KEY`) are supplied via environment variables or `.env` files and injected only into the processes that need them.

## How Secrets Work

### Generation

During `npx @syntropic137/setup init`, three cryptographically random passwords are generated:

| Secret | File | Purpose |
|--------|------|---------|
| Database password | `~/.syntropic137/secrets/db-password.secret` | PostgreSQL (TimescaleDB) |
| Redis password | `~/.syntropic137/secrets/redis-password.secret` | Redis cache and pub/sub |
| MinIO password | `~/.syntropic137/secrets/minio-password.secret` | S3-compatible artifact storage |

All secret files are created with `chmod 600` — readable only by the file owner.

### Docker Secrets

The Docker Compose stack mounts secrets under `/run/secrets/` in each container via Compose's secrets mechanism. The entrypoint script reads these files at startup and constructs connection URLs:

```
/run/secrets/db-password.secret → POSTGRES_PASSWORD → connection URL
/run/secrets/redis-password.secret → REDIS_URL with password
/run/secrets/minio-password.secret → MINIO_SECRET_KEY
```

This means infrastructure secrets are:
- Never visible in `docker inspect` output
- Never stored in container image layers
- Isolated from the application environment

### GitHub App Secrets

If you created a GitHub App during setup, additional secrets are stored:

- `~/.syntropic137/secrets/github-app-private-key.pem` — App private key
- `~/.syntropic137/secrets/github-webhook-secret.txt` — Webhook verification secret
- `~/.syntropic137/secrets/github-client-secret.txt` — OAuth client secret

All `chmod 600`.

## 1Password Integration

Syntropic137 supports 1Password Service Accounts for resolving secrets at runtime.

<Callout type="warn">
1Password Service Accounts require a **1Password Business or Enterprise** plan. They are not available on personal or family plans.
</Callout>

### Setup

1. Create a Service Account in your 1Password account
2. Add the token to your `.env`:

```bash
OP_SERVICE_ACCOUNT_TOKEN=your-service-account-token
```

3. The API service reads `op://` references and resolves them at startup

### Using `op://` References

In your `.env` or configuration, use 1Password references instead of raw values:

```bash
ANTHROPIC_API_KEY=op://Engineering/Anthropic/api-key
GITHUB_APP_PRIVATE_KEY=op://Engineering/SyntropicGitHub/private-key
```

<Callout type="idea">
**Coming soon:** 1Password CLI (`op`) integration for personal and family plans — resolve secrets locally without a Service Account. See [syntropic137/syntropic137#421](https://github.com/syntropic137/syntropic137/issues/421) for progress.
</Callout>

## Anthropic API Key

The `ANTHROPIC_API_KEY` is the one secret that agents need at runtime. It's handled separately from infrastructure secrets:

- Stored in `.env` (or resolved via 1Password)
- Injected into agent workspaces during execution
- The only secret visible to the agent process
- All other credentials (Git tokens, etc.) are configured during the workspace setup phase and cleared before the agent starts

See [Core Concepts — Workspaces](/docs/guide/core-concepts#workspaces) for details on the two-phase security model.

---

## Self-Hosting
> Deploy Syntropic137 on your own infrastructure — from bare metal to Kubernetes

## Deployment Architecture

Syntropic137 runs as a set of Docker services connected through a shared network:

<DeploymentArchitectureFlow />

## Quick Start with Docker Compose

```bash
npx @syntropic137/setup init
```

The setup wizard handles everything — Docker validation, secret generation, API key configuration, image pulls, and starting the stack. See [Getting Started](/docs/guide/getting-started) for the full walkthrough.

The dashboard will be available at `http://localhost:8137`.

## Services

| Service | Port | Description |
|---------|------|-------------|
| `api` | 8000 | FastAPI backend — REST API, SSE |
| `gateway` | 80 | nginx reverse proxy + React dashboard frontend |
| `event-store` | 50051 | gRPC event sourcing server |
| `event-collector` | 8080 | High-throughput event ingestion |
| `timescaledb` | 5432 | PostgreSQL + TimescaleDB for events and metrics |
| `redis` | 6379 | Caching, pub/sub, projection store |
| `minio` | 9000 | S3-compatible artifact storage |

## Workspace Isolation

Each agent execution runs in an isolated Docker workspace with a two-phase security model:

<WorkspaceIsolationFlow />

**Setup Phase** — Secrets are available briefly to configure credential helpers. Raw tokens are cleared before the agent starts.

**Agent Phase** — The agent runs with only `ANTHROPIC_API_KEY` in its environment. Git operations use cached credentials from the setup phase.

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `APP_ENVIRONMENT` | `development` | Environment mode (`development`, `production`) |
| `TIMESCALEDB_HOST` | `localhost` | TimescaleDB hostname |
| `TIMESCALEDB_PORT` | `5432` | TimescaleDB port |
| `REDIS_URL` | `redis://localhost:6379` | Redis connection URL |
| `MINIO_ENDPOINT` | `localhost:9000` | MinIO S3 endpoint |
| `MINIO_ACCESS_KEY` | — | MinIO access key |
| `MINIO_SECRET_KEY` | — | MinIO secret key |
| `GITHUB_APP_ID` | — | GitHub App ID for webhook triggers |
| `GITHUB_APP_PRIVATE_KEY` | — | GitHub App private key (PEM) |
| `ANTHROPIC_API_KEY` | — | API key for Claude agent execution |

## Scaling Options

### Single Server (Self-Host)

Recommended for **10–100 concurrent agents**:
- 4+ CPU cores, 8GB+ RAM (16GB recommended)
- 500GB NVMe storage
- Docker with workspace pooling (10–50 containers)

### Multi-Server

For **100–1,000 concurrent agents**, run multiple Syntropic137 instances behind a load balancer:

<ScalingFlow />

### Kubernetes

For **1,000+ concurrent agents** with auto-scaling:
- Use Kata Containers runtime for workspace isolation
- HPA with 70% CPU target, 3–20 replicas
- PersistentVolume for artifact storage

## Tunnels (Optional)

For secure external access and GitHub Actions webhook delivery, set up a tunnel. Syntropic137 includes built-in Cloudflare Tunnel support via a Docker Compose profile.

See the [Tunnels guide](/docs/guide/tunnels) for setup instructions.

## Secrets

Infrastructure secrets (database, Redis, MinIO) are stored as `chmod 600` files and mounted via Docker Compose's secrets mechanism — never baked into image layers. Application-level API keys (e.g. `ANTHROPIC_API_KEY`) are supplied via environment variables.

See [Secrets Management](/docs/guide/secrets) for details on how secrets work and optional 1Password integration.

---

## "Setup CLI"
> "npx @syntropic137/setup — interactive CLI for installing and managing the Syntropic137 platform."

The setup CLI is a zero-dependency Node.js tool for bootstrapping and managing your Syntropic137 installation. It wraps Docker Compose operations with an interactive TUI.

## Usage

```bash
npx @syntropic137/setup [command]
```

Running without a command shows an interactive menu.

## Commands

| Command | Purpose |
|---------|---------|
| `init` | Full setup wizard — Docker check, secrets, API key, GitHub App, plugin, pull images, start stack |
| `status` | Show running services (`docker compose ps`) |
| `start` | Start the stack |
| `stop` | Stop the stack |
| `logs` | Tail service logs (`docker compose logs -f`) |
| `update` | Pull latest container images and restart |
| `plugin` | Install or update the Claude Code plugin |
| `github-app` | Create or reconfigure the GitHub App |

## `init` Options

```bash
npx @syntropic137/setup init [options]

--org <name>         Create GitHub App under an organization (default: personal account)
--name <app-name>    GitHub App name (default: syntropic137)
--dir <path>         Install directory (default: ~/.syntropic137)
--skip-github        Skip GitHub App creation
--skip-docker        Generate config files only — don't pull images or start services
--webhook-url <url>  Set webhook URL for the GitHub App
```

## What `init` Creates

```
~/.syntropic137/
├── docker-compose.syntropic137.yaml   # Service definitions
├── selfhost-entrypoint.sh             # Secret injection script
├── selfhost.env.example               # Configuration reference
├── .env                               # Your configuration (chmod 600)
├── init-db/
│   └── 01-create-databases.sql        # Database initialization
├── secrets/                           # All chmod 600
│   ├── db-password.secret
│   ├── redis-password.secret
│   ├── minio-password.secret
│   └── github-app-private-key.pem     # If GitHub App configured
└── workspaces/                        # Agent workspace mount
```

## Reconfiguring

Run `init` again to reconfigure. The wizard detects an existing installation and asks whether to reconfigure from scratch or update specific settings. Existing secrets are backed up to `.bak` files.

<Callout type="idea">
**Planned:** Tunnel management and secrets reconfiguration directly from the interactive TUI. Tracked in [syntropic137/syntropic137#422](https://github.com/syntropic137/syntropic137/issues/422).
</Callout>

---

## Tunnels
> Expose Syntropic137 to the internet for GitHub webhooks and remote access.

By default, Syntropic137 binds to `127.0.0.1:8137` — localhost only. A tunnel exposes it to the internet so GitHub can deliver webhooks and you can access the dashboard remotely.

## When You Need a Tunnel

<Callout type="info">
Syntropic137's event polling covers most GitHub events **without** a tunnel — PRs, pushes, issues, and more work out of the box. Tunnels are only required for two things:
</Callout>

1. **GitHub Actions webhook events** — `workflow_run`, `check_run`, and other Actions events are not available via GitHub's Events API. Webhook delivery requires a reachable URL.
2. **Remote access** — accessing the dashboard or API from outside your local network.

If you only use push/PR/issue triggers and access the dashboard locally, you don't need a tunnel.

## Cloudflare Tunnels

Syntropic137 includes Cloudflare Tunnel support in its Docker Compose stack via the `tunnel` profile.

### Setup

1. Install cloudflared and authenticate:

```bash
brew install cloudflare/cloudflare/cloudflared
cloudflared tunnel login
```

2. Create a tunnel in the [Cloudflare Zero Trust dashboard](https://one.dash.cloudflare.com/) and copy the tunnel token.

3. Add three variables to your `~/.syntropic137/.env`:

```bash
COMPOSE_PROFILES=tunnel
CLOUDFLARE_TUNNEL_TOKEN=your-tunnel-token-here
SYN_PUBLIC_HOSTNAME=syn137.yourdomain.com
```

4. Restart the stack:

```bash
npx @syntropic137/setup stop
npx @syntropic137/setup start
```

The `cloudflared` container starts automatically and routes traffic from your domain to the gateway service. No port forwarding needed.

### Updating the GitHub App Webhook URL

After setting up the tunnel, update your GitHub App's webhook URL:

```bash
npx @syntropic137/setup github-app
```

Or manually in GitHub → Settings → Developer Settings → Your App → Webhook URL → set to `https://syn137.yourdomain.com/api/v1/webhooks/github`.

## Other Tunnel Options

While Cloudflare Tunnels are the built-in option, any tunnel that forwards HTTPS traffic to `localhost:8137` works:

- **ngrok** — `ngrok http 8137`
- **Tailscale Funnel** — `tailscale funnel 8137`
- **SSH tunnel** — `ssh -R 80:localhost:8137 your-server`

Set `SYN_PUBLIC_HOSTNAME` in your `.env` to your tunnel's public URL regardless of which provider you use.

---

## Why Syntropic137?
> What makes Syntropic137 different from running agents ad-hoc in your terminal.

You can run an AI agent in your terminal right now. So why build a platform around it?

Because running agents is easy. Running them **repeatably, observably, and safely** — at scale — is hard. Syntropic137 closes that gap.

<FeatureGrid>
  <FeatureCard
    icon="workflow"
    title="Repeatable Workflows"
    description="Multi-phase pipelines built on the Claude Code command standard. Research, plan, implement, review — every workflow runs the same way, every time."
    gradient="indigo"
  />
  <FeatureCard
    icon="layers"
    title="Immutable Event Store"
    description="Every state change is a permanent, queryable event. Domain events, observability telemetry, and conversation logs — nothing is ever lost."
    gradient="purple"
  />
  <FeatureCard
    icon="git"
    title="GitHub-Native Triggers"
    description="Webhook triggers enable self-healing CI, auto-responses to review comments, and PR-driven workflows. Agents respond in minutes."
    gradient="cyan"
  />
  <FeatureCard
    icon="shield"
    title="Workspace Isolation"
    description="Every agent runs in an ephemeral Docker container. API keys are never exposed to workspaces. Egress proxies control outbound traffic."
    gradient="green"
  />
</FeatureGrid>

## The Problem

When you run Claude Code in your terminal, you get results — but you lose everything else:

- **No record** of what the agent did, which tools it called, or how much it cost
- **No way to replay** a successful workflow on a different repo
- **No isolation** — the agent has access to your entire machine
- **No triggers** — you have to manually kick off every task

## What Syntropic137 Adds

| Capability | Without Syntropic137 | With Syntropic137 |
|-----------|---------------------|-------------------|
| **Execution** | One-off terminal sessions | Multi-phase workflows with YAML definitions |
| **Observability** | Read the terminal output | Token usage, tool timelines, cost tracking, session replay |
| **Isolation** | Runs on your machine | Ephemeral Docker containers with secret injection |
| **Automation** | Manual start | GitHub webhooks, scheduled triggers, event-driven pipelines |
| **Data** | Gone when the terminal closes | Event-sourced — every state change is permanent and queryable |
| **Cost** | Check your API dashboard | Per-session, per-workflow, per-org cost breakdown |

## Who It's For

- **Engineering teams** using AI agents for code review, research, and automation
- **Platform engineers** who need observability and cost controls around agent usage
- **Solo developers** who want repeatable workflows without building infrastructure

## Next Steps

Ready to try it? [Get started in 5 minutes →](/docs/guide/getting-started)

---

## Workflow Packages
> Install, create, and distribute pre-built workflow packages.

import { Files, Folder, File } from 'fumadocs-ui/components/files';

Workflow packages are the standard format for distributing pre-built workflows in Syntropic137.
After running `npx syntropic137 setup`, installing a workflow package is the fastest way to start
doing useful work with the platform.

## Quick Start

```bash
# Install the starter research workflow
syn workflow install ./workflows/examples/research-package/

# Run it
syn workflow run research-package-v1 --task "Investigate event sourcing patterns for our platform"

# See what's installed
syn workflow installed
```

## Installing Packages

Workflow packages can be installed from local directories or git repositories:

```bash
# Local directory
syn workflow install ./my-package/

# GitHub repository
syn workflow install https://github.com/org/workflow-library
syn workflow install org/workflow-library              # Shorthand
syn workflow install org/workflow-library --ref v2.0   # Specific version

# Validate before installing
syn workflow install ./my-package/ --dry-run
```

The install command resolves all prompt files and shared phases, then creates each
workflow via the API. Installed packages are tracked locally in
`~/.syntropic137/workflows/installed.json`.

## Package Formats

### Single Workflow

The simplest format — one workflow with its phase prompts:

<Files>
  <Folder name="my-workflow" defaultOpen>
    <File name="workflow.yaml" />
    <Folder name="phases" defaultOpen>
      <File name="discover.md" />
      <File name="synthesize.md" />
    </Folder>
    <File name="README.md" />
  </Folder>
</Files>

### Multi-Workflow Plugin

Bundle multiple workflows with a shared phase library:

<Files>
  <Folder name="my-plugin" defaultOpen>
    <File name="syntropic137-plugin.json" />
    <Folder name="workflows" defaultOpen>
      <Folder name="research" defaultOpen>
        <File name="workflow.yaml" />
        <Folder name="phases">
          <File name="*.md" />
        </Folder>
      </Folder>
      <Folder name="pr-review" defaultOpen>
        <File name="workflow.yaml" />
        <Folder name="phases">
          <File name="*.md" />
        </Folder>
      </Folder>
    </Folder>
    <Folder name="phase-library" defaultOpen>
      <File name="summarize.md" />
    </Folder>
    <File name="README.md" />
  </Folder>
</Files>

Shared phases are referenced with the `shared://` prefix:

```yaml
phases:
  - id: summarize
    prompt_file: shared://summarize  # → phase-library/summarize.md
```

Content is resolved at install time — no runtime dependency on the library.

## Creating Packages

### Scaffold from Template

```bash
# Single workflow
syn workflow init ./my-workflow --name "My Workflow" --type research --phases 3

# Multi-workflow plugin
syn workflow init ./my-plugin --name "My Plugin" --multi
```

### Phase Prompt Files

Phase prompts use optional YAML frontmatter followed by the prompt body:

```markdown
---
model: sonnet
argument-hint: "[topic]"
allowed-tools: Read,Glob,Grep,Bash
max-tokens: 4096
timeout-seconds: 300
---

You are a research assistant investigating: $ARGUMENTS

Use {{discovery}} to reference output from a previous phase.
```

Frontmatter provides defaults; `workflow.yaml` values always take precedence.

### Plugin Manifest

Multi-workflow plugins use `syntropic137-plugin.json` for metadata:

```json
{
  "manifest_version": 1,
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Research and review workflows",
  "author": "my-org",
  "license": "MIT"
}
```

## Exporting Workflows

Export a running workflow from Syntropic137 as a distributable plugin. Exported
plugins can be re-imported on another instance or shared via a marketplace.

```bash
# Export as a package (workflow.yaml + phase .md files)
syn workflow export <workflow-id> --output ./my-package/

# Export as a plugin (includes CC command wrapper for slash-command invocation)
syn workflow export <workflow-id> --format plugin --output ./my-plugin/
```

### Package Format (default)

Produces a directory that can be re-installed with `syn workflow install`:

<Files>
  <Folder name="my-package" defaultOpen>
    <File name="workflow.yaml" />
    <Folder name="phases" defaultOpen>
      <File name="discovery.md" />
      <File name="synthesis.md" />
    </Folder>
    <File name="README.md" />
  </Folder>
</Files>

### Plugin Format

Produces a Syntropic137 plugin with a manifest, CC command wrapper, and workflow:

<Files>
  <Folder name="my-plugin" defaultOpen>
    <File name="syntropic137-plugin.json" />
    <Folder name="commands" defaultOpen>
      <File name="syn-deep-research.md" />
    </Folder>
    <Folder name="workflows" defaultOpen>
      <Folder name="deep-research" defaultOpen>
        <File name="workflow.yaml" />
        <Folder name="phases" defaultOpen>
          <File name="discovery.md" />
          <File name="synthesis.md" />
        </Folder>
      </Folder>
    </Folder>
    <File name="README.md" />
  </Folder>
</Files>

The `commands/syn-*.md` wrapper calls `syn workflow run`, so the exported workflow
can also be invoked as a `/syn-*` slash command from Claude Code. The package itself
is a Syntropic137 plugin — the CC command is a convenience bridge.

### Round-Trip Guarantee

Exported packages are always re-importable:

```bash
syn workflow export my-workflow-v1 --output ./exported/
syn workflow install ./exported/   # produces an equivalent workflow
```

## Validating Packages

```bash
# Validate a package directory
syn workflow validate ./my-package/

# Validate a single YAML file
syn workflow validate ./workflow.yaml
```

Validation checks the YAML schema, verifies that all referenced `.md` files exist,
and resolves `shared://` references.

## Example Packages

The repository includes reference implementations:

- **`workflows/examples/research-package/`** — Single workflow with discovery + synthesis phases
- **`workflows/examples/starter-plugin/`** — Multi-workflow plugin with shared summarize phase

## Marketplace

The marketplace lets you discover, install, and share workflow plugins from
GitHub-hosted registries. Any GitHub repository with a `marketplace.json` at the
root can serve as a marketplace.

### Register a Marketplace

```bash
# Add the official Syntropic137 marketplace
syn marketplace add syntropic137/workflow-library

# Add a company-internal marketplace
syn marketplace add myorg/internal-workflows --name my-company

# Add from a specific branch or tag
syn marketplace add myorg/workflows --ref v2.0

# List registered marketplaces
syn marketplace list

# Refresh cached indexes
syn marketplace refresh

# Refresh a specific marketplace
syn marketplace refresh my-company

# Remove a marketplace
syn marketplace remove my-company
```

### Discover Workflows

```bash
# Search across all registered marketplaces
syn workflow search "research"
syn workflow search --category research
syn workflow search --tag multi-phase

# Show details of a specific plugin
syn workflow info research-toolkit
```

Search matches against plugin name, description, category, and tags
(case-insensitive). An empty query returns all plugins across all registries.

### Install from Marketplace

```bash
# Install by plugin name (resolved from registered marketplaces)
syn workflow install research-toolkit

# Still works: install from local paths and git URLs
syn workflow install ./my-package/
syn workflow install org/repo
```

When you pass a bare name (no slashes, not a path), the CLI checks registered
marketplaces first. If found, it clones the marketplace repo, resolves the
plugin's subdirectory, and installs the workflows.

### Update and Uninstall

```bash
# Update a package to the latest version
syn workflow update research-toolkit

# Check for updates without applying
syn workflow update research-toolkit --dry-run

# Uninstall (removes workflows from the platform)
syn workflow uninstall research-toolkit

# Uninstall but keep workflows running
syn workflow uninstall research-toolkit --keep-workflows
```

Updates compare the remote git SHA against the installed SHA. If they match,
the package is already up to date and no action is taken.

### Creating a Marketplace Repository

Any GitHub repository can be a marketplace. Create a `marketplace.json` at the
root and organize plugins in subdirectories:

#### Step 1: Create the Repository Structure

<Files>
  <Folder name="my-marketplace" defaultOpen>
    <File name="marketplace.json" />
    <Folder name="plugins" defaultOpen>
      <Folder name="research-toolkit" defaultOpen>
        <File name="syntropic137-plugin.json" />
        <Folder name="workflows" defaultOpen>
          <Folder name="deep-research">
            <File name="workflow.yaml" />
            <Folder name="phases">
              <File name="*.md" />
            </Folder>
          </Folder>
          <Folder name="quick-scan">
            <File name="workflow.yaml" />
            <Folder name="phases">
              <File name="*.md" />
            </Folder>
          </Folder>
        </Folder>
        <Folder name="phase-library">
          <File name="summarize.md" />
        </Folder>
      </Folder>
      <Folder name="pr-automation">
        <File name="workflow.yaml" />
        <Folder name="phases">
          <File name="*.md" />
        </Folder>
      </Folder>
    </Folder>
    <File name="README.md" />
  </Folder>
</Files>

#### Step 2: Write `marketplace.json`

```json
{
  "name": "my-marketplace",
  "syntropic137": {
    "type": "workflow-marketplace"
  },
  "plugins": [
    {
      "name": "research-toolkit",
      "source": "./plugins/research-toolkit",
      "version": "1.2.0",
      "description": "Deep research and quick-scan workflows",
      "category": "research",
      "tags": ["multi-phase", "deep-dive", "synthesis"]
    },
    {
      "name": "pr-automation",
      "source": "./plugins/pr-automation",
      "version": "0.5.0",
      "description": "Automated PR review and feedback",
      "category": "ci",
      "tags": ["github", "code-review"]
    }
  ]
}
```

#### Step 3: Push and Register

```bash
git push origin main

# Users register your marketplace:
syn marketplace add your-org/my-marketplace
```

### `marketplace.json` Schema

The `marketplace.json` file is the index that describes all plugins in the
marketplace. It must be a JSON object at the repository root.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Human-readable marketplace name (used as default registry name) |
| `syntropic137` | object | Yes | Marker identifying this as a Syntropic137 marketplace |
| `syntropic137.type` | string | Yes | Must be `"workflow-marketplace"` |
| `syntropic137.min_platform_version` | string | No | Minimum platform version (default `"0.0.0"`) |
| `plugins` | array | No | List of plugin entries (default `[]`) |

Each plugin entry in the `plugins` array:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Unique plugin name (used for `syn workflow install <name>`) |
| `source` | string | Yes | Relative path to the plugin directory (e.g., `"./plugins/my-plugin"`) |
| `version` | string | No | Semver version string (default `"0.1.0"`) |
| `description` | string | No | Short description shown in search results |
| `category` | string | No | Plugin category (e.g., `"research"`, `"ci"`, `"analysis"`) |
| `tags` | array | No | List of tags for filtering (e.g., `["multi-phase", "github"]`) |

The `source` path must be relative (no absolute paths or `..` traversal). Each
plugin directory follows the standard [package format](#package-formats) — either
a single workflow or a multi-workflow plugin.

### Caching and Refresh

Marketplace indexes are cached locally at `~/.syntropic137/marketplace/cache/`
to avoid cloning on every search or install.

- **Cache TTL:** 4 hours. After this, the next search or install re-fetches the index.
- **Force refresh:** `syn marketplace refresh` bypasses the TTL and fetches fresh indexes.
- **Cache location:** `~/.syntropic137/marketplace/cache/<registry-name>.json`
- **Registry config:** `~/.syntropic137/registries.json`

Searches and plugin lookups use the cache when fresh, falling back to a fresh
fetch when stale. If a fetch fails (network error, repo not found), stale cache
entries are skipped silently.

### Private Marketplaces

Private GitHub repositories work as marketplaces if git can authenticate.
The CLI uses your local git credential configuration — no special flags needed.

```bash
# Ensure git can access the private repo (any of these work):
# - GitHub CLI: gh auth login
# - SSH key: git clone git@github.com:myorg/private-marketplace.git
# - Credential helper: git config credential.helper

# Then register normally:
syn marketplace add myorg/private-marketplace --name internal
```

For CI environments, set the `GIT_ASKPASS` or `GH_TOKEN` environment variable,
or configure a credential helper that reads from environment variables.

### Troubleshooting

**"No marketplace.json found in repo"** — The repository must have a
`marketplace.json` at the root of the default branch (or the branch specified
with `--ref`).

**"syntropic137.type must be 'workflow-marketplace'"** — The `syntropic137`
key in `marketplace.json` must contain `"type": "workflow-marketplace"`.
This marker distinguishes marketplace repos from other Syntropic137 content.

**"Invalid registry name"** — Registry names must start with an alphanumeric
character and contain only letters, digits, hyphens, underscores, and dots.
Names like `../evil` or `my/registry` are rejected.

**Plugin not found after registering** — Run `syn marketplace refresh` to
re-fetch the latest index. The local cache may be stale.

**Private repo access denied** — Ensure `git clone` works for the repo URL
from your terminal. The CLI uses the same git credentials as your shell.

**"Package is already up to date"** — `syn workflow update` compares git
SHAs. If the remote HEAD hasn't changed, no update is needed.

### Limitations

- One marketplace index per repository (no nested marketplace files)
- No dependency resolution between plugins
- No version conflict detection across multiple marketplaces
- No rollback to a previous plugin version (uninstall and re-install at a pinned `--ref`)
- Search is substring-based, not fuzzy or ranked

## Learn More

- [CLI Reference](/docs/cli) — all `syn workflow` and `syn marketplace` commands
- [API Reference](/docs/api/workflows) — workflow creation endpoints

---

## Agents
> ''

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/agents/providers","method":"get"},{"path":"/agents/test","method":"post"},{"path":"/agents/chat","method":"post"}]} showTitle={true} />

---

## Artifacts
> Create, upload, and retrieve artifacts produced by agent sessions

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/artifacts","method":"get"},{"path":"/artifacts","method":"post"},{"path":"/artifacts/{artifact_id}","method":"get"},{"path":"/artifacts/{artifact_id}/content","method":"get"},{"path":"/artifacts/{artifact_id}/upload","method":"post"}]} showTitle={true} />

---

## Control
> Pause, resume, cancel, and inject context into running executions

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/executions/{execution_id}/pause","method":"post"},{"path":"/executions/{execution_id}/resume","method":"post"},{"path":"/executions/{execution_id}/cancel","method":"post"},{"path":"/executions/{execution_id}/inject","method":"post"},{"path":"/executions/{execution_id}/state","method":"get"}]} showTitle={true} />

---

## Conversations
> Retrieve conversation logs and metadata

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/conversations/{session_id}","method":"get"},{"path":"/conversations/{session_id}/metadata","method":"get"}]} showTitle={true} />

---

## Costs
> Track token costs per session and execution

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/costs/sessions","method":"get"},{"path":"/costs/sessions/{session_id}","method":"get"},{"path":"/costs/executions","method":"get"},{"path":"/costs/executions/{execution_id}","method":"get"},{"path":"/costs/summary","method":"get"}]} showTitle={true} />

---

## Events
> Query session events, timelines, and tool usage

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/events/recent","method":"get"},{"path":"/events/sessions/{session_id}","method":"get"},{"path":"/events/sessions/{session_id}/timeline","method":"get"},{"path":"/events/sessions/{session_id}/costs","method":"get"},{"path":"/events/sessions/{session_id}/tools","method":"get"}]} showTitle={true} />

---

## Execution
> Execute workflows and monitor active executions

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/workflows/{workflow_id}/execute","method":"post"},{"path":"/workflows/{workflow_id}/executions/{execution_id}","method":"get"},{"path":"/workflows/executions/active","method":"get"}]} showTitle={true} />

---

## Executions
> Query execution records and details

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/executions","method":"get"},{"path":"/executions/{execution_id}","method":"get"}]} showTitle={true} />

---

## API Reference
> REST API documentation for the Syntropic137 Dashboard API, auto-generated from the OpenAPI specification.

The Syntropic137 Dashboard API provides programmatic access to workflows, executions,
agent sessions, artifacts, and real-time observability data.

## Base URL

```
http://localhost:8137/api
```

## Authentication

The API currently supports internal access. Authentication is planned for a
future release.

## Endpoints

The API reference below is auto-generated from the OpenAPI specification. Use
the sidebar to navigate between endpoint groups.

---

## Insights
> ''

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/insights/overview","method":"get"},{"path":"/insights/cost","method":"get"},{"path":"/insights/contribution-heatmap","method":"get"}]} showTitle={true} />

---

## Metrics
> System-wide metrics and health data

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/metrics","method":"get"}]} showTitle={true} />

---

## Observability
> Token metrics and tool timelines for sessions

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/observability/sessions/{session_id}/tools","method":"get"},{"path":"/observability/sessions/{session_id}/tokens","method":"get"}]} showTitle={true} />

---

## Organizations
> ''

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/organizations","method":"get"},{"path":"/organizations","method":"post"},{"path":"/organizations/{organization_id}","method":"get"},{"path":"/organizations/{organization_id}","method":"delete"},{"path":"/organizations/{organization_id}","method":"put"}]} showTitle={true} />

---

## Repos
> ''

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/repos","method":"get"},{"path":"/repos","method":"post"},{"path":"/repos/{repo_id}","method":"get"},{"path":"/repos/{repo_id}/assign","method":"post"},{"path":"/repos/{repo_id}/unassign","method":"post"},{"path":"/repos/{repo_id}/health","method":"get"},{"path":"/repos/{repo_id}/cost","method":"get"},{"path":"/repos/{repo_id}/activity","method":"get"},{"path":"/repos/{repo_id}/failures","method":"get"},{"path":"/repos/{repo_id}/sessions","method":"get"}]} showTitle={true} />

---

## Sessions
> List and inspect agent sessions

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/sessions","method":"get"},{"path":"/sessions/{session_id}","method":"get"}]} showTitle={true} />

---

## Sse
> ''

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/sse/executions/{execution_id}","method":"get"},{"path":"/sse/activity","method":"get"},{"path":"/sse/health","method":"get"}]} showTitle={true} />

---

## Systems
> ''

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/systems","method":"get"},{"path":"/systems","method":"post"},{"path":"/systems/{system_id}","method":"get"},{"path":"/systems/{system_id}","method":"delete"},{"path":"/systems/{system_id}","method":"put"},{"path":"/systems/{system_id}/status","method":"get"},{"path":"/systems/{system_id}/cost","method":"get"},{"path":"/systems/{system_id}/activity","method":"get"},{"path":"/systems/{system_id}/patterns","method":"get"},{"path":"/systems/{system_id}/history","method":"get"}]} showTitle={true} />

---

## Triggers
> Manage GitHub and webhook triggers for workflow automation

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/triggers","method":"get"},{"path":"/triggers","method":"post"},{"path":"/triggers/history","method":"get"},{"path":"/triggers/{trigger_id}","method":"get"},{"path":"/triggers/{trigger_id}","method":"patch"},{"path":"/triggers/{trigger_id}","method":"delete"},{"path":"/triggers/{trigger_id}/history","method":"get"},{"path":"/triggers/presets/{preset_name}","method":"post"}]} showTitle={true} />

---

## Webhooks
> Incoming webhook endpoints (GitHub events)

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/webhooks/github","method":"post"}]} showTitle={true} />

---

## Workflows
> Manage workflow definitions and view run history

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document={"./openapi.json"} webhooks={[]} operations={[{"path":"/workflows","method":"get"},{"path":"/workflows","method":"post"},{"path":"/workflows/{workflow_id}","method":"get"},{"path":"/workflows/{workflow_id}","method":"delete"},{"path":"/workflows/{workflow_id}/runs","method":"get"},{"path":"/workflows/{workflow_id}/history","method":"get"},{"path":"/workflows/validate","method":"post"},{"path":"/workflows/{workflow_id}/phases/{phase_id}","method":"put"}]} showTitle={true} />

---

## syn agent
> "AI agent management and testing"

AI agent management and testing

## `syn agent chat`

Start an interactive chat session.

```bash
syn agent chat
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--provider`, `-p` | `text` | `claude` | Agent provider |
| `--system`, `-s` | `text` | --- | System prompt |
| `--model`, `-m` | `text` | --- | Model override |

---

## `syn agent list`

List available agent providers.

```bash
syn agent list
```

---

## `syn agent test`

Test an agent provider with a simple prompt.

```bash
syn agent test
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--provider`, `-p` | `text` | `claude` | Agent provider (claude, mock) |
| `--prompt` | `text` | `Say hello in one sentence.` | Test prompt |
| `--model`, `-m` | `text` | --- | Model override |

---

---

## syn artifacts
> "Browse and retrieve workflow artifacts"

Browse and retrieve workflow artifacts

## `syn artifacts content`

Print the raw content of an artifact.

```bash
syn artifacts content <artifact_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `artifact_id` | `text` | Yes | Artifact ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--raw` | `boolean` | `false` | Print raw content without syntax highlighting |

---

## `syn artifacts create`

Create a new artifact.

```bash
syn artifacts create --workflow <workflow> --type <artifact_type> --title <title> --content <content>
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--workflow`, `-w` | `text` | --- | Workflow ID |
| `--type`, `-t` | `text` | --- | Artifact type (code, document, research_summary) |
| `--title` | `text` | --- | Artifact title |
| `--content`, `-c` | `text` | --- | Artifact content |
| `--phase`, `-p` | `text` | --- | Phase ID |

---

## `syn artifacts list`

List artifacts, optionally filtered by workflow or phase.

```bash
syn artifacts list
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--workflow`, `-w` | `text` | --- | Filter by workflow ID |
| `--phase`, `-p` | `text` | --- | Filter by phase ID |
| `--type`, `-t` | `text` | --- | Filter by artifact type |
| `--limit` | `integer` | `50` | Max results (max 200) |

---

## `syn artifacts show`

Show artifact metadata and optionally its content.

```bash
syn artifacts show <artifact_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `artifact_id` | `text` | Yes | Artifact ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--no-content` | `boolean` | `false` | Skip content; show metadata only |

---

---

## syn config
> "Configuration management"

Configuration management

## `syn config env`

Show environment variable template.

```bash
syn config env
```

---

## `syn config show`

Display current configuration.

```bash
syn config show
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--show-secrets` | `boolean` | `false` | Show secret values |

---

## `syn config validate`

Validate configuration and show issues.

```bash
syn config validate
```

---

---

## syn control
> "Control running executions"

Control running executions

## `syn control cancel`

Cancel a running or paused execution.

```bash
syn control cancel <execution_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `execution_id` | `text` | Yes | Execution ID to cancel |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--reason`, `-r` | `text` | --- | Reason for cancelling |
| `--force`, `-f` | `boolean` | `false` | Skip confirmation prompt |

---

## `syn control inject`

Inject a message into a running execution.

```bash
syn control inject <execution_id> --message <message>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `execution_id` | `text` | Yes | Execution ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--message`, `-m` | `text` | --- | Message to inject |

---

## `syn control pause`

Pause a running execution at the next yield point.

```bash
syn control pause <execution_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `execution_id` | `text` | Yes | Execution ID to pause |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--reason`, `-r` | `text` | --- | Reason for pausing |

---

## `syn control resume`

Resume a paused execution.

```bash
syn control resume <execution_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `execution_id` | `text` | Yes | Execution ID to resume |

---

## `syn control status`

Get current execution control state.

```bash
syn control status <execution_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `execution_id` | `text` | Yes | Execution ID to check |

---

## `syn control stop`

Forcefully stop a running execution via SIGINT.

Sends a cancel signal that causes the engine to interrupt the Claude CLI
process via SIGINT and capture partial output as an interrupted execution.

```bash
syn control stop <execution_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `execution_id` | `text` | Yes | Execution ID to stop |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--reason`, `-r` | `text` | --- | Reason for stopping |
| `--force`, `-f` | `boolean` | `false` | Skip confirmation prompt |

---

---

## syn conversations
> "Inspect agent conversation logs"

Inspect agent conversation logs

## `syn conversations metadata`

Show metadata summary for a session's conversation.

```bash
syn conversations metadata <session_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `session_id` | `text` | Yes | Session ID |

---

## `syn conversations show`

Show parsed conversation log lines for a session.

```bash
syn conversations show <session_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `session_id` | `text` | Yes | Session ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--offset` | `integer` | `0` | Line offset for pagination |
| `--limit` | `integer` | `100` | Max lines to show (max 500) |

---

---

## syn costs
> "View cost tracking data for sessions and executions"

View cost tracking data for sessions and executions

## `syn costs execution`

Show detailed cost breakdown for an execution.

```bash
syn costs execution <execution_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `execution_id` | `text` | Yes | Execution ID |

---

## `syn costs executions`

List cost data for workflow executions.

```bash
syn costs executions
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--limit`, `-n` | `integer range` | `50` | Max results |

---

## `syn costs session`

Show detailed cost breakdown for a session.

```bash
syn costs session <session_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `session_id` | `text` | Yes | Session ID |

---

## `syn costs sessions`

List cost data for sessions.

```bash
syn costs sessions
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--execution`, `-e` | `text` | --- | Filter by execution ID |
| `--limit`, `-n` | `integer range` | `50` | Max results |

---

## `syn costs summary`

Show aggregated cost summary across all sessions and executions.

```bash
syn costs summary
```

---

---

## syn events
> "Query domain events and session observability"

Query domain events and session observability

## `syn events costs`

Show token usage and cost breakdown for a session.

```bash
syn events costs <session_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `session_id` | `text` | Yes | Session ID |

---

## `syn events recent`

Show recent domain events across all sessions.

```bash
syn events recent
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--limit` | `integer` | `50` | Max events to show (max 200) |

---

## `syn events session`

List events for a specific session.

```bash
syn events session <session_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `session_id` | `text` | Yes | Session ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--type`, `-t` | `text` | --- | Filter by event type |
| `--limit` | `integer` | `100` | Max events (max 1000) |
| `--offset` | `integer` | `0` | Pagination offset |

---

## `syn events timeline`

Show a chronological tool-call timeline for a session.

```bash
syn events timeline <session_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `session_id` | `text` | Yes | Session ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--limit` | `integer` | `100` | Max entries (max 500) |

---

## `syn events tools`

Show tool usage summary for a session.

```bash
syn events tools <session_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `session_id` | `text` | Yes | Session ID |

---

---

## syn execution
> "List and inspect workflow executions"

List and inspect workflow executions

## `syn execution list`

List all workflow executions across every workflow.

```bash
syn execution list
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--status`, `-s` | `text` | --- | Filter by status (running, completed, failed, …) |
| `--page` | `integer` | `1` | Page number |
| `--page-size` | `integer` | `50` | Items per page (max 100) |

---

## `syn execution show`

Show detailed information about a single execution.

```bash
syn execution show <execution_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `execution_id` | `text` | Yes | Execution ID |

---

---

## CLI Reference
> Command-line interface for Syntropic137.

The `syn` CLI provides commands for managing workflows, agents, and the Syntropic137
platform from your terminal.

## Installation

The CLI is included when you install Syntropic137:

```bash
uv sync
syn --help
```

## Global Commands

| Command | Description |
|---------|-------------|
| `syn health` | Check API server health status. |
| `syn run` | Execute a workflow (shortcut for 'syn workflow run'). |
| `syn version` | Show version information. |

## Command Groups

| Group | Description |
|-------|-------------|
| [`syn agent`](./agent) | AI agent management and testing |
| [`syn artifacts`](./artifacts) | Browse and retrieve workflow artifacts |
| [`syn config`](./config) | Configuration management |
| [`syn control`](./control) | Control running executions |
| [`syn conversations`](./conversations) | Inspect agent conversation logs |
| [`syn costs`](./costs) | View cost tracking data for sessions and executions |
| [`syn events`](./events) | Query domain events and session observability |
| [`syn execution`](./execution) | List and inspect workflow executions |
| [`syn insights`](./insights) | Global system insights and cost analysis |
| [`syn marketplace`](./marketplace) | Manage workflow marketplace registries. |
| [`syn metrics`](./metrics) | View aggregated workflow and session metrics |
| [`syn observe`](./observe) | Observability data for sessions — tool timelines and token metrics |
| [`syn org`](./org) | Manage organizations |
| [`syn repo`](./repo) | Manage repositories and their observability |
| [`syn sessions`](./sessions) | View and inspect agent sessions |
| [`syn system`](./system) | Manage systems and their observability |
| [`syn triggers`](./triggers) | Manage self-healing trigger rules |
| [`syn watch`](./watch) | Watch live execution or activity streams |
| [`syn workflow`](./workflow) | Manage workflows - create, list, run, and inspect |

## Global Options

| Option | Description |
|--------|-------------|
| `--help` | Show help message |

---

## syn insights
> "Global system insights and cost analysis"

Global system insights and cost analysis

## `syn insights cost`

Show global cost breakdown across repos, workflows, and models.

```bash
syn insights cost
```

---

## `syn insights heatmap`

Show a contribution heatmap of activity over time.

```bash
syn insights heatmap
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--org` | `text` | --- | Filter by organization ID |
| `--system` | `text` | --- | Filter by system ID |
| `--repo` | `text` | --- | Filter by repo ID |
| `--start` | `text` | --- | Start date (YYYY-MM-DD) |
| `--end` | `text` | --- | End date (YYYY-MM-DD) |
| `--metric`, `-m` | `text` | `sessions` | Metric: sessions, cost, tokens |

---

## `syn insights overview`

Show a global overview of all systems and their health.

```bash
syn insights overview
```

---

---

## syn marketplace
> "Manage workflow marketplace registries."

Manage workflow marketplace registries.

## `syn marketplace add`

Register a GitHub repo as a workflow marketplace.

```bash
syn marketplace add <repo>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `repo` | `text` | Yes | GitHub repo (org/repo shorthand) |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--ref`, `-r` | `text` | `main` | Git branch or tag |
| `--name`, `-n` | `text` | --- | Override registry name |

---

## `syn marketplace list`

List registered marketplace registries.

```bash
syn marketplace list
```

---

## `syn marketplace refresh`

Force-refresh cached marketplace indexes.

```bash
syn marketplace refresh <name>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | `text` | No | Registry name (refreshes all if omitted) |

---

## `syn marketplace remove`

Remove a registered marketplace.

```bash
syn marketplace remove <name>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | `text` | Yes | Registry name to remove |

---

---

## syn metrics
> "View aggregated workflow and session metrics"

View aggregated workflow and session metrics

## `syn metrics show`

Show aggregated metrics (optionally filtered by workflow).

```bash
syn metrics show
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--workflow`, `-w` | `text` | --- | Filter by workflow ID |

---

---

## syn observe
> "Observability data for sessions — tool timelines and token metrics"

Observability data for sessions — tool timelines and token metrics

## `syn observe tokens`

Show token breakdown for a session.

```bash
syn observe tokens <session_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `session_id` | `text` | Yes | Session ID |

---

## `syn observe tools`

Show tool execution timeline for a session.

```bash
syn observe tools <session_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `session_id` | `text` | Yes | Session ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--limit`, `-n` | `integer range` | `100` | Max results |

---

---

## syn org
> "Manage organizations"

Manage organizations

## `syn org create`

Create a new organization.

```bash
syn org create --name <name> --slug <slug>
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--name`, `-n` | `text` | --- | Organization name |
| `--slug`, `-s` | `text` | --- | URL-safe slug |
| `--created-by` | `text` | `cli` | Creator identifier |

---

## `syn org delete`

Delete an organization.

```bash
syn org delete <organization_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `organization_id` | `text` | Yes | Organization ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--force`, `-f` | `boolean` | `false` | Skip confirmation |

---

## `syn org list`

List all organizations.

```bash
syn org list
```

---

## `syn org show`

Show details of an organization.

```bash
syn org show <organization_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `organization_id` | `text` | Yes | Organization ID |

---

## `syn org update`

Update an organization's name or slug.

```bash
syn org update <organization_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `organization_id` | `text` | Yes | Organization ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--name`, `-n` | `text` | --- | New name |
| `--slug`, `-s` | `text` | --- | New slug |

---

---

## syn repo
> "Manage repositories and their observability"

Manage repositories and their observability

## `syn repo activity`

Show recent execution activity for a repo.

```bash
syn repo activity <repo_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `repo_id` | `text` | Yes | Repo ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--limit` | `integer` | `50` | Max entries |
| `--offset` | `integer` | `0` | Pagination offset |

---

## `syn repo assign`

Assign a repo to a system.

```bash
syn repo assign <repo_id> --system <system>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `repo_id` | `text` | Yes | Repo ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--system`, `-s` | `text` | --- | System ID |

---

## `syn repo cost`

Show cost breakdown for a repo.

```bash
syn repo cost <repo_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `repo_id` | `text` | Yes | Repo ID |

---

## `syn repo failures`

Show recent execution failures for a repo.

```bash
syn repo failures <repo_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `repo_id` | `text` | Yes | Repo ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--limit` | `integer` | `50` | Max failures to show |

---

## `syn repo health`

Show health metrics for a repo.

```bash
syn repo health <repo_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `repo_id` | `text` | Yes | Repo ID |

---

## `syn repo list`

List registered repositories.

```bash
syn repo list
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--org`, `-o` | `text` | --- | Filter by organization ID |
| `--system`, `-s` | `text` | --- | Filter by system ID |
| `--unassigned` | `boolean` | `false` | Only repos without a system |

---

## `syn repo register`

Register a repository with an organization.

```bash
syn repo register --org <org> --url <url>
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--org`, `-o` | `text` | --- | Organization ID |
| `--url`, `-u` | `text` | --- | Full repo name (owner/repo) |
| `--system`, `-s` | `text` | --- | Assign to system immediately |
| `--provider` | `text` | `github` | Provider (github, gitlab, …) |
| `--branch` | `text` | `main` | Default branch |
| `--private` | `boolean` | `false` | Private repo |
| `--created-by` | `text` | `cli` | Creator identifier |

---

## `syn repo sessions`

Show agent sessions associated with a repo.

```bash
syn repo sessions <repo_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `repo_id` | `text` | Yes | Repo ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--limit` | `integer` | `50` | Max sessions to show |

---

## `syn repo show`

Show repo details.

```bash
syn repo show <repo_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `repo_id` | `text` | Yes | Repo ID |

---

## `syn repo unassign`

Remove a repo from its system.

```bash
syn repo unassign <repo_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `repo_id` | `text` | Yes | Repo ID |

---

---

## syn sessions
> "View and inspect agent sessions"

View and inspect agent sessions

## `syn sessions list`

List agent sessions.

```bash
syn sessions list
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--workflow`, `-w` | `text` | --- | Filter by workflow ID |
| `--status`, `-s` | `text` | --- | Filter by status |
| `--limit`, `-n` | `integer range` | `50` | Max results |

---

## `syn sessions show`

Show detailed information for a session.

```bash
syn sessions show <session_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `session_id` | `text` | Yes | Session ID |

---

---

## syn system
> "Manage systems and their observability"

Manage systems and their observability

## `syn system activity`

Show recent execution activity for a system.

```bash
syn system activity <system_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `system_id` | `text` | Yes | System ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--limit` | `integer` | `50` | Max entries |
| `--offset` | `integer` | `0` | Pagination offset |

---

## `syn system cost`

Show cost breakdown for a system.

```bash
syn system cost <system_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `system_id` | `text` | Yes | System ID |

---

## `syn system create`

Create a new system within an organization.

```bash
syn system create --org <org> --name <name>
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--org`, `-o` | `text` | --- | Organization ID |
| `--name`, `-n` | `text` | --- | System name |
| `--description`, `-d` | `text` | `` | Description |
| `--created-by` | `text` | `cli` | Creator identifier |

---

## `syn system delete`

Delete a system.

```bash
syn system delete <system_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `system_id` | `text` | Yes | System ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--force`, `-f` | `boolean` | `false` | Skip confirmation |

---

## `syn system history`

Show full execution history for a system.

```bash
syn system history <system_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `system_id` | `text` | Yes | System ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--limit` | `integer` | `50` | Max entries |
| `--offset` | `integer` | `0` | Pagination offset |

---

## `syn system list`

List all systems, optionally filtered by organization.

```bash
syn system list
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--org`, `-o` | `text` | --- | Filter by organization ID |

---

## `syn system patterns`

Show failure patterns and cost outliers for a system.

```bash
syn system patterns <system_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `system_id` | `text` | Yes | System ID |

---

## `syn system show`

Show system details.

```bash
syn system show <system_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `system_id` | `text` | Yes | System ID |

---

## `syn system status`

Show health status of a system and its repos.

```bash
syn system status <system_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `system_id` | `text` | Yes | System ID |

---

## `syn system update`

Update a system's name or description.

```bash
syn system update <system_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `system_id` | `text` | Yes | System ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--name`, `-n` | `text` | --- | New name |
| `--description`, `-d` | `text` | --- | New description |

---

---

## syn triggers
> "Manage self-healing trigger rules"

Manage self-healing trigger rules

## `syn triggers delete`

Delete a trigger rule.

```bash
syn triggers delete <trigger_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `trigger_id` | `text` | Yes | Trigger ID |

---

## `syn triggers disable`

Disable all triggers for a repository.

```bash
syn triggers disable --repository <repository>
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--repository`, `-r` | `text` | --- | Disable all triggers for repo |

---

## `syn triggers enable`

Enable a built-in preset for a repository.

```bash
syn triggers enable <preset> --repository <repository>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `preset` | `text` | Yes | Preset name: self-healing | review-fix |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--repository`, `-r` | `text` | --- | Repository (owner/repo) |
| `--installation-id` | `text` | `` | GitHub App installation ID |
| `--created-by` | `text` | `cli` | Creator identifier |

---

## `syn triggers history`

Show trigger execution history.

```bash
syn triggers history <trigger_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `trigger_id` | `text` | Yes | Trigger ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--limit` | `integer` | `50` | Max entries to show |

---

## `syn triggers list`

List all registered triggers.

```bash
syn triggers list
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--repository`, `-r` | `text` | --- | Filter by repository |
| `--status`, `-s` | `text` | --- | Filter by status |

---

## `syn triggers pause`

Pause a trigger rule.

```bash
syn triggers pause <trigger_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `trigger_id` | `text` | Yes | Trigger ID |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--reason` | `text` | --- | Reason for pausing |

---

## `syn triggers register`

Register a new trigger rule.

```bash
syn triggers register --name <name> --event <event> --repository <repository> --workflow <workflow>
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--name`, `-n` | `text` | --- | Human-readable name |
| `--event`, `-e` | `text` | --- | GitHub event (e.g., check_run.completed) |
| `--repository`, `-r` | `text` | --- | Repository (owner/repo) |
| `--workflow`, `-w` | `text` | --- | Workflow ID to execute |
| `--condition`, `-c` | `text` | --- | Conditions: 'field operator value' |
| `--max-attempts` | `integer` | `3` | Max retry attempts per PR |
| `--budget` | `float` | `5.0` | Budget per trigger in USD |
| `--daily-limit` | `integer` | `20` | Max triggers per day |
| `--installation-id` | `text` | `` | GitHub App installation ID |
| `--created-by` | `text` | `cli` | Creator identifier |

---

## `syn triggers resume`

Resume a paused trigger rule.

```bash
syn triggers resume <trigger_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `trigger_id` | `text` | Yes | Trigger ID |

---

## `syn triggers show`

Show trigger details.

```bash
syn triggers show <trigger_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `trigger_id` | `text` | Yes | Trigger ID |

---

---

## syn watch
> "Watch live execution or activity streams"

Watch live execution or activity streams

## `syn watch activity`

Stream live global activity across all executions.

```bash
syn watch activity
```

---

## `syn watch execution`

Stream live events for a specific execution.

```bash
syn watch execution <execution_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `execution_id` | `text` | Yes | Execution ID to watch |

---

---

## syn workflow
> "Manage workflows - create, list, run, and inspect"

Manage workflows - create, list, run, and inspect

## `syn workflow create`

Create a new workflow.

```bash
syn workflow create <name>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | `text` | Yes | Name of the workflow |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--type`, `-t` | `text` | `custom` | Type: research, planning, implementation, review, deployment, custom |
| `--repo`, `-r` | `text` | `https://github.com/example/repo` | Repository URL for the workflow |
| `--ref` | `text` | `main` | Repository ref/branch |
| `--description`, `-d` | `text` | --- | Workflow description |

---

## `syn workflow delete`

Archive (soft-delete) a workflow template.

Archived workflows are hidden from 'syn workflow list' by default.
Use 'syn workflow list --include-archived' to see them.

```bash
syn workflow delete <workflow_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workflow_id` | `text` | Yes | Workflow ID (partial match supported) |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--force`, `-f` | `boolean` | `false` | Skip confirmation prompt |

---

## `syn workflow export`

Export a workflow as a distributable package or Claude Code plugin.

```bash
syn workflow export <workflow_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workflow_id` | `text` | Yes | Workflow ID to export |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--format`, `-f` | `text` | `package` | Export format: 'package' (default) or 'plugin' (Claude Code plugin) |
| `--output`, `-o` | `path` | `.` | Output directory (created if absent) |

---

## `syn workflow info`

Show details of a marketplace workflow plugin.

```bash
syn workflow info <name>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | `text` | Yes | Plugin name from marketplace |

---

## `syn workflow init`

Scaffold a new workflow package from a template.

```bash
syn workflow init <directory>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `directory` | `path` | No | Directory to scaffold |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--name`, `-n` | `text` | --- | Workflow name |
| `--type`, `-t` | `text` | `research` | Workflow type |
| `--phases` | `integer` | `3` | Number of phases |
| `--multi` | `boolean` | `false` | Scaffold multi-workflow plugin |

---

## `syn workflow install`

Install workflow(s) from a package, git repository, or marketplace.

```bash
syn workflow install <source>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `source` | `text` | Yes | Plugin name, local path, GitHub URL, or org/repo shorthand |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--ref` | `text` | `main` | Git branch/tag to clone |
| `--dry-run`, `-n` | `boolean` | `false` | Validate without installing |

---

## `syn workflow installed`

List installed workflow packages.

```bash
syn workflow installed
```

---

## `syn workflow list`

List all workflows in the system.

```bash
syn workflow list
```

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--include-archived` | `boolean` | `false` | Include archived workflows |

---

## `syn workflow run`

Execute a workflow.

```bash
syn workflow run <workflow_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workflow_id` | `text` | Yes | Workflow ID (partial match supported) |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--input`, `-i` | `text` | --- | Input variables as key=value |
| `--task`, `-t` | `text` | --- | Primary task description ($ARGUMENTS) |
| `--dry-run`, `-n` | `boolean` | `false` | Validate without executing |
| `--quiet`, `-q` | `boolean` | `false` | Minimal output |
| `--container`, `-c` | `boolean` | `true` | Run in isolated container |
| `--tenant` | `text` | --- | Tenant ID for multi-tenant attribution |

---

## `syn workflow search`

Search for workflows across registered marketplaces.

```bash
syn workflow search <query>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | `text` | No | Search term (matches name, description, tags) |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--category`, `-c` | `text` | --- | Filter by category |
| `--tag`, `-t` | `text` | --- | Filter by tag |
| `--registry`, `-r` | `text` | --- | Search specific marketplace only |

---

## `syn workflow show`

Show details of a specific workflow.

```bash
syn workflow show <workflow_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workflow_id` | `text` | Yes | Workflow ID (partial match supported) |

---

## `syn workflow status`

Show execution history for a workflow.

```bash
syn workflow status <workflow_id>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workflow_id` | `text` | Yes | Workflow ID (partial match supported) |

---

## `syn workflow uninstall`

Uninstall a workflow package.

```bash
syn workflow uninstall <name>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | `text` | Yes | Package name to uninstall |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--keep-workflows` | `boolean` | `false` | Remove from registry but keep workflows in the platform |

---

## `syn workflow update`

Update an installed workflow package to the latest version.

```bash
syn workflow update <name>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | `text` | Yes | Package name to update |

**Options:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--ref` | `text` | --- | Override git ref |
| `--dry-run`, `-n` | `boolean` | `false` | Check for updates without applying |

---

## `syn workflow validate`

Validate a workflow YAML file or package directory without creating it.

```bash
syn workflow validate <file>
```

**Arguments:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file` | `path` | Yes | YAML file or package directory to validate |

---

---