asljs-rq-cli 0.0.0-stage → 0.1.2

package/dist/config.d.ts

@@ -0,0 +1,63 @@
+import { type Folders, Io, type Setting } from 'asljs-rq';
+/**
+ * The environment variables `rq` reads.
+ */
+export declare const ENVIRONMENT_VARIABLES: readonly ["RQ_AI_COMMAND", "RQ_LOG_LEVEL", "RQ_LOG_FILE", "RQ_LOG_FORMAT"];
+/**
+ * The configuration `rq` runs with, as `rq config` prints it.
+ */
+export interface Configuration {
+    version: string;
+    workingDir: string;
+    /**
+     * The `rq.json` in use; `null` when there is none.
+     */
+    configFile: string | null;
+    requirementsDir: Setting;
+    documentsDir: Setting;
+    /**
+     * The command `rq.json` runs on the markdown files a command wrote; `null`
+     * when there is none.
+     */
+    markdownPostProcessing: string | null;
+    /**
+     * The agent of instruction steps and `rq coverage` when `--ai` names none:
+     * `RQ_AI_COMMAND`, or the first installed of `agents`, detected when a
+     * command needs it.
+     */
+    agent: {
+        command: string | null;
+        agents: string[];
+    };
+    log: {
+        level: LogSetting;
+        file: LogSetting;
+        format: LogSetting;
+    };
+    /**
+     * Each variable `rq` reads, and its value; `null` when it is not set.
+     */
+    environment: Record<string, string | null>;
+}
+/**
+ * A log setting and where it comes from: its option, its `RQ_LOG_`
+ * variable, or the default.
+ */
+export interface LogSetting {
+    value: string;
+    source: 'option' | 'environment' | 'default';
+}
+/**
+ * Prints the configuration: the folders and where they come from, the
+ * `rq.json` in use, the agent, the log settings, and the environment
+ * variables `rq` reads. `args` is the command line, for the log options.
+ */
+export declare function execConfig(io: Io, options: {
+    folders: Folders;
+    args: readonly string[];
+    json?: boolean;
+}): Promise<number>;
+/**
+ * The configuration `rq` runs with in the working folder of `io`.
+ */
+export declare function readConfiguration(io: Io, folders: Folders, args: readonly string[]): Promise<Configuration>;

package/dist/config.js

@@ -0,0 +1,78 @@
+import { AI_AGENTS } from 'asljs-agents';
+import { readLoggerOptions } from 'asljs-logging';
+import { findConfig } from 'asljs-mdcli';
+import { CONFIG_FILE } from 'asljs-rq';
+import { createRequire } from 'node:module';
+/**
+ * The environment variables `rq` reads.
+ */
+export const ENVIRONMENT_VARIABLES = ['RQ_AI_COMMAND',
+    'RQ_LOG_LEVEL',
+    'RQ_LOG_FILE',
+    'RQ_LOG_FORMAT'];
+/**
+ * Prints the configuration: the folders and where they come from, the
+ * `rq.json` in use, the agent, the log settings, and the environment
+ * variables `rq` reads. `args` is the command line, for the log options.
+ */
+export async function execConfig(io, options) {
+    const configuration = await readConfiguration(io, options.folders, options.args);
+    io.stdout.write(options.json
+        ? `${JSON.stringify(configuration, null, 2)}\n`
+        : describe(configuration));
+    return 0;
+}
+/**
+ * The configuration `rq` runs with in the working folder of `io`.
+ */
+export async function readConfiguration(io, folders, args) {
+    const found = await findConfig(io.cwd, CONFIG_FILE);
+    const environment = Object.fromEntries(ENVIRONMENT_VARIABLES.map(name => [name,
+        io.env[name] || null]));
+    const overrides = readLoggerOptions(args);
+    const pick = (option, variable, fallback) => option !== undefined
+        ? { value: option,
+            source: 'option' }
+        : environment[variable] !== null
+            ? { value: environment[variable],
+                source: 'environment' }
+            : { value: fallback,
+                source: 'default' };
+    const file = pick(overrides.file, 'RQ_LOG_FILE', 'stdout');
+    return { version: packageVersion(),
+        workingDir: io.cwd,
+        configFile: folders.configFile,
+        requirementsDir: folders.requirementsDir,
+        documentsDir: folders.documentsDir,
+        markdownPostProcessing: found?.config.markdownPostProcessing?.trim()
+            || null,
+        agent: { command: environment.RQ_AI_COMMAND,
+            agents: [...AI_AGENTS] },
+        log: { level: pick(overrides.level, 'RQ_LOG_LEVEL', file.source === 'default'
+                ? 'silent'
+                : 'information'),
+            file,
+            format: pick(overrides.format, 'RQ_LOG_FORMAT', 'auto') },
+        environment };
+}
+function describe(configuration) {
+    const setting = (value) => `${value.value} (${value.source})`;
+    const lines = [`version: ${configuration.version}`,
+        `workingDir: ${configuration.workingDir}`,
+        `configFile: ${configuration.configFile ?? '(none)'}`,
+        `requirementsDir: ${setting(configuration.requirementsDir)}`,
+        `documentsDir: ${setting(configuration.documentsDir)}`,
+        `markdownPostProcessing: ${configuration.markdownPostProcessing ?? '(none)'}`,
+        `agent: ${configuration.agent.command === null
+            ? `the first installed of ${configuration.agent.agents.join(', ')}, detected when needed`
+            : `${configuration.agent.command} (RQ_AI_COMMAND)`}`,
+        `logLevel: ${setting(configuration.log.level)}`,
+        `logFile: ${setting(configuration.log.file)}`,
+        `logFormat: ${setting(configuration.log.format)}`,
+        'environment:',
+        ...Object.entries(configuration.environment).map(([name, value]) => `  ${name}=${value ?? ''}`)];
+    return `${lines.join('\n')}\n`;
+}
+function packageVersion() {
+    return createRequire(import.meta.url)('../package.json').version;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { createCli, runCli, type CliState } from './cli.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { createCli, runCli } from './cli.js';

package/docs/Changing the graph.md

@@ -0,0 +1,108 @@
+# Changing the graph
+
+Commands that change the structure of the graph, so that no one edits links or
+results by hand. Each prints the files it created, changed or removed.
+
+Every command takes `--working-dir <folder>`, `--requirements-dir <folder>` and
+`--documents-dir <folder>`; see [Working folder][WF] and
+[Requirements and documents folders][FD] for how paths, ids and `.md` names are
+resolved. The scope - every `.md` document of the documents folder - is where
+the next free id, the links to rewrite or remove, and another parent of a
+requirement being linked are looked for.
+
+## rq add requirement
+
+```text
+rq add requirement <parent> <name> [--statement <text>] [--path <file>]
+                   [--working-dir <folder>]
+```
+
+Creates `R<n> <name>.md` in the parent's folder, with `<n>` the highest `R`
+number in the scope plus one, a level 1 heading equal to the file name, and the
+statement. Adds a link to it to the parent's `## Implementation` list.
+
+- `<parent>` must be a requirement; `<name>` must not contain `/` or `\`.
+- `--path` gives the new file's path instead; its name must still start with
+  `R<n>` (`T<n>` for a test), and its heading is its file name.
+- An existing file is an error.
+
+## rq add test
+
+```text
+rq add test <parent> <name> [--description <text>] [--step <command>]...
+                [--path <file>] [--working-dir <folder>]
+```
+
+Like `add requirement`, but creates `tests/T<n> <name>.md` next to the parent,
+with the description and a `## Steps` section holding one `shell` step, `###
+Step <n>`, per `--step`. Write other kinds of steps by editing the text; see
+[Requirements][RM].
+
+## rq link
+
+```text
+rq link <parent> <child> [--working-dir <folder>]
+```
+
+Adds a link to an existing requirement or test to the parent's `##
+Implementation` list. Refused when the parent is a test, when it already links
+to the child, when the child leads back to the parent, or when the child is a
+requirement another requirement of the scope already links to: a requirement has
+one parent, a test may have several.
+
+## rq unlink
+
+```text
+rq unlink <parent> <child> [--working-dir <folder>]
+```
+
+Removes every link from the parent to the child: an `## Implementation` item
+holding one goes with it, a link definition goes with its line, and any other
+link, or reference to a removed definition, is replaced by its text. An error
+when the parent does not link to the child.
+
+## rq remove
+
+```text
+rq remove <file> [--recursive] [--working-dir <folder>]
+```
+
+Deletes a requirement or a test, and removes the links to it from every document
+of the scope, as `unlink` does. A requirement that links to anything is refused
+unless `--recursive` is given; then every document only removed documents link
+to is removed too, down the graph.
+
+## rq move
+
+```text
+rq move <file> <destination> [--working-dir <folder>]
+```
+
+Moves or renames a requirement or a test. `<destination>` is the new path, or an
+existing folder to move it into; an existing file is an error, and so is a name
+of another kind, e.g. an `R` file renamed to `T` or `notes.md`.
+
+- Links to it from every document of the scope point at the new path, keeping
+  their `#` fragments.
+- Its own relative links, including images, are rewritten for its new folder.
+- When its heading is its old file name, the heading becomes the new file name,
+  and so does the text of `## Implementation` links that was the old heading.
+
+## rq log
+
+```text
+rq log <test> --result PASS|FAIL [--note <text>] [--time <time>] [--working-dir <folder>]
+```
+
+Records a result established another way: writes an execution file, `.rq/E<n>
+<test>.md` in the working folder, with the one test, its result and the note, in
+the format [`rq test`][TS] writes. `<test>` is a test file or id, e.g. `T12`.
+`--time` is ISO 8601, now by default; the note is written on one line. The test
+itself is not changed, except that the results are then recalculated and written
+as [`rq test`][TS] does, with `--time` as the `Updated` of the test and of every
+requirement recalculated above it.
+
+[TS]: <rq test.md>
+[RM]: ../../rq/docs/Requirements.md
+[FD]: ../../rq/docs/Requirements.md#requirements-and-documents-folders
+[WF]: ../../rq/docs/Requirements.md#working-folder

package/docs/Querying the graph.md

@@ -0,0 +1,71 @@
+# Querying the graph
+
+Commands that print the structure of the graph without changing anything. Paths
+are printed relative to the working folder, with `/` separators.
+
+The text output has one line per document: its kind - `requirement`, `test`,
+`other` for an `## Implementation` link to a document that is neither, or
+`missing` for one to no file - its path, and for a requirement or test its
+status, `PASS`, `FAIL` or `NOT RUN`, as its `## Status` records it, then for a
+requirement its coverage, `COMPLETE` or `INCOMPLETE`, when it was checked; see
+[Requirements][RM]. The commands take only requirement and test files.
+
+```text
+requirement  requirements/R1 Export.md  FAIL
+test         requirements/tests/T1 PDF export.md  PASS
+```
+
+With `--json` the same documents are printed as an array of `{ path, kind,
+title, result, coverage }`; `result` is `null` for any other document, and
+`coverage` for one that is not a requirement or was never checked.
+
+Every command takes `--working-dir <folder>`, `--requirements-dir <folder>` and
+`--documents-dir <folder>`, and a requirement or test as a path, `.md` name or
+id; see [Requirements and documents folders][FD]. The results are read from the
+working folder's `.rq` folder.
+
+## rq list
+
+```text
+rq list [path] [--working-dir <folder>] [--json]
+```
+
+Every document of the graph of a requirement file or folder, the requirements
+folder by default, in breadth-first order from the roots. Structure errors are
+written to standard error.
+
+## rq links
+
+```text
+rq links <requirement> [--working-dir <folder>] [--json]
+```
+
+What a requirement's `## Implementation` list links to.
+
+## rq backlinks
+
+```text
+rq backlinks <file> [--working-dir <folder>] [--json]
+```
+
+The requirements that link to a requirement or a test, looked for in every `.md`
+document of the documents folder. Links in a test are not edges, so a test is
+never a backlink.
+
+## rq tojson
+
+```text
+rq tojson [path] [--working-dir <folder>]
+```
+
+The graph of a requirement file or folder, the requirements folder by default,
+as JSON:
+
+- `roots` - the paths of the roots, empty when a folder has none;
+- `errors` - the structure errors;
+- `nodes` - every document, from the roots down, with `path`, `kind`, `title`,
+  `body` (the text between the heading and the first section), `links` (the
+  paths its `## Implementation` links to), `steps`, `result` and `coverage`.
+
+[RM]: ../../rq/docs/Requirements.md
+[FD]: ../../rq/docs/Requirements.md#requirements-and-documents-folders

package/docs/rq agents.md

@@ -0,0 +1,29 @@
+# rq agents
+
+Prints instructions for an AI agent that edits the files of a requirements
+folder directly, without `rq`: the formats of requirements, tests, `## Status`
+sections and execution files, and the rules every change keeps, so that the
+requirements stay one valid graph.
+
+```text
+rq agents [--working-dir <folder>] [--requirements-dir <folder>]
+          [--documents-dir <folder>]
+```
+
+It takes the folder options of every command, and they are checked as for every
+command, but the instructions do not depend on them.
+
+The instructions are made, when the command runs, from [Requirement files][RF],
+the page of the package that is the only description of the formats: its text,
+with every link replaced by its text so that it stands alone. They do not
+mention `rq`; they are about the files, not about the commands.
+
+Use it where `rq` is neither installed for the agent nor served to it by
+[rq-mcp][MC], e.g. to give Copilot or Claude the rules in an instructions file:
+
+```bash
+npx rq agents > .github/instructions/requirements.instructions.md
+```
+
+[MC]: ../../rq-mcp/docs/rq-mcp.md
+[RF]: <../../rq/docs/Requirement files.md>

package/docs/rq check.md

@@ -0,0 +1,32 @@
+# rq check
+
+Checks the structure of the graph and of each document without running anything.
+It exits with a non-zero code when it finds a problem.
+
+```text
+rq check [path] [--working-dir <folder>]
+```
+
+`[path]` is a requirement file, a folder, a `.md` name or an id, the
+requirements folder by default; see [Requirements][RM] for the problems it
+reports. `--working-dir`, `--requirements-dir` and `--documents-dir` set the
+folders that paths, names and ids resolve in; see [Working folder][WF] and
+[Requirements and documents folders][FD].
+
+```text
+Error  R1 Export.md: the link to R3.md points at no file.
+Error  tests/T2 CSV export.md: has a Log section; results are kept in .rq/E<n> files.
+```
+
+Without problems it prints a count:
+
+```text
+OK  2 requirements, 2 tests
+```
+
+Run it after editing documents by hand, and before `rq test`, which runs the
+steps.
+
+[RM]: ../../rq/docs/Requirements.md
+[FD]: ../../rq/docs/Requirements.md#requirements-and-documents-folders
+[WF]: ../../rq/docs/Requirements.md#working-folder

package/docs/rq config.md

@@ -0,0 +1,60 @@
+# rq config
+
+Prints the configuration `rq` runs with in the working folder, with the current
+values and where each comes from. It reads and writes nothing else.
+
+```text
+rq config [--json] [--working-dir <folder>] [--requirements-dir <folder>]
+          [--documents-dir <folder>]
+```
+
+```text
+version: 0.1.1
+workingDir: C:\projects\project1
+configFile: C:\projects\project1\rq.json
+requirementsDir: C:\projects\project1\requirements (rq.json)
+documentsDir: C:\projects\project1 (option)
+markdownPostProcessing: npx toolkit flint
+agent: the first installed of claude, copilot, detected when needed
+logLevel: silent (default)
+logFile: stdout (default)
+logFormat: auto (default)
+environment:
+  RQ_AI_COMMAND=
+  RQ_LOG_LEVEL=
+  RQ_LOG_FILE=
+  RQ_LOG_FORMAT=
+```
+
+- `version` - the version of `rq`.
+- `workingDir` - the [working folder][WF], whose `.rq` folder holds the results.
+- `configFile` - the `rq.json` in use, the nearest one from the working folder
+  up; `(none)` when there is none. See [Configuration][CF].
+- `requirementsDir`, `documentsDir` - the
+  [requirements and documents folders][FD], and where each comes from: `option`,
+  `rq.json` or `default`.
+- `markdownPostProcessing` - the command of `rq.json`; `(none)` when there is
+  none.
+- `agent` - the agent of instruction steps and `rq coverage` when `--ai` names
+  none: `RQ_AI_COMMAND`, or the first installed of `claude` and `copilot`. `rq
+  config` does not look for an installed agent; that happens when a command
+  needs one.
+- `logLevel`, `logFile`, `logFormat` - the log settings, and where each comes
+  from: `option` (`--loglevel`, `--logfile`, `--logformat`), `environment`
+  (`RQ_LOG_LEVEL`, `RQ_LOG_FILE`, `RQ_LOG_FORMAT`) or `default`. See the
+  repository's logging rules.
+- `environment` - each variable `rq` reads, and its value, empty when it is not
+  set.
+
+## Options
+
+- `--json` - print the same as a JSON object, with `null` for a missing value
+  and `{ value, source }` for each folder and log setting.
+- `--working-dir <folder>`, `--requirements-dir <folder>`, `--documents-dir
+  <folder>` - as for every command; `rq config` shows what they resolve to. A
+  requirements folder outside the documents folder is an error, here as in every
+  command.
+
+[CF]: ../../rq/docs/Requirements.md#configuration
+[FD]: ../../rq/docs/Requirements.md#requirements-and-documents-folders
+[WF]: ../../rq/docs/Requirements.md#working-folder

package/docs/rq coverage.md

@@ -0,0 +1,80 @@
+# rq coverage
+
+Asks an AI agent, for each requirement the targets select, whether its
+sub-requirements and its own tests together provide sufficient functional
+coverage, writes the verdict to the `- Coverage:` item of its `## Status`
+section, and the agent's analysis to its `## Coverage` section. It exits with a
+non-zero code when a checked requirement is incomplete or the graph has a
+structure error.
+
+```text
+rq coverage <target>... [--recurse] [--working-dir <folder>]
+            [--ai[=<agent>][:<model>]]
+```
+
+The targets are as for [`rq test`][TS]: ids, `.md` names, requirement files or
+folders. A requirement target checks itself, and with `--recurse` every
+requirement below it; a folder checks all its requirements. Tests are skipped.
+
+It is independent of `rq test`: it runs no steps and reads no results, and `rq
+test` keeps the coverage it writes. The agent judges coverage only: whether what
+the linked requirements state and what the linked tests check covers each
+statement. It is told to ignore test results and the `## Status` sections, not
+to report on them, and not to recommend running tests.
+
+```text
+COMPLETE    requirements/R1 Export.md
+INCOMPLETE  requirements/R2 CSV export.md - Nothing covers quoting of commas.
+```
+
+- The `## Coverage` section holds the analysis: when the requirement is
+  complete, which requirement or test covers each statement; when it is not,
+  each statement nothing covers and what to do - a test to add and what it
+  should check, a sub-requirement to add and its statement, or a change to make.
+  It explains only what is covered, what is not, and how to improve the
+  coverage. The agent is asked to name requirements and tests by their id; a
+  link it writes anyway is replaced by its text. Then each id of a requirement
+  or test below the requirement in the graph, outside code, becomes a reference
+  link to its document, e.g. `[T2][]`, with its definition at the end of the
+  section, or none when the document already defines that label for the same
+  file. Other ids, e.g. of the requirements a test builds as its fixture, stay
+  text. It is rewritten on every check, with its definitions, placed before `##
+  Status`; a heading the agent writes is escaped so the section stays one
+  section.
+
+```markdown
+## Coverage
+
+Nothing covers "quotes fields that contain commas": [T2][] checks plain values
+only.
+
+- Add a test that exports a value with a comma and checks it is quoted, or
+- extend [T2][] with such a value.
+
+## Status
+
+- Coverage: INCOMPLETE - Nothing covers quoting of commas.
+```
+
+- A requirement that links to nothing is `INCOMPLETE` without asking, with an
+  analysis that says to decompose it or add tests.
+- The agent reads the requirement and what it links to; it is allowed to read
+  and search files only, so it runs no command and changes no file. The reason
+  it gives for an incomplete verdict becomes the note.
+- The verdict is not invalidated by later edits: run `rq coverage` again after
+  changing a requirement or what it links to.
+
+## Options
+
+- `--recurse` - also check every requirement below a requirement target.
+- `--working-dir <folder>` - the working folder; see [Working folder][WF].
+- `--requirements-dir <folder>`, `--documents-dir <folder>` - see
+  [Requirements and documents folders][FD].
+- `--ai[=<agent>][:<model>]` - the agent, `claude` or `copilot`, and its model,
+  both optional; the first of `claude` and `copilot` that is installed by
+  default. No agent is an error. `RQ_AI_COMMAND` replaces the agent, as for
+  [`rq test`][TS].
+
+[FD]: ../../rq/docs/Requirements.md#requirements-and-documents-folders
+[TS]: <rq test.md>
+[WF]: ../../rq/docs/Requirements.md#working-folder

package/docs/rq test.md

@@ -0,0 +1,124 @@
+# rq test
+
+Runs the tests of requirements and tests, records the results in an execution
+file, writes the results that follow to the `## Status` sections as each test
+finishes, and reports the result of each target. It exits with a non-zero code
+when a reported node does not pass or the graph has a structure error.
+
+```text
+rq test <target>... [--recurse] [--working-dir <folder>] [--name <slug>]
+        [--ai[=<agent>][:<model>]]
+```
+
+## Targets
+
+Each target is one of:
+
+- an id, e.g. `R10` or `T12`, or a `.md` name: the requirement or test the
+  requirements folder and its subfolders hold;
+- a requirement or test file, relative to the working folder;
+- a folder, relative to the working folder; see [Requirements][RM] for how its
+  roots are found.
+
+See [Requirements and documents folders][FD] for how ids and names are matched.
+
+```text
+rq test R10 R56 R100 T12 --recurse
+```
+
+What runs:
+
+- a test target runs itself;
+- a requirement target runs the tests it links to directly, and with `--recurse`
+  every test below it;
+- a folder target runs every test of its graph.
+
+Each test runs once, however many targets reach it.
+
+## Results
+
+The run is written to `.rq/E<n> <slug>.md` in the working folder, with `<n>` the
+next free number; see [Requirements][RM] for the format. As each test finishes,
+it is added to that file, its result is written to its `## Status` section, and
+every requirement above it is recalculated and written, all with the time the
+test finished as `Updated`; a failed test fails every requirement above it, and
+each of them names it, with its note and the execution file. After the last
+test, the targets are recalculated too. A run that stops early leaves every test
+that finished recorded. Nothing is written when no test runs.
+
+## Output
+
+One line per test, as it finishes, with its note, and for a failed one the
+execution file. Then one line per other reported node: each requirement target,
+and with `--recurse` or for a folder every requirement below it; without
+`--recurse`, also each requirement a target links to, marked `(recorded)`, with
+the result its document records. Then one `Error` line per structure error, the
+path of the execution file, one `Updated` line per document whose `## Status`
+changed, in the order they changed, and one `Removed` line per old execution
+file the [retention][RT] removed.
+
+```text
+PASS     requirements/tests/T1 PDF export.md - 1 step
+FAIL     requirements/tests/T2 CSV export.md - step 1 exited with code 1: 1 test failed (.rq/E4 requirements.md)
+FAIL     requirements/R1 Export.md - 1 of 2 links failed: T2 CSV export: step 1 exited with code 1: 1 test failed (.rq/E4 requirements.md)
+FAIL     requirements/R2 CSV export.md - 1 of 1 links failed: T2 CSV export: step 1 exited with code 1: 1 test failed (.rq/E4 requirements.md)
+Error    R2 CSV export.md: the link to R3.md points at no file.
+Results  .rq/E4 requirements.md
+Updated  requirements/tests/T1 PDF export.md
+Updated  requirements/R1 Export.md
+Updated  requirements/R2 CSV export.md
+Updated  requirements/tests/T2 CSV export.md
+```
+
+Without `--recurse`, `rq test R1` runs the tests R1 links to and merges their
+results with the results its sub-requirements record, which it does not
+recalculate; `--recurse` reruns the tests below them too. The results come from
+the documents' `## Status` sections, never from `.rq`.
+
+```text
+PASS     requirements/tests/T1 PDF export.md - 1 step
+NOT RUN  requirements/R1 Export.md - 1 of 2 links not run
+NOT RUN  requirements/R2 CSV export.md (recorded) - 1 of 1 links not run
+```
+
+A requirement is:
+
+- `PASS` when every node it links to passes;
+- `FAIL` when one fails, or when it links to nothing, naming each failed test
+  below it with its note and execution file;
+- `NOT RUN` otherwise: something below it has no result yet.
+
+## Options
+
+- `--recurse` - also run the tests of every requirement below a requirement
+  target.
+- `--working-dir <folder>` - the working folder; the current directory by
+  default.
+- `--requirements-dir <folder>`, `--documents-dir <folder>` - the requirements
+  folder, where ids and names are searched for, and the documents folder; see
+  [Requirements and documents folders][FD].
+- `--name <slug>` - the slug of the execution file. By default the targets, a
+  path by its file or folder name: `rq test R10 T12` writes `E<n> R10 T12.md`.
+- `--ai[=<agent>][:<model>]` - the AI agent of instruction steps, `claude` or
+  `copilot`, and its model, both optional: `--ai`, `--ai=claude:fable`,
+  `--ai=copilot`.
+
+Instruction steps always use an agent: the one `--ai` names, or the first of
+`claude` and `copilot` that is installed. Such a step may read files and run
+commands, and is told and configured not to edit files; see [Requirements][RM]
+for what that does not prevent. An instruction step without an agent fails.
+Write `--ai=<agent>` with `=` when a target follows it, e.g. `rq test
+--ai=claude R1`, so that the target is not taken for the agent. Coverage is
+checked by [`rq coverage`][CV], not by `rq test`.
+
+## Environment
+
+- `RQ_AI_COMMAND` - a command line that replaces the agent. It gets the prompt
+  on standard input, and its verdict is the last line of its output that is
+  `{"result":"OK"}` or `{"result":"Fail","message":"..."}`.
+
+[CV]: <rq coverage.md>
+[RM]: ../../rq/docs/Requirements.md
+[RT]: ../../rq/docs/Requirements.md#results
+[FD]: ../../rq/docs/Requirements.md#requirements-and-documents-folders
+[WF]: ../../rq/docs/Requirements.md#working-folder