archal 0.9.19 → 0.10.0

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

@@ -0,0 +1,104 @@
+# Trace schema mapping
+
+Config reference for hosted Postgres/Supabase trace sources whose trace and span
+tables do not match the defaults below. Schema mapping, cursor mode, and filters
+live in the `.archal.json` `autoloop` block under `autoloop.source`, not in flags.
+
+## Contents
+
+- Defaults
+- Custom schema
+- Append-only sources
+- Filters for noisy sources
+
+## Defaults
+
+| Concept | Config field | Default |
+|---------|--------------|---------|
+| trace table | `source.mapping.traces.table` | `ai_traces` |
+| span table | `source.mapping.spans.table` | `ai_spans` |
+| trace id | `source.mapping.traces.idColumn` | `id` |
+| span id | `source.mapping.spans.idColumn` | `id` |
+| span trace id | `source.mapping.spans.traceIdColumn` | `trace_id` |
+| span parent id | `source.mapping.spans.parentSpanIdColumn` | `parent_span_id` |
+| trace updated cursor | `source.mapping.traces.updatedAtColumn` | `updated_at` |
+| span updated cursor | `source.mapping.spans.updatedAtColumn` | `updated_at` |
+| cursor mode | `source.cursor.mode` | `updated_at_id` |
+
+## Custom schema
+
+For a custom schema, set the mapping in `.archal.json`. Only the fields that
+differ from the defaults are required:
+
+```jsonc
+// .archal.json
+{
+  "autoloop": {
+    "source": {
+      "mapping": {
+        "traces": {
+          "table": "public.agent_traces",
+          "idColumn": "trace_id",
+          "updatedAtColumn": "updated_at"
+        },
+        "spans": {
+          "table": "public.agent_spans",
+          "idColumn": "span_id",
+          "traceIdColumn": "trace_id",
+          "parentSpanIdColumn": "parent_span_id",
+          "updatedAtColumn": "updated_at"
+        }
+      }
+    }
+  }
+}
+```
+
+## Append-only sources
+
+For append-only sources, switch the cursor to `created_at_id` and point it at the
+created-at columns:
+
+```jsonc
+// .archal.json
+{
+  "autoloop": {
+    "source": {
+      "cursor": { "mode": "created_at_id" },
+      "mapping": {
+        "traces": { "createdAtColumn": "created_at" },
+        "spans": { "createdAtColumn": "created_at" }
+      }
+    }
+  }
+}
+```
+
+`source.cursor.watermarks` is a repair escape hatch: set
+`{ traces: { at, id }, spans: { at, id } }` (any of which may be `null`) only when
+you need to re-seat the cursor after a bad import.
+
+## Filters for noisy sources
+
+Use filters to narrow a noisy source. All filter fields are optional:
+
+```jsonc
+// .archal.json
+{
+  "autoloop": {
+    "source": {
+      "filters": {
+        "workspaceIds": ["workspace_123"],
+        "agentIds": ["support-agent"],
+        "statuses": ["failed", "error"],
+        "traceGroups": ["billing-support"],
+        "limit": 250
+      }
+    }
+  }
+}
+```
+
+Arbitrary source metadata for the registration goes under `source.metadata` (a
+map of short-identifier keys to string values). Regression scenarios export is a top-level
+`autoloop.benchmarkExport: true` (the config key keeps the legacy `benchmark` name).

package/skills/eval/SKILL.md

@@ -2,7 +2,7 @@
 name: eval
 description: Run Archal scenarios or inline tasks against hosted clones, diagnose failed runs, and interpret satisfaction scores. Triggers on "run my scenario", "evaluate my agent", "archal run X", "debug this failing run", "what does this satisfaction score mean".
 user-invocable: true
-argument-hint: "[scenario.md or task description]"
+argument-hint: '[scenario.md or task description]'
 ---
 
 # Archal Eval Runner
@@ -35,14 +35,14 @@ If a local harness returns text but records zero clone-observed calls, check for
 Scenario from a file:
 
 ```bash
-archal run scenario.md
-archal run scenario.md --runs 5 --seed enterprise-repo   # N runs -> satisfaction score
+archal run scenario.md --docker
+archal run scenario.md --docker --runs 5 --seed enterprise-repo   # N runs -> satisfaction score
 ```
 
 Inline task (no scenario file):
 
 ```bash
-archal run --task "Create an issue titled hello" --harness ./.archal/harness.mjs --clone github
+archal run --task "Create an issue titled hello" --harness ./.archal/harness.mjs --docker --clone github
 ```
 
 `--task` only replaces the scenario file - it still needs a runnable agent path. `--clone` is required with `--task`; repeat or comma-separate for multiple clones.
@@ -52,11 +52,13 @@ When `.archal.json` exists in cwd, bare `archal run` uses it. If the user doesn'
 ## Interpret results
 
 Score breakdown:
+
 - `100%` = every run passed every criterion
 - `80%` = 4/5 runs passed
 - `0%` = none passed
 
 Criterion types:
+
 - `[D]` - deterministic state check. A failure is real; never a model variance artifact.
 - `[P]` - LLM judge reads trace + final state. A single failure can be variance; re-run with `--runs 3+` to confirm before acting on it.
 
@@ -65,30 +67,30 @@ Criterion types:
 Re-run with `-v` for the full trace, then classify with these signals:
 
 - **Agent bug** - wrong tool called, wrong arguments, stopped early.
-  *Signals:* trace shows the correct tool was available but the agent chose another; or arguments are malformed.
-  *Fix:* agent prompt, tool wiring, or underlying model.
+  _Signals:_ trace shows the correct tool was available but the agent chose another; or arguments are malformed.
+  _Fix:_ agent prompt, tool wiring, or underlying model.
 
 - **Scenario bug** - criteria are too strict, ambiguous, or contradict the Setup.
-  *Signals:* agent clearly did the right thing but a `[D]` criterion expects an exact count the Setup didn't guarantee; or two criteria contradict each other.
-  *Fix:* make Setup more specific, or relax the criterion. Use the `scenario` skill.
+  _Signals:_ agent clearly did the right thing but a `[D]` criterion expects an exact count the Setup didn't guarantee; or two criteria contradict each other.
+  _Fix:_ make Setup more specific, or relax the criterion. Use the `scenario` skill.
 
 - **Seed mismatch** - clone state doesn't match what Setup describes.
-  *Signals:* agent's first introspection tool call returns unexpected state (e.g. Setup says "4 stale issues" but the seed has 3).
-  *Fix:* different seed, or adjust Setup to match. `archal seed list <clone>` to browse.
+  _Signals:_ agent's first introspection tool call returns unexpected state (e.g. Setup says "4 stale issues" but the seed has 3).
+  _Fix:_ different seed, or adjust Setup to match. `archal seed list <clone>` to browse.
 
 - **Harness bug** - agent process never started, crashed immediately, or hung.
-  *Signals:* no tool calls in the trace, stderr shows a boot error, or the run times out at the configured `--timeout`.
-  *Fix:* smoke-test the harness directly with `AGENT_TASK="Reply with OK." node ./.archal/harness.mjs`, then look for an untouched starter stub, UI-only imports, missing provider keys, or interactive auth.
+  _Signals:_ no tool calls in the trace, stderr shows a boot error, or the run times out at the configured `--timeout`.
+  _Fix:_ smoke-test the harness directly with `AGENT_TASK="Reply with OK." node ./.archal/harness.mjs`, then look for an untouched starter stub, UI-only imports, missing provider keys, or interactive auth.
 
 ## CI mode
 
 ```bash
-archal run scenario.md --runs 3 --pass-threshold 80 -o json -q
+archal run scenario.md --docker --runs 3 --pass-threshold 80 -o json -q
 ```
 
 Exit codes: `0` pass, `1` fail or score < threshold, `2` validation error. For GitHub Actions, inject `ARCHAL_TOKEN` as a secret. Use a workspace API key (`archal_ws_...`) for CI, not a personal token.
 
-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.
+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. Create/list/revoke them with `archal workspace api-key create <label>`, `archal workspace api-keys`, and `archal workspace api-key revoke <key-id>` from an owner/admin user session. Use an owner/admin user credential, either `archal login` or a dashboard-issued user API key, for workspace administration.
 
 ## Artifacts + dashboard
 
@@ -108,6 +110,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

package/skills/free-account/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: free-account
+description: B2C free-tier guide — run scenarios and start clones within free entitlements. Use when an orchestrating or coding agent should use Archal under a free user account to "run my agent", evaluate a task against clones, or spin up clones without paid features.
+user-invocable: true
+argument-hint: "[repo, task, or 'run my agent']"
+---
+
+# Archal Free Account
+
+You are driving Archal under a free user account. Archal tests AI agents against
+clones of real services (GitHub, Slack, Stripe, etc.). On free, you can run
+scenarios and start clones within the free entitlements. You cannot start any
+autonomous loop, remediation, or observability-install flow. Stay inside the
+allowed commands below and never attempt a blocked one.
+
+## Authenticate first
+
+Do this before any other command.
+
+```bash
+archal login                # OAuth browser flow -> ~/.archal/credentials.json
+archal usage                # verify auth + plan
+```
+
+In CI, skip the browser flow and set a token:
+
+```bash
+export ARCHAL_TOKEN=...      # workspace or user token
+archal usage
+```
+
+Sessions are Archal-hosted, so provider credentials may be placeholders. You do
+not need real GitHub, Slack, or Stripe keys to start a clone or run a scenario.
+
+## Free limits
+
+State these upfront so the user is not surprised mid-run.
+
+| Limit | Free value |
+|-------|-----------|
+| Cost | $0 |
+| Workspace | free workspace entitlements only |
+| Concurrent sessions | 3 |
+| Session TTL | 30 minutes |
+| Credits | 5,000 per month, recurring |
+
+If the user asks for paid workspace capabilities, point them to
+https://archal.ai/contact. Do not attempt blocked actions.
+
+## Allowed commands only
+
+Use only these on free. Nothing else.
+
+```bash
+archal run <scenario.md>           # run a scenario against clones
+archal clone start [clones...]     # start one or more hosted clones
+archal clone status                # inspect the active session
+archal clone stop                  # tear the session down
+archal clone                       # list available clones
+archal clone seed <clone> <name>   # apply a named seed to a running clone
+archal scenario list               # list scenarios
+archal seed list                   # list seeds
+archal usage                       # check plan, credits, and quota
+```
+
+## Prohibited on free
+
+Never instruct any of these. They are Pro features and fail closed: the web
+returns HTTP 402 and the CLI fails closed with an entitlement error. Do not run
+them, do not retry them, and do not describe them as available.
+
+- autonomous remediation loops (`archal autoloop ...`)
+- remediation / fix runs
+- `archal autoloop detach`
+- observability-install flow
+
+This mirrors the server-side blocked set: `start_loop`, `reproduce_failure`,
+`retry_loop`, `connect_observability`. If the user wants any of these, point
+them to https://archal.ai/contact.
+
+## Quota awareness
+
+Check quota with `archal usage` before a run, and watch for quota-exceeded
+results during a run. On quota-exceeded, stop and direct the user to
+https://archal.ai/contact. Do not retry a blocked or over-quota command, and do
+not try to work around the limit.
+
+## What to report back
+
+After a run or clone session, give the user:
+
+- command run
+- satisfaction score or clone session id
+- credits used and remaining (from `archal usage`)
+- the upgrade pointer (https://archal.ai/contact) if anything was blocked or
+  over quota
+
+## Docs
+
+- Quickstart: https://docs.archal.ai/quickstart
+- Contact for plan changes: https://archal.ai/contact
+- Writing scenarios: https://docs.archal.ai/guides/writing-scenarios
+- Clones and seeds: https://docs.archal.ai/clones/overview

package/skills/install-agent/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: install-agent
+description: Connect an agent's repo and its production observability to Archal so its traces get captured and graded. Detects an existing observability stack (LangSmith, Langfuse, Datadog, OpenTelemetry, Braintrust), connects the GitHub App, opens an observability setup PR, and routes an existing trace vendor's output to the dashboard OTLP endpoint or autoloop hosted ingest. USE THIS whenever the user says "connect my agent", "install the Archal agent", "set up observability", "capture my agent's traces", "hook up my production traces", "where do my traces go", or asks how to get an already-running agent into Archal. Reach for it before telling anyone a capability is missing — read the honest limits below first.
+user-invocable: true
+argument-hint: "[repo + where its traces live]"
+---
+
+# Archal Install Agent
+
+You are connecting a real, already-running agent to Archal so its production
+behavior gets captured and graded. Two things have to land: (1) Archal can read
+the **repo** (GitHub App), and (2) Archal can read the agent's **traces** —
+either by adding instrumentation through a setup PR, or by ingesting an existing
+observability vendor. Once traces flow, grading and the autoloop take over.
+
+Be honest about what this is. The "install agent" is **not** a sandboxed coding
+agent that edits arbitrary code in the repo. It is deterministic repo inspection
+plus a deterministic, templated setup PR, plus an optional one-shot managed
+planner (an LLM call) that only relocates the bootstrap file and writes advisory
+PR-body text. Set that expectation up front so nobody waits for an autonomous
+coder that does not exist yet. The honest limit is spelled out below — do not
+oversell it.
+
+## Why this exists
+
+Archal grades agent behavior from traces. An agent that already runs in
+production has traces somewhere — your own logs, or a vendor like Langfuse or
+Braintrust. The install path's whole job is to get those traces into Archal's
+normalized shape without you hand-writing exporters or copying secrets around.
+Capturing the trace is the precondition for everything downstream: grading,
+reproduction, and the autoloop that turns reproduced failures into PRs.
+
+## Discover first
+
+Before changing anything, read the repo and find out where traces live:
+
+1. `package.json` / `pyproject.toml` / `requirements.txt`: language and
+   framework. Language matters — the planner and `@archal/state-capture` are
+   TypeScript-only today (see limits).
+2. Existing observability dependencies. Archal's detector recognizes exactly
+   five vendors by dependency name:
+   - `langsmith` -> LangSmith
+   - `langfuse`, `langfuse-node` (TS) / `langfuse` (py) -> Langfuse
+   - `dd-trace` (TS) / `ddtrace` (py) -> Datadog
+   - `@opentelemetry/sdk-node`, `@opentelemetry/sdk-trace-node` (TS) /
+     `opentelemetry-sdk` (py) -> OpenTelemetry
+   - `braintrust` -> Braintrust
+   A repo with any of these is a candidate for **augment**; a repo with none is
+   **greenfield**.
+3. GitHub remote — augment/greenfield setup PRs and the autoloop need a GitHub
+   remote that resolves to `github.com/<owner>/<repo>`:
+   ```bash
+   git remote get-url origin
+   ```
+4. Where do the traces actually go? Ask the user. The answer routes you:
+   - already in a hosted vendor (Langfuse, Braintrust) or a Postgres/Supabase
+     table -> hosted autoloop ingest path (delegate detail to `autoloop` skill)
+   - exported files on disk -> drop into an autoloop watch directory or send via dashboard OTLP
+   - nowhere yet / only app logs -> the observability setup PR
+
+Never print secrets while inspecting. Show env var names or secret references,
+never plaintext keys or database URLs.
+
+## Preconditions
+
+- Archal CLI installed in the repo or reachable with `npx archal`
+- authenticated user (`archal login`) or `ARCHAL_TOKEN=archal_ws_...` (a
+  workspace key for CI)
+- the **Archal GitHub App** installed on the target repo (required for the setup
+  PR and for autoloop fix PRs)
+- a GitHub remote resolving to `github.com/<owner>/<repo>`
+- for the ingest path: a read-only credential for the trace vendor
+
+If a precondition is missing, make the smallest safe change and name what is
+still required. Do not fake a connection.
+
+## Step 1 — connect the GitHub App
+
+The repo connection is the GitHub App, not a token paste. Confirm the **Archal
+GitHub App** is installed on the target repository and that the org granted it
+access. Without it, the setup PR cannot be opened and the autoloop cannot open
+fix PRs. If it is not installed, send the user to the dashboard's integration
+flow to install it, then continue.
+
+## Step 2 — open the observability setup PR
+
+When traces are not yet exported anywhere (or the user wants Archal's own
+capture), open the **observability setup PR**. It is a deterministic, templated
+patch — every file's contents are pre-generated; nothing is freely authored by
+an LLM. The patch resolves into one of two install modes:
+
+### Greenfield (no existing observability detected)
+
+Adds standard OpenTelemetry instrumentation pointed at Archal's OTLP endpoint:
+
+- `archal-otel.ts` (TS) or `archal_otel.py` (Python) — an OpenTelemetry init
+  bootstrap (OTLP HTTP exporter + the node/python SDK), **not** an Archal-only
+  exporter
+- `archal-replay-capsule.ts` / `archal_replay_capsule.py` — a replay helper
+  template
+- OpenTelemetry SDK + framework instrumentation added to `package.json` (TS) or
+  `requirements.txt` (Python)
+- an `.env.example` entry for the workspace key and an `ARCHAL_OBSERVABILITY.md`
+  guide
+
+### Augment (existing observability detected, TypeScript only)
+
+When the repo already has one of the five vendors above **and** is TypeScript,
+the PR instead adds Archal's state capture alongside the existing stack rather
+than replacing it:
+
+- `archal-state-capture.ts` importing from `@archal/state-capture`
+- `@archal/state-capture` and `@opentelemetry/api` added to `package.json`
+- the same `.env.example` entry and `ARCHAL_OBSERVABILITY.md` guide
+
+Python repos with existing observability fall back to the greenfield
+OpenTelemetry install — `@archal/state-capture` has no Python build yet, and the
+PR body says so. Tell the user that explicitly rather than implying parity.
+
+### The optional install planner (managed LLM)
+
+On Pro/Enterprise workspaces, for a TypeScript greenfield/augment install with
+repo detection available, one managed LLM call (intent `observability-install`,
+public label **Archal install planner**, routed through the managed eval model
+lane — gemini-class — and metered as `cogs_only` spend) adapts the deterministic
+patch to the repo's real layout. It is strictly additive and **fail-open**: any
+availability, auth, plan-gate, or validation problem ships the deterministic
+patch unchanged. The planner can only:
+
+- relocate the bootstrap file to a better directory (path only — file contents
+  are never edited)
+- append advisory text to the PR body (where to wire startup, which functions to
+  wrap)
+
+It never edits application code, never modifies existing instrumentation, and
+never runs free-form codegen. Disable it with `ARCHAL_INSTALL_PLANNER_DISABLED=1`
+to force the deterministic install.
+
+## Step 3 — ingest an existing observability vendor
+
+If the agent already emits traces to a vendor, you usually do **not** need the
+setup PR. The two ingest paths are:
+
+- **Dashboard OTLP endpoint** — point the vendor's exporter at the Archal OTLP
+  URL shown in the dashboard. Works for OpenTelemetry-compatible vendors (OTel,
+  Langfuse, Braintrust, Datadog, custom HTTP). No CLI command required.
+- **Hosted autoloop** — for Postgres/Supabase sources, register the source with
+  `archal autoloop --source ...`. Archal polls the database directly.
+
+**Delegate the deep mapping to the `autoloop` skill.** It owns the per-vendor
+flags, schema/cursor/filter mapping for database sources, and the full
+import/grade/reproduce/fix loop.
+
+## The honest limit
+
+There is **no sandboxed coding agent** that reads the whole repo and edits
+arbitrary code to wire up instrumentation. For a small or conventional repo, the
+setup PR drops in and works. For a large or unusual repo, the setup PR is a
+**generic bootstrap the user finishes** — they still import the bootstrap at
+startup and wrap the call sites the planner's advisory section points at. Say
+this plainly. The typed model lanes `remediation_agent` and
+`observability_install_agent` exist in the contract but are
+`agent-executor-contract-only`: the lane is declared, but no real executor
+consumes it yet. Do not describe either as a working autonomous coder.
+
+## Failure taxonomy
+
+Classify precisely; do not paper over a missing precondition:
+
+- **GitHub App not connected** — setup PR and fix PRs cannot open. Install the
+  Archal GitHub App on the repo.
+- **No GitHub remote** — augment/greenfield PRs need `github.com/<owner>/<repo>`.
+- **Language unsupported by augment** — Python with existing observability falls
+  back to greenfield OTel; `@archal/state-capture` is TS-only.
+- **Planner skipped** — wrong plan (needs Pro/Enterprise), non-TypeScript,
+  `augment-existing-vendor` legacy mode, detection unavailable, or
+  `ARCHAL_INSTALL_PLANNER_DISABLED=1`. The deterministic patch still ships; this
+  is not a failure, just a narrower install.
+- **Setup PR is a stub for this repo** — large/unusual layout; the user finishes
+  wiring. Not a bug; the honest limit.
+- **Trace ingest failure** — bad credential, rejected upload, or missing workspace auth.
+  Check the dashboard OTLP endpoint config or `archal autoloop status` for the hosted path.
+- **No usable trace evidence** — once ingested, grading or reproduction can still
+  block if the trace lacks task context or state. Hand off to the `autoloop`
+  skill's evidence diagnosis.
+
+## What to report back
+
+After install or debugging, give the user:
+
+- repo full name and whether the GitHub App is connected
+- chosen path: setup PR (greenfield vs augment) or hosted autoloop / dashboard OTLP ingest
+- if a setup PR: the install mode, the files it adds, and whether the planner ran
+- if ingest: provider, source id, and the next step (dashboard OTLP config or `archal autoloop` command)
+- whether traces are flowing into Archal yet, or the exact blocker
+- next command or next owner
+
+## Docs
+
+- Autoloop production traces: https://docs.archal.ai/guides/autoloop-production-traces
+- CLI reference: https://docs.archal.ai/cli/autoloop
+- Quickstart: https://docs.archal.ai/quickstart

package/skills/onboard/SKILL.md

@@ -11,16 +11,15 @@ You are setting up Archal in this project. Archal tests AI agents against servic
 ## If this is a cold-start
 
 The user may have landed here without running `npx archal init` first. If the
-CLI is missing (see "Install + auth" below) AND no `.archal-manifest.json`
-exists in any skill directory (`.claude/skills/`, `.codex/skills/`,
-`.cursor/skills/`, `.windsurf/skills/`), the canonical first command is:
+CLI or project files are missing (see "Install + auth" below), the canonical
+first command is:
 
 ```bash
 npx archal init
 ```
 
-That adds `archal` as a devDependency, installs skills for every detected
-agent platform (Claude Code, Codex, Cursor, Windsurf), and creates a starter
+That adds `archal` as a devDependency when a `package.json` is present, installs
+the packaged skills for detected local agent targets, and creates a starter
 `.archal.json`, `.archal/harness.mjs`, and `scenarios/first-run.md`. Re-invoke
 the onboard skill after it completes.
 
@@ -54,8 +53,10 @@ archal usage                # verify auth + plan
 In CI, set `ARCHAL_TOKEN` to a **workspace API key** (`archal_ws_...`)
 instead of running `archal login`. Workspace keys are bound to one workspace,
 do not expire when a team member leaves, and are the recommended auth for CI.
-Create one with `archal workspace api-key create <label> --scope sessions:write`
-(requires owner or admin role) or from the dashboard under Settings > API Keys.
+Create one with `archal workspace api-key create <label>` (requires owner or
+admin role) or from the dashboard under Settings > API Keys. List and revoke
+keys with `archal workspace api-keys` and
+`archal workspace api-key revoke <key-id>`.
 Personal tokens (`arc_...`) are fine for local dev but should not be used in CI.
 
 Treat workspace API keys as runtime and CI credentials, not governance
@@ -85,7 +86,16 @@ Confirm detected clones, then ask which of these the user wants. Each delegates
 - `"agent": { "command": "node", "args": ["./agent.js"] }` - plain Node script
 - `"agent": { "command": "python", "args": ["agent.py"] }` - Python agent
 
-If the user doesn't have a harness yet, prefer `npx archal init`; it creates `./.archal/harness.mjs`, points `.archal.json` at it, and adds a starter scenario without overwriting existing files. The generated harness is a guarded stub: Archal refuses to score it until the user edits it to call their Cursor, Codex, Claude Code, or custom agent. A custom harness should read `AGENT_TASK` from env, call the agent runtime, print `{ "text": "..." }` to stdout, and call `reportAgentMetrics()` from `archal/harness` with accumulated `{ inputTokens, outputTokens, llmCallCount }` before exit. Service clients need one explicit routing mode: use sandbox/Docker routing when the harness calls normal service URLs such as `https://api.github.com`, or configure SDK base URLs from `AGENT_CLONE_URLS` and add the JSON headers from `AGENT_ROUTE_HEADERS` to those clone requests. Alternative: skip `agent` in `.archal.json` and pass `--harness <path>` per-run.
+If the user doesn't have a harness yet, prefer `npx archal init`; it creates `./.archal/harness.mjs`, points `.archal.json` at it, and adds a starter scenario without overwriting existing files. The generated harness is a guarded stub: Archal refuses to score it until the user edits it to call their Cursor, Codex, Claude Code, or custom agent. A custom harness should read `AGENT_TASK` from env, call the agent runtime, print `{ "text": "..." }` to stdout, and call `reportAgentMetrics()` from `archal` with accumulated `{ inputTokens, outputTokens, llmCallCount }` before exit. Service clients need one explicit routing mode: use sandbox/Docker routing when the harness calls normal service URLs such as `https://api.github.com`, or configure SDK base URLs from `AGENT_CLONE_URLS` and add the JSON headers from `AGENT_ROUTE_HEADERS` to those clone requests. Alternative: skip `agent` in `.archal.json` and pass `--harness <path>` per-run.
+
+### Or run a packaged agent (no harness to write)
+
+If the user wants a ready-made agent, use a packaged agent instead of writing a harness. Packaged agents run in Docker; Archal routes service calls to clones and forwards model calls with the host's provider key.
+
+- `archal run <scenario>.md --sandbox` - run the bundled OpenClaw agent (needs Docker). Pick the model with `--agent-model <provider/model>`; export the matching key in the shell first (`OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY`).
+- `archal run <scenario>.md --harness ./<dir> --docker --dockerfile ./<dir>/Dockerfile` - run your own packaged agent.
+
+See the "Run a packaged agent" guide: https://docs.archal.ai/guides/packaged-agents
 
 ### Option A - Evaluate an agent with scenarios
 
@@ -109,7 +119,7 @@ Same `.archal.json` as Option A (inline `--task` still needs an agent). Use this
      "clones": ["<detected clones>"]
    }
    ```
-2. Demo: `archal run --task "Create an issue titled hello" --clone github`.
+2. Demo: `archal run --task "Create an issue titled hello" --harness . --docker --clone github`.
 3. For the generated first-run project, use bare `archal run` after wiring `.archal/harness.mjs`.
 
 ### Option C - Clones in a Vitest suite
@@ -122,16 +132,17 @@ Do not paste a sample config here. The right shape depends on what's already in
 
 Run: `archal clone start <detected clones>` - gives live clone URLs the user's SDK clients can point at. `archal clone status` shows the active session; `archal clone stop` tears down.
 
-### Option E - Attach real trace sources
-
-Use this when the repo already has agent traces from pre-production or
-production and the user wants Archal to import, grade, reproduce, and turn
-reproduced failures into GitHub issues or PRs.
+### Option E - Autoloop real trace sources
 
-**Delegate to the `attach` skill.** It owns the trace-source mapping,
-`archal/harness.json`, `archal/scenario.md`, seed templates, `archal attach`
+**Delegate to the `autoloop` skill.** It owns the trace-source mapping,
+`archal/harness.json`, `archal/scenario.md`, seed templates, `archal autoloop`
 commands, dashboard expectations, and failure taxonomy. Do not inline the
-Attach flow here; it changes faster than starter scenario setup.
+Autoloop flow here; it changes faster than starter scenario setup.
+
+Set the expectation carefully: Autoloop is not arbitrary production trace replay.
+It can reproduce only failures with enough trace evidence plus repo-owned
+scenario/seed context to reconstruct realistic clone state. Missing evidence
+should block with a clear artifact instead of being guessed.
 
 ## Verify
 
@@ -155,4 +166,4 @@ Run the first scenario or task. For Options A and B, hand off to the `eval` skil
 
 - Quickstart: https://docs.archal.ai/quickstart
 - Full docs: https://docs.archal.ai
-- Attach production traces: https://docs.archal.ai/guides/attach-production-traces
+- Autoloop production traces: https://docs.archal.ai/guides/autoloop-production-traces