archal 0.9.14 → 0.9.16

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

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

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

@@ -1,8 +1,7 @@
 import {
   bootstrapArchalVitestRouting
-} from "../chunk-L6HSMJ3F.js";
-import "../chunk-KTMNDJFB.js";
-import "../chunk-YJICENME.js";
+} from "../chunk-FU2VLK75.js";
+import "../chunk-CJJ32YQF.js";
 
 // src/runtime/setup-files.ts
 import { existsSync, rmSync } from "fs";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "archal",
-  "version": "0.9.14",
-  "description": "Test your agents & integrations against digital twins",
+  "version": "0.9.16",
+  "description": "Test your agents & integrations against service clones",
   "type": "module",
   "main": "dist/index.cjs",
   "types": "dist/index.d.cts",
@@ -13,6 +13,10 @@
       "types": "./dist/index.d.cts",
       "default": "./dist/index.cjs"
     },
+    "./harness": {
+      "types": "./dist/harness.d.cts",
+      "default": "./dist/harness.cjs"
+    },
     "./vitest": {
       "types": "./dist/vitest/index.d.ts",
       "import": "./dist/vitest/index.js",
@@ -31,20 +35,27 @@
     "agent",
     "testing",
     "mcp",
-    "digital-twin",
+    "service-clone",
     "archal",
     "vitest"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=20.20"
   },
   "files": [
     "bin",
     "dist",
     "skills",
-    "twin-assets",
+    "clone-assets",
     "LICENSE"
   ],
+  "scripts": {
+    "verify:artifacts": "node scripts/assert-artifacts.mjs",
+    "prepack": "pnpm run verify:artifacts",
+    "prepare": "node scripts/prepare.cjs",
+    "typecheck:raw": "node --check bin/archal.cjs && node --check scripts/assert-artifacts.mjs && node --check scripts/prepare.cjs",
+    "typecheck": "pnpm run typecheck:raw"
+  },
   "peerDependencies": {
     "vitest": ">=2.1.0"
   },
@@ -53,9 +64,7 @@
       "optional": true
     }
   },
-  "scripts": {
-    "verify:artifacts": "node scripts/assert-artifacts.mjs",
-    "typecheck:raw": "node --check bin/archal.cjs && node --check scripts/assert-artifacts.mjs && node --check scripts/prepare.cjs",
-    "typecheck": "pnpm run typecheck:raw"
+  "dependencies": {
+    "picomatch": "^4.0.4"
   }
-}
+}

package/skills/eval/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: eval
-description: Run Archal scenarios or inline tasks against hosted twins, 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".
+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]"
 ---
@@ -12,9 +12,9 @@ You run Archal scenarios and inline tasks, then help the user interpret the resu
 ## What only you know (product mental model)
 
 - `archal run` spawns the user's agent as a child process. The agent needs:
-  - A **runnable agent path**. Two ways to supply it: explicit `--harness <path>` (e.g. `./.archal/harness.ts`), or `.archal.json` with an `agent` command. Repo-local auto-discovery also walks up from cwd for a top-level `harness.{ts,js,mjs,cjs}`.
-  - A **headless boundary** — no UI, no browser OAuth. The process is spawned without a shell, so interactive auth hangs forever.
-  - Env vars — auto-injected. `ARCHAL_ENGINE_TASK` is the prompt; `ARCHAL_<TWIN>_BASE_URL` / `ARCHAL_<TWIN>_URL` point at twins; `ARCHAL_PREFLIGHT=1` is set during boot check (harness should exit early).
+  - A **runnable agent path**. Two ways to supply it: explicit `--harness <path>` (e.g. `./.archal/harness.mjs` from `archal init`), or `.archal.json` with an `agent` command. Repo-local auto-discovery also walks up from cwd for a top-level `harness.{ts,js,mjs,cjs}`.
+  - A **headless boundary** - no UI, no browser OAuth. The process is spawned without a shell, so interactive auth hangs forever.
+  - Env vars - auto-injected. `AGENT_TASK` is the prompt; service clones are reached through normal service URLs in a controlled runtime.
 - Every `archal run` writes local artifacts under `.archal/cache/last-run.json` and `.archal/cache/runs/*.json` **regardless** of `--output`. `--output json` is only for machine-readable stdout; it's not needed for local persistence.
 - **Satisfaction score** = (runs passing all criteria) / (total runs). `[D]` criteria are deterministic state checks; `[P]` criteria are LLM-judged from trace + final state.
 
@@ -23,10 +23,12 @@ You run Archal scenarios and inline tasks, then help the user interpret the resu
 When the agent path is uncertain, or after any change to the harness file, smoke-test the harness directly before `archal run`:
 
 ```bash
-ARCHAL_PREFLIGHT=1 ARCHAL_ENGINE_TASK="Reply with OK and do not use tools." npx tsx ./.archal/harness.ts
+AGENT_TASK="Reply with OK and do not use tools." node ./.archal/harness.mjs
 ```
 
-A harness that exits cleanly with no tool calls is ready. Catches: no runnable entrypoint, UI-boot assumptions, missing provider keys, service bridge misconfig. A failure here is much easier to diagnose than a silent timeout inside `archal run`.
+A wired harness that exits cleanly with no service calls is ready. If it says the starter harness is still a stub, edit `.archal/harness.mjs` to call the user's Cursor, Codex, Claude Code, or custom agent first. Other failures catch: no runnable entrypoint, UI-boot assumptions, missing provider keys, service bridge misconfig.
+
+If a local harness returns text but records zero clone-observed calls, check for real-service auth signals such as `api.github.com` plus `401`/`Bad credentials`. That means the harness did not reach the clone. Fix by running the SDK under sandbox/Docker routing, or by reading `AGENT_CLONE_URLS` for clone REST URLs and adding the JSON headers from `AGENT_ROUTE_HEADERS` to clone requests.
 
 ## Running
 
@@ -34,18 +36,18 @@ 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 --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.ts --twin github
+archal run --task "Create an issue titled hello" --harness ./.archal/harness.mjs --clone github
 ```
 
-`--task` only replaces the scenario file — it still needs a runnable agent path. `--twin` is required with `--task`; repeat or comma-separate for multiple twins.
+`--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.
 
-When `.archal.json` exists in cwd, bare `archal run` uses it. If the user doesn't have one yet, that's setup — hand off to the `onboard` skill, which owns harness creation and `.archal.json` scaffolding.
+When `.archal.json` exists in cwd, bare `archal run` uses it. If the user doesn't have one yet, that's setup - hand off to the `onboard` skill, which owns harness creation and `.archal.json` scaffolding.
 
 ## Interpret results
 
@@ -55,28 +57,28 @@ Score breakdown:
 - `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.
+- `[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.
 
 ## Diagnose failures
 
 Re-run with `-v` for the full trace, then classify with these signals:
 
-- **Agent bug** — wrong tool called, wrong arguments, stopped early.
+- **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.
 
-- **Scenario bug** — criteria are too strict, ambiguous, or contradict the Setup.
+- **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.
 
-- **Seed mismatch** — twin state doesn't match what Setup describes.
+- **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 <twin>` to browse.
+  *Fix:* different seed, or adjust Setup to match. `archal seed list <clone>` to browse.
 
-- **Harness bug** — agent process never started, crashed immediately, or hung.
+- **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 `ARCHAL_PREFLIGHT=1 ARCHAL_ENGINE_TASK="Reply with OK." npx tsx ./.archal/harness.ts`, then look for UI-only imports, missing provider keys, or interactive auth.
+  *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
 
@@ -84,20 +86,22 @@ Re-run with `-v` for the full trace, then classify with these signals:
 archal run scenario.md --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.
+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.
 
 ## Artifacts + dashboard
 
 - **Local (always written):** `.archal/cache/last-run.json` (summary), `.archal/cache/runs/*.json` (full redacted trace).
-- **Hosted:** every run also uploads to https://www.archal.ai/dashboard — useful for sharing a failing trace with a colleague or comparing across agent model versions.
+- **Hosted:** every run also uploads to https://www.archal.ai/dashboard - useful for sharing a failing trace with a colleague or comparing across agent model versions.
 
-Don't tell users they need `-o json` to save artifacts locally — that's only for stdout.
+Don't tell users they need `-o json` to save artifacts locally - that's only for stdout.
 
 ## Anti-patterns
 
-- Don't re-document the `archal run` flag list here. `archal run --help` and https://docs.archal.ai/cli/run own that — they'll drift if duplicated.
-- Don't guess the agent path. If the user doesn't have `--harness`, a repo-local harness, or `.archal.json`, hand off to `onboard` — it owns setup.
-- Don't promote `--proxy` as default. It's for agents that still call real service domains through raw HTTPS clients. Env-var wiring is the primary path; proxy is a fallback.
+- Don't re-document the `archal run` flag list here. `archal run --help` and https://docs.archal.ai/cli/run own that - they'll drift if duplicated.
+- Don't guess the agent path. If the user doesn't have `--harness`, a repo-local harness, or `.archal.json`, hand off to `onboard` - it owns setup.
+- Don't promote local proxy or Archal-owned route env as normal service simulation. Scored runs use a controlled runtime with transparent TLS interception against real service domains; uncontainerized proxy routing is low-fidelity debug only.
 - Don't classify a single `[P]` failure as an agent bug without re-running. Probabilistic criteria need sample size.
 - Don't treat a `[D]` failure as model variance. Deterministic failures are real bugs.
 
@@ -106,4 +110,4 @@ Don't tell users they need `-o json` to save artifacts locally — that's only f
 - Running with an agent: https://docs.archal.ai/guides/run-with-agent
 - Existing repo playbook: https://docs.archal.ai/guides/existing-agent-repo
 - Scenario authoring: hand off to the `scenario` skill
-- Twin sessions: https://docs.archal.ai/guides/twin-sessions
+- Clone sessions: https://docs.archal.ai/guides/clone-sessions

package/skills/onboard/SKILL.md

@@ -6,35 +6,40 @@ user-invocable: true
 
 # Archal Onboard
 
-You are setting up Archal in this project. Archal tests AI agents against digital twins of real services (GitHub, Slack, Stripe, etc.). Handle installation and auth yourself; delegate the workflow-specific setup to the matching sub-skill.
+You are setting up Archal in this project. Archal tests AI agents against service clones of real services (GitHub, Slack, Stripe, etc.). Handle installation and auth yourself; delegate the workflow-specific setup to the matching sub-skill.
 
 ## 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 `.claude/skills/`, the canonical first command is:
+exists in any skill directory (`.claude/skills/`, `.codex/skills/`,
+`.cursor/skills/`, `.windsurf/skills/`), the canonical first command is:
 
 ```bash
 npx archal init
 ```
 
-That adds `archal` as a devDependency and reinstalls these skills at the
-right version. Re-invoke the onboard skill after it completes.
+That adds `archal` as a devDependency, installs skills for every detected
+agent platform (Claude Code, Codex, Cursor, Windsurf), and creates a starter
+`.archal.json`, `.archal/harness.mjs`, and `scenarios/first-run.md`. Re-invoke
+the onboard skill after it completes.
 
 ## Discover first
 
 Before asking anything, read the repo:
 
-1. `package.json` deps → infer likely twins:
-   - `@octokit/rest`, `octokit` → `github`
-   - `stripe` → `stripe`
-   - `@slack/web-api`, `@slack/bolt` → `slack`
-   - `@linear/sdk` → `linear`
-   - `@supabase/supabase-js` → `supabase`
-   - `googleapis`, `@google-cloud/*` → `google-workspace`
-   - `jira-client`, `jira.js` → `jira`
+1. `package.json` deps -> infer likely clones:
+   - `@octokit/rest`, `octokit` -> `github`
+   - `stripe` -> `stripe`
+   - `@slack/web-api`, `@slack/bolt` -> `slack`
+   - `@linear/sdk` -> `linear`
+   - `@supabase/supabase-js` -> `supabase`
+   - `googleapis`, `@google-cloud/*` -> `google-workspace`
+   - `jira-client`, `jira.js` -> `jira`
+   - Apify SDK or `api.apify.com` usage -> `apify`
+   - Tavily SDK or `api.tavily.com` usage -> `tavily`
 2. Existing vitest config? Existing scenarios? Existing `.archal.json`? Those change which workflow makes sense.
-3. If no `package.json` or no matching deps: ask "Which services does your agent interact with?" and show the full list: `github`, `slack`, `stripe`, `linear`, `jira`, `supabase`, `google-workspace`, `ramp`.
+3. If no `package.json` or no matching deps: ask "Which services does your agent interact with?" and point them to the clone catalog (`archal clone --json`) rather than maintaining a separate list here.
 
 ## Install + auth
 
@@ -46,10 +51,21 @@ archal login                # OAuth browser flow, or: archal login --token <toke
 archal usage                # verify auth + plan
 ```
 
-In CI, set `ARCHAL_TOKEN` instead of running `archal login`.
+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.
+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
+credentials. They can run clones, upload and read traces, and read usage for
+their bound workspace. They cannot manage workspace API keys or audit events.
+Use an owner/admin user credential, either `archal login` or a dashboard-issued
+user API key, for workspace administration.
 
 If something feels wrong (missing CLI, stale skills), these are the
-recovery commands — don't run them otherwise:
+recovery commands - don't run them otherwise:
 
 ```bash
 npx archal --version           # CLI reachable? prints e.g. 0.9.12
@@ -58,70 +74,69 @@ npx archal init --skills-only  # re-stage skills if they drifted
 
 ## Pick a workflow
 
-Confirm detected twins, then ask which of these the user wants. Each delegates to a sub-skill where appropriate — don't inline those flows.
+Confirm detected clones, then ask which of these the user wants. Each delegates to a sub-skill where appropriate - don't inline those flows.
 
 ### The `agent` command (Options A and B both need this)
 
-`archal run` spawns the agent as a child process, headlessly — no UI, no browser auth. The `agent` field in `.archal.json` is the shell command that invokes it. Typical shapes:
+`archal run` spawns the agent as a child process, headlessly - no UI, no browser auth. The `agent` field in `.archal.json` is the shell command that invokes it. Typical shapes:
 
-- `"agent": "npx tsx ./.archal/harness.ts"` — custom TS entrypoint, most common
-- `"agent": "node ./agent.js"` — plain Node script
-- `"agent": "python agent.py"` — Python agent
+- `"agent": { "command": "node", "args": ["./.archal/harness.mjs"] }` - scaffolded by `archal init`
+- `"agent": { "command": "npx", "args": ["tsx", "./.archal/harness.ts"] }` - custom TS entrypoint
+- `"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, scaffold one at `./.archal/harness.ts` that reads `ARCHAL_ENGINE_TASK` from env and calls their agent's runtime. 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/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.
 
-### Option A — Evaluate an agent with scenarios
+### Option A - Evaluate an agent with scenarios
 
-Write markdown scenario files that describe setup, prompt, and success criteria; `archal run` executes them against twins.
+Write markdown scenario files that describe setup, prompt, and success criteria; `archal run` executes them against clones.
 
 1. Create `.archal.json`:
    ```json
-   {
-     "agent": "npx tsx ./.archal/harness.ts",
-     "twins": ["<detected twins>"]
-   }
+   { "agent": { "command": "<agent command>", "args": ["<arg1>", "..."] }, "clones": ["<detected clones>"], "scenarios": ["scenarios/first-run.md"] }
    ```
-2. **Delegate to the `scenario` skill** to author a starter scenario. Don't paste a canned example here — the skill knows the markdown format and success-criteria syntax.
+2. **Delegate to the `scenario` skill** to author a starter scenario. Don't paste a canned example here - the skill knows the markdown format and success-criteria syntax.
 3. Run: `archal run scenarios/<first>.md`. **Hand off to the `eval` skill** for result interpretation and failure diagnosis.
 
-### Option B — Run quick inline tasks
+### Option B - Run quick inline tasks
 
 Same `.archal.json` as Option A (inline `--task` still needs an agent). Use this when the user wants ad-hoc runs before committing to scenario files.
 
 1. `.archal.json`:
    ```json
    {
-     "agent": "npx tsx ./.archal/harness.ts",
-     "twins": ["<detected twins>"]
+     "agent": { "command": "node", "args": ["./.archal/harness.mjs"] },
+     "clones": ["<detected clones>"]
    }
    ```
-2. Demo: `archal run --task "Create an issue titled hello" --twin github`.
+2. Demo: `archal run --task "Create an issue titled hello" --clone github`.
+3. For the generated first-run project, use bare `archal run` after wiring `.archal/harness.mjs`.
 
-### Option C — Twins in a Vitest suite
+### Option C - Clones in a Vitest suite
 
-**Delegate to the `vitest` skill.** It handles reading the existing vitest config, identifying which tests should route, picking the right composition pattern, and seeding the twins.
+**Delegate to the `vitest` skill.** It handles reading the existing vitest config, identifying which tests should route, picking the right composition pattern, and seeding the clones.
 
 Do not paste a sample config here. The right shape depends on what's already in the repo.
 
-### Option D — Persistent twins to develop against
+### Option D - Persistent clones to develop against
 
-Run: `archal twin start <detected twins>` — gives live twin URLs the user's SDK clients can point at. `archal twin status` shows the active session; `archal twin stop` tears down.
+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.
 
 ## Verify
 
-Run the first scenario or task. For Options A and B, hand off to the `eval` skill to interpret the satisfaction score and diagnose failures — that skill owns the runtime mental model (`[D]` vs `[P]` criteria, trace inspection, harness preflight).
+Run the first scenario or task. For Options A and B, hand off to the `eval` skill to interpret the satisfaction score and diagnose failures - that skill owns the runtime mental model (`[D]` vs `[P]` criteria, trace inspection, harness execution diagnostics).
 
 ## `.archal.json` schema
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `agent` | string or `{ command, args }` | yes (for scenarios) | | Shell command to run the agent |
+| `agent` | `{ command, args?, env? }` | yes (for scenarios) | | Agent command as an object (not a plain string) |
 | `title` | string | no | | Display name for reports |
-| `twins` | string[] | no | inferred | Which twins to provision |
+| `clones` | string[] | no | inferred | Which clones to provision |
 | `scenarios` | string[] | no | | Scenario file paths relative to config |
-| `seeds` | `Record<string, string>` | no | | Per-twin seed overrides |
+| `seeds` | `Record<string, string>` | no | | Per-clone seed overrides |
 | `agentModel` | string | no | | LLM model the agent uses |
-| `model` | string | no | `gemini-2.5-pro` | Evaluator model |
+| `evaluatorModel` | string | no | Archal LLM judge | Evaluator/judge model; set this only when bringing your own judge key |
 | `runs` | number | no | `1` | Runs per scenario |
 | `timeout` | number | no | `180` | Timeout per run in seconds |
 

package/skills/scenario/SKILL.md

@@ -7,7 +7,7 @@ argument-hint: "[scenario description or file path]"
 
 # Archal Scenario Writer
 
-You write and edit Archal scenario files. Scenarios are markdown files that define a test for an AI agent running against digital twins.
+You write and edit Archal scenario files. Scenarios are markdown files that define a test for an AI agent running against service clones.
 
 ## Scenario format
 
@@ -24,11 +24,11 @@ The task instruction given to the agent.
 Answer key for the evaluator. Never shown to the agent.
 
 ## Success Criteria
-- [D] Deterministic criterion checked against twin state
+- [D] Deterministic criterion checked against clone state
 - [P] Probabilistic criterion judged by LLM
 
 ## Config
-twins: github
+clones: github
 timeout: 90
 runs: 3
 ```
@@ -49,7 +49,7 @@ runs: 3
 
 Each criterion is a bullet point. Tag with `[D]` or `[P]`:
 
-- `[D]` = **Deterministic**. Checked against twin state programmatically. Use for counts, existence checks, state assertions. No LLM cost.
+- `[D]` = **Deterministic**. Checked against clone state programmatically. Use for counts, existence checks, state assertions. No LLM cost.
 - `[P]` = **Probabilistic**. Judged by LLM evaluator from the trace and final state. Use for tone, quality, correctness, reasoning.
 
 If no tag is provided, Archal infers the type:
@@ -78,19 +78,23 @@ If no tag is provided, Archal infers the type:
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
-| `twins` | comma-separated | inferred from content | Which twins to use |
+| `clones` | comma-separated | inferred from content | Which clones to use |
 | `seed` | string | | Named seed to load |
 | `timeout` | integer | `180` | Seconds per run |
 | `runs` | integer | `1` | Number of runs |
-| `evaluator-model` | string | `gemini-2.5-pro` | LLM for `[P]` criteria |
+| `evaluator-model` | string | Archal LLM judge | LLM for `[P]` criteria; set this only when bringing your own judge key |
 | `tags` | comma-separated | | Scenario tags |
 
 Aliases for `evaluator-model`: `evaluator`, `evaluatormodel`, `model`.
 
-## Available twins and general-purpose seeds
+## Available clones and general-purpose seeds
 
-| Twin | Seeds |
+The full clone and seed surface is manifest-backed. Prefer `archal clone --json`
+and `archal seed list` over maintaining a separate list in this skill.
+
+| Clone | Seeds |
 |------|-------|
+| `apify` | `empty` |
 | `github` | `empty`, `small-project`, `enterprise-repo`, `ci-cd-pipeline`, `stale-issues`, `large-backlog` |
 | `slack` | `empty`, `engineering-team`, `busy-workspace`, `incident-active` |
 | `stripe` | `empty`, `small-business`, `checkout-flow`, `subscription-lifecycle`, `subscription-heavy` |
@@ -98,13 +102,13 @@ Aliases for `evaluator-model`: `evaluator`, `evaluatormodel`, `model`.
 | `linear` | `empty`, `small-team`, `engineering-org`, `multi-team`, `busy-backlog` |
 | `supabase` | `empty`, `small-project`, `saas-starter`, `ecommerce` |
 | `google-workspace` | `empty`, `assistant-baseline`, `gmail-busy-inbox`, `calendar-packed-week` |
+| `tavily` | `empty` |
 | `ramp` | `empty`, `default` |
 | `discord` | `empty`, `small-server`, `harvested` |
-| `telegram` | `empty`, `harvested` |
 
-## Twin auto-detection from content
+## Clone auto-detection from content
 
-If no `twins:` config is set, Archal infers twins from keywords in Setup, Expected Behavior, and Prompt:
+If no `clones:` config is set, Archal infers clones from keywords in Setup, Expected Behavior, and Prompt:
 
 - `github`, `repository`, `pull request`, `create_issue` -> `github`
 - `slack`, `slack channel`, `send_message` -> `slack`
@@ -115,21 +119,19 @@ If no `twins:` config is set, Archal infers twins from keywords in Setup, Expect
 - `google workspace`, `gmail`, `calendar event`, `inbox` -> `google-workspace`
 - `discord`, `guild`, `text channel` -> `discord`
 
-Not every twin has auto-detect keywords — `telegram` in particular has
-none. If your scenario uses `telegram`, set `twins: telegram` in the
-Config block or in `.archal.json`. `ramp` auto-detects on `ramp`,
+Not every clone has auto-detect keywords. `ramp` auto-detects on `ramp`,
 `bill`, `expense`, `reimbursement`, `fund`, `card spend`.
 
 ## Multi-service scenarios
 
-Use multiple twins by listing them in config:
+Use multiple clones by listing them in config:
 
 ```markdown
 ## Config
-twins: github, slack
+clones: github, slack
 ```
 
-The Setup section can describe state across both services. Each twin gets its own seed.
+The Setup section can describe state across both services. Each clone gets its own seed.
 
 ## Validation
 
@@ -137,18 +139,18 @@ Run `archal scenario list` to verify scenarios parse correctly. A valid scenario
 - A title (H1 heading)
 - A Prompt section
 - At least one success criterion
-- At least one referenced twin (explicit or inferred)
+- At least one referenced clone (explicit or inferred)
 - Positive timeout and runs values
 
 ## Common mistakes to avoid
 
 1. Writing `[D]` criteria that require subjective judgment
 2. Writing `[P]` criteria that could be checked deterministically
-3. Forgetting to specify which twin the scenario uses
+3. Forgetting to specify which clone the scenario uses
 4. Writing Setup descriptions that are too vague for seed generation
 5. Using seed names that don't exist (check the seed table above)
 
 ## Documentation
 
 - Writing scenarios: https://docs.archal.ai/guides/writing-scenarios
-- Twins and seeds: https://docs.archal.ai/twins/overview
+- Clones and seeds: https://docs.archal.ai/clones/overview