agent-orcha 0.0.4 → 0.0.5

package/dist/templates/agents/sandbox.agent.yaml

@@ -0,0 +1,56 @@
+name: sandbox
+description: A coding assistant that can execute JavaScript, fetch web pages, and search the web
+version: "1.0.0"
+
+llm:
+  name: default
+  temperature: 0.3
+
+prompt:
+  system: |
+    You are a hands-on coding assistant with access to a JavaScript sandbox and web tools.
+
+    Capabilities:
+    1. **Code execution** — Run JavaScript in an isolated sandbox using sandbox_exec.
+       Use console.log() for output and return values for results.
+       The sandbox supports async/await, standard JS globals (JSON, Math, Date, Buffer, URL, etc.),
+       and persists state across calls within a session.
+
+    2. **Web fetching** — Fetch and read web pages or API endpoints using sandbox_web_fetch.
+       HTML pages are automatically converted to clean markdown.
+       Use raw=true for JSON APIs or non-HTML content.
+
+    3. **Web search** — Search the web using sandbox_web_search to find information,
+       documentation, or answers to questions.
+
+    Workflow:
+    - When asked to solve a problem, write and execute code to verify your solution
+    - When asked about external data, search the web or fetch specific URLs
+    - Combine tools: search for information, fetch relevant pages, then process data with code
+    - Always show your work — share code and results with the user
+
+    Rules:
+    - The sandbox does NOT have fetch or require — use sandbox_web_fetch for HTTP requests
+    - Check the error field in execution results to catch failures
+    - For multi-step computations, use the persistent sandbox state to build up results
+  inputVariables:
+    - query
+
+tools:
+  - sandbox:exec
+  - sandbox:web_fetch
+  - sandbox:web_search
+
+skills:
+  - sandbox
+
+output:
+  format: text
+
+metadata:
+  category: utility
+  tags:
+    - sandbox
+    - coding
+    - web
+    - example

package/dist/templates/knowledge/example.knowledge.yaml

@@ -17,9 +17,6 @@ splitter:
 
 embedding: default  # References embedding config in llm.json
 
-store:
-  type: memory  # Use 'chroma' for production with persistent storage
-
 search:
   defaultK: 4
   scoreThreshold: 0.2

package/dist/templates/knowledge/org-chart/personnel.csv

@@ -0,0 +1,21 @@
+employee_id,employee_name,title,department_id,department_name,manager_id,manager_name,location,hire_date,status,review_period,rating,strengths,areas_for_growth,summary
+E001,Sarah Chen,Chief Executive Officer,D01,Executive,,,,2018-03-15,active,2025-H1,5,Visionary leadership and strategic planning,Delegation to new VPs,Exceptional year driving company growth from 50 to 120 employees. Led Series B fundraising and established international partnerships.
+E002,James Rodriguez,VP of Engineering,D02,Engineering,E001,Sarah Chen,San Francisco,2019-01-10,active,2025-H1,5,Technical architecture and team scaling,"Cross-functional communication, documentation",Built engineering org from 8 to 35 engineers. Architected migration to microservices reducing latency by 40%.
+E003,Priya Patel,VP of Product,D03,Product,E001,Sarah Chen,San Francisco,2019-06-01,active,2025-H1,4,Customer empathy and roadmap prioritization,Data-driven decision making,Successfully launched 3 major product lines. Needs to leverage analytics more in feature prioritization.
+E004,Marcus Thompson,VP of Sales,D04,Sales,E001,Sarah Chen,New York,2020-02-01,active,2025-H1,4,Relationship building and enterprise deals,Pipeline forecasting accuracy,Exceeded revenue targets by 22%. Enterprise segment grew 45% YoY. Forecasting still needs improvement.
+E005,Lisa Wang,VP of People,D05,People & Culture,E001,Sarah Chen,San Francisco,2020-09-01,active,2025-H1,4,Culture building and talent acquisition,Retention strategy for senior engineers,Reduced time-to-hire by 30%. Employee satisfaction scores at 4.2/5. Attrition in senior engineering needs attention.
+E006,David Kim,Senior Staff Engineer,D02,Engineering,E002,James Rodriguez,San Francisco,2019-03-20,active,2025-H1,5,System design and mentoring junior engineers,Public speaking and conference presence,Led redesign of payment processing system handling $2M daily transactions. Mentored 6 engineers to promotion.
+E007,Anna Kowalski,Staff Engineer,D02,Engineering,E002,James Rodriguez,Remote,2020-01-15,active,2025-H1,4,Backend performance optimization,Frontend skills and full-stack contribution,Optimized database queries reducing P99 latency from 800ms to 120ms. Should broaden full-stack capabilities.
+E008,Carlos Mendez,Senior Engineer,D02,Engineering,E006,David Kim,San Francisco,2021-04-01,active,2025-H1,4,API design and testing practices,Ownership of larger projects independently,Designed REST API v3 adopted by 200+ integrators. Ready for staff-level scope with more independent ownership.
+E009,Emily Foster,Senior Engineer,D02,Engineering,E006,David Kim,Remote,2021-07-15,active,2025-H1,3,Code quality and thorough reviews,Delivery speed and prioritization,Excellent code quality but missed 2 sprint deadlines. Needs to balance perfectionism with delivery velocity.
+E010,Raj Gupta,Engineer,D02,Engineering,E007,Anna Kowalski,San Francisco,2022-06-01,active,2025-H1,4,Quick learner with strong algorithms background,Production debugging and operational skills,Shipped 3 features in first year. Strong CS fundamentals. Needs more exposure to production operations and on-call.
+E011,Sophie Martin,Senior Product Manager,D03,Product,E003,Priya Patel,San Francisco,2020-03-01,active,2025-H1,4,User research and feature specification,Stakeholder management across engineering teams,Led mobile app redesign increasing DAU by 35%. Should improve collaboration with engineering leads on technical constraints.
+E012,Tom Bradley,Product Manager,D03,Product,E003,Priya Patel,Remote,2021-11-01,active,2025-H1,3,Competitive analysis and market research,Defining measurable success metrics for features,Good market intuition but feature specs lack clear KPIs. Needs to define measurable outcomes before development starts.
+E013,Rachel Green,Enterprise Account Executive,D04,Sales,E004,Marcus Thompson,New York,2020-08-01,active,2025-H1,5,Closing complex enterprise deals,Mentoring junior sales reps,Closed 3 deals over $500K including the Globex contract. Top performer in the sales organization.
+E014,Michael Scott,Account Executive,D04,Sales,E004,Marcus Thompson,New York,2021-03-15,active,2025-H1,3,Enthusiasm and client rapport,Following structured sales methodology and CRM discipline,Strong relationship builder but pipeline management is inconsistent. CRM data entry needs significant improvement.
+E015,Nina Petrov,Sales Development Rep,D04,Sales,E013,Rachel Green,New York,2022-09-01,active,2025-H1,4,Cold outreach and lead qualification,Transitioning from SDR to AE conversations,Generated 45 qualified opportunities in H1. Shows strong AE potential and is ready for promotion consideration.
+E016,Alex Rivera,Senior Designer,D03,Product,E003,Priya Patel,San Francisco,2020-05-15,active,2025-H1,4,UI/UX design and design system maintenance,User research methodology and testing,Redesigned the component library saving 200+ engineering hours. Should deepen skills in user testing and research.
+E017,Jordan Lee,DevOps Engineer,D02,Engineering,E002,James Rodriguez,Remote,2021-01-10,active,2025-H1,4,CI/CD pipelines and infrastructure automation,Security best practices and compliance,Reduced deployment time from 45min to 8min. Built monitoring dashboards adopted by all teams. Should pursue security certifications.
+E018,Maria Santos,People Operations Manager,D05,People & Culture,E005,Lisa Wang,San Francisco,2021-06-01,active,2025-H1,4,Process improvement and employee onboarding,Conflict resolution and difficult conversations,Revamped onboarding reducing ramp-up time by 25%. Needs coaching on handling performance improvement plans.
+E019,Chris Evans,Junior Engineer,D02,Engineering,E007,Anna Kowalski,San Francisco,2023-01-15,active,2025-H1,3,Eagerness to learn and strong collaboration,Code architecture and design patterns,Good progress for first year. Completes assigned tasks well. Needs to develop ability to break down larger problems independently.
+E020,Diana Torres,Marketing Manager,D04,Sales,E004,Marcus Thompson,Remote,2021-08-01,active,2025-H1,4,Content strategy and demand generation,Marketing analytics and attribution modeling,Grew inbound leads by 60% through content marketing. Should develop stronger analytics capabilities for ROI measurement.

package/dist/templates/knowledge/org-chart.knowledge.yaml

@@ -0,0 +1,49 @@
+name: org-chart
+description: Company org chart with personnel directory and performance reviews
+
+source:
+  type: file
+  path: knowledge/org-chart/personnel.csv
+
+loader:
+  type: csv
+
+splitter:
+  type: character
+  chunkSize: 800
+  chunkOverlap: 0
+
+embedding: default
+
+search:
+  defaultK: 5
+
+graph:
+  directMapping:
+    entities:
+      - type: Department
+        idColumn: department_id
+        nameColumn: department_name
+        properties: []
+      - type: Employee
+        idColumn: employee_id
+        nameColumn: employee_name
+        properties:
+          - title
+          - location
+          - hire_date
+          - status
+          - rating
+          - strengths
+          - areas_for_growth
+    relationships:
+      - type: WORKS_IN
+        source: Employee
+        target: Department
+        sourceIdColumn: employee_id
+        targetIdColumn: department_id
+      - type: REPORTS_TO
+        source: Employee
+        target: Employee
+        sourceIdColumn: employee_id
+        targetIdColumn: manager_id

package/dist/templates/knowledge/pet-store.knowledge.yaml

@@ -0,0 +1,78 @@
+name: pet-store
+description: Pet store inventory with species, breeds, pets, and supplies
+
+source:
+  type: database
+  connectionString: sqlite://knowledge/pet-store/pet-store.db
+  query: |
+    SELECT
+      p.id       AS pet_id,
+      p.name     AS pet_name,
+      p.age,
+      p.price,
+      p.status,
+      p.description AS content,
+      b.id       AS breed_id,
+      b.name     AS breed_name,
+      b.size,
+      b.temperament,
+      b.avg_lifespan,
+      s.id       AS species_id,
+      s.name     AS species_name
+    FROM pets p
+    JOIN breeds b ON p.breed_id = b.id
+    JOIN species s ON b.species_id = s.id
+  contentColumn: content
+  metadataColumns:
+    - pet_id
+    - pet_name
+    - breed_name
+    - species_name
+    - status
+    - price
+
+loader:
+  type: text
+
+splitter:
+  type: character
+  chunkSize: 500
+  chunkOverlap: 50
+
+embedding: default
+
+search:
+  defaultK: 5
+
+graph:
+  directMapping:
+    entities:
+      - type: Species
+        idColumn: species_id
+        nameColumn: species_name
+        properties: []
+      - type: Breed
+        idColumn: breed_id
+        nameColumn: breed_name
+        properties:
+          - size
+          - temperament
+          - avg_lifespan
+      - type: Pet
+        idColumn: pet_id
+        nameColumn: pet_name
+        properties:
+          - age
+          - price
+          - status
+    relationships:
+      - type: IS_BREED
+        source: Breed
+        target: Species
+        sourceIdColumn: breed_id
+        targetIdColumn: species_id
+      - type: BELONGS_TO
+        source: Pet
+        target: Breed
+        sourceIdColumn: pet_id
+        targetIdColumn: breed_id

package/dist/templates/knowledge/web-docs.knowledge.yaml

@@ -0,0 +1,20 @@
+name: web-docs
+description: Solar System knowledge base scraped from Wikipedia
+
+source:
+  type: web
+  url: https://en.wikipedia.org/wiki/Solar_System
+  selector: ".mw-parser-output"
+
+loader:
+  type: text
+
+splitter:
+  type: recursive
+  chunkSize: 1000
+  chunkOverlap: 200
+
+embedding: default
+
+search:
+  defaultK: 4

package/dist/templates/llm.json

@@ -17,7 +17,7 @@
     "gemini": {
       "provider": "gemini",
       "apiKey": "your-gemini-api-key-here",
-      "model": "gemini-2.0-flash-exp",
+      "model": "gemini-2.5-flash",
       "temperature": 0.7
     }
   },
@@ -38,7 +38,7 @@
     "gemini": {
       "provider": "gemini",
       "apiKey": "your-gemini-api-key-here",
-      "model": "text-embedding-004"
+      "model": "gemini-embedding-001"
     }
   }
 }

package/dist/templates/mcp.json

@@ -7,6 +7,9 @@
       "description": "Web fetch capabilities for retrieving URLs and returning markdown",
       "timeout": 30000,
       "enabled": true
+    },
+    "htmlhost": {
+      "url": "https://htmlhost.jax.workers.dev/mcp"
     }
   },
   "globalOptions": {

package/dist/templates/skills/orcha-builder/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: orcha-builder
+description: Documentation for creating and modifying ORCHA resources (agents, workflows, skills, functions, knowledge stores)
+---
+
+# ORCHA Resource Schemas
+
+Use this reference when creating or modifying ORCHA resources. All resource files live in the workspace root under their respective directories.
+
+---
+
+## Agents (`agents/<name>.agent.yaml`)
+
+```yaml
+name: my-agent                    # Unique identifier (kebab-case)
+description: What the agent does  # Human-readable description
+version: "1.0.0"                  # Optional, defaults to 1.0.0
+
+llm:
+  name: default                   # LLM config name from llm.json
+  temperature: 0.7                # 0.0 = deterministic, 1.0 = creative
+
+prompt:
+  system: |
+    You are a helpful assistant.
+    Your instructions go here.
+  inputVariables:
+    - query                       # Variables injected at runtime
+
+tools:                            # Optional tool references
+  - mcp:server-name               # All tools from an MCP server
+  - knowledge:store-name          # Knowledge search tools
+  - function:my-function          # Custom function tool
+  - builtin:tool-name             # Built-in tool
+  - sandbox:exec                  # Sandbox tools (exec, web_fetch, web_search)
+  - workspace:read                  # Workspace tools (read, write, list, list_resources)
+
+skills:                           # Optional skills
+  - skill-name                    # Skill name from skills directory
+  # OR
+  mode: all                       # Include all available skills
+
+output:                           # Optional output config
+  format: text                    # text | json | structured
+  schema:                         # Required if format is structured
+    type: object
+    properties:
+      result:
+        type: string
+
+memory:                           # Optional conversation memory
+  enabled: true
+  maxLines: 100                   # Max conversation history lines
+
+metadata:                         # Optional metadata
+  category: general
+  tags:
+    - example
+
+integrations:                     # Optional integrations
+  - type: collabnook
+    url: wss://collabnook.com/ws
+    channel: general
+    botName: MyBot
+
+triggers:                         # Optional triggers
+  - type: cron
+    schedule: "*/5 * * * *"       # Cron expression
+    input:
+      query: "Periodic task"
+```
+
+---
+
+## Step-Based Workflows (`workflows/<name>.workflow.yaml`)
+
+```yaml
+name: my-workflow
+description: What the workflow does
+version: "1.0.0"
+type: steps                       # "steps" for step-based workflows
+
+input:
+  schema:                         # Typed input fields
+    query:
+      type: string                # string | number | boolean | array | object
+      required: true
+      description: "The user query"
+
+steps:
+  - id: step-one                  # Unique step identifier (NOT "name")
+    agent: agent-name             # Agent to invoke
+    input:
+      query: "{{query}}"          # Variable interpolation
+    output:                       # Output is an object (NOT a string)
+      key: step_one_result        # Variable name to store result
+      extract: output             # Optional: extract a specific field
+
+  - id: step-two
+    agent: another-agent
+    input:
+      query: "{{step_one_result}}"
+    output:
+      key: step_two_result
+    condition: "{{step_one_result}}"  # Optional: skip if falsy
+
+  - parallel:                     # Parallel execution (no "name" key here)
+      - id: branch-a
+        agent: agent-a
+        input:
+          query: "{{query}}"
+        output:
+          key: result_a
+      - id: branch-b
+        agent: agent-b
+        input:
+          query: "{{query}}"
+        output:
+          key: result_b
+
+config:                           # Optional workflow config
+  timeout: 300000                 # Default 300000ms
+  onError: stop                   # stop | continue | retry
+
+output:
+  result: "{{step_two_result}}"
+```
+
+---
+
+## LangGraph Workflows (`workflows/<name>.workflow.yaml`)
+
+```yaml
+name: my-graph-workflow
+description: Graph-based workflow with tool and agent discovery
+version: "1.0.0"
+type: langgraph
+
+input:
+  schema:                         # Typed input fields (same as step-based)
+    query:
+      type: string
+      required: true
+      description: "The user query"
+
+prompt:                           # REQUIRED for langgraph workflows
+  system: |
+    You are a helpful assistant that uses available tools and agents.
+  goal: "Answer the user's query using available tools"
+
+graph:
+  model: default                  # LLM config name, defaults to "default"
+  tools:
+    sources:                      # Tool sources to discover
+      - mcp
+      - knowledge
+      - function
+      - builtin
+    mode: all                     # all | none | include | exclude
+    exclude:                      # Optional exclusion list
+      - dangerous_tool
+  agents:
+    mode: all                     # all | none | include | exclude
+    exclude:
+      - architect                  # Prevent recursive invocation
+  executionMode: react            # react | single-turn (default: react)
+  maxIterations: 10               # Max tool-call loops (default: 10)
+  timeout: 300000                 # Timeout in ms (default: 300000)
+
+output:
+  result: "{{result}}"
+```
+
+---
+
+## Knowledge Stores (`knowledge/<name>.knowledge.yaml`)
+
+```yaml
+name: my-knowledge
+description: What this knowledge store contains
+
+source:
+  # Directory source
+  type: directory                 # directory | file | database | web | s3
+  path: ./docs                    # Relative to workspace root
+  pattern: "**/*.md"              # Glob pattern for file matching (NOT "glob")
+  recursive: true                 # Default: true
+
+  # --- OR file source ---
+  # type: file
+  # path: ./data/report.pdf
+
+  # --- OR database source ---
+  # type: database
+  # connectionString: postgresql://user:pass@host:5432/db  # postgresql://, mysql://, or sqlite://
+  # query: "SELECT content FROM documents"
+  # contentColumn: content        # Default: "content"
+  # metadataColumns: [id, title]  # Optional
+  # batchSize: 100                # Optional, default: 100
+
+  # --- OR web source ---
+  # type: web
+  # url: https://example.com/docs
+  # selector: ".main-content"     # Optional CSS selector
+  # headers:                      # Optional custom headers
+  #   Authorization: "Bearer token"
+
+loader:                           # REQUIRED (has defaults)
+  type: text                      # text | pdf | csv | json | markdown
+
+splitter:
+  type: recursive                 # character | recursive | token | markdown
+  chunkSize: 1000
+  chunkOverlap: 200
+
+embedding: default                # String reference to llm.json config (NOT an object)
+
+search:                           # Optional
+  defaultK: 4
+  scoreThreshold: 0.5             # Optional minimum score
+
+graph:                            # Optional: enable graph entities via direct mapping
+  directMapping:
+    entities:
+      - type: Person              # Entity type label
+        idColumn: id              # Column for entity ID
+        nameColumn: name          # Optional: column for display name
+        properties:               # Columns to include as properties
+          - email                 # String = same column name
+          - { role: job_title }   # Object = { propertyName: columnName }
+    relationships:                # Optional: define relationships
+      - type: WORKS_FOR
+        source: Person            # Source entity type
+        target: Organization      # Target entity type
+        sourceIdColumn: person_id
+        targetIdColumn: org_id
+        groupNode: department     # Optional: group by column
+```
+
+---
+
+## Custom Functions (`functions/<name>.function.js`)
+
+```javascript
+export const metadata = {
+  name: "my-function",
+  description: "What this function does",
+  version: "1.0.0",
+  tags: ["utility"]
+};
+
+export const parameters = {
+  type: "object",
+  properties: {
+    input: {
+      type: "string",
+      description: "The input parameter"
+    }
+  },
+  required: ["input"]
+};
+
+export default async function({ input }) {
+  // Your logic here
+  return { result: `Processed: ${input}` };
+}
+```
+
+---
+
+## Skills (`skills/<name>/SKILL.md`)
+
+```markdown
+---
+name: my-skill
+description: What this skill teaches the agent
+---
+
+# Skill Title
+
+Instructions, context, and knowledge that get injected into the agent's prompt.
+Use markdown formatting for structure.
+```
+
+Skills with `sandbox: true` in frontmatter indicate they require sandbox tools.
+
+---
+
+## MCP Server Configuration (`mcp.json`)
+
+The `mcp.json` file in the workspace root configures external MCP servers. Agents reference them via `mcp:<server-name>` in their tools list.
+
+```json
+{
+  "version": "1.0.0",
+  "servers": {
+    "server-name": {
+      "url": "https://example.com/mcp",
+      "description": "What this server provides",
+      "timeout": 30000,
+      "enabled": true
+    }
+  },
+  "globalOptions": {
+    "throwOnLoadError": false,
+    "prefixToolNameWithServerName": true,
+    "additionalToolNamePrefix": "",
+    "defaultToolTimeout": 30000
+  }
+}
+```
+
+**Server config fields:**
+- `url` — Required for remote servers (auto-detects `streamable-http` transport)
+- `command` + `args` — Required for local stdio servers (auto-detects `stdio` transport)
+- `transport` — Explicit: `stdio`, `sse`, `streamable-http`, or `sse-only` (auto-detected if omitted)
+- `headers` — Optional HTTP headers (e.g. for auth)
+- `env` — Optional environment variables (for stdio servers)
+- `description` — Optional human-readable description
+- `timeout` — Request timeout in ms (default: 30000)
+- `enabled` — Set to `false` to disable without removing (default: true)
+
+**Adding a new MCP server:**
+1. Read `mcp.json` first to preserve existing servers
+2. Add the new server entry to the `servers` object
+3. Write the updated `mcp.json` back
+4. Create an agent that references it with `tools: [mcp:server-name]`
+
+---
+
+## Best Practices
+
+- **Naming**: Use kebab-case for all resource names (e.g. `weather-bot`, `data-pipeline`)
+- **Temperature**: Use 0.0-0.3 for structured/deterministic tasks, 0.5-0.7 for creative/conversational
+- **Tools**: Only include tools the agent actually needs — fewer tools = better focus
+- **Prompts**: Be specific and include examples in system prompts; use inputVariables for dynamic content
+- **Read before write**: Always read an existing resource before modifying it to preserve fields you're not changing
+- **Uniqueness**: Check `workspace_list_resources` before creating to avoid name collisions
+- **Skills**: Use skills to share knowledge across multiple agents without duplicating prompt content

package/dist/templates/skills/sandbox/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: sandbox
+description: Execute JavaScript code and fetch web content in an isolated sandbox
+sandbox: true
+---
+
+# Sandbox Execution
+
+You have access to sandbox tools for running JavaScript code and fetching web content.
+
+## Tool: sandbox_exec
+
+Execute JavaScript code in an isolated VM sandbox.
+
+**Parameters:**
+- `code` (required): JavaScript code to execute (runs in async context, so `await` works)
+- `timeout` (optional): Execution timeout in milliseconds
+
+**Returns:** JSON with `stdout` (console output), `result` (return value), and `error` (if any)
+
+**Available globals:** JSON, Math, Date, Buffer, URL, URLSearchParams, TextEncoder, TextDecoder, setTimeout, and standard JS built-ins.
+
+**Not available:** `fetch`, `require`, file system access. Use `sandbox_web_fetch` for HTTP requests.
+
+## Tool: sandbox_web_fetch
+
+Fetch web page content or API responses.
+
+**Parameters:**
+- `url` (required): HTTP or HTTPS URL to fetch
+- `raw` (optional): Return raw content without HTML-to-markdown conversion
+- `runScripts` (optional): Run page JavaScript before extracting content (default: true)
+
+**Returns:** JSON with `content`, `url`, `status`, and `truncated`
+
+## Tool: sandbox_web_search
+
+Search the web using DuckDuckGo.
+
+**Parameters:**
+- `query` (required): Search query
+- `num_results` (optional): Max results to return (default 10)
+
+**Returns:** JSON with `results` (formatted list) and `query`
+
+## Usage Examples
+
+Run JavaScript code:
+```
+sandbox_exec({ code: "const sum = [1,2,3].reduce((a,b) => a+b, 0); console.log(sum); return sum;" })
+```
+
+Fetch a web page:
+```
+sandbox_web_fetch({ url: "https://example.com" })
+```
+
+## Best Practices
+
+1. Use `console.log()` for output and `return` for the final result
+2. Use `sandbox_web_fetch` for HTTP requests instead of trying to use `fetch` in sandbox_exec
+3. Check the `error` field in results to verify execution success
+4. Handle errors gracefully — read `error` for diagnostics