repoactive 0.3.1.dev3__tar.gz → 0.4.0.dev1__tar.gz

{repoactive-0.3.1.dev3 → repoactive-0.4.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repoactive
-Version: 0.3.1.dev3
+Version: 0.4.0.dev1
 Summary: Script-driven code changes with automated merge requests
 License-Expression: GPL-3.0-or-later
 License-File: LICENSE
@@ -8,15 +8,16 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Version Control
 Classifier: Topic :: Software Development :: Version Control :: Git
-Requires-Python: >=3.11
+Requires-Python: >=3.12
 Requires-Dist: pydantic-settings>=2.14.2
 Requires-Dist: pydantic<3.0.0,>=2.13.4
 Requires-Dist: pygithub<3.0.0,>=2.9.1
@@ -27,28 +28,40 @@ Description-Content-Type: text/markdown
 
 # repoactive - Script-driven code changes with automated merge requests
 
+[![PyPI](https://img.shields.io/pypi/v/repoactive.svg)](https://pypi.org/project/repoactive/)
+[![CI](https://github.com/schmir/repoactive/actions/workflows/ci.yml/badge.svg)](https://github.com/schmir/repoactive/actions/workflows/ci.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/repoactive.svg)](https://pypi.org/project/repoactive/)
+[![License](https://img.shields.io/pypi/l/repoactive.svg)](LICENSE)
+
 > **Warning:** This project is in an early stage of development. Use at your
 > own risk.
 
 `repoactive` runs your scripts against a git repository and optionally keeps
 the corresponding merge requests up to date. You write the scripts that
 produce the code changes; `repoactive` handles the rest - branches, commits,
-and (with `--mode publish`) the full MR lifecycle.
+and (with `--mode publish`) the full MR lifecycle. This document says merge
+request (MR) throughout; on GitHub, read that as pull request (PR).
 
 ## Contents
 
 - [Use cases](#use-cases)
+  - [How it compares](#how-it-compares)
 - [Installation](#installation)
 - [Quick start](#quick-start)
 - [How it works](#how-it-works)
+  - [What a run produces](#what-a-run-produces)
   - [Keeping the local clone current](#keeping-the-local-clone-current)
-- [Usage](#usage)
+  - [Undoing a run](#undoing-a-run)
+- [Commands](#commands)
+  - [`repoactive run`](#repoactive-run)
+  - [`repoactive recent-commits`](#repoactive-recent-commits)
+  - [`repoactive validate-config`](#repoactive-validate-config)
+  - [`repoactive dump-schema`](#repoactive-dump-schema)
+  - [`repoactive info jobs`](#repoactive-info-jobs)
+  - [`repoactive info tags`](#repoactive-info-tags)
   - [Environment variables](#environment-variables)
-- [Inspecting repoactive commits](#inspecting-repoactive-commits)
-- [Validating configuration](#validating-configuration)
-- [Listing jobs](#listing-jobs)
-- [Listing tags](#listing-tags)
 - [Configuration](#configuration)
+  - [Editor support](#editor-support)
   - [`[job-defaults]`](#job-defaults)
   - [`[job.<name>]`](#jobname)
   - [Stacking MRs](#stacking-mrs)
@@ -58,19 +71,20 @@ and (with `--mode publish`) the full MR lifecycle.
   - [Variables passed to job commands](#variables-passed-to-job-commands)
   - [Passing secrets to commands with `secret_env`](#passing-secrets-to-commands-with-secret_env)
   - [Overriding values on the command line](#overriding-values-on-the-command-line)
-- [Selecting jobs with tags](#selecting-jobs-with-tags)
-  - [Keeping unmerged branches current](#keeping-unmerged-branches-current)
-- [Disabling jobs](#disabling-jobs)
-- [Running a job on a schedule](#running-a-job-on-a-schedule)
-  - [One run at a time per repository](#one-run-at-a-time-per-repository)
-- [Gating jobs with `run_only_if_changed`](#gating-jobs-with-run_only_if_changed)
-- [Throttling jobs with `cooldown_period`](#throttling-jobs-with-cooldown_period)
-- [Throttling a job when a superset lands with `cooldown_on`](#throttling-a-job-when-a-superset-lands-with-cooldown_on)
-- [Limiting job runtime with `timeout`](#limiting-job-runtime-with-timeout)
-- [Generating jobs dynamically](#generating-jobs-dynamically)
+- [Run control](#run-control)
+  - [Selecting jobs with tags](#selecting-jobs-with-tags)
+  - [Disabling jobs](#disabling-jobs)
+  - [Running a job on a schedule](#running-a-job-on-a-schedule)
+  - [Gating jobs with `run_only_if_changed`](#gating-jobs-with-run_only_if_changed)
+  - [Throttling jobs with `cooldown_period`](#throttling-jobs-with-cooldown_period)
+  - [Throttling a job when a superset lands with `cooldown_on`](#throttling-a-job-when-a-superset-lands-with-cooldown_on)
+  - [Limiting job runtime with `timeout`](#limiting-job-runtime-with-timeout)
+  - [Generating jobs dynamically](#generating-jobs-dynamically)
 - [Requirements](#requirements)
 - [Appendix](#appendix)
   - [jj revset aliases](#jj-revset-aliases)
+- [Changelog](#changelog)
+- [License](#license)
 
 ## Use cases
 
@@ -81,6 +95,23 @@ and (with `--mode publish`) the full MR lifecycle.
 - Automating any periodic code transformation that should go through a
   review process
 
+### How it compares
+
+[Renovate](https://docs.renovatebot.com/) and
+[Dependabot](https://docs.github.com/en/code-security/dependabot) are built
+around dependency updates; repoactive runs whatever script you write, so the
+change can be anything the repository generates - a lock-file upgrade is
+just the simplest case.
+[multi-gitter](https://github.com/lindell/multi-gitter) also runs your
+script and opens the MR, but as a one-shot bulk operation across
+repositories; repoactive is built for re-running against one repository: an
+unchanged diff leaves the MR untouched, a changed one updates it, branches
+are rebased onto the moving base branch, cooldowns keep a landed change from
+immediately reopening, and jobs can stack their MRs on one another. And it
+is a plain CLI working against your local clone - no hosted service and
+nothing to install into the repository - that talks to GitHub and GitLab,
+including self-hosted instances.
+
 ## Installation
 
 `repoactive` is published on [PyPI](https://pypi.org/project/repoactive/).
@@ -125,13 +156,25 @@ needs a GitHub or GitLab API token in the environment. See
 4. **Run the job locally.** In the default `local` mode nothing is pushed
    and no MR is created - repoactive just records the diff your script
    produced on the branch `repoactive/uv-lock-upgrade` and prints a
-   `jj op restore` command to undo the run:
+   `jj op restore` command to [undo the run](#undoing-a-run):
 
    ```bash
    repoactive run
    ```
 
-5. **Publish it.** Put the API token your platform uses in the environment
+5. **Look at what it produced.** The change lives on the job's branch, so
+   your own working copy still looks untouched:
+
+   ```bash
+   repoactive recent-commits              # every repoactive commit, newest first
+   jj diff -r repoactive/uv-lock-upgrade  # the diff the script produced
+   git show repoactive/uv-lock-upgrade    # the same, through colocated git
+   ```
+
+   The appendix has [jj revset aliases](#jj-revset-aliases) for querying
+   repoactive's commits directly.
+
+6. **Publish it.** Put the API token your platform uses in the environment
    (`GITHUB_TOKEN` for GitHub.com, `GITLAB_TOKEN` for GitLab.com by
    default), fetch the latest base branch, then let repoactive push the
    branch and open - or update - the merge request:
@@ -148,9 +191,9 @@ needs a GitHub or GitLab API token in the environment. See
 ## How it works
 
 You configure one or more **jobs**, each with a script (any shell command or
-executable) that modifies the repository's working tree. `repoactive` runs
-each script, captures the resulting diff, and records the change locally.
-With `--mode publish` it also:
+executable) that modifies the repository's files. `repoactive` runs each
+script, captures the resulting diff, and records the change locally. With
+`--mode publish` it also:
 
 - opens a new merge request if one does not already exist for that job, or
 - updates the existing merge request branch if the diff has changed.
@@ -158,17 +201,18 @@ With `--mode publish` it also:
 Branches and MR descriptions are managed automatically - the only code you
 need to write is the script that produces the change.
 
-```
-[your script] → diff → repoactive → branch
-                                       ↓ (with --mode push or --mode publish)
-                                    git push → merge request
-                                                    ↑ (with --mode publish)
-                                            (create or update)
-```
-
 1. `repoactive` creates a new commit on top of the base branch or on top of
-   other repoactive managed branches.
-2. It runs the job's script against the working tree.
+   other repoactive managed branches, and checks that commit out into a
+   temporary jj workspace.
+2. It runs the job's script in that workspace, which is also the script's
+   working directory. **Your own working copy is never touched** - a run is
+   safe with uncommitted changes in your checkout, and the script sees a
+   clean tree at the base branch rather than whatever you have lying around.
+   The workspace is a full checkout, so paths relative to the repository
+   root resolve normally; [`RA_WORKSPACE_DIR`](#ra_workspace_dir) names it
+   for scripts that change directory, and
+   [`RA_CONFIG_SOURCE_DIR`](#ra_config_source_dir) reaches helper files kept
+   beside the config. The workspace is discarded when the job finishes.
 3. If the script produced a diff, it records the change. With `--mode push`
    or `--mode publish`, it pushes the branch; with `--mode publish`, it also
    creates or updates the merge request. On a re-run, if the diff matches
@@ -183,20 +227,63 @@ need to write is the script that produces the change.
    is now stale, so it is deleted; with `--mode push` or `--mode publish`,
    the deletion is pushed to the remote.
 
-> **jj commits the whole working tree.** Because `repoactive` uses jj, every
-> new file your script creates inside the working directory is added to the
-> commit unless it is git-ignored. There is no way to select which
-> working-tree changes become part of the commit - they all will. Keep
-> `.gitignore` up to date so build artifacts, caches, and other stray files
-> your script produces do not end up in the diff.
+> **jj commits the whole workspace.** Because `repoactive` uses jj, every
+> new file your script creates inside the workspace is added to the commit
+> unless it is git-ignored. There is no way to select which of the script's
+> changes become part of the commit - they all will. Keep `.gitignore` up to
+> date so build artifacts, caches, and other stray files your script
+> produces do not end up in the diff.
+
+### What a run produces
+
+For the quick-start job above, a `--mode publish` run pushes the branch
+`repoactive/uv-lock-upgrade` and opens an MR titled
+`[repoactive] build: upgrade dependencies`. Its description holds the job's
+`description` (when set), the command and its captured output in a code
+block, and - for [stacked jobs](#stacking-mrs) - links to the parent MRs
+([a real example](https://github.com/schmir/repoactive/pull/7)):
+
+```
+$ uv lock --upgrade
+Using CPython 3.14.1
+Resolved 51 packages in 4.19s
+Updated annotated-types v0.7.0 -> v0.8.0
+Updated nox v2026.4.10 -> v2026.7.11
+Updated ruff v0.15.21 -> v0.16.0
+Updated ty v0.0.58 -> v0.0.63
+```
+
+The commit carries the same output (unless `output_in_commit` is disabled)
+plus the `Repoactive-Job` trailer that
+[`recent-commits`](#repoactive-recent-commits), the
+[cooldown check](#throttling-jobs-with-cooldown_period), and the
+[unmerged-branch refresh](#keeping-unmerged-branches-current) all key on:
+
+```
+[repoactive] build: upgrade dependencies
+
+,----[ uv lock --upgrade ]
+| Using CPython 3.14.1
+| Resolved 51 packages in 4.19s
+| Updated annotated-types v0.7.0 -> v0.8.0
+| Updated nox v2026.4.10 -> v2026.7.11
+| Updated ruff v0.15.21 -> v0.16.0
+| Updated ty v0.0.58 -> v0.0.63
+`----
+
+Repoactive-Job: uv-lock-upgrade
+```
 
 ### Keeping the local clone current
 
 `repoactive` works entirely from the **local** repository view and never
-fetches from the remote on its own. Rebasing onto `trunk()`, cooldown
-throttling, and the unmerged-branch refresh all read the local `trunk()` /
-base branches, so a merge that happened on the remote is invisible until the
-local clone advances past it.
+fetches from the remote on its own. Jobs target `trunk()` unless they set a
+`base_branch` - that is jj's built-in revset for the tip of the repository's
+main branch (`main@origin`, `master@origin`, and friends), as the local
+clone last saw it. Rebasing onto `trunk()`, cooldown throttling, and the
+unmerged-branch refresh all read the local `trunk()` / base branches, so a
+merge that happened on the remote is invisible until the local clone
+advances past it.
 
 **Fetch before each run.** Run `jj git fetch` (or `git fetch --prune`) in
 the same cron job or CI pipeline that invokes `repoactive`, before it. If
@@ -206,13 +293,42 @@ because the commit that would trigger it has not reached the local base
 branch. See
 [ADR 0005](docs/adr/0005-local-repository-is-the-source-of-truth.md).
 
-## Usage
+### Undoing a run
+
+Every `run` captures the jj operation id beforehand and prints a
+`jj op restore <id>` command at the end of the run (last, since a run can
+produce a lot of output). Run it to roll the local repository - commits,
+bookmarks and colocated git refs - back to the state it was in before the
+run. It only undoes local changes: a branch already pushed or an MR already
+created by a `--mode push`/`--mode publish` run is not affected, as the hint
+panel itself points out.
+
+## Commands
 
 ```bash
 # Print the installed version and exit
 repoactive --version
 ```
 
+Every command that works against a repository accepts `--repo`/`-r` and
+`--debug`/`-d`. The commands that read configuration - `run`,
+`validate-config`, `info jobs`, and `info tags` - also accept the same
+`--config`/`-c` and `--set`/`-s` options, described in the
+[`repoactive run`](#repoactive-run) table below. `recent-commits` works from
+the repository alone and reads no configuration;
+[`dump-schema`](#repoactive-dump-schema) touches no repository at all and
+takes only `--output`.
+
+All commands exit with these status codes:
+
+| Code | Meaning                                                                                    |
+| ---- | ------------------------------------------------------------------------------------------ |
+| 0    | Success                                                                                    |
+| 1    | Failure (invalid configuration, a failed job, ...)                                         |
+| 2    | `run` only: another run holds the [per-repository lock](#one-run-at-a-time-per-repository) |
+
+### `repoactive run`
+
 ```
 repoactive run [OPTIONS] [JOBS]...
 ```
@@ -249,64 +365,7 @@ repoactive run --debug
 | `--tag TAG`                     | `-t`  | Run jobs carrying any of these tags (repeatable). With no tags/jobs the default run targets the `enabled` tag                |
 | `--debug`                       | `-d`  | Enable debug logging                                                                                                         |
 
-### Environment variables
-
-Besides the command-line options, repoactive reads a few `REPOACTIVE_*`
-environment variables that tune how it presents itself in the current
-environment (as opposed to the [configuration](#configuration), which
-describes the jobs to run). They are handled uniformly: all of them go
-through a single settings model and are validated together at startup, so a
-misconfigured variable fails immediately with a one-line error naming it
-instead of surfacing mid-run or being silently ignored. Values are
-case-insensitive.
-
-#### `REPOACTIVE_UI`
-
-`interactive` (default) or `noninteractive`.
-
-Every `run` captures the jj operation id beforehand and prints a
-`jj op restore <id>` command at the end of the run (last, since a run can
-produce a lot of output). Run it to roll the local repository - commits,
-bookmarks and colocated git refs - back to the state it was in before the
-run. It only undoes local changes: a branch already pushed or an MR already
-created by a `--mode push`/`--mode publish` run is not affected, as the hint
-panel itself points out.
-
-`noninteractive` suppresses these "how to undo" hint panels. Set it where
-nobody is at the keyboard, say an unattended CI job. This is an explicit
-switch rather than CI auto-detection, because a CI container someone has
-logged in to _is_ interactive.
-
-#### `REPOACTIVE_LOG_LEVEL`
-
-`debug`, `info`, `warning`, `error`, or `critical`; unset by default
-(logging off).
-
-Enables logging at that level without passing `--debug` on every invocation;
-an explicit `--debug` takes precedence.
-
-#### `REPOACTIVE_LOG_HANDLER`
-
-`rich` or `plain`; defaults to `rich`, or `plain` when `REPOACTIVE_UI` is
-`noninteractive`.
-
-How log records are rendered: a colorized column layout via
-[rich](https://github.com/Textualize/rich), or the stdlib's plain stream
-handler (e.g. when the output is collected by a log aggregator).
-
-#### `REPOACTIVE_PROGRESS_LINES`
-
-An integer (default: `8`).
-
-While a job's command runs in an interactive terminal, repoactive shows a
-live, scrolling block of its most recent output lines. The block stays on
-screen once the command finishes, with the job's status line printed below
-it. `REPOACTIVE_PROGRESS_LINES` sets how many lines that live tail shows;
-`0` or less disables the live block entirely. When output is not a terminal
-(piped or in CI) the block is disabled and the command's output is left
-untouched.
-
-## Inspecting repoactive commits
+### `repoactive recent-commits`
 
 ```
 repoactive recent-commits [OPTIONS] [JOBS]...
@@ -339,7 +398,7 @@ repoactive recent-commits --status unmerged
 | `--status [all\|merged\|unmerged]` | `-s`  | Filter by merge status into trunk (default: `all`)     |
 | `--debug`                          | `-d`  | Enable debug logging                                   |
 
-## Validating configuration
+### `repoactive validate-config`
 
 ```
 repoactive validate-config [OPTIONS]
@@ -366,10 +425,29 @@ code 1.
 Validation checks include unknown keys, missing required fields, invalid
 `depends_on` references, and circular job dependencies.
 
-The command accepts the same `--config`, `--set`, `--repo`, and `--debug`
-options as [`repoactive run`](#usage).
+### `repoactive dump-schema`
+
+```
+repoactive dump-schema --output PATH
+```
 
-## Listing jobs
+Write the JSON schema of the TOML config to a file. Use it to pin the schema
+your editor validates against to the version you have installed, rather than
+the published one:
+
+```bash
+repoactive dump-schema -o config-schema.json
+```
+
+See [Editor support](#editor-support) for wiring it up. Unlike the other
+commands this one only reads the installed models, so it takes neither
+`--repo` nor `--debug`.
+
+| Option          | Short | Description                            |
+| --------------- | ----- | -------------------------------------- |
+| `--output PATH` | `-o`  | File to write the schema to (required) |
+
+### `repoactive info jobs`
 
 ```
 repoactive info jobs [OPTIONS]
@@ -393,10 +471,7 @@ build           Build the project   enabled
     └── deploy  Deploy to staging   nightly, risky
 ```
 
-The command accepts the same `--config`, `--set`, `--repo`, and `--debug`
-options as [`repoactive run`](#usage).
-
-## Listing tags
+### `repoactive info tags`
 
 ```
 repoactive info tags [OPTIONS]
@@ -428,8 +503,54 @@ nightly:
   benchmark            Run nightly benchmarks  nightly
 ```
 
-The command accepts the same `--config`, `--set`, `--repo`, and `--debug`
-options as [`repoactive run`](#usage).
+### Environment variables
+
+Besides the command-line options, repoactive reads a few `REPOACTIVE_*`
+environment variables that tune how it presents itself in the current
+environment (as opposed to the [configuration](#configuration), which
+describes the jobs to run). They are handled uniformly: all of them go
+through a single settings model and are validated together at startup, so a
+misconfigured variable fails immediately with a one-line error naming it
+instead of surfacing mid-run or being silently ignored. Values are
+case-insensitive.
+
+#### `REPOACTIVE_UI`
+
+`interactive` (default) or `noninteractive`.
+
+`noninteractive` suppresses the ["how to undo" hint panels](#undoing-a-run)
+printed after each run. Set it where nobody is at the keyboard, say an
+unattended CI job. This is an explicit switch rather than CI auto-detection,
+because a CI container someone has logged in to _is_ interactive.
+
+#### `REPOACTIVE_LOG_LEVEL`
+
+`debug`, `info`, `warning`, `error`, or `critical`; unset by default
+(logging off).
+
+Enables logging at that level without passing `--debug` on every invocation;
+an explicit `--debug` takes precedence.
+
+#### `REPOACTIVE_LOG_HANDLER`
+
+`rich` or `plain`; defaults to `rich`, or `plain` when `REPOACTIVE_UI` is
+`noninteractive`.
+
+How log records are rendered: a colorized column layout via
+[rich](https://github.com/Textualize/rich), or the stdlib's plain stream
+handler (e.g. when the output is collected by a log aggregator).
+
+#### `REPOACTIVE_PROGRESS_LINES`
+
+An integer (default: `8`).
+
+While a job's command runs in an interactive terminal, repoactive shows a
+live, scrolling block of its most recent output lines. The block stays on
+screen once the command finishes, with the job's status line printed below
+it. `REPOACTIVE_PROGRESS_LINES` sets how many lines that live tail shows;
+`0` or less disables the live block entirely. When output is not a terminal
+(piped or in CI) the block is disabled and the command's output is left
+untouched.
 
 ## Configuration
 
@@ -450,16 +571,37 @@ Every key in `[job-defaults]` supplies the default for the matching per-job
 key; any job may override it by setting the same key in its `[job.<name>]`
 block.
 
+### Editor support
+
+`repoactive` publishes a JSON schema for the config format, so an editor
+with TOML schema support (Even Better TOML in VS Code, Taplo, the JetBrains
+TOML plugin) can complete field names, show what each one does, and flag
+typos as you type - useful given how many optional keys a job accepts. Point
+the `"$schema"` key at the published schema:
+
+```toml
+"$schema" = "https://raw.githubusercontent.com/schmir/repoactive/refs/heads/main/config-schema.json"
+
+[job.uv-lock-upgrade]
+command = "uv lock --upgrade"
+title = "build: upgrade dependencies"
+```
+
+`"$schema"` is part of the config format: `repoactive` accepts it and
+ignores it. The URL above tracks `main`; to validate against the version you
+actually have installed, write the schema out with
+[`repoactive dump-schema`](#repoactive-dump-schema) and point `"$schema"` at
+that file instead.
+
 ### `[job-defaults]`
 
-**MR/PR options:**
+**MR options:**
 
-- **`labels`** (default: `[]`) - Labels applied to every MR/PR. Per-job
+- **`labels`** (default: `[]`) - Labels applied to every MR. Per-job
   `labels` are merged with, not replaced by, this list.
 - **`auto_merge`** (default: `false`) - When `true`, enable auto-merge on
-  every MR/PR so it merges automatically once its pipeline passes. On
-  GitHub, the repository must have "Allow auto-merge" enabled in its
-  settings.
+  every MR so it merges automatically once its pipeline passes. On GitHub,
+  the repository must have "Allow auto-merge" enabled in its settings.
 - **`required_approvals`** (default: none) - Minimum number of approvals
   required before the MR can be merged. **GitLab only** - this sets the
   per-MR approval requirement. GitHub has no per-PR equivalent (required
@@ -474,12 +616,13 @@ block.
   no job is named after your base branch (e.g. a job named `main`) - the two
   branches would otherwise collide.
 - **`mr_title_prefix`** (default: `"[repoactive] "`) - Prefix prepended to
-  every MR/PR title. Set to `""` to disable.
+  every MR title. Set to `""` to disable.
 - **`commit_title_prefix`** (default: `"[repoactive] "`) - Prefix prepended
   to every commit title. Set to `""` to disable.
-- **`base_branch`** (default: repo default) - Target branch for all jobs
-  that do not set their own. May also be a jj revset expression such as
-  `trunk()`, `root()`, or a user-defined revset alias.
+- **`base_branch`** (default: `trunk()`, the repository's main branch as the
+  local clone last saw it) - Target branch for all jobs that do not set
+  their own. May also be a jj revset expression such as `trunk()`, `root()`,
+  or a user-defined revset alias.
 
 **Run control:**
 
@@ -511,37 +654,38 @@ underscores.
 
 **Required:**
 
-- **`command`** - Shell command (or executable path) run in the repository
-  working directory. A non-zero exit is a failure.
-- **`title`** - MR/PR title (also the commit subject, after
+- **`command`** - Shell command (or executable path) run in the job's
+  temporary workspace, not in your checkout (see
+  [How it works](#how-it-works)). A non-zero exit is a failure.
+- **`title`** - MR title (also the commit subject, after
   `commit_title_prefix`).
 
-**MR/PR options:**
+**MR options:**
 
-- **`description`** - Body text of the MR/PR.
-- **`labels`** (default: `[]`) - Extra labels for this job's MR/PR, merged
-  with `job-defaults.labels`.
-- **`draft`** (default: `false`) - Open the MR/PR as a draft. On GitHub,
-  draft state cannot be changed after creation.
-- **`create_mr`** (default: `true`) - Whether to create an MR/PR: `true`
+- **`description`** - Body text of the MR.
+- **`labels`** (default: `[]`) - Extra labels for this job's MR, merged with
+  `job-defaults.labels`.
+- **`draft`** (default: `false`) - Open the MR as a draft. On GitHub, draft
+  state cannot be changed after creation.
+- **`create_mr`** (default: `true`) - Whether to create an MR: `true`
   (always), `false` (push the branch but skip the MR), or
   `"unless-superseded"` (skip when a dependent's MR from the same run
   already contains this job's changes - see [Stacking MRs](#stacking-mrs)).
 - **`auto_merge`** (default: inherited from `job-defaults`) - When `true`,
-  enable auto-merge on this job's MR/PR.
+  enable auto-merge on this job's MR.
 - **`required_approvals`** (default: inherited from `job-defaults`) -
   Minimum number of approvals required before this job's MR can be merged.
   GitLab only; see `job-defaults.required_approvals`.
 
 **Branch and commit options:**
 
-- **`base_branch`** (default: inherited) - Target branch for this job's
-  MR/PR. May also be a jj revset expression such as `trunk()`, `root()`, or
-  a user-defined revset alias.
+- **`base_branch`** (default: inherited, ultimately `trunk()`) - Target
+  branch for this job's MR. May also be a jj revset expression such as
+  `trunk()`, `root()`, or a user-defined revset alias.
 - **`branch_prefix`** (default: inherited) - Override the branch-name prefix
   for this job only.
-- **`mr_title_prefix`** (default: inherited) - Override the MR/PR title
-  prefix for this job only.
+- **`mr_title_prefix`** (default: inherited) - Override the MR title prefix
+  for this job only.
 - **`commit_title_prefix`** (default: inherited) - Override the commit title
   prefix for this job only.
 - **`output_in_commit`** (default: `true`) - Append the job's command and
@@ -599,14 +743,13 @@ Because a dependent's MR already contains its dependencies' changes, a
 dependency chain normally opens one MR per job that produced a diff. Setting
 `create_mr = "unless-superseded"` on the earlier jobs collapses that: such a
 job skips its MR when a dependent job produced an MR in the same run, so the
-chain yields a single MR on the topmost job that actually changed something
-
-- falling back to the job below it when the jobs above came up empty. The
-  branch is still pushed either way. Only the current run counts: a
-  dependent that is empty, failed, on cooldown, or not selected does not
-  suppress anything. See
-  [ADR 0009](docs/adr/0009-unless-superseded-mr-creation.md) for details and
-  limitations.
+chain yields a single MR on the topmost job that actually changed
+something - falling back to the job below it when the jobs above came up
+empty. The branch is still pushed either way. Only the current run counts: a
+dependent that is empty, failed, on cooldown, or not selected does not
+suppress anything. See
+[ADR 0009](docs/adr/0009-unless-superseded-mr-creation.md) for details and
+limitations.
 
 ### Example
 
@@ -718,9 +861,8 @@ title = "run the shared check script for this job"
 
 #### `RA_WORKSPACE_DIR`
 
-A job's command runs in a temporary jj workspace, which is also its working
-directory. `RA_WORKSPACE_DIR` names that directory explicitly, so a command
-that changes directory can still find its way back:
+`RA_WORKSPACE_DIR` names the job's [temporary workspace](#how-it-works)
+explicitly, so a command that changes directory can still find its way back:
 
 ```toml
 [job.build]
@@ -882,7 +1024,13 @@ job across several flags - put a new job's required fields in one expression
 unknown key or malformed value is reported with the offending `--set`
 argument named.
 
-## Selecting jobs with tags
+## Run control
+
+The sections below cover the run-control options from the
+[configuration reference](#jobname) in detail: which jobs a run selects, how
+to schedule and throttle them, and how to generate jobs dynamically.
+
+### Selecting jobs with tags
 
 Which jobs a `repoactive run` touches is decided by **tags**. Every job has
 a set of tags, with a smart default:
@@ -917,8 +1065,8 @@ mistyped one.
 Because assigning a tag removes the implicit `enabled` tag, **tags are
 load-bearing, not free-form labels**: tagging a job takes it out of the bare
 `repoactive run`. If you want a job to stay in the default run _and_ belong
-to a group, list both: `tags = ["enabled", "weekly"]`. (For MR/PR labels,
-use `labels` - a separate concept.)
+to a group, list both: `tags = ["enabled", "weekly"]`. (For MR labels, use
+`labels` - a separate concept.)
 
 Tag selection is _explicit_ selection, so - like naming a job - it ignores
 the `enabled`/`disabled` defaults and force-includes dependencies. The bare
@@ -926,7 +1074,7 @@ the `enabled`/`disabled` defaults and force-includes dependencies. The bare
 itself selected is dropped
 (`==> [name] skipped (dependency not in default run)`).
 
-### Keeping unmerged branches current
+#### Keeping unmerged branches current
 
 The bare `repoactive run` additionally refreshes **any job that currently
 has an unmerged branch**, regardless of its tags. A branch is "unmerged"
@@ -945,7 +1093,7 @@ don't have to wait for the next weekly run to resolve a conflict with
 disabled job's unmerged branch is refreshed too: it was most likely created
 by an explicit run, and letting it drift out of date helps no one.)
 
-## Disabling jobs
+### Disabling jobs
 
 Set `disabled = true` on a `[job.<name>]` to keep it in the config but leave
 it out of normal runs; it is exactly sugar for `tags = ["disabled"]` (so the
@@ -966,7 +1114,7 @@ disabled = true
   `repoactive run --tag disabled`, which runs everything currently turned
   off.
 
-## Running a job on a schedule
+### Running a job on a schedule
 
 `repoactive` is not a daemon and has no built-in scheduler - the cadence of
 a job is whatever cadence you invoke it with. To run a job on a fixed
@@ -994,7 +1142,7 @@ inferring a schedule from `repoactive`'s own history: real cron is stateful
 and excludes the other days, whereas `repoactive` only ever sees what has
 _landed_ (see `cooldown_period` below).
 
-### One run at a time per repository
+#### One run at a time per repository
 
 A `repoactive run` takes an exclusive per-repository lock for its duration,
 so two runs against the same repository never interleave (and corrupt each
@@ -1012,7 +1160,7 @@ The lock is an advisory `flock` on `.jj/repoactive.lock`; the OS releases it
 automatically if a run is killed, so a crashed run never leaves the
 repository locked.
 
-## Gating jobs with `run_only_if_changed`
+### Gating jobs with `run_only_if_changed`
 
 `run_only_if_changed` lets a job declare that it should only run when
 specific upstream jobs actually produced a diff. If none of the named jobs
@@ -1046,12 +1194,15 @@ Key behaviour:
 - **Dependents are unaffected.** A skipped job records a no-op result (like
   a job on cooldown), so any job that `depends_on` it still runs on the base
   branch - the skip does not cascade.
-- **No ordering constraint.** Names in `run_only_if_changed` do not have to
-  appear in `depends_on`. Any job that runs before this one in topological
-  order can be listed; in practice most usages name a direct dependency, as
-  in the example above.
+- **Watched jobs must run first.** A watched job does not have to appear in
+  `depends_on`, but it must be ordered before this one so its result is
+  known when the gate is evaluated - either as a (direct or transitive)
+  `depends_on` ancestor, or simply earlier in the config file. Listing a job
+  that runs later (or alongside, with no `depends_on` edge) is rejected at
+  config load. In practice most usages name a direct dependency, as in the
+  example above.
 
-## Throttling jobs with `cooldown_period`
+### Throttling jobs with `cooldown_period`
 
 Every commit `repoactive` creates carries a `Repoactive-Job: <name>` trailer
 identifying the job that produced it. When a job sets `cooldown_period`,
@@ -1074,7 +1225,14 @@ runs: `repoactive` does not fetch, so a clone that has not pulled the merge
 will not see the cooldown and will re-run the job. See
 [Keeping the local clone current](#keeping-the-local-clone-current).
 
-## Throttling a job when a superset lands with `cooldown_on`
+Naming a job explicitly on the command line (`repoactive run <name>`)
+overrides its cooldown: the job runs now regardless of when it last landed,
+as if its `cooldown_period` were unset. The cooldown only ever gates the
+_default_ run and `--tag` selection, the automated paths it exists to
+throttle. Jobs pulled in only as dependencies of a named job are not
+themselves named, so they keep their own cooldowns.
+
+### Throttling a job when a superset lands with `cooldown_on`
 
 Some jobs are strict supersets of others. `uv lock --upgrade` refreshes
 every dependency group, so its diff already contains everything
@@ -1114,7 +1272,7 @@ has an open, unmerged branch is always refreshed regardless of cooldown (see
 its branch is rebased and, if the change is now redundant, self-closes on
 the next run.
 
-## Limiting job runtime with `timeout`
+### Limiting job runtime with `timeout`
 
 A job's `command` can hang or run away. Setting `timeout` caps how long the
 command may run; when the limit is reached `repoactive` kills the command's
@@ -1144,7 +1302,7 @@ title = "chore: fix lint"
 timeout = "0s"        # opt out of the timeout entirely
 ```
 
-## Generating jobs dynamically
+### Generating jobs dynamically
 
 Sometimes the useful set of jobs depends on the repository's contents - one
 job per package in a monorepo, one per entry in a manifest - and you don't
@@ -1175,7 +1333,7 @@ title = "build: upgrade pkg-a"
 
 Fragments may only contain `[job.<name>]` tables; anything else (e.g.
 `[job-defaults]`) fails the generator. To set defaults for the emitted jobs,
-set them on the generator itself — they are inherited (see below).
+set them on the generator itself - they are inherited (see below).
 
 Key points:
 
@@ -1184,10 +1342,10 @@ Key points:
   it emits.
 - **Inheritance with override.** Each emitted job inherits the generator's
   `tags`, `cooldown_period`, `base_branch`, `timeout`, `labels`,
-  `branch_prefix`/title prefixes, `draft` and `create_mr` unless its own
-  fragment sets them. It also defaults to `depends_on = ["<generator>"]`
-  (i.e. built flat on `trunk()`); override `depends_on` to a sibling emitted
-  job to stack them into an MR chain.
+  `branch_prefix`/title prefixes, `draft`, `create_mr` and `auto_merge`
+  unless its own fragment sets them. It also defaults to
+  `depends_on = ["<generator>"]` (i.e. built flat on `trunk()`); override
+  `depends_on` to a sibling emitted job to stack them into an MR chain.
 - **Stable names are your responsibility.** Cooldown, branches and the
   `Repoactive-Job` trailer all key on a job's `name`, so derive emitted
   names deterministically from repository state (`upgrade-pkg-a`, not a
@@ -1218,17 +1376,17 @@ design.
 
 ## Requirements
 
-- Python 3.11 or later
+- A Unix-like operating system (Linux, macOS, BSD). `repoactive` uses POSIX
+  process groups to enforce [`timeout`](#limiting-job-runtime-with-timeout)
+  and `flock` for the
+  [per-repository run lock](#one-run-at-a-time-per-repository); Windows is
+  not supported.
+- Python 3.12 or later
 - [jj (Jujutsu)](https://github.com/jj-vcs/jj) - `repoactive` uses jj to
   manage branches and commits in the target repository
 - A configured jj user name and email - jj records them as the commit
-  author. Set them once with:
-
-  ```bash
-  jj config set --user user.name "My Name"
-  jj config set --user user.email "me@example.com"
-  ```
-
+  author. Set them once with the `jj config set` commands shown in
+  [Quick start](#quick-start) step 1.
 - A GitLab or GitHub API token exposed via the environment variable named in
   `platform.token_env` (default: `GITHUB_TOKEN` for GitHub.com,
   `GITLAB_TOKEN` for GitLab.com)
@@ -1256,3 +1414,12 @@ jj log -r 'repoactive_unmerged()'
 jj log -r 'repoactive() & committer_date(after:"2025-01-01")'
 jj log -r 'repoactive() & description(regex:"(?m)^Repoactive-Job: uv-lock-upgrade$")'
 ```
+
+## Changelog
+
+User-facing changes are recorded in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+`repoactive` is licensed under the
+[GNU General Public License v3.0 or later](LICENSE).