@allurereport/plugin-agent 3.11.0 → 3.12.0

package/README.md

@@ -104,6 +104,38 @@ The preferred CLI entrypoint is:
 npx allure agent -- npm test
 ```
 
+To analyze existing Allure results or dump archives downloaded from CI without
+rerunning tests, use `agent inspect`. Positional arguments match Allure results
+directories. `--dump` accepts paths or glob patterns and can be repeated for
+multiple jobs or environments:
+
+```shell
+npx allure agent inspect path/to/allure-results
+npx allure agent inspect --dump allure-results-linux.zip --dump allure-results-macos.zip
+npx allure agent inspect --config ./allurerc.mjs --output ./agent-output path/to/allure-results
+```
+
+`agent inspect` accepts the same result inputs and configuration-style options as
+`allure generate`, including result directory globs, `--dump`, `--config`,
+`--cwd`, `--report-name`, `--history-limit`, and `--hide-labels`. Its `--output`
+option writes the agentic output directory.
+
+`allure agent` and `allure agent inspect` use `--report auto` by default. This
+writes the agent-readable artifacts and, when the stored visible result count is
+1000 or fewer, also writes a single-file Awesome report at `awesome/index.html`
+inside the agent output directory. Runs above that threshold skip the human
+report to avoid excessive output. Check `manifest/human-report.json`, the Human
+Report section in `index.md`, or `allure agent query --latest summary` to see
+whether a report was generated.
+
+If you need the human-readable report from the most recent agent run, first run
+`npx allure agent latest` when the output directory is unknown. Then check
+`<output>/manifest/human-report.json`; when its status is `generated`, open
+`<output>/<path>` from that manifest, usually `<output>/awesome/index.html`.
+Use `--report off` for agent-only artifacts, `--report awesome` to force the
+single-file Awesome report regardless of result count, or `--report config` to
+force the configured non-agent report plugins inside the agent output directory.
+
 You can provide compact inline expectations for the common review path:
 
 ```shell
@@ -125,7 +157,9 @@ npx allure agent \
   -- npm test
 ```
 
-That command uses an agent-only profile by default, so configured presentation and export plugins such as Awesome, Dashboard, or TestOps are ignored for that run.
+That command uses the default `--report auto` policy. Configured presentation or
+export plugins such as Dashboard or TestOps are otherwise ignored for agent runs
+unless you explicitly use `--report config`.
 
 ## Options
 
@@ -284,6 +318,7 @@ support is unclear:
 - Use `allure --version`, `allure agent capabilities --json`, and `allure agent --help` before choosing flags when the local CLI surface is unknown.
 - Use `allure agent latest` to print the newest output directory and `index.md` path when `--output` was omitted.
 - Use `allure agent latest`, `state-dir`, `query`, `select`, and `--rerun-*` according to their loop/task/problem mapping instead of treating them as interchangeable helper commands.
+- Use `allure agent inspect <allure-results-dir-or-glob>` or `allure agent inspect --dump <archive-or-glob>` when you need agent-readable markdown and manifests from existing Allure results without rerunning tests locally; repeat `--dump` for multiple CI jobs or environments.
 - Use `allure agent query --latest summary|tests|findings|test` or `allure agent query --from <output-dir> ...` to inspect prior output as focused JSON before manually opening raw manifests.
 - Use `allure agent select --from <output-dir> --output <file>` when you want the CLI to write the test plan and print a short summary with the file path, source output, preset, and selected count.
 - When rerunning previous failures, use `allure agent --rerun-latest --rerun-preset failed -- <command>` or `allure agent --rerun-from <output-dir> --rerun-preset failed -- <command>` instead of manually rebuilding runner-specific test names.

package/dist/capabilities.d.ts

@@ -10,7 +10,13 @@ export declare const createAgentCapabilities: () => {
         readonly run: {
             readonly supported: true;
             readonly usage: "allure agent [options] -- <command>";
-            readonly options: readonly ["--config", "--cwd", "--output", "--expectations", "--goal", "--task-id", "--expect-tests", "--expect-label", "--expect-env", "--expect-test", "--expect-prefix", "--expect-step-containing", "--forbid-label", "--expect-steps", "--expect-attachments", "--expect-attachment", "--environment", "--environment-name", "--silent", "--rerun-from", "--rerun-latest", "--rerun-preset", "--rerun-environment", "--rerun-label"];
+            readonly options: readonly ["--config", "--cwd", "--output", "--report", "--expectations", "--goal", "--task-id", "--expect-tests", "--expect-label", "--expect-env", "--expect-test", "--expect-prefix", "--expect-step-containing", "--forbid-label", "--expect-steps", "--expect-attachments", "--expect-attachment", "--environment", "--environment-name", "--silent", "--rerun-from", "--rerun-latest", "--rerun-preset", "--rerun-environment", "--rerun-label"];
+        };
+        readonly inspect: {
+            readonly supported: true;
+            readonly usage: "allure agent inspect [options] [<allure-results-dir-or-glob> ...]";
+            readonly inputs: readonly ["allure-results-directories", "dump-archives"];
+            readonly options: readonly ["--config", "--cwd", "--output", "--report", "--report-name", "--name", "--dump", "--open", "--port", "--history-limit", "--hide-labels", "--expectations", "--goal", "--task-id", "--expect-tests", "--expect-label", "--expect-env", "--expect-test", "--expect-prefix", "--expect-step-containing", "--forbid-label", "--expect-steps", "--expect-attachments", "--expect-attachment", "--environment", "--environment-name"];
         };
         readonly latest: {
             readonly supported: true;
@@ -77,8 +83,30 @@ export declare const createAgentCapabilities: () => {
     readonly output: {
         readonly automaticTempDirectory: true;
         readonly explicitOutputOption: "--output <dir>";
+        readonly explicitOutputCleanup: "When --output is provided, the output directory and its lifetime are caller-managed. Agent-mode cleanup will not remove it, so agents that pass --output should remove or archive that directory when it is no longer needed; later state compaction drops missing explicit outputs from the registry.";
         readonly schema: "allure-agent-output/v1";
-        readonly files: readonly ["index.md", "AGENTS.md", "manifest/run.json", "manifest/test-events.jsonl", "manifest/tests.jsonl", "manifest/findings.jsonl", "manifest/expected.json", "tests/<environment>/<slug>.md", "artifacts/global/"];
+        readonly files: readonly ["index.md", "AGENTS.md", "manifest/run.json", "manifest/test-events.jsonl", "manifest/tests.jsonl", "manifest/findings.jsonl", "manifest/expected.json", "manifest/human-report.json", "tests/<environment>/<slug>.md", "artifacts/global/", "awesome/index.html"];
+    };
+    readonly humanReports: {
+        readonly supported: true;
+        readonly option: "--report <auto|off|awesome|config>";
+        readonly defaultMode: "auto";
+        readonly modes: {
+            readonly auto: "Generate a single-file Awesome report when the stored visible result count is 1000 or fewer; skip above that threshold.";
+            readonly off: "Disable human-readable reports and write agent artifacts only.";
+            readonly awesome: "Force a single-file Awesome report and ignore the auto threshold.";
+            readonly config: "Force the configured non-agent report plugins inside the agent output directory and ignore the auto threshold.";
+        };
+        readonly threshold: {
+            readonly resultCount: 1000;
+            readonly appliesTo: "auto";
+            readonly countSource: "Allure store visible logical test results with retries excluded";
+            readonly generatedWhen: "<= 1000";
+            readonly skippedWhen: "> 1000";
+        };
+        readonly statusManifest: "manifest/human-report.json";
+        readonly defaultGeneratedPath: "awesome/index.html";
+        readonly discovery: readonly ["When a user asks for a human-readable report after an agent run, first use `allure agent latest` if no output directory is known.", "Read `<output>/manifest/human-report.json`, the Human Report section of `<output>/index.md`, or `allure agent query --latest summary` to check whether a report already exists.", "If the status is `generated`, use `<output>/<path>` from the human-report manifest; for auto and awesome this is usually `<output>/awesome/index.html`.", "If the status is `skipped`, `disabled`, `failed`, or the manifest is missing, generate a report only from available results or dumps with the requested `--report` mode."];
     };
     readonly unsupported: {
         readonly discovery: true;
@@ -95,5 +123,5 @@ export declare const createAgentCapabilities: () => {
         readonly expectationControls: readonly ["--expect-evidence"];
     };
 };
-export declare const AGENT_TASK_MAP_HELP = "Agent task map:\n  allure --version\n  allure agent --help\n  allure agent capabilities\n      Setup and capability detection. Use when the local CLI surface is unknown,\n      generated guidance may be stale, or an agent needs supported flags without\n      guessing.\n\n  allure agent --goal ... -- <command>\n      Run a test command with runtime evidence, scope expectations, and\n      agent-readable artifacts for review, debugging, smoke checks, or validation.\n\n  allure agent latest\n      Recover the newest agent output directory and index.md when --output was\n      omitted or a follow-up task needs the previous run.\n\n  allure agent state-dir\n      Show where project-scoped latest-run pointers are stored. Useful when\n      latest cannot find a run or CI/sandbox state looks wrong.\n\n  allure agent select --latest\n  allure agent select --from <output-dir>\n      Inspect/filter prior results and write an Allure test plan before rerun.\n\n  allure agent query --latest summary\n  allure agent query --from <output-dir> tests\n  allure agent query --from <output-dir> findings\n      Inspect prior agent output as focused JSON without manually loading raw\n      manifests. Use for summaries, filtered test lists, findings, or one test.\n\n  allure agent --rerun-latest -- <command>\n  allure agent --rerun-from <output-dir> -- <command>\n      Rerun the failed, unsuccessful, or selected tests from prior agent output\n      through Allure test plan support.\n\nEnvironment:\n  ALLURE_AGENT_STATE_DIR=<dir>\n      Override the project-scoped state directory. Useful in CI, sandboxes, or\n      multi-job setups that need a deterministic shared state location.\n";
+export declare const AGENT_TASK_MAP_HELP = "Agent task map:\n  allure --version\n  allure agent --help\n  allure agent capabilities\n      Setup and capability detection. Use when the local CLI surface is unknown,\n      generated guidance may be stale, or an agent needs supported flags without\n      guessing.\n\n  allure agent --goal ... -- <command>\n      Run a test command with runtime evidence, scope expectations, and\n      agent-readable artifacts for review, debugging, smoke checks, or validation.\n      Use --report auto|off|awesome|config to control the optional human report.\n      The default --report auto may already generate awesome/index.html in the\n      agent output when the stored visible result count is 1000 or fewer.\n\n  allure agent inspect [<allure-results-dir-or-glob> ...]\n  allure agent inspect --dump <archive-or-glob> [--dump <archive-or-glob> ...]\n      Restore one or more dump archives and/or read existing Allure results\n      directories, then produce agent-readable artifacts without executing a\n      test command. Use --report auto|off|awesome|config to control the optional\n      human report. Use after downloading CI dump artifacts created by\n      allure run --dump or when local results already exist.\n\n  allure agent latest\n      Recover the newest agent output directory and index.md when --output was\n      omitted or a follow-up task needs the previous run. If a user asks for a\n      human-readable report from the last run, start here, then inspect\n      <output>/manifest/human-report.json and use <output>/<path> when status is\n      generated.\n\n  allure agent state-dir\n      Show the shared state directory that stores per-project run registries. Useful when\n      latest cannot find a run or CI/sandbox state looks wrong.\n\n  allure agent select --latest\n  allure agent select --from <output-dir>\n      Inspect/filter prior results and write an Allure test plan before rerun.\n\n  allure agent query --latest summary\n  allure agent query --from <output-dir> tests\n  allure agent query --from <output-dir> findings\n      Inspect prior agent output as focused JSON without manually loading raw\n      manifests. Use for summaries, human_report status, filtered test lists,\n      findings, or one test.\n\n  allure agent --rerun-latest -- <command>\n  allure agent --rerun-from <output-dir> -- <command>\n      Rerun the failed, unsuccessful, or selected tests from prior agent output\n      through Allure test plan support.\n\nEnvironment:\n  ALLURE_AGENT_STATE_DIR=<dir>\n      Override the shared agent state directory. Useful in CI, sandboxes, or\n      multi-job setups that need a deterministic shared state location.\n\nHuman reports:\n  Default agent runs use --report auto. For 1000 or fewer stored visible logical\n  results, the last run may already contain a human-readable single-file Awesome\n  report at <output>/awesome/index.html. Larger runs are skipped in auto mode to\n  avoid excessive output.\n\n  When a user asks for \"the report\" after a run, do not assume it needs to be\n  regenerated. First run allure agent latest when the output directory is\n  unknown, then read <output>/manifest/human-report.json or\n  allure agent query --latest summary. If the human-report status is generated,\n  return or open <output>/<path> from that manifest. If the status is skipped,\n  disabled, failed, or missing, rerun or inspect existing results/dumps with the\n  requested --report mode, for example --report awesome to force the single-file\n  Awesome report or --report config to force configured report plugins.\n";
 export declare const isAgentTaskMapHelpRequest: (args: string[]) => boolean;

package/dist/capabilities.js

@@ -14,6 +14,7 @@ export const createAgentCapabilities = () => ({
                 "--config",
                 "--cwd",
                 "--output",
+                "--report",
                 "--expectations",
                 "--goal",
                 "--task-id",
@@ -37,6 +38,39 @@ export const createAgentCapabilities = () => ({
                 "--rerun-label",
             ],
         },
+        inspect: {
+            supported: true,
+            usage: "allure agent inspect [options] [<allure-results-dir-or-glob> ...]",
+            inputs: ["allure-results-directories", "dump-archives"],
+            options: [
+                "--config",
+                "--cwd",
+                "--output",
+                "--report",
+                "--report-name",
+                "--name",
+                "--dump",
+                "--open",
+                "--port",
+                "--history-limit",
+                "--hide-labels",
+                "--expectations",
+                "--goal",
+                "--task-id",
+                "--expect-tests",
+                "--expect-label",
+                "--expect-env",
+                "--expect-test",
+                "--expect-prefix",
+                "--expect-step-containing",
+                "--forbid-label",
+                "--expect-steps",
+                "--expect-attachments",
+                "--expect-attachment",
+                "--environment",
+                "--environment-name",
+            ],
+        },
         latest: {
             supported: true,
             usage: "allure agent latest [--cwd <dir>]",
@@ -102,6 +136,7 @@ export const createAgentCapabilities = () => ({
     output: {
         automaticTempDirectory: true,
         explicitOutputOption: "--output <dir>",
+        explicitOutputCleanup: "When --output is provided, the output directory and its lifetime are caller-managed. Agent-mode cleanup will not remove it, so agents that pass --output should remove or archive that directory when it is no longer needed; later state compaction drops missing explicit outputs from the registry.",
         schema: "allure-agent-output/v1",
         files: [
             "index.md",
@@ -111,8 +146,36 @@ export const createAgentCapabilities = () => ({
             "manifest/tests.jsonl",
             "manifest/findings.jsonl",
             "manifest/expected.json",
+            "manifest/human-report.json",
             "tests/<environment>/<slug>.md",
             "artifacts/global/",
+            "awesome/index.html",
+        ],
+    },
+    humanReports: {
+        supported: true,
+        option: "--report <auto|off|awesome|config>",
+        defaultMode: "auto",
+        modes: {
+            auto: "Generate a single-file Awesome report when the stored visible result count is 1000 or fewer; skip above that threshold.",
+            off: "Disable human-readable reports and write agent artifacts only.",
+            awesome: "Force a single-file Awesome report and ignore the auto threshold.",
+            config: "Force the configured non-agent report plugins inside the agent output directory and ignore the auto threshold.",
+        },
+        threshold: {
+            resultCount: 1000,
+            appliesTo: "auto",
+            countSource: "Allure store visible logical test results with retries excluded",
+            generatedWhen: "<= 1000",
+            skippedWhen: "> 1000",
+        },
+        statusManifest: "manifest/human-report.json",
+        defaultGeneratedPath: "awesome/index.html",
+        discovery: [
+            "When a user asks for a human-readable report after an agent run, first use `allure agent latest` if no output directory is known.",
+            "Read `<output>/manifest/human-report.json`, the Human Report section of `<output>/index.md`, or `allure agent query --latest summary` to check whether a report already exists.",
+            "If the status is `generated`, use `<output>/<path>` from the human-report manifest; for auto and awesome this is usually `<output>/awesome/index.html`.",
+            "If the status is `skipped`, `disabled`, `failed`, or the manifest is missing, generate a report only from available results or dumps with the requested `--report` mode.",
         ],
     },
     unsupported: {
@@ -141,13 +204,27 @@ export const AGENT_TASK_MAP_HELP = `Agent task map:
   allure agent --goal ... -- <command>
       Run a test command with runtime evidence, scope expectations, and
       agent-readable artifacts for review, debugging, smoke checks, or validation.
+      Use --report auto|off|awesome|config to control the optional human report.
+      The default --report auto may already generate awesome/index.html in the
+      agent output when the stored visible result count is 1000 or fewer.
+
+  allure agent inspect [<allure-results-dir-or-glob> ...]
+  allure agent inspect --dump <archive-or-glob> [--dump <archive-or-glob> ...]
+      Restore one or more dump archives and/or read existing Allure results
+      directories, then produce agent-readable artifacts without executing a
+      test command. Use --report auto|off|awesome|config to control the optional
+      human report. Use after downloading CI dump artifacts created by
+      allure run --dump or when local results already exist.
 
   allure agent latest
       Recover the newest agent output directory and index.md when --output was
-      omitted or a follow-up task needs the previous run.
+      omitted or a follow-up task needs the previous run. If a user asks for a
+      human-readable report from the last run, start here, then inspect
+      <output>/manifest/human-report.json and use <output>/<path> when status is
+      generated.
 
   allure agent state-dir
-      Show where project-scoped latest-run pointers are stored. Useful when
+      Show the shared state directory that stores per-project run registries. Useful when
       latest cannot find a run or CI/sandbox state looks wrong.
 
   allure agent select --latest
@@ -158,7 +235,8 @@ export const AGENT_TASK_MAP_HELP = `Agent task map:
   allure agent query --from <output-dir> tests
   allure agent query --from <output-dir> findings
       Inspect prior agent output as focused JSON without manually loading raw
-      manifests. Use for summaries, filtered test lists, findings, or one test.
+      manifests. Use for summaries, human_report status, filtered test lists,
+      findings, or one test.
 
   allure agent --rerun-latest -- <command>
   allure agent --rerun-from <output-dir> -- <command>
@@ -167,7 +245,22 @@ export const AGENT_TASK_MAP_HELP = `Agent task map:
 
 Environment:
   ALLURE_AGENT_STATE_DIR=<dir>
-      Override the project-scoped state directory. Useful in CI, sandboxes, or
+      Override the shared agent state directory. Useful in CI, sandboxes, or
       multi-job setups that need a deterministic shared state location.
+
+Human reports:
+  Default agent runs use --report auto. For 1000 or fewer stored visible logical
+  results, the last run may already contain a human-readable single-file Awesome
+  report at <output>/awesome/index.html. Larger runs are skipped in auto mode to
+  avoid excessive output.
+
+  When a user asks for "the report" after a run, do not assume it needs to be
+  regenerated. First run allure agent latest when the output directory is
+  unknown, then read <output>/manifest/human-report.json or
+  allure agent query --latest summary. If the human-report status is generated,
+  return or open <output>/<path> from that manifest. If the status is skipped,
+  disabled, failed, or missing, rerun or inspect existing results/dumps with the
+  requested --report mode, for example --report awesome to force the single-file
+  Awesome report or --report config to force configured report plugins.
 `;
 export const isAgentTaskMapHelpRequest = (args) => args.length === 2 && args[0] === "agent" && (args[1] === "--help" || args[1] === "-h");

package/dist/guidance.d.ts

@@ -5,13 +5,13 @@ export type EnrichmentActionDefinition = {
     guidance: string;
 };
 export declare const ENRICHMENT_ACTIONS_BY_CHECK_NAME: Record<string, EnrichmentActionDefinition>;
-export declare const AGENT_WORKFLOWS_MARKDOWN = "Use the smallest workflow that matches the task. Each workflow has the same shape: when to use it, which agent-mode commands help, and what must be true before you call the task done.\n\n### Validate A Change\n\nUse when code or tests changed and you need a user-facing safety conclusion. For small mechanical changes, use this same workflow with narrower expectations rather than a separate shortcut.\n\nCommands:\n\n- `allure agent --goal <text> --expect-* -- <command>`\n\nDone when:\n\n- the expected scope ran and no forbidden scope appeared\n- `index.md`, `manifest/run.json`, `manifest/tests.jsonl`, and `manifest/findings.jsonl` were reviewed\n- the `index.md` path was reported\n- the changed package build and required static checks passed when this repository guide requires them\n\n### Add Or Update Tests\n\nUse when creating or changing tests for a feature, fix, or behavior gap.\n\nCommands:\n\n- `allure agent --goal <text> --expect-tests <count> --expect-test \"<fullName>\" --expect-label name=value --expect-step-containing <text> -- <command>`\n\nDone when:\n\n- the tests prove the intended behavior rather than only touching the code path\n- scope expectations match the intended feature, issue, or package slice\n- each expected test has enough steps or attachments for a reviewer to understand what happened\n- weak evidence, scope drift, and unexpected-test findings are fixed or explicitly accepted as out of scope\n\n### Review Existing Coverage\n\nUse when auditing a package, command matrix, feature area, or business behavior without necessarily changing tests first.\n\nCommands:\n\n- one scoped `allure agent --goal <text> --expect-* -- <command>` run per review group\n\nDone when:\n\n- the audit is split into reviewable groups, or it is explicitly documented as a broad package-health run\n- each group has expectations that describe the intended scope\n- runtime artifacts are reviewed before source-only coverage conclusions\n- uncovered behavior is recorded as follow-up test work instead of being hidden in a broad pass/fail summary\n\n### Triage Failures\n\nUse when tests failed, broke, or runner output does not match agent artifacts.\n\nCommands:\n\n- `allure agent latest`\n- `allure agent --rerun-latest --rerun-preset failed -- <command>`\n- `allure agent --rerun-from <output-dir> --rerun-preset failed -- <command>`\n\nDone when:\n\n- failing, broken, or unmodeled runner-visible failures are represented in agent artifacts, or partial modeling is called out explicitly\n- `artifacts/global/stderr.txt` and global errors were checked when failures are missing from `manifest/tests.jsonl`\n- reruns use prior agent output instead of hand-built runner test names whenever the runner can consume the generated test plan\n\n### Rerun A Prior Scope\n\nUse when prior agent output already identifies failed, unsuccessful, or review-targeted tests and the next run should stay focused.\n\nCommands:\n\n- `allure agent select --latest [--preset review|failed|unsuccessful|all]`\n- `allure agent select --from <output-dir> [--environment <id>] [--label name=value]`\n- `allure agent --rerun-latest -- <command>`\n- `allure agent --rerun-from <output-dir> -- <command>`\n\nDone when:\n\n- the rerun scope comes from Allure testplan support\n- `--rerun-preset`, `--rerun-environment`, or `--rerun-label` filters explain any narrowed selection\n- manual test names are used only as a fallback when testplan support is unavailable\n- the rerun output is reviewed before making a new conclusion\n\n### Improve Evidence Quality\n\nUse when tests pass or fail but the runtime story is too weak to review.\n\nCommands:\n\n- `allure agent --expect-step-containing <text> --expect-steps <count> --expect-attachments <count> -- <command>`\n- `allure agent --expect-attachment <name|name=value|content-type=value> -- <command>`\n\nDone when:\n\n- steps describe real setup, actions, state transitions, or assertions\n- attachments contain runtime evidence such as payloads, responses, screenshots, DOM snapshots, diffs, logs, or traces\n- placeholder steps, generic `\"passed\"` attachments, and other dummy evidence are removed\n- the same intended scope was rerun and no high-confidence evidence findings remain\n\n### Recover Or Diagnose Agent Mode\n\nUse when agent output is missing, the latest run cannot be found, local CLI support is unclear, or state behaves differently in CI or a sandbox.\n\nCommands:\n\n- `allure --version`\n- `allure agent capabilities --json`\n- `allure agent --help`\n- `allure agent latest`\n- `allure agent state-dir`\n- `ALLURE_AGENT_STATE_DIR=<dir>`\n\nDone when:\n\n- supported local commands and flags are known from capabilities or help output\n- the output directory, `index.md` path, or state directory is identified, or the reason it is unavailable is documented\n- console-only conclusions stay provisional until agent-mode artifacts are available";
-export declare const AGENT_COMMAND_TASK_MAP: readonly ["`allure --version`, `allure agent capabilities --json`, and `allure agent --help`: setup and capability-detection loop. Use when the local CLI surface is unknown, generated guidance may be stale, or you need to choose supported flags without guessing.", "`allure agent --goal ... -- <command>`: test review, feature delivery, smoke-check, and coverage loops. Use when a test command needs runtime evidence, scope expectations, and user-facing conclusions based on agent artifacts rather than console output alone.", "`allure agent latest`: output recovery loop. Use when a previous run omitted `--output`, you need the newest output directory and `index.md` path, or a follow-up task needs prior output before selecting or rerunning tests.", "`allure agent state-dir`: tooling diagnosis loop. Use when `latest` cannot find a run, CI or sandbox state looks wrong, or you need to explain where project-scoped latest pointers are stored.", "`allure agent query --latest summary|tests|findings|test` / `allure agent query --from <output-dir> ...`: output inspection loop. Use when you need a focused JSON summary, filtered tests, filtered findings, or one test from prior agent output without manually loading raw manifests first.", "`allure agent select --latest` / `allure agent select --from <output-dir>`: rerun-planning loop. Use when you need to inspect, filter, or write the Allure test plan from prior results before executing another run. Without `--output`, stdout is raw testplan JSON; with `--output`, stdout summarizes the file path, source output, preset, and selected count.", "`allure agent --rerun-latest` / `allure agent --rerun-from <output-dir>`: focused retry loop. Use when prior output already identifies failed, unsuccessful, or review-targeted tests and you should rerun that slice through Allure testplan support instead of rebuilding runner-specific test names.", "`ALLURE_AGENT_STATE_DIR=<dir>`: CI and sandbox state-control loop. Use when multiple jobs need a deterministic state location, the default temp state is not shared, or the default state directory is not writable."];
+export declare const AGENT_WORKFLOWS_MARKDOWN = "Use the smallest workflow that matches the task. Each workflow has the same shape: when to use it, which agent-mode commands help, and what must be true before you call the task done.\n\n### Validate A Change\n\nUse when code or tests changed and you need a user-facing safety conclusion. For small mechanical changes, use this same workflow with narrower expectations rather than a separate shortcut.\n\nCommands:\n\n- `allure agent --goal <text> --expect-* -- <command>`\n\nDone when:\n\n- the expected scope ran and no forbidden scope appeared\n- `index.md`, `manifest/run.json`, `manifest/tests.jsonl`, and `manifest/findings.jsonl` were reviewed\n- the `index.md` path was reported\n- the changed package build and required static checks passed when this repository guide requires them\n\n### Add Or Update Tests\n\nUse when creating or changing tests for a feature, fix, or behavior gap.\n\nCommands:\n\n- `allure agent --goal <text> --expect-tests <count> --expect-test \"<fullName>\" --expect-label name=value --expect-step-containing <text> -- <command>`\n\nDone when:\n\n- the tests prove the intended behavior rather than only touching the code path\n- scope expectations match the intended feature, issue, or package slice\n- each expected test has enough steps or attachments for a reviewer to understand what happened\n- weak evidence, scope drift, and unexpected-test findings are fixed or explicitly accepted as out of scope\n\n### Review Existing Coverage\n\nUse when auditing a package, command matrix, feature area, or business behavior without necessarily changing tests first.\n\nCommands:\n\n- one scoped `allure agent --goal <text> --expect-* -- <command>` run per review group\n- `allure agent inspect --goal <text> --expect-* <allure-results-dir-or-glob>` or `--dump <archive-or-glob>` when the evidence already exists as local results or CI dump artifacts\n\nDone when:\n\n- the audit is split into reviewable groups, or it is explicitly documented as a broad package-health run\n- each group has expectations that describe the intended scope\n- runtime artifacts are reviewed before source-only coverage conclusions\n- uncovered behavior is recorded as follow-up test work instead of being hidden in a broad pass/fail summary\n\n### Review Existing Evidence\n\nUse when CI has already produced dump archives or local Allure results already exist and you need agent-readable review artifacts without rerunning tests locally.\n\nCommands:\n\n- `allure agent inspect <allure-results-dir-or-glob>`\n- `allure agent inspect --dump <archive-or-glob>`\n- `allure agent inspect --dump <linux.zip> --dump <macos.zip>`\n- `allure agent inspect --goal <text> --expect-* --dump <archive-or-glob>`\n\nDone when:\n\n- all intended result directories or dump artifacts were downloaded or present and matched by the command\n- `index.md`, `manifest/run.json`, `manifest/tests.jsonl`, and `manifest/findings.jsonl` were reviewed\n- the review calls out that inspect-derived output cannot add missing live process logs or rerun-time evidence unless those artifacts were captured in the results or dumps\n- any environment-specific gaps between CI jobs are explicit\n\n### Triage Failures\n\nUse when tests failed, broke, or runner output does not match agent artifacts.\n\nCommands:\n\n- `allure agent latest`\n- `allure agent --rerun-latest --rerun-preset failed -- <command>`\n- `allure agent --rerun-from <output-dir> --rerun-preset failed -- <command>`\n\nDone when:\n\n- failing, broken, or unmodeled runner-visible failures are represented in agent artifacts, or partial modeling is called out explicitly\n- `artifacts/global/stderr.txt` and global errors were checked when failures are missing from `manifest/tests.jsonl`\n- reruns use prior agent output instead of hand-built runner test names whenever the runner can consume the generated test plan\n\n### Rerun A Prior Scope\n\nUse when prior agent output already identifies failed, unsuccessful, or review-targeted tests and the next run should stay focused.\n\nCommands:\n\n- `allure agent select --latest [--preset review|failed|unsuccessful|all]`\n- `allure agent select --from <output-dir> [--environment <id>] [--label name=value]`\n- `allure agent --rerun-latest -- <command>`\n- `allure agent --rerun-from <output-dir> -- <command>`\n\nDone when:\n\n- the rerun scope comes from Allure testplan support\n- `--rerun-preset`, `--rerun-environment`, or `--rerun-label` filters explain any narrowed selection\n- manual test names are used only as a fallback when testplan support is unavailable\n- the rerun output is reviewed before making a new conclusion\n\n### Improve Evidence Quality\n\nUse when tests pass or fail but the runtime story is too weak to review.\n\nCommands:\n\n- `allure agent --expect-step-containing <text> --expect-steps <count> --expect-attachments <count> -- <command>`\n- `allure agent --expect-attachment <name|name=value|content-type=value> -- <command>`\n\nDone when:\n\n- steps describe real setup, actions, state transitions, or assertions\n- attachments contain runtime evidence such as payloads, responses, screenshots, DOM snapshots, diffs, logs, or traces\n- placeholder steps, generic `\"passed\"` attachments, and other dummy evidence are removed\n- the same intended scope was rerun and no high-confidence evidence findings remain\n\n### Recover Or Diagnose Agent Mode\n\nUse when agent output is missing, the latest run cannot be found, local CLI support is unclear, or state behaves differently in CI or a sandbox.\n\nCommands:\n\n- `allure --version`\n- `allure agent capabilities --json`\n- `allure agent --help`\n- `allure agent latest`\n- `allure agent state-dir`\n- `ALLURE_AGENT_STATE_DIR=<dir>`\n\nDone when:\n\n- supported local commands and flags are known from capabilities or help output\n- the output directory, `index.md` path, or state directory is identified, or the reason it is unavailable is documented\n- console-only conclusions stay provisional until agent-mode artifacts are available";
+export declare const AGENT_COMMAND_TASK_MAP: readonly ["`allure --version`, `allure agent capabilities --json`, and `allure agent --help`: setup and capability-detection loop. Use when the local CLI surface is unknown, generated guidance may be stale, or you need to choose supported flags without guessing.", "`allure agent --goal ... -- <command>`: test review, feature delivery, smoke-check, and coverage loops. Use when a test command needs runtime evidence, scope expectations, and user-facing conclusions based on agent artifacts rather than console output alone. The default `--report auto` may also write a human-readable `awesome/index.html` for small runs.", "`allure agent inspect <allure-results-dir-or-glob>` / `allure agent inspect --dump <archive-or-glob>`: existing evidence review loop. Use after downloading one or more dump archives or when Allure results already exist and you need agent-readable markdown, manifests, and optional human report output without rerunning tests locally. Repeat `--dump` to merge multiple environments or jobs.", "`allure agent latest`: output recovery loop. Use when a previous run omitted `--output`, you need the newest output directory and `index.md` path, a user asks for the human-readable report from the last run, or a follow-up task needs prior output before selecting or rerunning tests.", "`allure agent state-dir`: tooling diagnosis loop. Use when `latest` cannot find a run, CI or sandbox state looks wrong, or you need to explain where per-project run registries are stored.", "`allure agent query --latest summary|tests|findings|test` / `allure agent query --from <output-dir> ...`: output inspection loop. Use when you need a focused JSON summary, human-report status, filtered tests, filtered findings, or one test from prior agent output without manually loading raw manifests first.", "`allure agent select --latest` / `allure agent select --from <output-dir>`: rerun-planning loop. Use when you need to inspect, filter, or write the Allure test plan from prior results before executing another run. Without `--output`, stdout is raw testplan JSON; with `--output`, stdout summarizes the file path, source output, preset, and selected count.", "`allure agent --rerun-latest` / `allure agent --rerun-from <output-dir>`: focused retry loop. Use when prior output already identifies failed, unsuccessful, or review-targeted tests and you should rerun that slice through Allure testplan support instead of rebuilding runner-specific test names.", "`ALLURE_AGENT_STATE_DIR=<dir>`: CI and sandbox state-control loop. Use when multiple jobs need a deterministic state location, the default temp state is not shared, or the default state directory is not writable."];
 export declare const AGENT_VERIFICATION_RULES: readonly ["If a command executes tests and its result will be used for smoke checking, reasoning, review, coverage analysis, debugging, or any user-facing conclusion, run it through `allure agent`. It preserves the original console logs and adds agent-mode artifacts without inheriting the normal report or export plugins from the project config.", "Use `allure agent` for smoke checks too, even when the change is small or mechanical.", "Only skip agent mode when it is impossible or when you are debugging agent mode itself.", "After changing a package in this repository, run that package build command before finalizing (for example, `yarn workspace <package-name> build`).", "After each agent-mode test run, print the `index.md` path from that run's output directory so users can open the run overview quickly."];
 export declare const AGENT_TEST_ENRICHMENT_BEST_PRACTICES: readonly ["Steps must wrap real actions, state transitions, or assertions. Prefer a small setup/action/assertion narrative over event-by-event step spam.", "Attachments must capture real runtime evidence from that execution: payloads, responses, screenshots, DOM snapshots, diffs, logs, or traces.", "Add metadata only when it improves scope review, debugging, or downstream policy. Keep labels and parameters intentionally minimal.", "If multiple call sites need the same evidence, instrument the helper once. Example: teach `runCommand` to emit a step instead of wrapping every `runCommand(...)` call site with identical step blocks."];
 export declare const AGENT_ANTI_DUMMY_POLICY: readonly ["Do not add empty wrapper steps, placeholder attachments, or generic strings such as `passed`, `success`, or static boilerplate.", "Do not attach evidence that is not grounded in the current test execution. Synthetic summaries are fine only when they are derived from real runtime artifacts.", "Do not inflate metadata with labels, stories, or severities that no expectation, review step, or policy actually uses."];
 export declare const AGENT_ACCEPTANCE_CHECKLIST: readonly ["The rerun matches the intended scope and does not trigger forbidden or unexpected-test findings.", "Each touched test shows enough evidence to explain what happened and what was verified.", "Retries include per-attempt diagnostics when the same test reruns.", "No high-confidence anti-dummy findings remain, especially `noop-dominated-steps` or low-signal `step-spam` traces."];
 export declare const AGENT_REVIEW_COMPLETENESS_CHECKLIST: readonly ["The relevant scope was run with agent mode unless that was impossible.", "Scoped reviews created expectations before the final rerun, unless the task was an intentionally broad package-health audit.", "The final conclusion was based on `manifest/run.json`, `manifest/test-events.jsonl`, `index.md`, `manifest/tests.jsonl`, and `manifest/findings.jsonl` rather than console output alone.", "Any missing or partial runtime modeling was called out explicitly before the review was considered complete."];
 export declare const AGENT_PARTIAL_RUNTIME_REVIEW_RULES: readonly ["Suite-load, import, or setup failures may appear only in `artifacts/global/stderr.txt` or global errors instead of `manifest/tests.jsonl`.", "If runner-visible failures are not represented as logical tests, inspect global stderr and treat the run as a partial runtime review, not a clean result set.", "Console-only conclusions stay provisional when agent output is missing, incomplete, or partially modeled."];
-export declare const AGENT_INSTRUCTIONS_TEMPLATE = "## Allure Agent Mode Instructions\n\n- If a command executes tests and its result will be used for smoke checking, reasoning, review, coverage analysis, debugging, or any user-facing conclusion, run it through `allure agent`. It preserves the original console logs and adds agent-mode artifacts without inheriting the normal report or export plugins from the project config.\n- Use `allure agent` for smoke checks too, even when the change is small or mechanical.\n- Only skip agent mode when it is impossible or when you are debugging agent mode itself.\n- After each agent-mode test run, print the `index.md` path from that run's output directory so users can open the run overview quickly.\n- Use `allure agent latest` to print the newest output directory and `index.md` path when `--output` was omitted.\n- Use `allure agent capabilities --json` when you need structured supported-command, expectation, output, rerun, and unsupported-feature data without scraping help text.\n- Use `allure agent state-dir` to inspect where the current project stores its latest-agent state.\n- Use `allure agent latest`, `state-dir`, `query`, `select`, and `--rerun-*` according to their loop/task/problem mapping instead of treating them as interchangeable helper commands.\n- Use `allure agent query --latest summary|tests|findings|test` or `allure agent query --from <output-dir> ...` to inspect prior output as focused JSON before manually opening raw manifests.\n- Use `allure agent select --latest` or `allure agent select --from <output-dir>` to inspect the review-targeted test plan before rerunning; add `--output <file>` when you want the CLI to write the plan and print a short selection summary.\n- Use `allure agent --rerun-latest -- <command>` or `allure agent --rerun-from <output-dir> -- <command>` to rerun only the selected tests.\n- When rerunning previous failures, use `allure agent --rerun-latest --rerun-preset failed -- <command>` or `allure agent --rerun-from <output-dir> --rerun-preset failed -- <command>` instead of manually rebuilding runner-specific test names.\n- Use `--rerun-preset review|failed|unsuccessful|all`, repeated `--rerun-environment <id>`, and repeated `--rerun-label name=value` when you need a narrower rerun selection from the previous output.\n- Use `ALLURE_AGENT_STATE_DIR` when you need to override where the current project stores latest-agent state for `latest`, `state-dir`, or `--rerun-latest`.\n- Prefer inline `allure agent` expectation flags such as `--goal`, `--expect-tests`, `--expect-test`, `--expect-label`, and `--expect-step-containing`; use `--expectations <file>` only when flags become awkward.\n- Run tests with `allure agent` and review `manifest/run.json`, `manifest/test-events.jsonl`, `index.md`, `manifest/tests.jsonl`, and `manifest/findings.jsonl`.\n- Enrich only the intended tests. Add real steps for real setup, actions, and assertions.\n- Attach only real runtime evidence such as payloads, responses, screenshots, DOM snapshots, diffs, logs, or traces.\n- Keep metadata minimal. Add labels or severity only when scope review, debugging, or quality policy uses them.\n- Instrument stable helpers when several call sites need the same evidence. For example, teach `runCommand` to emit a step instead of wrapping every caller.\n- Reject the rerun if scope drifts, evidence stays weak, or high-confidence noop-style findings remain.";
+export declare const AGENT_INSTRUCTIONS_TEMPLATE = "## Allure Agent Mode Instructions\n\n- If a command executes tests and its result will be used for smoke checking, reasoning, review, coverage analysis, debugging, or any user-facing conclusion, run it through `allure agent`. It preserves the original console logs and adds agent-mode artifacts without inheriting the normal report or export plugins from the project config.\n- Use `allure agent` for smoke checks too, even when the change is small or mechanical.\n- Only skip agent mode when it is impossible or when you are debugging agent mode itself.\n- After each agent-mode test run, print the `index.md` path from that run's output directory so users can open the run overview quickly.\n- Use `allure agent latest` to print the newest output directory and `index.md` path when `--output` was omitted.\n- When a user asks for the human-readable report from the last run, use `allure agent latest` first if the output directory is unknown, then check `manifest/human-report.json`; when its status is `generated`, use the path recorded there, usually `awesome/index.html`.\n- Use `allure agent capabilities --json` when you need structured supported-command, expectation, output, rerun, and unsupported-feature data without scraping help text.\n- Use `allure agent state-dir` to inspect the shared state directory that stores per-project run registries.\n- Use `allure agent latest`, `state-dir`, `query`, `select`, and `--rerun-*` according to their loop/task/problem mapping instead of treating them as interchangeable helper commands.\n- Use `allure agent inspect <allure-results-dir-or-glob>` or `allure agent inspect --dump <archive-or-glob>` when you need agent-readable markdown and manifests from existing Allure results without rerunning tests locally; repeat `--dump` for multiple CI jobs or environments.\n- Use `--report auto|off|awesome|config` to control human report output. The default `auto` mode writes `awesome/index.html` for 1000 or fewer stored visible logical results and records generated, skipped, disabled, or failed status in `manifest/human-report.json`.\n- Use `allure agent query --latest summary|tests|findings|test` or `allure agent query --from <output-dir> ...` to inspect prior output as focused JSON before manually opening raw manifests.\n- Use `allure agent select --latest` or `allure agent select --from <output-dir>` to inspect the review-targeted test plan before rerunning; add `--output <file>` when you want the CLI to write the plan and print a short selection summary.\n- Use `allure agent --rerun-latest -- <command>` or `allure agent --rerun-from <output-dir> -- <command>` to rerun only the selected tests.\n- When rerunning previous failures, use `allure agent --rerun-latest --rerun-preset failed -- <command>` or `allure agent --rerun-from <output-dir> --rerun-preset failed -- <command>` instead of manually rebuilding runner-specific test names.\n- Use `--rerun-preset review|failed|unsuccessful|all`, repeated `--rerun-environment <id>`, and repeated `--rerun-label name=value` when you need a narrower rerun selection from the previous output.\n- Use `ALLURE_AGENT_STATE_DIR` when you need to override the shared agent state directory for `latest`, `state-dir`, or `--rerun-latest`.\n- Prefer inline `allure agent` expectation flags such as `--goal`, `--expect-tests`, `--expect-test`, `--expect-label`, and `--expect-step-containing`; use `--expectations <file>` only when flags become awkward.\n- Run tests with `allure agent` and review `manifest/run.json`, `manifest/test-events.jsonl`, `index.md`, `manifest/tests.jsonl`, and `manifest/findings.jsonl`.\n- Enrich only the intended tests. Add real steps for real setup, actions, and assertions.\n- Attach only real runtime evidence such as payloads, responses, screenshots, DOM snapshots, diffs, logs, or traces.\n- Keep metadata minimal. Add labels or severity only when scope review, debugging, or quality policy uses them.\n- Instrument stable helpers when several call sites need the same evidence. For example, teach `runCommand` to emit a step instead of wrapping every caller.\n- Reject the rerun if scope drifts, evidence stays weak, or high-confidence noop-style findings remain.";
 export declare const renderAgentsGuide: () => string;

package/dist/guidance.js

@@ -194,6 +194,7 @@ Use when auditing a package, command matrix, feature area, or business behavior
 Commands:
 
 - one scoped \`allure agent --goal <text> --expect-* -- <command>\` run per review group
+- \`allure agent inspect --goal <text> --expect-* <allure-results-dir-or-glob>\` or \`--dump <archive-or-glob>\` when the evidence already exists as local results or CI dump artifacts
 
 Done when:
 
@@ -202,6 +203,24 @@ Done when:
 - runtime artifacts are reviewed before source-only coverage conclusions
 - uncovered behavior is recorded as follow-up test work instead of being hidden in a broad pass/fail summary
 
+### Review Existing Evidence
+
+Use when CI has already produced dump archives or local Allure results already exist and you need agent-readable review artifacts without rerunning tests locally.
+
+Commands:
+
+- \`allure agent inspect <allure-results-dir-or-glob>\`
+- \`allure agent inspect --dump <archive-or-glob>\`
+- \`allure agent inspect --dump <linux.zip> --dump <macos.zip>\`
+- \`allure agent inspect --goal <text> --expect-* --dump <archive-or-glob>\`
+
+Done when:
+
+- all intended result directories or dump artifacts were downloaded or present and matched by the command
+- \`index.md\`, \`manifest/run.json\`, \`manifest/tests.jsonl\`, and \`manifest/findings.jsonl\` were reviewed
+- the review calls out that inspect-derived output cannot add missing live process logs or rerun-time evidence unless those artifacts were captured in the results or dumps
+- any environment-specific gaps between CI jobs are explicit
+
 ### Triage Failures
 
 Use when tests failed, broke, or runner output does not match agent artifacts.
@@ -272,10 +291,11 @@ Done when:
 - console-only conclusions stay provisional until agent-mode artifacts are available`;
 export const AGENT_COMMAND_TASK_MAP = [
     "`allure --version`, `allure agent capabilities --json`, and `allure agent --help`: setup and capability-detection loop. Use when the local CLI surface is unknown, generated guidance may be stale, or you need to choose supported flags without guessing.",
-    "`allure agent --goal ... -- <command>`: test review, feature delivery, smoke-check, and coverage loops. Use when a test command needs runtime evidence, scope expectations, and user-facing conclusions based on agent artifacts rather than console output alone.",
-    "`allure agent latest`: output recovery loop. Use when a previous run omitted `--output`, you need the newest output directory and `index.md` path, or a follow-up task needs prior output before selecting or rerunning tests.",
-    "`allure agent state-dir`: tooling diagnosis loop. Use when `latest` cannot find a run, CI or sandbox state looks wrong, or you need to explain where project-scoped latest pointers are stored.",
-    "`allure agent query --latest summary|tests|findings|test` / `allure agent query --from <output-dir> ...`: output inspection loop. Use when you need a focused JSON summary, filtered tests, filtered findings, or one test from prior agent output without manually loading raw manifests first.",
+    "`allure agent --goal ... -- <command>`: test review, feature delivery, smoke-check, and coverage loops. Use when a test command needs runtime evidence, scope expectations, and user-facing conclusions based on agent artifacts rather than console output alone. The default `--report auto` may also write a human-readable `awesome/index.html` for small runs.",
+    "`allure agent inspect <allure-results-dir-or-glob>` / `allure agent inspect --dump <archive-or-glob>`: existing evidence review loop. Use after downloading one or more dump archives or when Allure results already exist and you need agent-readable markdown, manifests, and optional human report output without rerunning tests locally. Repeat `--dump` to merge multiple environments or jobs.",
+    "`allure agent latest`: output recovery loop. Use when a previous run omitted `--output`, you need the newest output directory and `index.md` path, a user asks for the human-readable report from the last run, or a follow-up task needs prior output before selecting or rerunning tests.",
+    "`allure agent state-dir`: tooling diagnosis loop. Use when `latest` cannot find a run, CI or sandbox state looks wrong, or you need to explain where per-project run registries are stored.",
+    "`allure agent query --latest summary|tests|findings|test` / `allure agent query --from <output-dir> ...`: output inspection loop. Use when you need a focused JSON summary, human-report status, filtered tests, filtered findings, or one test from prior agent output without manually loading raw manifests first.",
     "`allure agent select --latest` / `allure agent select --from <output-dir>`: rerun-planning loop. Use when you need to inspect, filter, or write the Allure test plan from prior results before executing another run. Without `--output`, stdout is raw testplan JSON; with `--output`, stdout summarizes the file path, source output, preset, and selected count.",
     "`allure agent --rerun-latest` / `allure agent --rerun-from <output-dir>`: focused retry loop. Use when prior output already identifies failed, unsuccessful, or review-targeted tests and you should rerun that slice through Allure testplan support instead of rebuilding runner-specific test names.",
     "`ALLURE_AGENT_STATE_DIR=<dir>`: CI and sandbox state-control loop. Use when multiple jobs need a deterministic state location, the default temp state is not shared, or the default state directory is not writable.",
@@ -322,15 +342,18 @@ export const AGENT_INSTRUCTIONS_TEMPLATE = `## Allure Agent Mode Instructions
 - Only skip agent mode when it is impossible or when you are debugging agent mode itself.
 - After each agent-mode test run, print the \`index.md\` path from that run's output directory so users can open the run overview quickly.
 - Use \`allure agent latest\` to print the newest output directory and \`index.md\` path when \`--output\` was omitted.
+- When a user asks for the human-readable report from the last run, use \`allure agent latest\` first if the output directory is unknown, then check \`manifest/human-report.json\`; when its status is \`generated\`, use the path recorded there, usually \`awesome/index.html\`.
 - Use \`allure agent capabilities --json\` when you need structured supported-command, expectation, output, rerun, and unsupported-feature data without scraping help text.
-- Use \`allure agent state-dir\` to inspect where the current project stores its latest-agent state.
+- Use \`allure agent state-dir\` to inspect the shared state directory that stores per-project run registries.
 - Use \`allure agent latest\`, \`state-dir\`, \`query\`, \`select\`, and \`--rerun-*\` according to their loop/task/problem mapping instead of treating them as interchangeable helper commands.
+- Use \`allure agent inspect <allure-results-dir-or-glob>\` or \`allure agent inspect --dump <archive-or-glob>\` when you need agent-readable markdown and manifests from existing Allure results without rerunning tests locally; repeat \`--dump\` for multiple CI jobs or environments.
+- Use \`--report auto|off|awesome|config\` to control human report output. The default \`auto\` mode writes \`awesome/index.html\` for 1000 or fewer stored visible logical results and records generated, skipped, disabled, or failed status in \`manifest/human-report.json\`.
 - Use \`allure agent query --latest summary|tests|findings|test\` or \`allure agent query --from <output-dir> ...\` to inspect prior output as focused JSON before manually opening raw manifests.
 - Use \`allure agent select --latest\` or \`allure agent select --from <output-dir>\` to inspect the review-targeted test plan before rerunning; add \`--output <file>\` when you want the CLI to write the plan and print a short selection summary.
 - Use \`allure agent --rerun-latest -- <command>\` or \`allure agent --rerun-from <output-dir> -- <command>\` to rerun only the selected tests.
 - When rerunning previous failures, use \`allure agent --rerun-latest --rerun-preset failed -- <command>\` or \`allure agent --rerun-from <output-dir> --rerun-preset failed -- <command>\` instead of manually rebuilding runner-specific test names.
 - Use \`--rerun-preset review|failed|unsuccessful|all\`, repeated \`--rerun-environment <id>\`, and repeated \`--rerun-label name=value\` when you need a narrower rerun selection from the previous output.
-- Use \`ALLURE_AGENT_STATE_DIR\` when you need to override where the current project stores latest-agent state for \`latest\`, \`state-dir\`, or \`--rerun-latest\`.
+- Use \`ALLURE_AGENT_STATE_DIR\` when you need to override the shared agent state directory for \`latest\`, \`state-dir\`, or \`--rerun-latest\`.
 - Prefer inline \`allure agent\` expectation flags such as \`--goal\`, \`--expect-tests\`, \`--expect-test\`, \`--expect-label\`, and \`--expect-step-containing\`; use \`--expectations <file>\` only when flags become awkward.
 - Run tests with \`allure agent\` and review \`manifest/run.json\`, \`manifest/test-events.jsonl\`, \`index.md\`, \`manifest/tests.jsonl\`, and \`manifest/findings.jsonl\`.
 - Enrich only the intended tests. Add real steps for real setup, actions, and assertions.
@@ -349,8 +372,9 @@ export const renderAgentsGuide = () => `# AGENTS Guide
 1. Read \`manifest/run.json\` for the current phase, counts, and modeling summary.
 2. Tail \`manifest/test-events.jsonl\` for the newest structured updates while the run is active.
 3. Open \`index.md\` for run-level status, scope summary, and the highest-priority findings.
-4. Open the relevant file under \`tests/<environment>/<historyId-or-trId>.md\` for evidence review.
-5. Follow links into \`.assets/\` for test-scoped artifacts and into \`artifacts/global/\` for process logs such as stdout and stderr.
+4. If a human-readable report is needed, read \`manifest/human-report.json\`; when status is \`generated\`, open the recorded path such as \`awesome/index.html\`.
+5. Open the relevant file under \`tests/<environment>/<historyId-or-trId>.md\` for evidence review.
+6. Follow links into \`.assets/\` for test-scoped artifacts and into \`artifacts/global/\` for process logs such as stdout and stderr.
 
 ## Directory Contract
 
@@ -360,6 +384,8 @@ export const renderAgentsGuide = () => `# AGENTS Guide
 - \`manifest/tests.jsonl\` contains one logical test summary per line.
 - \`manifest/findings.jsonl\` contains one advisory finding per line.
 - \`manifest/expected.json\` contains normalized expectations from inline flags or \`--expectations <file>\` when provided.
+- \`manifest/human-report.json\` records whether a human-readable report was generated, skipped, disabled, or failed.
+- \`awesome/index.html\` is the default single-file human report path when \`--report auto\` or \`--report awesome\` generates it.
 - \`tests/<environment>/<slug>.md\` contains one logical test per file.
 - Retries from the same run are nested inside the same logical test file.
 - \`tests/<environment>/<slug>.assets/\` contains copied attachments for that logical test.

package/dist/harness.d.ts

@@ -1,5 +1,6 @@
 import type { Statistic, TestLabel, TestStatus } from "@allurereport/core-api";
 import { type EnrichmentActionCategory } from "./guidance.js";
+import type { AgentHumanReportStatus } from "./model.js";
 export type AgentFindingSeverity = "info" | "warning" | "high";
 export type AgentFindingCategory = "bootstrap" | "scope" | "metadata" | "evidence" | "smells";
 export type AgentScopeMatch = "match" | "unexpected" | "forbidden" | "unknown";
@@ -111,11 +112,13 @@ export type AgentRunManifest = {
         findings_manifest: string;
         test_events_manifest?: string;
         expected_manifest: string | null;
+        human_report_manifest?: string | null;
         process_logs: {
             stdout: string | null;
             stderr: string | null;
         };
     };
+    human_report?: AgentHumanReportStatus | null;
     modeling?: {
         completeness: "complete" | "partial";
         reasons: string[];
@@ -265,6 +268,7 @@ export type AgentOutputBundle = {
     tests: AgentTestManifestLine[];
     findings: AgentFindingManifestLine[];
     expected?: AgentExpectations;
+    humanReport?: AgentHumanReportStatus;
 };
 export type AgentEnrichmentAction = {
     checkName: string;

package/dist/harness.js

@@ -179,12 +179,16 @@ export const loadAgentOutput = async (outputDir) => {
     const expected = run.paths.expected_manifest && run.expectations_present
         ? await readJson(join(absoluteOutputDir, run.paths.expected_manifest))
         : undefined;
+    const humanReport = run.paths.human_report_manifest
+        ? await readJson(join(absoluteOutputDir, run.paths.human_report_manifest))
+        : undefined;
     return {
         outputDir: absoluteOutputDir,
         run,
         tests,
         findings,
         expected,
+        humanReport,
     };
 };
 export const planAgentEnrichmentReview = (output, options = {}) => {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { type AgentAttachmentExpectationInput, type AgentEvidenceExpectationInput, type AgentExpectationSelectorInput, type AgentExpectationsInput, type AgentPluginOptions, parseAgentExpectations, } from "./model.js";
+export { type AgentAttachmentExpectationInput, type AgentEvidenceExpectationInput, type AgentExpectationSelectorInput, type AgentExpectationsInput, type AgentHumanReportEntry, type AgentHumanReportError, type AgentHumanReportMode, type AgentHumanReportStatus, type AgentHumanReportStatusName, type AgentHumanReportStatusProvider, type AgentPluginOptions, parseAgentExpectations, } from "./model.js";
 export * from "./capabilities.js";
 export * from "./errors.js";
 export * from "./harness.js";

package/dist/invalid-output.js

@@ -1,6 +1,6 @@
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-const isFileNotFoundError = (error) => typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+import { isFileNotFoundError } from "./utils.js";
 const emptyAgentStats = () => ({
     total: 0,
     failed: 0,

package/dist/model.d.ts

@@ -24,6 +24,30 @@ export type AgentExpectationsInput = {
     evidence?: AgentEvidenceExpectationInput;
     notes?: string | string[];
 };
+export type AgentHumanReportMode = "auto" | "off" | "awesome" | "config";
+export type AgentHumanReportStatusName = "pending" | "disabled" | "skipped" | "generated" | "failed";
+export type AgentHumanReportEntry = {
+    plugin_id: string;
+    path: string;
+};
+export type AgentHumanReportError = {
+    plugin_id?: string;
+    message: string;
+};
+export type AgentHumanReportStatus = {
+    schema_version: "allure-agent-human-report/v1";
+    mode: AgentHumanReportMode;
+    status: AgentHumanReportStatusName;
+    result_count: number | null;
+    threshold: number;
+    path: string | null;
+    reports: AgentHumanReportEntry[];
+    reason: string | null;
+    error: string | null;
+    errors?: AgentHumanReportError[];
+    generated_at?: string;
+};
+export type AgentHumanReportStatusProvider = AgentHumanReportStatus | (() => AgentHumanReportStatus | undefined | Promise<AgentHumanReportStatus | undefined>);
 export type AgentPluginOptions = {
     outputDir?: string;
     expectationsPath?: string;
@@ -33,5 +57,6 @@ export type AgentPluginOptions = {
     loopId?: string;
     taskId?: string;
     conversationId?: string;
+    humanReport?: AgentHumanReportStatusProvider;
 };
 export declare const parseAgentExpectations: (rawContent: string) => AgentExpectationsInput;