> ## Documentation Index
> Fetch the complete documentation index at: https://llmwiki.atomicstrata.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# workflow

> Run and inspect declarative profile workflows.

`llmwiki workflow` runs workflows declared by the active profile. Workflows are
configuration, not code: each stage declares what entity types it reads, what it
may write, optional artifact outputs, and optional gates.

## Discover workflows

```bash theme={null}
llmwiki workflow list
llmwiki workflow show research
```

`workflow list` prints every workflow id declared by the active profile.
`workflow show` prints the stage list, reads, writes, gates, projection file, and
declared actions.

## Start and inspect a run

```bash theme={null}
llmwiki workflow start research --input topic=attention
llmwiki workflow status
llmwiki workflow status <run-id>
llmwiki workflow events <run-id>
```

Workflow runs are durable records under `.llmwiki/`. `workflow status` is
read-only and exits non-zero when a run is blocked by profile changes,
unavailable state, or other integrity problems.

## Advance a run

```bash theme={null}
llmwiki workflow advance <run-id>
```

Advancing moves the run to the next stage when its current stage is satisfied.
A stage with an unapplied write, unsatisfied gate, or blocked output stays parked
until the required action is taken.

## Submit stage output

```bash theme={null}
llmwiki workflow submit <run-id> \
  --kind page \
  --entity-type ideas \
  --slug sparse-attention-idea \
  --body-file ./idea.md
```

Supported output kinds:

| Kind | Required flags |
| - | - |
| `page` | `--entity-type`, `--slug`, `--body-file` |
| `relation` | `--output-file` containing JSON `{ "type", "from", "to" }` |
| `lifecycle-transition` | `--entity-type`, `--slug`, `--to-state`, optional `--evidence-file` |
| `artifact` | `--artifact-type`, `--slug`, `--body-file` |

Every output is checked against the active profile. Page outputs must satisfy
field contracts and lifecycle rules. Relation outputs must match declared
endpoint types. Artifact outputs must match the stage's `artifactWrites` list.

## Gates and trusted writes

Profiles can declare `trust:`, `human:`, and `agent:` gates.

* A `trust:` gate requires an out-of-workspace operator grant before a clean
  stage write auto-applies live.
* The grant is `LLMWIKI_TRUSTED_WRITE=<profileId>` or `LLMWIKI_TRUSTED_WRITE=*`.
* A parked output prints whether the grant can help. Planner denials and
  quarantine decisions are not overridden by the grant.
* A `human:` gate is satisfied only through the interactive confirmation path.
  `--actor human` is rejected.

```bash theme={null}
LLMWIKI_TRUSTED_WRITE=autosci \
  llmwiki workflow submit <run-id> --kind page --entity-type papers --slug p1 --body-file ./paper.md
```

## Workflow actions

Profiles can expose named actions as shortcuts over workflow operations.

```bash theme={null}
llmwiki workflow action list
llmwiki workflow action show research.begin
llmwiki workflow action run research.begin --input topic=attention
```

Action authority is composed from the profile's requested permission, local
configuration, and the surface hard cap. CLI and SDK can reach `trusted-write`
when granted. MCP and viewer surfaces are capped at `staged-write`.

## Adapt, project, and finish runs

```bash theme={null}
llmwiki workflow adapt --dry-run
llmwiki workflow adapt <run-id> --apply
llmwiki workflow project <run-id>
llmwiki workflow fail <run-id> --detail "waiting on data"
llmwiki workflow resume <run-id>
llmwiki workflow cancel <run-id>
```

`workflow project` writes a derived markdown projection only when the workflow
declares `projectionFile`. It does not change the run state.

## When to use the local engine

`llmwiki workflow` is the lightweight tier: each invocation runs locally on one
machine, with mutations serialized by the project lock and no orchestration
service required. Run records persist under `.llmwiki/` between invocations,
including while a run waits for human approval. The whole run does not need to
finish in one process or terminal session. It remains supported on its existing
experimental terms.

It is not a durable orchestration platform. Reach for your own coordinator,
built on the standard [SDK](/guides/sdk-packages), when you need:

* automatic work dispatch and worker recovery after process failure
* distributed execution or managed multi-user approval routing
* built-in scheduling or event-triggered execution of repeated runs
* coordination across several projects or services

Persisted local state is not a promise of automatic replay or retry of an
interrupted action. Inspect the recorded state before taking recovery actions.

That coordinator calls compiler services for retained data and authorized
effects; it does not gain approval or trusted-write authority by existing. See
[External orchestration and operation authority](/guides/sdk#external-orchestration-and-operation-authority).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.