keystone-cli 0.7.2 → 1.0.0

package/README.md

@@ -14,6 +14,26 @@ Keystone allows you to define complex automation workflows using a simple YAML s
 
 ---
 
+## 📚 Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Bundled Workflows](#bundled-workflows)
+- [Configuration](#configuration)
+- [Workflow Example](#workflow-example)
+- [Expression Syntax](#expression-syntax)
+- [Step Types](#step-types)
+- [Advanced Features](#advanced-features)
+- [Agent Definitions](#agent-definitions)
+- [CLI Commands](#cli-commands)
+- [Security](#security)
+- [Architecture](#architecture)
+- [Project Structure](#project-structure)
+- [License](#license)
+
+---
+
 ## ✨ Features
 
 - ⚡ **Local-First:** Built on Bun with a local SQLite database for state management.
@@ -25,8 +45,8 @@ Keystone allows you to define complex automation workflows using a simple YAML s
 - 🛠️ **Extensible:** Support for shell, file, HTTP request, LLM, and sub-workflow steps.
 - 🔌 **MCP Support:** Integrated Model Context Protocol server.
 - 🛡️ **Secret Redaction:** Automatically redacts environment variables and secrets from logs and outputs.
-- 🧠 **Semantic Memory:** Store and retrieve step outputs using vector embeddings/RAG.
-- 🎯 **Prompt Optimization:** Automatically optimize prompts using iterative evaluation (DSPy-style).
+- 🧠 **Semantic Memory:** Store/search text with vector embeddings (and auto-index via `learn`).
+- 🎯 **Prompt Optimization:** Iteratively optimize prompts via `keystone optimize` + workflow `eval`.
 
 ---
 
@@ -74,7 +94,7 @@ source <(keystone completion bash)
 ```bash
 keystone init
 ```
-This creates the `.keystone/` directory for configuration and seeds `.keystone/workflows/` with default automation files and agents (like `scaffold-feature` and `keystone-architect`).
+This creates the `.keystone/` directory for configuration and seeds `.keystone/workflows/` plus `.keystone/workflows/agents/` with bundled workflows and agents (see "Bundled Workflows" below).
 
 ### 2. Configure your Environment
 Add your API keys to the generated `.env` file:
@@ -86,11 +106,19 @@ Alternatively, you can use the built-in authentication management:
 ```bash
 keystone auth login openai
 keystone auth login anthropic
+keystone auth login anthropic-claude
+keystone auth login openai-chatgpt
+keystone auth login gemini
+keystone auth login github
 ```
+Use `anthropic-claude` for Claude Pro/Max subscriptions (OAuth) instead of an API key.
+Use `openai-chatgpt` for ChatGPT Plus/Pro subscriptions (OAuth) instead of an API key.
+Use `gemini` (alias `google-gemini`) for Google Gemini subscriptions (OAuth) instead of an API key.
+Use `github` to authenticate GitHub Copilot via the GitHub device flow.
 
 ### 3. Run a Workflow
 ```bash
-keystone run basic-shell
+keystone run scaffold-feature
 ```
 Keystone automatically looks in `.keystone/workflows/` (locally and in your home directory) for `.yaml` or `.yml` files.
 
@@ -101,9 +129,39 @@ keystone ui
 
 ---
 
+## 🧰 Bundled Workflows
+
+`keystone init` seeds these workflows under `.keystone/workflows/` (and the agents they rely on under `.keystone/workflows/agents/`):
+
+- `scaffold-feature`: Interactive workflow scaffolder. Prompts for requirements, plans files, generates content, and writes them.
+- `scaffold-plan`: Generates a file plan from `requirements` input.
+- `scaffold-generate`: Generates file contents from `requirements` plus a `files` plan.
+- `decompose-problem`: Decomposes a problem into research/implementation/review tasks, waits for approval, runs sub-workflows, and summarizes.
+- `decompose-research`: Runs a single research task (`task`) with optional `context`/`constraints`.
+- `decompose-implement`: Runs a single implementation task (`task`) with optional `research` findings.
+- `decompose-review`: Reviews a single implementation task (`task`) with optional `implementation` results.
+- `dev`: Self-bootstrapping DevMode workflow for an interactive plan/implement/verify loop.
+
+Example runs:
+```bash
+keystone run scaffold-feature
+keystone run decompose-problem -i problem="Add caching to the API" -i context="Node/Bun service"
+```
+
+The sub-workflows are used by the top-level workflows, but can be run directly if you want just one phase.
+
+---
+
 ## ⚙️ Configuration
 
-Keystone uses a local configuration file at `.keystone/config.yaml` to manage model providers and model mappings.
+Keystone loads configuration from project `.keystone/config.yaml` (and user-level config; see `keystone config show` for search order) to manage model providers and model mappings.
+
+Search order (highest precedence first):
+- `KEYSTONE_CONFIG`
+- `.keystone/config.yaml` or `.keystone/config.yml`
+- `$XDG_CONFIG_HOME/keystone/config.yaml` or `~/.config/keystone/config.yaml` (and `.yml`)
+
+Global state (when enabled) is stored at `$XDG_DATA_HOME/keystone/state.db` or `~/.local/share/keystone/state.db`.
 
 ```yaml
 default_provider: openai
@@ -114,11 +172,23 @@ providers:
     base_url: https://api.openai.com/v1
     api_key_env: OPENAI_API_KEY
     default_model: gpt-4o
+  openai-chatgpt:
+    type: openai-chatgpt
+    base_url: https://api.openai.com/v1
+    default_model: gpt-5-codex
   anthropic:
     type: anthropic
     base_url: https://api.anthropic.com/v1
     api_key_env: ANTHROPIC_API_KEY
     default_model: claude-3-5-sonnet-20240620
+  anthropic-claude:
+    type: anthropic-claude
+    base_url: https://api.anthropic.com/v1
+    default_model: claude-3-5-sonnet-20240620
+  google-gemini:
+    type: google-gemini
+    base_url: https://cloudcode-pa.googleapis.com
+    default_model: gemini-3-pro-high
   groq:
     type: openai
     base_url: https://api.groq.com/openai/v1
@@ -126,8 +196,11 @@ providers:
     default_model: llama-3.3-70b-versatile
 
 model_mappings:
+  "gpt-5*": openai-chatgpt
   "gpt-*": openai
+  "claude-4*": anthropic-claude
   "claude-*": anthropic
+  "gemini-*": google-gemini
   "o1-*": openai
   "llama-*": groq
 
@@ -141,11 +214,21 @@ mcp_servers:
     env:
       GITHUB_PERSONAL_ACCESS_TOKEN: "your-github-pat" # Or omit if GITHUB_TOKEN is in your .env
 
-storage:
+engines:
+  allowlist:
+    codex:
+      command: codex
+      version: "1.2.3"
+      versionArgs: ["--version"]
+  denylist: ["bash", "sh"]
 
+storage:
   retention_days: 30
+  redact_secrets_at_rest: true
 ```
 
+`storage.retention_days` sets the default window used by `keystone maintenance` / `keystone prune`. `storage.redact_secrets_at_rest` controls whether secret inputs and known secrets are redacted before storing run data (default `true`).
+
 ### Model & Provider Resolution
 
 Keystone resolves which provider to use for a model in the following order:
@@ -196,6 +279,36 @@ providers:
 
 Authentication tokens for Copilot are managed automatically after the initial login. 
 
+### OpenAI ChatGPT Plus/Pro (OAuth)
+
+Keystone supports using your ChatGPT Plus/Pro subscription (OAuth) instead of an API key:
+
+```bash
+keystone auth login openai-chatgpt
+```
+
+Then map models to the `openai-chatgpt` provider in your config.
+
+### Anthropic Claude Pro/Max (OAuth)
+
+Keystone supports using your Claude Pro/Max subscription (OAuth) instead of an API key:
+
+```bash
+keystone auth login anthropic-claude
+```
+
+Then map models to the `anthropic-claude` provider in your config. This flow uses the Claude web auth code and refreshes tokens automatically.
+
+### Google Gemini (OAuth)
+
+Keystone supports using your Google Gemini subscription (OAuth) instead of an API key:
+
+```bash
+keystone auth login gemini
+```
+
+Then map models to the `google-gemini` provider in your config.
+
 ### API Key Management
 
 For other providers, you can either store API keys in a `.env` file in your project root:
@@ -260,6 +373,10 @@ finally:
     type: shell
     run: echo "Workflow finished"
 
+outputs:
+  slack_message: ${{ steps.notify.output }}
+```
+
 ### Expression Syntax
 
 Keystone uses `${{ }}` syntax for dynamic values. Expressions are evaluated using a safe AST parser.
@@ -271,15 +388,12 @@ Keystone uses `${{ }}` syntax for dynamic values. Expressions are evaluated usin
 - `${{ item }}`: Access the current item in a `foreach` loop.
 - `${{ args.name }}`: Access tool arguments (available ONLY inside agent tool execution steps).
 - `${{ secrets.NAME }}`: Access redacted secrets.
-- `${{ env.NAME }}`: Access environment variables.
-
-Standard JavaScript-like expressions are supported: `${{ steps.build.status == 'success' ? '🚀' : '❌' }}`.
+- `${{ env.NAME }}`: Access environment variables (process env merged with workflow-level `env`).
+  Workflow-level `env` is evaluated per step; if an expression cannot be resolved yet, the variable is skipped with a warning.
 
----
+Inputs support `values` for enums and `secret: true` for sensitive values (redacted in logs and at rest by default; resumptions may require re-entry).
 
-outputs:
-  slack_message: ${{ steps.notify.output }}
-```
+Standard JavaScript-like expressions are supported: `${{ steps.build.status == 'success' ? '🚀' : '❌' }}`.
 
 ---
 
@@ -287,27 +401,148 @@ outputs:
 
 Keystone supports several specialized step types:
 
+- Any step can optionally define `inputSchema` and/or `outputSchema` (JSON Schema) to validate evaluated inputs before execution and outputs after completion.
+
 - `shell`: Run arbitrary shell commands.
-- `llm`: Prompt an agent and get structured or unstructured responses. Supports `schema` (JSON Schema) for structured output.
+- `llm`: Prompt an agent and get structured or unstructured responses. Supports `outputSchema` (JSON Schema) for structured output.
   - `allowClarification`: Boolean (default `false`). If `true`, allows the LLM to ask clarifying questions back to the user or suspend the workflow if no human is available.
   - `maxIterations`: Number (default `10`). Maximum number of tool-calling loops allowed for the agent.
   - `allowInsecure`: Boolean (default `false`). Set `true` to allow risky tool execution.
   - `allowOutsideCwd`: Boolean (default `false`). Set `true` to allow tools to access files outside of the current working directory.
+  - `handoff`: Optional engine tool definition that lets the LLM delegate work to an allowlisted external CLI with structured inputs.
 - `request`: Make HTTP requests (GET, POST, etc.).
+  - `allowInsecure`: Boolean (default `false`). If `true`, skips SSRF protections and allows non-HTTPS/local URLs.
+  - Cross-origin redirects are blocked for non-GET/HEAD requests unless `allowInsecure: true`; on cross-origin redirects, non-essential headers are stripped.
 - `file`: Read, write, or append to files.
   - `allowOutsideCwd`: Boolean (default `false`). Set `true` to allow reading/writing files outside of the current working directory.
 - `human`: Pause execution for manual confirmation or text input.
   - `inputType: confirm`: Simple Enter-to-continue prompt.
   - `inputType: text`: Prompt for a string input, available via `${{ steps.id.output }}`.
 - `workflow`: Trigger another workflow as a sub-step.
-- `script`: Run arbitrary JavaScript in a sandbox. On Bun, uses `node:vm` (since `isolated-vm` requires V8).
-  - ⚠️ **Security Note:** The `node:vm` sandbox is not secure against malicious code. Only run scripts from trusted sources.
+  - `outputMapping`: Map sub-workflow outputs to step outputs.
+    ```yaml
+    outputMapping:
+      final_result: result_from_subflow
+      status: state
+    ```
+- `join`: Aggregate outputs from dependencies and enforce a completion condition.
+  - `target`: `'steps'` (default) or `'branches'` (for foreach).
+  - `condition`: `'all'` (default), `'any'`, or a number.
+- `blueprint`: Generate a structured system blueprint with an agent (persisted as an artifact).
+- `script`: Run JavaScript in a sandboxed subprocess. Requires `allowInsecure: true`.
 - `sleep`: Pause execution for a specified duration.
+  - `durable`: Boolean (default `false`). If `true` and duration >= 60s, the wait is persisted and can resume after restarts.
 - `memory`: Store or retrieve information from the semantic memory vector database.
+- `engine`: Run an allowlisted external CLI and capture a structured summary.
+  - `env` and `cwd` are required and must be explicit.
+  - `input` is sent to stdin (objects/arrays are JSON-encoded).
+  - Summary is parsed from stdout or a file at `KEYSTONE_ENGINE_SUMMARY_PATH` and stored as an artifact.
+
+### Human Steps in Non-Interactive Mode
+If stdin is not a TTY (CI, piped input), `human` steps suspend. Resume by providing an answer via inputs using the step id and `__answer`:
+
+```bash
+keystone run my-workflow --resume -i approve='{"__answer":true}'
+keystone resume <run_id> -i ask='{"__answer":"hello"}'
+```
+
+Human steps remain suspended until they receive an answer; the scheduler only resumes sleep timers.
+
+### Durable Sleeps and Scheduler
+For long waits, set `durable: true` on `sleep` steps (>=60s) to persist across restarts:
 
-All steps support common features like `needs` (dependencies), `if` (conditionals), `retry`, `timeout`, `foreach` (parallel iteration), `concurrency` (max parallel items for foreach), `transform` (post-process output using expressions), `learn` (auto-index for few-shot), and `reflexion` (self-correction loop).
+```yaml
+- id: wait_for_window
+  type: sleep
+  duration: 900000 # 15 minutes
+  durable: true
+```
 
-Workflows also support a top-level `concurrency` field to limit how many steps can run in parallel across the entire workflow. This must be a positive integer.
+Run the scheduler to resume runs when timers elapse:
+
+```bash
+keystone scheduler --interval 30
+```
+
+All steps support common features:
+- `needs`: Array of step IDs this step depends on.
+- `if`: Conditional expression.
+- `retry`: `{ count, backoff: 'linear'|'exponential', baseDelay }`.
+- `timeout`: Maximum execution time in milliseconds.
+- `foreach`: Iterate over an array in parallel.
+- `concurrency`: Limit parallel items for `foreach` (must be a positive integer).
+- `pool`: Assign step to a resource pool.
+- `compensate`: Step to run if the workflow rolls back.
+- `transform`: Post-process output using expressions.
+- `learn`: Auto-index for few-shot.
+- `reflexion`: Self-correction loop.
+- `auto_heal`: LLM-powered automatic error recovery (alias: `autoHeal`).
+- `inputSchema` / `outputSchema`: JSON Schema validation.
+- `outputRetries`: Max retries for output validation failures.
+- `repairStrategy`: Strategy for output repair (`reask`, `repair`, `hybrid`).
+
+Workflows also support a top-level `concurrency` field to limit how many steps can run in parallel across the entire workflow. This must resolve to a positive integer (number or expression).
+
+### Engine Steps
+Engine steps run allowlisted external CLIs and capture a structured summary for safe chaining.
+
+**Configuration (`.keystone/config.yaml`)**
+```yaml
+engines:
+  allowlist:
+    codex:
+      command: codex
+      version: "1.2.3"
+      versionArgs: ["--version"]
+```
+
+**Workflow example**
+```yaml
+- id: run_engine
+  type: engine
+  command: codex
+  args: ["run"]
+  cwd: .
+  env:
+    PATH: ${{ env.PATH }}
+  input:
+    task: "Summarize the repository"
+  outputSchema:
+    type: object
+    properties:
+      summary: { type: string }
+    required: [summary]
+```
+
+The engine can optionally write a summary file to `KEYSTONE_ENGINE_SUMMARY_PATH`. Otherwise, Keystone attempts to parse JSON/YAML from stdout and stores the summary as an artifact.
+
+### LLM Handoff to Engine
+Use `handoff` to expose an engine tool to the LLM with structured inputs:
+
+```yaml
+- id: delegate
+  type: llm
+  agent: planner
+  prompt: "Decide what to run and delegate to the engine."
+  handoff:
+    name: run_engine
+    inputSchema:
+      type: object
+      properties:
+        task: { type: string }
+      required: [task]
+    engine:
+      command: codex
+      args: ["run"]
+      cwd: .
+      env:
+        PATH: ${{ env.PATH }}
+      outputSchema:
+        type: object
+        properties:
+          summary: { type: string }
+        required: [summary]
+```
 
 ### Self-Healing Steps
 Steps can be configured to automatically recover from failures using an LLM agent.
@@ -337,6 +572,7 @@ When a step fails, the specified agent is invoked with the error details. The ag
   foreach: ${{ steps.list_files.output }}
   concurrency: 5 # Process 5 files at a time (must be a positive integer)
   run: echo "Processing ${{ item }}"
+```
 
 #### Example: Script Step
 ```yaml
@@ -344,11 +580,139 @@ When a step fails, the specified agent is invoked with the error details. The ag
   type: script
   allowInsecure: true
   run: |
-    const data = context.steps.fetch_data.output;
+    const data = steps.fetch_data.output;
     return data.map(i => i.value * 2).reduce((a, b) => a + b, 0);
 ```
+
+---
+
+## 🔧 Advanced Features
+
+### Idempotency Keys
+
+Make retries and resume operations safe for side-effecting steps by specifying an `idempotencyKey`. When a key matches a previous successful execution, the cached result is returned instead of re-executing the step.
+
+```yaml
+- id: charge_customer
+  type: request
+  url: https://api.stripe.com/charge
+  body: { amount: 100, customer: ${{ inputs.customer_id }} }
+  # Expression that evaluates to a unique key for this operation
+  idempotencyKey: '"charge-" + inputs.customer_id + "-" + inputs.order_id'
+  # Optional: dedupe across runs and expire after a TTL
+  idempotencyScope: global
+  idempotencyTtlSeconds: 86400
+```
+
+If a key is already in-flight, the step fails with an in-flight error to avoid duplicate side effects. To bypass deduplication for a run, use `keystone run --no-dedup`.
+
+Manage idempotency records via CLI:
+- `keystone dedup list` - View all idempotency records
+- `keystone dedup clear <run_id>` - Clear records for a specific run
+- `keystone dedup clear --all` - Clear all records
+- `keystone dedup prune` - Remove expired records
+
+### AllowFailure Pattern
+
+Enable fail-forward steps that continue workflow execution even when they fail. Useful for agentic exploration where some attempts may naturally fail.
+
+```yaml
+- id: try_approach_a
+  type: llm
+  agent: explorer
+  prompt: "Try approach A to solve the problem"
+  allowFailure: true  # Workflow continues if this fails
+
+- id: analyze_results
+  type: llm
+  agent: analyst
+  prompt: |
+    Approach A status: ${{ steps.try_approach_a.status }}
+    Error (if any): ${{ steps.try_approach_a.error }}
+    Output: ${{ steps.try_approach_a.output }}
 ```
 
+The step's `status` will be `'success'` even when it fails internally, but the `error` field will contain the failure details.
+
+### Global Errors Block
+
+Define workflow-level error handling that runs when a step exhausts retries. Access failure context via `last_failed_step`.
+
+```yaml
+name: resilient-workflow
+steps:
+  - id: critical_step
+    type: shell
+    run: exit 1
+    retry: { count: 2, backoff: exponential }
+
+errors:
+  - id: analyze_failure
+    type: llm
+    agent: debugger
+    prompt: |
+      Step ${{ last_failed_step.id }} failed with:
+      Error: ${{ last_failed_step.error }}
+      Suggest remediation steps.
+```
+
+The errors block runs after all retries/auto_heal are exhausted and before the `finally` block.
+
+### Input Enums and Secrets
+
+Constrain input values and mark sensitive data for automatic redaction.
+
+```yaml
+inputs:
+  environment:
+    type: string
+    values: [dev, staging, prod]  # Only these values allowed
+    default: dev
+  api_key:
+    type: string
+    secret: true  # Redacted in logs and at rest
+```
+
+Schema validation errors include path-level details and are surfaced before/after step execution.
+
+### Resource Pools
+
+Manage concurrency for external resources (like APIs or databases) across a workflow using `pools`.
+
+```yaml
+name: rate-limited-workflow
+pools:
+  api_pool: 2  # Limit to 2 concurrent steps using this pool
+
+steps:
+  - id: step1
+    type: request
+    url: ...
+    pool: api_pool
+  
+  - id: step2
+    type: request
+    url: ...
+    pool: api_pool
+```
+
+### Compensations (Rollback)
+
+Define "undo" actions for steps that have side effects. Compensations run in reverse order (LIFO) if a workflow fails or is cancelled.
+
+```yaml
+- id: create_user
+  type: request
+  url: https://api.example.com/users
+  compensate:
+    id: delete_user
+    type: request
+    url: https://api.example.com/users/${{ steps.create_user.outputs.id }}
+    method: DELETE
+```
+
+You can also define a workflow-level `compensate` step to handle overall cleanup.
+
 ---
 
 ## 🤖 Agent Definitions
@@ -380,7 +744,34 @@ Keystone comes with a set of **Standard Tools** that can be enabled for any agen
 - `list_files`: List files in a directory (arguments: `path`)
 - `search_files`: Search for files by glob pattern (arguments: `pattern`, `dir`)
 - `search_content`: Search for string or regex within files (arguments: `query`, `dir`, `pattern`)
-- `run_command`: Run a shell command (arguments: `command`, `dir`). Requires `allowInsecure: true` on the step unless whitelisted.
+- `run_command`: Run a shell command (arguments: `command`, `dir`). Risky commands require `allowInsecure: true` on the LLM step.
+
+#### Standard Tool Examples
+
+Agents can use these tools to interact with their environment. Here is how they appear when used by an agent:
+
+**Read File:**
+```yaml
+- name: read_file
+  arguments:
+    path: "src/utils/logger.ts"
+```
+
+**Write File:**
+```yaml
+- name: write_file
+  arguments:
+    path: "new_file.txt"
+    content: "Hello from Keystone!"
+```
+
+**Run Command:**
+```yaml
+- name: run_command
+  arguments:
+    command: "ls -la"
+    dir: "."
+```
 
 Tool arguments are passed to the tool's execution step via the `args` variable.
 
@@ -487,54 +878,95 @@ In these examples, the agent will have access to all tools provided by the MCP s
 | Command | Description |
 | :--- | :--- |
 | `init` | Initialize a new Keystone project |
-| `run <workflow>` | Execute a workflow (use `-i key=val` for inputs, `--dry-run` to test, `--debug` for REPL) |
-| `optimize <workflow>` | Optimize a specific step in a workflow (requires --target) |
-| `resume <run_id>` | Resume a failed or paused workflow |
+| `run <workflow>` | Execute a workflow (use `-i key=val`, `--resume` to auto-resume, `--dry-run`, `--debug`, `--no-dedup`, `--explain`) |
+| `resume <run_id>` | Resume a failed/paused/crashed workflow by ID (use `-i key=val` to answer human steps) |
 | `validate [path]` | Check workflow files for errors |
 | `workflows` | List available workflows |
 | `history` | Show recent workflow runs |
 | `logs <run_id>` | View logs, outputs, and errors for a specific run (`-v` for full output) |
 | `graph <workflow>` | Generate a Mermaid diagram of the workflow |
-| `config` | Show current configuration and providers |
+| `test [path]` | Run workflow tests with fixtures and snapshots |
+| `optimize <workflow>` | Optimize a specific step in a workflow (requires --target and workflow `eval`) |
+| `compile` | Compile a project into a single executable with embedded assets |
+| `dev <task>` | Run the self-bootstrapping DevMode workflow |
+| `manifest` | Show embedded assets manifest |
+| `config show` | Show current configuration and discovery paths (alias: `list`) |
 | `auth status [provider]` | Show authentication status |
-| `auth login [provider]` | Login to an authentication provider (github, openai, anthropic) |
+| `auth login [provider]` | Login to an authentication provider (github, openai, anthropic, openai-chatgpt, anthropic-claude, gemini/google-gemini) |
 | `auth logout [provider]` | Logout and clear authentication tokens |
 | `ui` | Open the interactive TUI dashboard |
 | `mcp start` | Start the Keystone MCP server |
 | `mcp login <server>` | Login to a remote MCP server |
+| `scheduler` | Run the durable timer scheduler to resume sleep timers |
+| `timers list` | List durable timers |
+| `timers clear` | Clear durable timers by run ID or `--all` |
+| `dedup list [run_id]` | List idempotency records (optionally filter by run) |
+| `dedup clear <target>` | Clear idempotency records by run ID or `--all` |
+| `dedup prune` | Remove expired idempotency records |
 | `completion [shell]` | Generate shell completion script (zsh, bash) |
 | `maintenance [--days N]` | Perform database maintenance (prune old runs and vacuum) |
+| `prune [--days N]` | Alias for `maintenance` |
 
 ---
- 
- ## 🛡️ Security
- 
- ### Shell Execution
- By default, Keystone analyzes shell commands for potentially dangerous patterns (like shell injection, `rm -rf`, piped commands). If a risk is detected:
- - In interactive mode, the user is prompted for confirmation.
- - In non-interactive mode, the step is suspended or failed.
- 
- You can bypass this check if you trust the command:
- ```yaml
- - id: deploy
-   type: shell
-   run: ./deploy.sh ${{ inputs.env }}
-   allowInsecure: true
- ```
- 
- ### Expression Safety
- Expressions `${{ }}` are evaluated using a safe AST parser (`jsep`) which:
- - Prevents arbitrary code execution (no `eval` or `Function`).
- - Whitelists safe global objects (`Math`, `JSON`, `Date`, etc.).
- - Blocks access to sensitive properties (`constructor`, `__proto__`).
- - Enforces a maximum template length to prevent ReDoS attacks.
- 
- ### Script Sandboxing
- The `script` step uses Node.js `vm` module. While it provides isolation for variables, it is **not a security boundary** for malicious code. Only run scripts from trusted sources.
- 
- ---
- 
- ## 📂 Project Structure
+
+Input keys passed via `-i key=val` must be alphanumeric/underscore and cannot be `__proto__`, `constructor`, or `prototype`.
+
+### Dry Run
+`keystone run --dry-run` prints shell commands without executing them and skips non-shell steps (including human prompts). Outputs from skipped steps are empty, so conditional branches may differ from a real run.
+
+## 🛡️ Security
+
+### Shell Execution
+Keystone blocks shell commands that match common injection/destructive patterns (like `rm -rf /` or pipes to shells). To run them, set `allowInsecure: true` on the step. Prefer `${{ escape(...) }}` when interpolating user input.
+
+You can bypass this check if you trust the command:
+```yaml
+- id: deploy
+  type: shell
+  run: ./deploy.sh ${{ inputs.env }}
+  allowInsecure: true
+```
+
+### Expression Safety
+Expressions `${{ }}` are evaluated using a safe AST parser (`jsep`) which:
+- Prevents arbitrary code execution (no `eval` or `Function`).
+- Whitelists safe global objects (`Math`, `JSON`, `Date`, etc.).
+- Blocks access to sensitive properties (`constructor`, `__proto__`).
+- Enforces a maximum template length to prevent ReDoS attacks.
+
+### Script Sandboxing
+Script steps run in a separate subprocess by default. This reduces risk but is **not a security boundary** for malicious code. Script steps are disabled by default; set `allowInsecure: true` to run them.
+
+### HTTP Requests
+Request steps enforce SSRF protections and require HTTPS by default. Cross-origin redirects are blocked for non-GET/HEAD requests unless `allowInsecure: true`, and non-essential headers are stripped on cross-origin redirects.
+
+---
+
+## 🏗️ Architecture
+
+```mermaid
+graph TD
+    CLI[CLI Entry Point] --> WR[WorkflowRunner]
+    CLI --> MCP[MCP Server]
+    WR --> SE[Step Executor]
+    WR --> FE[ForeachExecutor]
+    WR --> DB[(WorkflowDb)]
+    SE --> LLM[LLM Executor]
+    SE --> Shell[Shell Executor]
+    SE --> File[File Operations]
+    SE --> HTTP[HTTP Requests]
+    SE --> Human[Human Input]
+    LLM --> Adapters[LLM Adapters]
+    Adapters --> OpenAI
+    Adapters --> Anthropic
+    Adapters --> Copilot
+    Adapters --> ChatGPT
+    LLM --> MCPClient[MCP Client]
+    WR --> Eval[Expression Evaluator]
+    WR --> Pool[Resource Pool Manager]
+```
+
+## 📂 Project Structure
 
 - `src/db/`: SQLite persistence layer.
 - `src/runner/`: The core execution engine, handles parallelization and retries.