archal 0.9.19 → 0.9.20

package/dist/vitest/runtime/hosted-session-reaper.js

@@ -4,7 +4,7 @@ import {
   createHostedAuthLease,
   parsePositiveInteger,
   runHostedSessionReaper
-} from "../chunk-WZ7SA4CK.js";
+} from "../chunk-ARVS45PP.js";
 
 // src/runtime/hosted-session-reaper.ts
 var VITEST_AUTH_LEASE_OPTIONS = {

package/dist/vitest/runtime/setup-files.js

@@ -1,7 +1,7 @@
 import {
   bootstrapArchalVitestRouting
-} from "../chunk-L36NXAU6.js";
-import "../chunk-WZ7SA4CK.js";
+} from "../chunk-6CBYFCFK.js";
+import "../chunk-ARVS45PP.js";
 
 // src/runtime/setup-files.ts
 import { existsSync, rmSync } from "fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archal",
-  "version": "0.9.19",
+  "version": "0.9.20",
   "description": "Test your agents & integrations against service clones",
   "type": "module",
   "main": "dist/index.cjs",
@@ -17,6 +17,10 @@
       "types": "./dist/harness.d.cts",
       "default": "./dist/harness.cjs"
     },
+    "./scenarios": {
+      "types": "./dist/scenarios.d.cts",
+      "default": "./dist/scenarios.cjs"
+    },
     "./vitest": {
       "types": "./dist/vitest/index.d.ts",
       "import": "./dist/vitest/index.js",
@@ -47,6 +51,7 @@
     "dist",
     "skills",
     "clone-assets",
+    "agents",
     "LICENSE"
   ],
   "peerDependencies": {
@@ -58,8 +63,8 @@
     }
   },
   "dependencies": {
-    "@aws-sdk/client-secrets-manager": "^3.1001.0",
-    "e2b": "^2.19.5",
+    "@aws-sdk/client-secrets-manager": "^3.1065.0",
+    "e2b": "^2.28.2",
     "picomatch": "^4.0.4"
   },
   "scripts": {

package/skills/archal-agent/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: archal-agent
+description: The front door for using Archal to test, debug, and fix an AI agent. START HERE, then route to the right sub-skill instead of guessing. Use when the user says "use Archal", "test my agent", "set up Archal", "my agent is failing", "reproduce this production failure", "grade my traces", or otherwise wants to evaluate, debug, or auto-fix an agent against service clones. Pick this whenever the request is Archal-shaped but the specific workflow is unclear.
+user-invocable: true
+argument-hint: "[what you want to do with your agent]"
+---
+
+# Archal
+
+You are the entry point for Archal. Archal is the QA layer for AI agents: it
+runs an agent against stateful behavioral clones of real services (GitHub,
+Slack, Stripe, Linear, Jira, Supabase, and more), scores how well it satisfies
+each scenario, and turns failures into reproductions and PR fixes. Your job here
+is to orient the operator and route to the sub-skill that owns their workflow.
+Do not inline those flows; hand off by exact name and let the sub-skill drive.
+
+## Product mental model
+
+Archal tests AI agents against service clones instead of real services, so every
+run is deterministic and replayable. You describe a task and success criteria,
+the agent runs against clones, and an evaluator scores satisfaction (a
+probability, not pass/fail). When a real production trace shows a failure, Archal
+reproduces it on clones from trace evidence and ships the fix as a GitHub PR.
+Everything aims at the same thing: deterministic, replayable evals you can trust.
+
+## Decision guide
+
+| I want to... | Route to |
+|--------------|----------|
+| Set up Archal in a repo from scratch (install, auth, detect clones) | `onboard` |
+| Write or edit a scenario test file | `scenario` |
+| Load explicit JSON/SQL/catalog state into a clone (deterministic, no LLM) | `seed` |
+| Run scenarios or tasks and interpret satisfaction scores and failures | `eval` |
+| Wire clones into an existing Vitest suite | `vitest` |
+| Connect a repo's production observability so traces get captured | `install-agent` |
+| Run the autoloop (ingest -> grade -> find-failed -> reproduce-on-clones) and ship the fix as a PR (autofix) over real trace sources | `autoloop` |
+| Turn autofix or autoloop on/off for an agent | `autoloop`; the copilot can toggle either |
+
+If the user is brand new and has none of this set up, start with `onboard`; it
+detects clones and routes onward from there.
+
+## The sub-skills
+
+Each lives in `packages/archal/skills/` and owns its own commands, contracts,
+and mental model. Route by exact name:
+
+- `onboard` — set up Archal in a repo from scratch: install the CLI, handle auth,
+  detect which clones the agent needs, and hand off to the right workflow.
+- `scenario` — author and edit scenario test files (Setup / Prompt / Expected
+  Behavior / Success Criteria) that `archal run` executes against clones.
+- `seed` — load explicit JSON, SQL, or catalog state into a clone deterministically,
+  with no LLM in the loop, so runs start from a known fixture state.
+- `eval` — run scenarios or inline tasks against clones and interpret the results:
+  satisfaction scores, `[D]` vs `[P]` criteria, trace inspection, failure diagnosis.
+- `vitest` — wire clones into an existing Vitest suite using the right composition
+  pattern, so the agent's own tests route through clones.
+- `install-agent` — connect a repo's production observability (OTLP, Langfuse,
+  Braintrust, database trace tables) so real agent traces are captured for Archal.
+- `autoloop` — the loop over real trace sources: ingest a trace, grade it for a
+  real failure, find the failed trace, and reproduce it on clones. Autofix (the
+  fix/PR step) is a separate toggle on top of this: when turned on, autoloop
+  reproduces a failure and ships the fix as a PR.
+
+## Autoloop and autofix toggles
+
+Autoloop (ingest -> grade -> find-failed -> reproduce-on-clones) and autofix (the
+fix/PR step) are **separate per-agent toggles**. Autofix is opt-in: it is not part
+of autoloop until it is turned on. Either can be switched on or off per agent from
+the agents tab, the CLI (`--execution-policy reproduce` is autoloop with autofix
+off; `fix` turns autofix on), or by asking the Archal copilot in chat — the
+copilot can toggle either for an agent. When the user asks to turn autofix or
+autoloop on/off for an agent, handle the toggle, then route to `autoloop` for the
+deeper flow.
+
+## Provider-switchable remediation
+
+The Archal copilot is not locked to one model. When autofix reproduces a failure
+and writes a fix, the user can drive that remediation with their own agent —
+`archal preprod` exposes `--remediation-agent auto|codex|claude|cursor` so the
+fix is written by their Claude Code, Cursor, or Codex — or let Archal's managed
+agent do it. Mention this when the user asks who writes the fix or wants to use
+their own coding agent, then route to `autoloop`.
+
+## Docs
+
+- Quickstart: https://docs.archal.ai/quickstart
+- Full docs: https://docs.archal.ai

package/skills/{attach → autoloop}/SKILL.md

@@ -1,22 +1,27 @@
 ---
-name: attach
-description: Connect Archal Attach to a repo and trace source, validate prerequisites, configure trace schema mapping, and diagnose import, grade, reproduction, and PR-fix runs.
+name: autoloop
+description: Wire Archal Autoloop to a repo plus a real agent-trace source, then drive the import -> grade -> reproduce -> PR-fix loop. USE THIS whenever the user wants to turn production agent traces into reproducible failures and fixes: "I have prod agent traces and want to reproduce a failure", "import my Langfuse / Braintrust / OTel / Supabase traces", "connect a trace source", "grade my prod traces", "turn a failed trace into a PR", "set up / configure the autoloop", or any mention of replaying, grading, or auto-fixing real traces. Also fires when diagnosing a stuck import, grade, reproduction, or PR-fix run, or configuring trace schema mapping.
 user-invocable: true
 argument-hint: "[repo, trace source, or failure description]"
 ---
 
-# Archal Attach
+# Archal Autoloop
 
 You help users connect real agent traces to Archal. Your job is to wire the repo,
 trace source, harness contract, scenario contract, and GitHub PR path without
 guessing or leaking secrets.
 
-Attach is not a replacement for `archal run`. It uses the same harness and clone
+Autoloop is not a replacement for `archal run`. It uses the same harness and clone
 routing ideas, but the trigger is a trace that already happened.
 
+Autoloop is also not arbitrary production trace replay. It can reproduce a
+failure only when the trace, scenario contract, and seed templates contain
+enough evidence to reconstruct the service state that matters. If the evidence
+is thin, block and name the missing data instead of claiming reproduction.
+
 ## Product mental model
 
-Attach does this loop:
+Autoloop does this loop:
 
 1. Import a trace and its child spans from a read-only source.
 2. Grade whether the trace contains a real failure.
@@ -25,17 +30,25 @@ Attach does this loop:
 4. Run the reproduction against service clones through the customer harness.
 5. If reproduced, patch the repo and open a GitHub issue or PR.
 
-Default policy is `fix`. Narrower policies stop earlier:
+Steps 1-4 are **autoloop**: ingest -> grade -> find the failed trace ->
+reproduce on clones. Step 5 (writing the fix and opening the PR) is **autofix**,
+a separate opt-in step that is *not* part of autoloop until it is turned on.
+Both are per-agent toggles, switchable from the agents tab, the CLI, or by asking
+the Archal copilot in chat.
+
+The CLI maps these toggles to `--execution-policy`: `reproduce` runs autoloop
+only with autofix off, while `fix` turns autofix on (autoloop plus the fix/PR
+step). Narrower policies stop earlier:
 
-| Policy | Stops after |
-|--------|-------------|
-| `observe` | import |
-| `grade` | grading |
-| `reproduce` | reproduction |
-| `fix` | PR or blocked fix status |
+| Policy | Stops after | Autofix |
+|--------|-------------|---------|
+| `observe` | import | off |
+| `grade` | grading | off |
+| `reproduce` | reproduction | off |
+| `fix` | PR or blocked fix status | on |
 
 Do not invent or promote separate top-level judge, reproduce, fix, or
-trace-replay commands. The public command is `archal attach`. Local stop
+trace-replay commands. The public command is `archal autoloop`. Local stop
 command is `archal detach` for file-backed trace directories.
 
 ## Discover first
@@ -67,6 +80,8 @@ Before changing anything, inspect the repo:
    Hosted sources and `--execution-policy fix` need a GitHub remote.
 5. Trace source shape, if available:
    - provider: local files, Postgres, Supabase
+   - or local/client-ingested sources normalized through `archal trace-source`
+     such as file, HTTP/OTel, Langfuse, Braintrust, S3/GCS, or custom JSON
    - trace table and span table names
    - id columns
    - parent span column
@@ -78,7 +93,7 @@ only the env var name or secret reference.
 
 ## Preconditions
 
-You need these before a full hosted Attach setup:
+You need these before a full hosted Autoloop setup:
 
 - Archal CLI installed in the repo or reachable with `npx archal`
 - authenticated user (`archal login`) or `ARCHAL_TOKEN=archal_ws_...`
@@ -132,7 +147,7 @@ The command must be headless and repeatable. It should run the real agent path,
 not a hand-authored mock. During reproduction, Archal invokes this command
 through `archal run`, so the agent should read the task from `AGENT_TASK` and
 print its final answer to stdout. If the project already has `.archal.json` for
-`archal run`, align the Attach harness with that command.
+`archal run`, align the Autoloop harness with that command.
 
 ### 3. Add or verify `archal/scenario.md`
 
@@ -174,127 +189,75 @@ archal/seeds/
   jira-escalations.json
 ```
 
-Seed templates should contain stable service state for the task family. Attach
+Seed templates should contain stable service state for the task family. Autoloop
 can then fill in trace-specific identifiers. This is much safer than expecting
 weak traces to reconstruct full service state.
 
 ## Hosted database source
 
-Use this when traces live in Postgres or Supabase.
-
-First, create or request a read-only database user. Then keep the URL in an env
-var:
-
-```bash
-export TRACE_DATABASE_URL='postgres://readonly:...'
-```
-
-Run a check:
-
-```bash
-npx archal attach \
-  --repo . \
-  --source supabase \
-  --database-url-env TRACE_DATABASE_URL \
-  --source-id prod-agent-traces \
-  --check
-```
+Use this when traces live in Postgres or Supabase. Create a read-only DB user,
+keep the URL in `TRACE_DATABASE_URL` (or a secret ref in hosted production), then
+`--check` the source and re-run without `--check` to register it. Registration
+posts the source config to Archal and returns; hosted workers own polling after
+that, so local `archal detach` does not disable it.
 
-Register:
+See `references/hosted-sources.md` for the full check, register, and
+`--database-url-secret-ref` flag blocks.
 
-```bash
-npx archal attach \
-  --repo . \
-  --source supabase \
-  --database-url-env TRACE_DATABASE_URL \
-  --source-id prod-agent-traces
-```
+## Client-side trace ingestion
 
-This posts the source config to Archal and returns. It does not start a local
-watcher and does not write local source state.
+Use `archal trace-source` when traces are not already in a hosted Postgres or
+Supabase table. This command normalizes source-specific payloads into Archal
+trace upload envelopes, writes them to a trace directory, and can upload them to
+hosted Autoloop when workspace auth is available.
 
-Use a secret reference when the customer already has one:
+Common paths:
 
 ```bash
-npx archal attach \
-  --repo . \
-  --source postgres \
-  --database-url-secret-ref aws-secretsmanager://customer/prod-agent-traces
+npx archal trace-source import ./exports --preview --json
+npx archal trace-source import ./exports --upload --repository owner/repo
+
+npx archal trace-source connect langfuse \
+  --base-url https://cloud.langfuse.com \
+  --api-key-env LANGFUSE_READ_KEY \
+  --out .archal/traces/inbox
+npx archal trace-source test langfuse
+npx archal trace-source sync langfuse --upload --repository owner/repo
+npx archal trace-source watch langfuse --upload --repository owner/repo
+
+npx archal trace-source connect custom --name "prod exporter" --out .archal/traces/inbox
+npx archal trace-source serve "prod exporter" --port 4319
 ```
 
-`--database-url-secret-ref` must not contain a plaintext credential.
+Use `archal trace-source status [source]` to inspect registry validation,
+cursor, and last-sync state. `watch` is for pull-style sources; push sources
+stay continuous through `serve`.
 
 ## Trace schema mapping
 
-Defaults:
+Hosted sources default to `ai_traces` / `ai_spans` with `id` / `trace_id`
+columns and `updated_at_id` cursor mode. When the customer's tables differ, pass
+mapping flags to override table names, id columns, parent-span column, and
+cursor columns; switch to `created_at_id` cursor mode for append-only sources;
+and use `--source-*` filters to scope noisy sources by workspace, agent, status,
+trace group, or limit.
 
-| Concept | Default |
-|---------|---------|
-| trace table | `ai_traces` |
-| span table | `ai_spans` |
-| trace id | `id` |
-| span id | `id` |
-| span trace id | `trace_id` |
-| trace updated cursor | `updated_at` |
-| span updated cursor | `updated_at` |
-| cursor mode | `updated_at_id` |
-
-For a custom schema, pass mapping flags:
-
-```bash
-npx archal attach \
-  --repo . \
-  --source postgres \
-  --database-url-env TRACE_DATABASE_URL \
-  --trace-table public.agent_traces \
-  --span-table public.agent_spans \
-  --trace-id-column trace_id \
-  --span-id-column span_id \
-  --span-trace-id-column trace_id \
-  --parent-span-id-column parent_span_id \
-  --trace-updated-at-column updated_at \
-  --span-updated-at-column updated_at
-```
-
-For append-only sources:
-
-```bash
-npx archal attach \
-  --repo . \
-  --source supabase \
-  --database-url-env TRACE_DATABASE_URL \
-  --cursor-mode created_at_id \
-  --trace-created-at-column created_at \
-  --span-created-at-column created_at
-```
-
-Use filters for noisy sources:
-
-```bash
-npx archal attach \
-  --repo . \
-  --source supabase \
-  --database-url-env TRACE_DATABASE_URL \
-  --source-workspace-id workspace_123 \
-  --source-agent-id support-agent \
-  --source-status failed error \
-  --source-trace-group billing-support \
-  --source-limit 250
-```
+See `references/trace-schema-mapping.md` for the full defaults table plus the
+custom-schema, append-only, and filter flag blocks.
 
 ## Local trace directory
 
 Use this for a local pilot or exported trace files:
 
 ```bash
-npx archal attach ./prod-traces --repo . --execution-policy reproduce
+npx archal autoloop ./prod-traces --repo . --execution-policy reproduce
 ```
 
 Artifacts are written under:
 
 ```text
-.archal/attach/
-  attachments.json
+.archal/autoloop/
+  autoloops.json
   runs.jsonl
   raw/
   grades/
@@ -313,17 +276,25 @@ npx archal detach ./prod-traces --repo .
 
 Do not describe `archal detach` as a hosted source disable command.
 
-## Dashboard expectations
+## CLI-first operation
 
-The workspace dashboard has three Attach pages:
+Prefer CLI and artifact evidence for handoffs unless the user explicitly asks
+for a workspace page.
 
-- Imported traces: source status, imported rows, grade verdict, blocked reason.
-- Reproduced failures: seed evidence, reproduction status, clone parity, run
-  artifacts.
-- Opened issues/PRs: GitHub issue, PR, branch, checks, and fix status.
+- Local file-backed loops: `archal autoloop <trace-dir> --repo ...` starts the
+  watcher, `archal detach <trace-dir> --repo ...` stops it, `archal
+  autoloop-status --repo ...` summarizes trace jobs, and `archal
+  autoloop-reprocess --repo ... <trace-id>` retries terminal jobs after a
+  blocker is fixed.
+- Hosted database sources: `archal autoloop --source postgres|supabase ...`
+  registers the source and returns. Local `archal detach` does not disable a
+  hosted source because hosted workers own polling after registration.
+- Safe resume means re-running the same `archal autoloop` registration or
+  reprocessing a terminal local trace only after the missing evidence,
+  credential, mapping, harness, or GitHub blocker is corrected.
 
-Do not route users to an old single Attach page. The user-facing pages are the
-three workspace dashboard pages above.
+Report exact artifact paths and statuses. Do not make dashboard pages the only
+place a user can understand what happened.
 
 ## How to diagnose failures
 
@@ -331,6 +302,8 @@ Classify failures precisely:
 
 - Trace import failure: database/source auth, mapping, cursor, filters, bad
   trace shape.
+- Trace ingestion failure: `trace-source` adapter mismatch, rejected hosted
+  upload, missing workspace auth, bad idempotency key, or receiver auth failure.
 - Grade failure: judge could not determine expected outcome, missing evaluator
   contract, trace lacks task context.
 - Missing evidence: trace does not contain enough state to seed. Add spans,
@@ -351,7 +324,7 @@ claim reproduction succeeded.
 
 ## Artifact reading guide
 
-Local file-backed Attach uses repo-local artifacts. Hosted Attach exposes the
+Local file-backed Autoloop uses repo-local artifacts. Hosted Autoloop exposes the
 same phase information in the dashboard.
 
 | Artifact | What to inspect |
@@ -387,7 +360,7 @@ After setup or debugging, give the user:
 - source provider and source id
 - repo full name
 - execution policy
-- dashboard pages to inspect
+- CLI status command to run next
 - artifacts produced, if local
 - whether import, grade, seed, reproduce, and fix phases are ready
 - exact blocker if any
@@ -395,8 +368,9 @@ After setup or debugging, give the user:
 
 ## Docs
 
-- Attach production traces: https://docs.archal.ai/guides/attach-production-traces
-- CLI reference: https://docs.archal.ai/cli/attach
+- Autoloop production traces: https://docs.archal.ai/guides/autoloop-production-traces
+- Autonomous loops: https://docs.archal.ai/guides/autoloop-production-traces
+- CLI reference: https://docs.archal.ai/cli/autoloop
 - Running with an agent: https://docs.archal.ai/guides/run-with-agent
 - Writing scenarios: https://docs.archal.ai/guides/writing-scenarios
 - Seeds: https://docs.archal.ai/guides/seeds

package/skills/autoloop/references/hosted-sources.md

@@ -0,0 +1,62 @@
+# Hosted database source
+
+Full flag reference for registering a hosted Postgres or Supabase trace source.
+Use this when traces live in Postgres or Supabase. Registration posts the source
+config to Archal and returns; hosted workers own polling after that.
+
+## Contents
+
+- Read-only credential
+- Check the source
+- Register the source
+- Secret reference (hosted production)
+
+## Read-only credential
+
+First, create or request a read-only database user. Then keep the URL in an env
+var:
+
+```bash
+export TRACE_DATABASE_URL='postgres://readonly:...'
+```
+
+## Check the source
+
+Run a check:
+
+```bash
+npx archal autoloop \
+  --repo . \
+  --source supabase \
+  --database-url-env TRACE_DATABASE_URL \
+  --source-id prod-agent-traces \
+  --check
+```
+
+## Register the source
+
+Register:
+
+```bash
+npx archal autoloop \
+  --repo . \
+  --source supabase \
+  --database-url-env TRACE_DATABASE_URL \
+  --source-id prod-agent-traces
+```
+
+This posts the source config to Archal and returns. It does not start a local
+watcher and does not write local source state.
+
+## Secret reference (hosted production)
+
+Use a secret reference when the customer already has one:
+
+```bash
+npx archal autoloop \
+  --repo . \
+  --source postgres \
+  --database-url-secret-ref aws-secretsmanager://customer/prod-agent-traces
+```
+
+`--database-url-secret-ref` must not contain a plaintext credential.

package/skills/autoloop/references/trace-schema-mapping.md

@@ -0,0 +1,73 @@
+# Trace schema mapping
+
+Full mapping-flag reference for hosted Postgres/Supabase trace sources. Use this
+when the customer's trace and span tables do not match the defaults below.
+
+## Contents
+
+- Defaults
+- Custom schema flags
+- Append-only sources
+- Filters for noisy sources
+
+## Defaults
+
+| Concept | Default |
+|---------|---------|
+| trace table | `ai_traces` |
+| span table | `ai_spans` |
+| trace id | `id` |
+| span id | `id` |
+| span trace id | `trace_id` |
+| trace updated cursor | `updated_at` |
+| span updated cursor | `updated_at` |
+| cursor mode | `updated_at_id` |
+
+## Custom schema flags
+
+For a custom schema, pass mapping flags:
+
+```bash
+npx archal autoloop \
+  --repo . \
+  --source postgres \
+  --database-url-env TRACE_DATABASE_URL \
+  --trace-table public.agent_traces \
+  --span-table public.agent_spans \
+  --trace-id-column trace_id \
+  --span-id-column span_id \
+  --span-trace-id-column trace_id \
+  --parent-span-id-column parent_span_id \
+  --trace-updated-at-column updated_at \
+  --span-updated-at-column updated_at
+```
+
+## Append-only sources
+
+For append-only sources:
+
+```bash
+npx archal autoloop \
+  --repo . \
+  --source supabase \
+  --database-url-env TRACE_DATABASE_URL \
+  --cursor-mode created_at_id \
+  --trace-created-at-column created_at \
+  --span-created-at-column created_at
+```
+
+## Filters for noisy sources
+
+Use filters for noisy sources:
+
+```bash
+npx archal autoloop \
+  --repo . \
+  --source supabase \
+  --database-url-env TRACE_DATABASE_URL \
+  --source-workspace-id workspace_123 \
+  --source-agent-id support-agent \
+  --source-status failed error \
+  --source-trace-group billing-support \
+  --source-limit 250
+```

package/skills/eval/SKILL.md

@@ -90,6 +90,40 @@ Exit codes: `0` pass, `1` fail or score < threshold, `2` validation error. For G
 
 Workspace API keys are runtime and CI credentials bound to one workspace. They can run clones, upload and read traces, and read usage for that workspace. They cannot manage audit events or workspace API keys. Use an owner/admin user credential, either `archal login` or a dashboard-issued user API key, for workspace administration.
 
+## Pre-production autonomous loop
+
+Use `archal preprod start` when the user wants a coding agent to run a bounded
+pack of scenarios before shipping, remediate failures, rerun, validate, and
+open a draft PR. This is different from post-production `archal autoloop`: it
+starts from repo scenarios and clone runs, not imported production traces.
+
+First do a safe dry run:
+
+```bash
+archal preprod start --scenario-count 20 --dry-run --artifacts .archal/preprod
+```
+
+Then, only after the dry-run artifacts look like real agent/scenario failures,
+allow the managed remediation path:
+
+```bash
+archal preprod start \
+  --scenario-count 20 \
+  --allow-external-execution \
+  --remediation-agent codex \
+  --validation-command 'pnpm test' \
+  --open-pr \
+  --pr-command 'gh pr create --draft --fill' \
+  --artifacts .archal/preprod
+```
+
+Read `.archal/preprod/preprod-result.json`,
+`.archal/preprod/preprod-failures.json`, and the remediation context before
+summarizing results. Treat runs without validation evidence as local
+remediation passes, not release proof. If a run stops after `initial-runs`,
+`fix`, or `validation`, resume with `archal preprod start --resume
+.archal/preprod --artifacts .archal/preprod`.
+
 ## Artifacts + dashboard
 
 - **Local (always written):** `.archal/cache/last-run.json` (summary), `.archal/cache/runs/*.json` (full redacted trace).
@@ -108,6 +142,6 @@ Don't tell users they need `-o json` to save artifacts locally - that's only for
 ## Docs
 
 - Running with an agent: https://docs.archal.ai/guides/run-with-agent
-- Existing repo playbook: https://docs.archal.ai/guides/existing-agent-repo
+- Existing repo playbook: https://docs.archal.ai/guides/run-with-agent
 - Scenario authoring: hand off to the `scenario` skill
 - Clone sessions: https://docs.archal.ai/guides/clone-sessions