archal 0.9.20 → 0.10.0

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

@@ -1,8 +1,27 @@
 # 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.
+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.
+
+The starter takes only `--repo`, `--source`, the credential
+(`--database-url-env` or `--database-url-secret-ref`), `--execution-policy`,
+`--check`, and `--json`. The source identity, schema mapping, cursor, and filters
+live in the `.archal.json` `autoloop` block — see `trace-schema-mapping.md`. A
+minimal config names the source:
+
+```jsonc
+// .archal.json
+{
+  "autoloop": {
+    "source": { "name": "prod-agent-traces" }
+  }
+}
+```
+
+This is the detail behind **Breakpoint 3** in `SKILL.md`: never accept a
+privileged connection string, pass the credential by env-var name (or secret
+ref), and confirm the role is read-only before running any `--source` command.
 
 ## Contents
 
@@ -13,50 +32,63 @@ config to Archal and returns; hosted workers own polling after that.
 
 ## Read-only credential
 
-First, create or request a read-only database user. Then keep the URL in an env
-var:
+First create (or ask the user to create) a read-only database role scoped to the
+trace tables. For Postgres:
+
+```sql
+CREATE ROLE archal_trace_reader LOGIN PASSWORD '<generated>';
+GRANT CONNECT ON DATABASE <db> TO archal_trace_reader;
+GRANT USAGE ON SCHEMA public TO archal_trace_reader;
+GRANT SELECT ON ai_traces, ai_spans TO archal_trace_reader;  -- trace/span tables only
+```
+
+Then keep the URL in an env var; never inline it in a command and never echo it:
 
 ```bash
-export TRACE_DATABASE_URL='postgres://readonly:...'
+export TRACE_DATABASE_URL='postgres://archal_trace_reader:...'
 ```
 
 ## Check the source
 
-Run a check:
+Run a readiness check. `--check --json` emits `{ ok, checks[], nextStep? }` and
+exits `2` when not ready:
 
 ```bash
 npx archal autoloop \
   --repo . \
   --source supabase \
   --database-url-env TRACE_DATABASE_URL \
-  --source-id prod-agent-traces \
-  --check
+  --check --json
 ```
 
+The source name comes from `autoloop.source.name` in `.archal.json`, not a flag.
+
 ## Register the source
 
-Register:
+Drop `--check` to register:
 
 ```bash
 npx archal autoloop \
   --repo . \
   --source supabase \
   --database-url-env TRACE_DATABASE_URL \
-  --source-id prod-agent-traces
+  --execution-policy reproduce
 ```
 
-This posts the source config to Archal and returns. It does not start a local
-watcher and does not write local source state.
+Set `--execution-policy` to match the Autofix answer from Breakpoint 1
+(`reproduce` = no PRs, `fix` = open PRs). Registration 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:
+Use a secret reference when the customer already has one. The ref must not
+contain a plaintext credential:
 
 ```bash
 npx archal autoloop \
   --repo . \
   --source postgres \
-  --database-url-secret-ref aws-secretsmanager://customer/prod-agent-traces
+  --database-url-secret-ref aws-secretsmanager://customer/prod-agent-traces \
+  --execution-policy reproduce
 ```
-
-`--database-url-secret-ref` must not contain a plaintext credential.

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

@@ -1,73 +1,104 @@
 # 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.
+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 flags
+- Custom schema
 - 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
+| 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:
+For append-only sources, switch the cursor to `created_at_id` and point it at the
+created-at columns:
 
-```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
+```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 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
+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,64 +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.
-
-## 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`.
+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
 

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

@@ -1,6 +1,6 @@
 ---
 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 wires an existing trace vendor through `archal trace-source`. 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.
+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]"
 ---
@@ -54,8 +54,8 @@ Before changing anything, read the repo and find out where traces live:
    ```
 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 -> ingest path (`archal trace-source`, delegate detail to `autoloop`)
-   - exported files on disk -> `archal trace-source import`
+     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,
@@ -139,34 +139,17 @@ 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 — you normalize the existing traces with `archal trace-source`. This is
-the genuine ingest path. It maps a vendor's payloads into Archal's trace upload
-envelopes and uploads them to hosted autoloop when workspace auth is present.
-
-Supported providers: `langfuse`, `braintrust`, `otel`, `http`, `supabase`,
-`postgres`, `file`, `custom`. Pull/sync vendors (`langfuse`, `braintrust`,
-Postgres/Supabase) are fetched on a cursor; push sources (`otel`, `http`,
-`custom`) receive traces continuously through `serve`.
-
-The command surface:
-
-```bash
-archal trace-source connect <provider>   # register a source (e.g. langfuse, braintrust, otel, custom)
-archal trace-source test [source]        # validate credentials and reachability
-archal trace-source sync [source]        # pull-fetch new traces (langfuse/braintrust/db)
-archal trace-source watch [source]       # continuous pull loop
-archal trace-source serve [source]       # receiver for push sources (otel/http/custom)
-archal trace-source import <path>        # normalize exported trace files on disk
-archal trace-source status [source]      # registry validation, cursor, last-sync state
-archal trace-source list                 # registered sources
-archal trace-source use|disable <source> # select / disable a source
-```
+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 (`--base-url`, `--api-key-env`, `--out`, `--upload`, `--repository`,
-schema/cursor/filter mapping for database sources) and the full
-import/grade/reproduce/fix loop. Quote the command names here; point the user
-there for the flag detail and the autoloop wiring.
+flags, schema/cursor/filter mapping for database sources, and the full
+import/grade/reproduce/fix loop.
 
 ## The honest limit
 
@@ -195,9 +178,8 @@ Classify precisely; do not paper over a missing precondition:
   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** — `trace-source` adapter mismatch, bad credential,
-  rejected upload, or missing workspace auth. Use `archal trace-source test` and
-  `status` to localize it.
+- **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.
@@ -207,15 +189,14 @@ Classify precisely; do not paper over a missing precondition:
 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 `trace-source` ingest
+- 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 `archal trace-source` command
+- 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
-- Autonomous loops: https://docs.archal.ai/guides/autoloop-production-traces
 - CLI reference: https://docs.archal.ai/cli/autoloop
 - Quickstart: https://docs.archal.ai/quickstart