forgeo-cli 0.6.0__tar.gz → 0.7.1__tar.gz

{forgeo_cli-0.6.0 → forgeo_cli-0.7.1}/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-08-17
+
+### Added
+
+- An animated demo GIF in the README, showing Forgeo running a backlog task
+  end to end, plus an Open Graph social-preview image for the docs site.
+
+### Changed
+
+- The default agent prompt (used by `forgeo init`) now names `AGENTS.md` and
+  `CONTEXT.md` explicitly when telling the agent to keep project overview and
+  conventions up to date.
+
+## [0.7.0] - 2026-08-16
+
+### Added
+
+- `task_context` config key: a path to a file (e.g. `CONTEXT.md`) whose
+  contents are prepended to every agent instruction — tasks and refactoring
+  runs alike — before the task description. The agent gets the high-level
+  project overview instead of only the isolated task; the file is re-read on
+  every run, so the agent's own updates are picked up on the next cycle. A
+  missing or unreadable file never fails a cycle: it is logged, `forgeo
+  validate` reports it as a warning, and the run proceeds with the bare
+  instruction.
+- The default agent prompt (used by `forgeo init`) now tells the agent to
+  read `AGENTS.md` (and `CONTEXT.md` if present) at the start of the session
+  and to keep them updated when a change materially affects the project
+  overview.
+
+- `forgeo run --task <id>` runs exactly one specific `OPEN` task by id and
+  exits, instead of letting `forgeo once` pick the oldest one — for triage:
+  rerun a `FAILED` task (after reopening it) or try a risky task now. It
+  shares the same per-forgeo lock as the daemon and `forgeo once`, so it
+  never overlaps them; it refuses with a clear error when the task does not
+  exist or is not `OPEN`, and while another daemon/`once`/`run` holds the
+  lock.
+
 ## [0.6.0] - 2026-08-14
 
 ### Added
@@ -283,7 +321,9 @@ Initial release of the scheduled, agent-driven software forgeo.
   overlapping-run skipping.
 - Dogfooding docs removed; local configs kept out of the repository.
 
-[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.7.1...HEAD
+[0.7.1]: https://github.com/lucaGazzola/forgeo/compare/v0.7.0...v0.7.1
+[0.7.0]: https://github.com/lucaGazzola/forgeo/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/lucaGazzola/forgeo/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/lucaGazzola/forgeo/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/lucaGazzola/forgeo/compare/v0.3.0...v0.4.0

{forgeo_cli-0.6.0 → forgeo_cli-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgeo-cli
-Version: 0.6.0
+Version: 0.7.1
 Summary: A scheduled software forgeo: executes backlog tasks on main, refactors when idle, and writes BLOCKER.md when it needs human input.
 Project-URL: Homepage, https://forgeo.org
 Project-URL: Documentation, https://forgeo.org
@@ -64,6 +64,10 @@ Description-Content-Type: text/markdown
 [![CI](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml/badge.svg)](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+<div align="center">
+  <img src="docs/img/demo.gif" alt="Forgeo running a backlog task end to end" width="720">
+</div>
+
 **Forgeo is a software factory for your coding-agent.**
 You're already working with an AI coding agent, prompting it task by task
 or giving it a goal. Forgeo organizes your work in a structured way with
@@ -83,50 +87,93 @@ agent CLI.
 
 The full walkthrough is in [Getting started](docs/getting-started.md).
 
-```bash
-# 1. Install (any one of these)
+### 1. Install the CLI
 
-# Homebrew (macOS / Linux)
+Pick any one installer (no root needed; re-running it upgrades Forgeo).
+
+```bash
+# Homebrew (macOS / Linux): prebuilt binary, no Python required
 brew install lucaGazzola/forgeo/forgeo
 
-# or: the one-liner (prebuilt binary, no Python required)
+# One-liner (Linux / macOS / Windows): prebuilt binary, falls back to pip
 curl -fsSL https://forgeo.org/install.sh | bash
 
-# or: pipx
+# pip (Python 3.11+)
 pipx install forgeo-cli
+```
 
-# 2. Create your Forgeo (guided wizard, run from your project root)
-forgeo init
+### 2. Create your Forgeo
 
-# 3. Start Forgeo (detached in the background; exits immediately)
-forgeo start   # every interval_minutes, implement the oldest OPEN task (dependencies first)
-forgeo stop    # stop the daemon again
+```bash
+forgeo init
 ```
 
-`forgeo init` writes `forgeo.yaml` and a `.forgeo/` folder for the backlog
-and logs. Fill the backlog with plain JSON tasks (see
-[Backlog format](docs/backlog.md)) or add them from the web console while
-it runs, Forgeo does the rest. Open the dashboard with `forgeo web` (default <http://0.0.0.0:8790>), or keep it always-on with `forgeo web -d` (stop it with `forgeo web stop`, check it with `forgeo web status`):
+Guided wizard, run from your project root. Writes `forgeo.yaml` (the
+config) and a `.forgeo/` folder for the backlog, logs and blocker files.
+
+The base flow is then three steps: fill the backlog, check the
+configuration, start the daemon.
+
+### 3. Fill the backlog
+
+```bash
+# Either: edit the backlog file by hand — a plain JSON task list (see
+# Backlog format), created on first use:
+#   .forgeo/backlog.json
+
+# Or: add tasks from the web console once your forgeo is registered
+# (first `forgeo start` registers it automatically):
+forgeo web      # dashboard at http://0.0.0.0:8790, or keep it on with `forgeo web -d`
+```
 
 ![Forgeo web console](docs/img/console.png)
 
-By default the dashboard is open to anyone who can reach the port. On a
-shared host, protect it with bearer-token auth: `forgeo web --token`
-generates a token (printed once, saved to `~/.config/forgeo/web.toml`) and
-requires `Authorization: Bearer <token>` on every `/api/*` route — see
-[Web console & HTTP API](docs/web-console-api.md).
-
-One-off commands: `forgeo once` (single cycle), `forgeo status` (summary),
-`forgeo validate` (read-only dry run before starting), `forgeo stop`,
-`forgeo restart`, every command is in the
-[CLI reference](docs/cli-reference.md).
-
-You can run several factories at once, one per repository, each config is
-fully independent (own backlog, logs, locks). Register each `forgeo.yaml`
-in the instance registry with `forgeo instance add NAME --config PATH`,
-manage any of them by name with `forgeo start/status/stop --name NAME`,
-list them all with `forgeo list`, and get one aggregate overview with the
-central dashboard, `forgeo web`.
+### 4. Check the configuration
+
+```bash
+forgeo validate
+```
+
+Read-only dry run before the first start: verifies `forgeo.yaml`, the git
+repo, branch and remote, that the backlog parses (fetching it once when it
+is an HTTP endpoint), the agent command, and the lock state. Never invokes
+the agent and writes nothing.
+
+### 5. Start the daemon
+
+```bash
+forgeo start
+```
+
+Starts the daemon **detached in the background** and exits. Every
+`interval_minutes` it runs one cycle: pick the oldest `OPEN` task whose
+dependencies are all `COMPLETED`, run your coding agent on it, commit the
+result. When the backlog is empty, the same agent runs a refactoring pass
+over the codebase instead.
+
+### Day-to-day commands
+
+```bash
+forgeo status    # Config, backlog counts, next runnable task, daemon running?, last outcome
+forgeo once      # Run exactly one cycle in the foreground, no daemon left behind
+forgeo run --task SELF-012  # Run one specific OPEN task now (triage)
+forgeo stop      # Stop the background daemon
+forgeo restart   # Stop and start again (re-reads forgeo.yaml after edits)
+forgeo web       # Dashboard: every instance's backlog, run history and logs
+```
+
+`forgeo web` defaults to an open dashboard on `http://0.0.0.0:8790`; on a
+shared host protect it with `forgeo web --token` (requires
+`Authorization: Bearer <token>` on every `/api/*` route — see
+[Web console & HTTP API](docs/web-console-api.md)).
+
+### Multiple repositories (instances)
+
+Run several factories at once, one per repository; each config is fully
+independent (own backlog, logs, locks). Register each `forgeo.yaml` with
+`forgeo instance add NAME --config PATH`, manage any of them by name with
+`forgeo start/status/stop --name NAME`, list them all with `forgeo list`,
+and get one aggregate overview with the central dashboard, `forgeo web`.
 
 ## Documentation
 

{forgeo_cli-0.6.0 → forgeo_cli-0.7.1}/README.md

@@ -10,6 +10,10 @@
 [![CI](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml/badge.svg)](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+<div align="center">
+  <img src="docs/img/demo.gif" alt="Forgeo running a backlog task end to end" width="720">
+</div>
+
 **Forgeo is a software factory for your coding-agent.**
 You're already working with an AI coding agent, prompting it task by task
 or giving it a goal. Forgeo organizes your work in a structured way with
@@ -29,50 +33,93 @@ agent CLI.
 
 The full walkthrough is in [Getting started](docs/getting-started.md).
 
-```bash
-# 1. Install (any one of these)
+### 1. Install the CLI
 
-# Homebrew (macOS / Linux)
+Pick any one installer (no root needed; re-running it upgrades Forgeo).
+
+```bash
+# Homebrew (macOS / Linux): prebuilt binary, no Python required
 brew install lucaGazzola/forgeo/forgeo
 
-# or: the one-liner (prebuilt binary, no Python required)
+# One-liner (Linux / macOS / Windows): prebuilt binary, falls back to pip
 curl -fsSL https://forgeo.org/install.sh | bash
 
-# or: pipx
+# pip (Python 3.11+)
 pipx install forgeo-cli
+```
 
-# 2. Create your Forgeo (guided wizard, run from your project root)
-forgeo init
+### 2. Create your Forgeo
 
-# 3. Start Forgeo (detached in the background; exits immediately)
-forgeo start   # every interval_minutes, implement the oldest OPEN task (dependencies first)
-forgeo stop    # stop the daemon again
+```bash
+forgeo init
 ```
 
-`forgeo init` writes `forgeo.yaml` and a `.forgeo/` folder for the backlog
-and logs. Fill the backlog with plain JSON tasks (see
-[Backlog format](docs/backlog.md)) or add them from the web console while
-it runs, Forgeo does the rest. Open the dashboard with `forgeo web` (default <http://0.0.0.0:8790>), or keep it always-on with `forgeo web -d` (stop it with `forgeo web stop`, check it with `forgeo web status`):
+Guided wizard, run from your project root. Writes `forgeo.yaml` (the
+config) and a `.forgeo/` folder for the backlog, logs and blocker files.
+
+The base flow is then three steps: fill the backlog, check the
+configuration, start the daemon.
+
+### 3. Fill the backlog
+
+```bash
+# Either: edit the backlog file by hand — a plain JSON task list (see
+# Backlog format), created on first use:
+#   .forgeo/backlog.json
+
+# Or: add tasks from the web console once your forgeo is registered
+# (first `forgeo start` registers it automatically):
+forgeo web      # dashboard at http://0.0.0.0:8790, or keep it on with `forgeo web -d`
+```
 
 ![Forgeo web console](docs/img/console.png)
 
-By default the dashboard is open to anyone who can reach the port. On a
-shared host, protect it with bearer-token auth: `forgeo web --token`
-generates a token (printed once, saved to `~/.config/forgeo/web.toml`) and
-requires `Authorization: Bearer <token>` on every `/api/*` route — see
-[Web console & HTTP API](docs/web-console-api.md).
-
-One-off commands: `forgeo once` (single cycle), `forgeo status` (summary),
-`forgeo validate` (read-only dry run before starting), `forgeo stop`,
-`forgeo restart`, every command is in the
-[CLI reference](docs/cli-reference.md).
-
-You can run several factories at once, one per repository, each config is
-fully independent (own backlog, logs, locks). Register each `forgeo.yaml`
-in the instance registry with `forgeo instance add NAME --config PATH`,
-manage any of them by name with `forgeo start/status/stop --name NAME`,
-list them all with `forgeo list`, and get one aggregate overview with the
-central dashboard, `forgeo web`.
+### 4. Check the configuration
+
+```bash
+forgeo validate
+```
+
+Read-only dry run before the first start: verifies `forgeo.yaml`, the git
+repo, branch and remote, that the backlog parses (fetching it once when it
+is an HTTP endpoint), the agent command, and the lock state. Never invokes
+the agent and writes nothing.
+
+### 5. Start the daemon
+
+```bash
+forgeo start
+```
+
+Starts the daemon **detached in the background** and exits. Every
+`interval_minutes` it runs one cycle: pick the oldest `OPEN` task whose
+dependencies are all `COMPLETED`, run your coding agent on it, commit the
+result. When the backlog is empty, the same agent runs a refactoring pass
+over the codebase instead.
+
+### Day-to-day commands
+
+```bash
+forgeo status    # Config, backlog counts, next runnable task, daemon running?, last outcome
+forgeo once      # Run exactly one cycle in the foreground, no daemon left behind
+forgeo run --task SELF-012  # Run one specific OPEN task now (triage)
+forgeo stop      # Stop the background daemon
+forgeo restart   # Stop and start again (re-reads forgeo.yaml after edits)
+forgeo web       # Dashboard: every instance's backlog, run history and logs
+```
+
+`forgeo web` defaults to an open dashboard on `http://0.0.0.0:8790`; on a
+shared host protect it with `forgeo web --token` (requires
+`Authorization: Bearer <token>` on every `/api/*` route — see
+[Web console & HTTP API](docs/web-console-api.md)).
+
+### Multiple repositories (instances)
+
+Run several factories at once, one per repository; each config is fully
+independent (own backlog, logs, locks). Register each `forgeo.yaml` with
+`forgeo instance add NAME --config PATH`, manage any of them by name with
+`forgeo start/status/stop --name NAME`, list them all with `forgeo list`,
+and get one aggregate overview with the central dashboard, `forgeo web`.
 
 ## Documentation
 

{forgeo_cli-0.6.0 → forgeo_cli-0.7.1}/docs/agent-contract.md

@@ -19,18 +19,28 @@ the process environment is augmented as follows:
 
 | Variable | Meaning |
 | --- | --- |
-| `FORGEO_TASK` | The full instruction for this run: title, blank line, description, and an "Acceptance criteria:" list when present. |
-| `FORGEO_REPO` | The absolute path of the repository. |
-| `FORGEO_BRANCH` | The branch everything is committed to (default `main`). |
-| *every `agent_env` key* | Any extra variables from `agent_env` in the config. |
-| *inherited environment* | The daemon's own environment. |
+| <span style="white-space: nowrap">`FORGEO_TASK`</span> | The full instruction for this run: the project context when `task_context` is configured, then title, blank line, description, and an "Acceptance criteria:" list when present. |
+| <span style="white-space: nowrap">`FORGEO_REPO`</span> | The absolute path of the repository. |
+| <span style="white-space: nowrap">`FORGEO_BRANCH`</span> | The branch everything is committed to (default `main`). |
+| <span style="white-space: nowrap">*every `agent_env` key*</span> | Any extra variables from `agent_env` in the config. |
+| <span style="white-space: nowrap">*inherited environment*</span> | The daemon's own environment. |
 
 `FORGEO_*` variables are set unconditionally and take precedence over both the
 inherited environment and `agent_env`.
 
+### The task is not the whole picture
+
+A task description is isolated by design: it describes one unit of work, not
+the project. When `task_context` is set (see
+[Configuration](configuration.md#task_context)), Forgeo prepends the contents
+of that file — the high-level project overview — to `FORGEO_TASK` before the
+task, under a `# Project context` heading, followed by the task under a
+`# Task` heading. The file is re-read on every run, so an agent's own updates
+to it are seen by the next cycle.
+
 For a refactoring run (empty backlog) the same contract applies: the refactor
-prompt arrives as `FORGEO_TASK` with the task id `REFACTOR` and title
-"Refactoring pass".
+prompt arrives as `FORGEO_TASK` (with the context prepended when configured),
+with the task id `REFACTOR` and title "Refactoring pass".
 
 ## Exit codes
 
@@ -38,10 +48,10 @@ The exit code decides the outcome of the run:
 
 | Exit code | Outcome | What happens |
 | --- | --- | --- |
-| `0` | **SUCCESS** | Everything is committed (`git add -A && git commit`) with the message `<title> (#<id>)`, pushed when a remote is set, and the task is marked `COMPLETED`. |
-| `no_changes_exit_code` (default `3`) | **SUCCESS, no changes** | The agent explicitly reports the task needs **no code change**: the task is marked `COMPLETED` without a commit (and the run record notes why). Only accepted when the working tree is clean. |
-| `blocked_exit_code` (default `2`) | **BLOCKED** | The agent needs a human decision. Partial work is committed as `<title> [partial]`, the agent's reason is persisted on the task (`blocker_reason`), optional Telegram and/or webhook notifications are sent, and the task is marked `BLOCKED`. `BLOCKER.md` is rendered from the backlog's `BLOCKED` tasks on the next cycle — real per-task reasons, never generic text — and disappears once the last one is resolved (reopen it from the web console). |
-| anything else | **ERROR** | Changes are discarded (`git reset --hard` + `git clean -fd`), the failure is logged, and the task is marked `FAILED`. |
+| <span style="white-space: nowrap">`0`</span> | **SUCCESS** | Everything is committed (`git add -A && git commit`) with the message `<title> (#<id>)`, pushed when a remote is set, and the task is marked `COMPLETED`. |
+| <span style="white-space: nowrap">`no_changes_exit_code` (default `3`)</span> | **SUCCESS, no changes** | The agent explicitly reports the task needs **no code change**: the task is marked `COMPLETED` without a commit (and the run record notes why). Only accepted when the working tree is clean. |
+| <span style="white-space: nowrap">`blocked_exit_code` (default `2`)</span> | **BLOCKED** | The agent needs a human decision. Partial work is committed as `<title> [partial]`, the agent's reason is persisted on the task (`blocker_reason`), optional Telegram and/or webhook notifications are sent, and the task is marked `BLOCKED`. `BLOCKER.md` is rendered from the backlog's `BLOCKED` tasks on the next cycle — real per-task reasons, never generic text — and disappears once the last one is resolved (reopen it from the web console). |
+| <span style="white-space: nowrap">anything else</span> | **ERROR** | Changes are discarded (`git reset --hard` + `git clean -fd`), the failure is logged, and the task is marked `FAILED`. |
 
 The blocked exit code is configurable via `blocked_exit_code` in
 [forgeo.yaml](configuration.md), and the no-change exit code via
@@ -125,6 +135,9 @@ agent_command: >
   Make the code changes requested below and nothing else. Do NOT run
   git commit, git push, or git add -A — Forgeo commits your work.
   Verify with the test suite where applicable.
+  Read AGENTS.md at the start of the session, and CONTEXT.md if present;
+  if your change materially affects the project overview or conventions,
+  update AGENTS.md and CONTEXT.md accordingly.
   $FORGEO_TASK"
 ```
 

{forgeo_cli-0.6.0 → forgeo_cli-0.7.1}/docs/backlog.md

@@ -80,10 +80,10 @@ cheap/fast model and hard ones to a frontier model:
 
 | Status | Meaning |
 | --- | --- |
-| `OPEN` | To be picked by Forgeo. |
-| `BLOCKED` | Waiting on a human decision; Forgeo pauses while any task is blocked. |
-| `COMPLETED` | The agent finished and the work was committed (and pushed). |
-| `FAILED` | The agent errored; changes were discarded and the reason is recorded in `failure_reason`. |
+| <span style="white-space: nowrap">`OPEN`</span> | To be picked by Forgeo. |
+| <span style="white-space: nowrap">`BLOCKED`</span> | Waiting on a human decision; Forgeo pauses while any task is blocked. |
+| <span style="white-space: nowrap">`COMPLETED`</span> | The agent finished and the work was committed (and pushed). |
+| <span style="white-space: nowrap">`FAILED`</span> | The agent errored; changes were discarded and the reason is recorded in `failure_reason`. |
 
 ## Retrying a failed task
 
@@ -298,8 +298,8 @@ then treats that endpoint exactly like the file:
 
 | When | Request |
 | --- | --- |
-| Every read | `GET <url>` returns the whole document |
-| Every write | `POST <url>` sends the whole document back |
+| <span style="white-space: nowrap">Every read</span> | `GET <url>` returns the whole document |
+| <span style="white-space: nowrap">Every write</span> | `POST <url>` sends the whole document back |
 
 ```yaml
 backlog: https://api.example.com/api/forgeo/backlog

{forgeo_cli-0.6.0 → forgeo_cli-0.7.1}/docs/cli-reference.md

@@ -1,7 +1,7 @@
 # CLI reference
 
 All commands read `forgeo.yaml` from the current directory; pass
-`--config <file>` to use a different one. `start`, `once`, `status`,
+`--config <file>` to use a different one. `start`, `once`, `run`, `status`,
 `validate`, `stop` and `restart` also accept `--name <instance>` to resolve
 the config from the **instance registry** — see [`forgeo instance`](#forgeo-instance)
 below.
@@ -20,8 +20,8 @@ Guided first-time setup: interactively write a `forgeo.yaml`.
 
 | Flag | Description |
 | --- | --- |
-| `--config <file>` | Where to write the config (default `forgeo.yaml`). |
-| `--force` | Overwrite an existing config file. |
+| <span style="white-space: nowrap">`--config <file>`</span> | Where to write the config (default `forgeo.yaml`). |
+| <span style="white-space: nowrap">`--force`</span> | Overwrite an existing config file. |
 
 Exit codes:
 
@@ -41,10 +41,10 @@ foreground instead, interruptible with Ctrl-C.
 
 | Flag | Description |
 | --- | --- |
-| `--config <file>` | Forgeo YAML file (default `forgeo.yaml`). Mutually exclusive with `--name`. |
-| `--name <name>` | Registered instance name resolved from the registry. Mutually exclusive with `--config`. |
-| `--interval-minutes <n>` | Override the schedule interval from the config for this run. |
-| `-f`, `--foreground` | Run the daemon in the foreground instead of starting it detached. |
+| <span style="white-space: nowrap">`--config <file>`</span> | Forgeo YAML file (default `forgeo.yaml`). Mutually exclusive with `--name`. |
+| <span style="white-space: nowrap">`--name <name>`</span> | Registered instance name resolved from the registry. Mutually exclusive with `--config`. |
+| <span style="white-space: nowrap">`--interval-minutes <n>`</span> | Override the schedule interval from the config for this run. |
+| <span style="white-space: nowrap">`-f`, `--foreground`</span> | Run the daemon in the foreground instead of starting it detached. |
 
 The daemon wakes every `interval_minutes` and runs one cycle. When no config
 exists, `forgeo start` offers the guided setup. A second `start` (or `once`)
@@ -81,8 +81,8 @@ Run exactly **one cycle** and exit; no daemon needed.
 
 | Flag | Description |
 | --- | --- |
-| `--config <file>` | Forgeo YAML file (default `forgeo.yaml`). Mutually exclusive with `--name`. |
-| `--name <name>` | Registered instance name resolved from the registry. Mutually exclusive with `--config`. |
+| <span style="white-space: nowrap">`--config <file>`</span> | Forgeo YAML file (default `forgeo.yaml`). Mutually exclusive with `--name`. |
+| <span style="white-space: nowrap">`--name <name>`</span> | Registered instance name resolved from the registry. Mutually exclusive with `--config`. |
 
 `forgeo once` shares the run lock with the daemon, so it never overlaps a
 running `forgeo start` — useful to test a config or process a backlog without
@@ -92,13 +92,38 @@ Outcomes a cycle can produce:
 
 | Outcome | Meaning |
 | --- | --- |
-| `task` | A task ran and finished. |
-| `refactor` | A refactoring pass ran (backlog was empty). |
-| `blocked` | A `BLOCKED` task exists; `BLOCKER.md` re-rendered from the backlog; paused. |
-| `paused` | A blocker file exists; nothing ran. |
-| `dirty` | The working tree was dirty; the task was not started. |
-| `skipped` | A previous run was still in progress (daemon only). |
-| `error` | A cycle crashed (daemon only). |
+| <span style="white-space: nowrap">`task`</span> | A task ran and finished. |
+| <span style="white-space: nowrap">`refactor`</span> | A refactoring pass ran (backlog was empty). |
+| <span style="white-space: nowrap">`blocked`</span> | A `BLOCKED` task exists; `BLOCKER.md` re-rendered from the backlog; paused. |
+| <span style="white-space: nowrap">`paused`</span> | A blocker file exists; nothing ran. |
+| <span style="white-space: nowrap">`dirty`</span> | The working tree was dirty; the task was not started. |
+| <span style="white-space: nowrap">`skipped`</span> | A previous run was still in progress (daemon only). |
+| <span style="white-space: nowrap">`error`</span> | A cycle crashed (daemon only). |
+
+## `forgeo run`
+
+Run exactly **one specific task** by id and exit — no daemon, no waiting for
+the backlog order. Use it for triage: rerun a `FAILED` task immediately
+(after reopening it), or try a risky task right now instead of letting the
+scheduler pick it later.
+
+```bash
+forgeo run --task SELF-012
+```
+
+| Flag | Description |
+| --- | --- |
+| <span style="white-space: nowrap">`--task <id>`</span> | Id of the `OPEN` task to run. **Required.** |
+| <span style="white-space: nowrap">`--config <file>`</span> | Forgeo YAML file (default `forgeo.yaml`). Mutually exclusive with `--name`. |
+| <span style="white-space: nowrap">`--name <name>`</span> | Registered instance name resolved from the registry. Mutually exclusive with `--config`. |
+
+`forgeo run` shares the per-forgeo run lock with the daemon and `forgeo once`,
+so it never overlaps them — it refuses (exit `1`) while the lock is held. It
+also refuses (exit `1`) with a clear message when the task does not exist in
+the backlog or its status is not `OPEN` (a `FAILED` task must be reopened
+first, e.g. from the web console or by editing the backlog). On success it
+prints `Cycle finished: <outcome>` and records the run in `runs.jsonl` like
+any other task run.
 
 ## `forgeo status`
 
@@ -106,8 +131,8 @@ Print a read-only summary of Forgeo. Never starts an agent.
 
 | Flag | Description |
 | --- | --- |
-| `--config <file>` | Forgeo YAML file (default `forgeo.yaml`). Mutually exclusive with `--name`. |
-| `--name <name>` | Registered instance name resolved from the registry. Mutually exclusive with `--config`. |
+| <span style="white-space: nowrap">`--config <file>`</span> | Forgeo YAML file (default `forgeo.yaml`). Mutually exclusive with `--name`. |
+| <span style="white-space: nowrap">`--name <name>`</span> | Registered instance name resolved from the registry. Mutually exclusive with `--config`. |
 
 Output:
 
@@ -144,8 +169,8 @@ while a daemon is active.
 
 | Flag | Description |
 | --- | --- |
-| `--config <file>` | Forgeo YAML file (default `forgeo.yaml`). Mutually exclusive with `--name`. |
-| `--name <name>` | Registered instance name resolved from the registry. Mutually exclusive with `--config`. |
+| <span style="white-space: nowrap">`--config <file>`</span> | Forgeo YAML file (default `forgeo.yaml`). Mutually exclusive with `--name`. |
+| <span style="white-space: nowrap">`--name <name>`</span> | Registered instance name resolved from the registry. Mutually exclusive with `--config`. |
 
 It validates, reporting **all** problems at once:
 
@@ -187,9 +212,9 @@ first).
 
 | Flag | Description |
 | --- | --- |
-| `--config <file>` | Forgeo YAML file (default `forgeo.yaml`). Mutually exclusive with `--name`. |
-| `--name <name>` | Registered instance name resolved from the registry. Mutually exclusive with `--config`. |
-| `--timeout <seconds>` | How long to wait for the daemon to exit (default `600`). |
+| <span style="white-space: nowrap">`--config <file>`</span> | Forgeo YAML file (default `forgeo.yaml`). Mutually exclusive with `--name`. |
+| <span style="white-space: nowrap">`--name <name>`</span> | Registered instance name resolved from the registry. Mutually exclusive with `--config`. |
+| <span style="white-space: nowrap">`--timeout <seconds>`</span> | How long to wait for the daemon to exit (default `600`). |
 
 Exit code is `0` on success, `1` when Forgeo is not running, the lock
 records a dead PID, or the daemon did not exit within the timeout.
@@ -210,17 +235,17 @@ values while running so its lock files are never detached from the config.
 
 | Flag | Description |
 | --- | --- |
-| `--config <file>` | Forgeo YAML file (default `forgeo.yaml`). Mutually exclusive with `--name`. |
-| `--name <name>` | Registered instance name resolved from the registry. Mutually exclusive with `--config`. |
-| `--timeout <seconds>` | How long to wait for the old daemon to exit (default `600`). |
+| <span style="white-space: nowrap">`--config <file>`</span> | Forgeo YAML file (default `forgeo.yaml`). Mutually exclusive with `--name`. |
+| <span style="white-space: nowrap">`--name <name>`</span> | Registered instance name resolved from the registry. Mutually exclusive with `--config`. |
+| <span style="white-space: nowrap">`--timeout <seconds>`</span> | How long to wait for the old daemon to exit (default `600`). |
 
 On success it prints the new daemon PID and interval.
 
 ### `--config` vs `--name`
 
-On `start`, `once`, `status`, `validate`, `stop` and `restart`, `--name`
-resolves the `forgeo.yaml` from the instance registry instead of reading
-`--config`. The two flags are mutually exclusive — passing both is an
+On `start`, `once`, `run`, `status`, `validate`, `stop` and `restart`,
+`--name` resolves the `forgeo.yaml` from the instance registry instead of
+reading `--config`. The two flags are mutually exclusive — passing both is an
 argparse error. An unknown instance name prints a clear error and exits
 non-zero.
 
@@ -244,7 +269,7 @@ differs from `config.name`.
 
 | Flag | Description |
 | --- | --- |
-| `--config <file>` | Path to the `forgeo.yaml` to register. **Required.** |
+| <span style="white-space: nowrap">`--config <file>`</span> | Path to the `forgeo.yaml` to register. **Required.** |
 
 - The name must match `^[a-zA-Z0-9._-]+$`; invalid or duplicate names are
   rejected with a clear error (exit `1`).
@@ -273,11 +298,11 @@ running.
 
 | Flag | Description |
 | --- | --- |
-| `--host <address>` | Bind address (default `0.0.0.0`). |
-| `--port <port>` | Bind port (default `8790`). |
-| `-d`, `--detach` | Start the dashboard in the background and return once it binds. |
-| `--token [TOKEN]` | Require a bearer token on every `/api/*` route (see below). |
-| `--timeout <seconds>` | How long to wait for the dashboard to bind when detached (default `30`). |
+| <span style="white-space: nowrap">`--host <address>`</span> | Bind address (default `0.0.0.0`). |
+| <span style="white-space: nowrap">`--port <port>`</span> | Bind port (default `8790`). |
+| <span style="white-space: nowrap">`-d`, `--detach`</span> | Start the dashboard in the background and return once it binds. |
+| <span style="white-space: nowrap">`--token [TOKEN]`</span> | Require a bearer token on every `/api/*` route (see below). |
+| <span style="white-space: nowrap">`--timeout <seconds>`</span> | How long to wait for the dashboard to bind when detached (default `30`). |
 
 Without `-d` the dashboard runs in the foreground; interrupt it with Ctrl-C
 or stop it from another terminal with `forgeo web stop`.
@@ -322,7 +347,7 @@ Stop the running dashboard gracefully (SIGTERM) and wait for it to exit.
 
 | Flag | Description |
 | --- | --- |
-| `--timeout <seconds>` | How long to wait for the dashboard to exit (default `30`). |
+| <span style="white-space: nowrap">`--timeout <seconds>`</span> | How long to wait for the dashboard to exit (default `30`). |
 
 Exit code is `0` on success, `1` when the dashboard is not running, the lock
 records a dead PID, or it did not exit within the timeout. The lock file is