orc-ai 0.1.31 → 0.1.35

package/README.md

@@ -136,7 +136,7 @@ The web dashboard ships inside the `orc` binary and is served by the API process
 | `GET /api/*`                       | All REST routes                                                                                                                |
 | `GET /openapi.json`, `GET /docs`   | Swagger UI                                                                                                                     |
 | `GET /mcp`                         | MCP server (streamable HTTP)                                                                                                   |
-| `GET /tasks/<id>`, `/flows/<name>`, … | `index.html` again - a navigation request matching no static file falls back to the SPA shell, so dashboard links are shareable |
+| `GET /tasks/<id>`, `/knowledge`, … | `index.html` again - a navigation request matching no static file falls back to the SPA shell, so dashboard links are shareable |
 
 Override the served dist directory with `ORC_WEB_DIST=/path/to/web/dist` if you want to host a custom build (e.g. a fork). If no dist is found, the server runs in pure-API mode.
 
@@ -181,7 +181,9 @@ Or with [docker-compose.yml](docker-compose.yml):
 docker compose up -d
 ```
 
-The container defaults to the `claude` backend (direct Anthropic API via SDK — no host CLI needed). To delegate to an agent running on the host instead, set `ORC_AGENT_LOOP_DEFAULT_BACKEND=agentapi` and run [coder/agentapi](https://github.com/coder/agentapi) on the host:
+The source Docker image includes Node, ACPX, Claude Code and Codex CLI, with versions pinned in the Dockerfile. Its default backend is `claude` through the Anthropic SDK. Tool installation alone does not supply authentication: provide `ANTHROPIC_API_KEY` for Claude, `OPENAI_API_KEY` or a container-local Codex login for `codex-cli`, and the credentials required by whichever agent ACPX launches. Mount your repository and use its **container path** as the project folder. Agent configuration/session files can persist in the Compose `orc-home` volume. Existing ORC policies still apply; native Codex rule interception is not certified by CLI/tool availability. These source changes do not update an already published image.
+
+To delegate to an agent running on the host instead, set `ORC_AGENT_LOOP_DEFAULT_BACKEND=agentapi` and run [coder/agentapi](https://github.com/coder/agentapi) on the host:
 
 ```bash
 agentapi server --allowed-hosts '*' -- \
@@ -340,6 +342,12 @@ orc doctor --json   # same, machine-readable
 
 The dashboard shows the same probe: the agent-backend field on a task is a picker that marks each backend ready or unavailable, and names the one a task with no backend of its own will use. `GET /api/backends` is the endpoint behind both.
 
+Standalone executables embed the SDK adapter, but its native Claude executable is
+external. Install Claude Code on `PATH` to use `claude` in a standalone build; an
+API key alone does not supply that executable. The npm distribution uses the SDK's
+installed optional executable. Windows npm shims require their `cli.js` and Node
+or Bun; missing executable prerequisites are reported before launching a session.
+
 Enable the task loop in `~/.orc/config.json`:
 
 ```json
@@ -443,21 +451,18 @@ The graph itself is deterministic; only the nodes are agents. That means loops,
 
 ```bash
 orc flow list                                    # what graphs are available
-orc flow show orc-plan-build-verify              # nodes, edges, limits
-orc task add "Fix the flaky test" --flow orc-fix-verify
+orc flow show orc-default              # nodes, edges, limits
+orc task add "Fix the flaky test" --flow orc-default --skill orc-bugfix
 orc flow status <taskId>                         # active nodes + the ledger of outcomes
 orc flow resume <taskId> --outcome approved      # resolve a human gate
 orc flow halt <taskId>                           # stop it and kill live nodes
 ```
 
-| Built-in flow           | Shape                                                                        |
-| ----------------------- | ---------------------------------------------------------------------------- |
-| `orc-default`           | build → review → done, looping back while `max_review_rounds` allows         |
-| `orc-review-only`       | A single review pass for a task you moved straight to `review`               |
-| `orc-plan-build-verify` | planner → coder → reviewer, looping until acceptance criteria pass           |
-| `orc-fix-verify`        | bugfix → independent confirmation the fix holds and a regression test exists  |
-| `orc-supervisor`        | Executor keeping its context, plus a supervisor re-verifying from a clean one |
-| `orc-parallel-review`   | Fan out to correctness / security / tests reviewers, join on all three       |
+| Built-in workflow | Use it for |
+| --- | --- |
+| `orc-default` | Development: understand, plan as needed, implement, verify and independently review; bounded rework. `required_review: false` explicitly skips agent review. |
+| `orc-human-review` | The same development process plus human sign-off. Agent review and human approval are always required, even if `required_review` is false. |
+| `orc-review-only` | Review existing work; approve, request changes, or pause when evidence is insufficient. |
 
 **Nodes** are `agent` (runs a session with a skill), `gate` (deterministic branching, fan-out, join points), `human` (waits for you), or `terminal` (ends the run and sets the task's final status). **Edges** carry declarative conditions — `outcome`, `visits`, `var`, `elapsed_secs`, composed with `all`/`any`/`not` — which are data, never evaluated code.
 
@@ -562,6 +567,21 @@ npx skills add niradler/orc --all -g
 
 Skill templates live in `skills/*/SKILL.md` (built-in) and `~/.orc/skills/` (user-defined). Agents discover them via `skill_list` and load with `skill_read`.
 
+On the **Skills** page, each built-in has an **Agent discovery** toggle, plus
+**Hide all built-ins** and **Show all built-ins** controls. Visibility applies
+across the installation and defaults to visible. Hidden built-ins stay on the
+Skills page for management and remain readable by name, including supporting
+files; existing task flows continue to use them. User/imported skills and authored
+global/project instruction overrides remain discoverable.
+
+The policy is saved under `skills.hidden_builtins` in `~/.orc/config.json` and
+read afresh for discovery, including by existing MCP processes. `GET /api/skills`
+omits hidden built-ins; `include_hidden=true` returns the management catalog with
+`discovery_hidden` metadata. `GET /api/skills/settings/visibility` reads the policy and
+`PUT /api/skills/settings/visibility` replaces its `hidden_builtins` array using the usual
+API authentication. This installation-wide preference ignores project config.
+New built-ins default to visible until hidden explicitly.
+
 | Skill              | Type     | Purpose                                                                     |
 | ------------------ | -------- | --------------------------------------------------------------------------- |
 | `orc-worker-base`  | Base     | Default worker behavior - ORC awareness, status updates, deliverable format |
@@ -596,9 +616,19 @@ orc skill validate ./my-workflow
 orc skill export my-workflow ./exported/my-workflow
 ```
 
+Import public GitHub skills from **Skills → Import from GitHub**. Paste a repository URL, `owner/repo`, a GitHub skill-folder URL, or a `https://skills.sh/owner/repo/skill` link, discover the skills, then select which to import. ORC copies each complete folder at the displayed commit, including nested documentation, scripts and binary assets. Existing names are never overwritten by an import. Select up to 16 skills per import (64 MiB total).
+
+```bash
+orc skill import vercel-labs/agent-skills --list
+orc skill import vercel-labs/agent-skills --skill web-design-guidelines
+orc skill sync web-design-guidelines
+```
+
+Imported skills remain editable: open the skill, choose `SKILL.md` or a supporting text file, then **Edit** and **Save changes**. **Sync from GitHub** fetches the source again and compares each file against its last imported version. Local edits are kept when upstream has not changed that file. If both sides changed the same file, the whole sync pauses and lists conflicts. **Review override → Replace listed files** requires confirmation and replaces only those conflicts with upstream versions; unrelated local edits remain. If the local files or upstream commit changed since review, ORC requires a new sync check. Sync retains the previous folder under `~/.orc/skill-sync-backups/`; import provenance and upstream baselines live under `~/.orc/skill-imports/`. These backups are retained until manually removed. Private repositories and non-GitHub sources are not supported by this importer.
+
 The dashboard can import a skill folder or add supporting files individually, then open each file from the detail sheet. API `POST /api/skills` and MCP `skill_create` accept optional `files: [{ path, content, encoding? }]` alongside `name` and the full `SKILL.md` `content`. Encoding defaults to `utf8`. Bundles allow 512 supporting files, 8 MiB per file and 16 MiB total. Paths must stay inside the skill folder; symlinks are excluded and cannot be read. The legacy `references` inventory is retained for existing clients. Worker prompts include the skill's entry path and file inventory so relative links resolve from the skill directory.
 
-### Shared agents and APM packages
+### Shared agents and portable packages
 
 ORC shares authored definitions across coding agents through one library. An agent profile describes the specialist; a backend selects the coding agent that runs it. Profiles use [APM's `.agent.md` format](https://microsoft.github.io/apm/producer/author-primitives/instructions-and-agents/): YAML frontmatter with a required `description`, optional `name`, `model`, `tools`, `color`, and `handoffs`, followed by Markdown instructions. Unknown agent fields are preserved. Standalone profiles live in `~/.orc/agents/`; project profiles in `.apm/agents/` override matching shared IDs.
 
@@ -621,7 +651,9 @@ Select a shared profile independently of its backend in an ORC flow:
 
 The same profile instructions and relative file locations reach every backend. Pinned models are supported by Claude SDK, Claude CLI, Codex CLI, and ACPX. Tool allowlists are enforced by Claude SDK and Claude CLI; other adapters reject profiles declaring tool restrictions. Unsupported model/tool settings fail before launch. Tool names and model IDs must be valid for the selected coding agent. Explicit session/flow model choices override the profile's model. Handoffs remain authored declarations; ORC flow edges control execution. Package instructions without `applyTo` are included automatically; scoped instructions retain their original glob strings or arrays in an on-demand index, which the coding agent applies when working on matching files.
 
-The dashboard's Agents page imports packages and creates/reads profiles. API `/api/agents` and `/api/agent-packages`, SDK clients, CLI, and MCP all access the same files. MCP tools are `agent_list`, `agent_read`, `agent_create`, `agent_package_list`, `agent_package_read`, and `agent_package_import`. Package agent IDs are namespaced as `<package>/<file-stem>`.
+The dashboard's **Packages** page imports OpenAPM and portable Agent Plugins v1.0.0 folders, inspects/exports their files, and saves reusable agent setups. **Run with → Open in ORC terminal** prepares the selected packages through Microsoft APM or Vercel skills, then opens the coding agent. Deployment persists in the chosen project; normal upstream trust and authentication prompts remain. Whole portable plugins activate through APM/Copilot; skills-only plugins can use Vercel with Claude, Codex or Copilot. See [Reusable agent packages](docs/agent-packages.md) for requirements and supported combinations.
+
+The **Agents** page creates/reads specialist profiles. API `/api/agents` and `/api/agent-packages`, SDK clients, CLI, and MCP all access the same files. MCP tools are `agent_list`, `agent_read`, `agent_create`, `agent_package_list`, `agent_package_read`, and `agent_package_import`. Package agent IDs are namespaced as `<package>/<file-stem>`.
 
 ## MCP tools
 
@@ -724,7 +756,7 @@ ORC merges config in priority order (later wins):
 | `ORC_API_HOST`                   | `127.0.0.1`           | API listen host (set to `0.0.0.0` in Docker)      |
 | `ORC_API_PORT`                   | `7700`                | API listen port                                   |
 | `ORC_API_SECRET`                 | -                     | Bearer token for auth                             |
-| `ORC_TERMINALS_ALLOW_WITHOUT_SECRET` | `false`           | Allow dashboard Terminals with no API secret (loopback-bound API only) |
+| `ORC_TERMINALS_ALLOW_WITHOUT_SECRET` | `false`           | Legacy option; no longer needed. Terminals follow API open/authenticated mode |
 | `ORC_TELEGRAM_TOKEN`             | -                     | Enables the Telegram gateway when set             |
 | `AGENTAPI_URL`                   | `http://127.0.0.1:3284` | URL of host agentapi server (for `agentapi` backend) |
 | `ANTHROPIC_API_KEY`              | -                     | Required for the `claude` backend (Anthropic SDK) |
@@ -820,8 +852,14 @@ See [AGENTS.md](./AGENTS.md) for the full development guide and coding conventio
 
 ## Learn more
 
+- [Evolving Wiki](./docs/evolving-wiki.md) - cited retrieval, automatic session consolidation, evaluated skill promotion, and human revert
+- [Agent Rules](./docs/agent-rules.md) - opt-in tool protection, revision history, deterministic job actions, and evidence-based skill evaluation
 - [Usage Guide](./docs/usage-guide.md) - best practices for memory, tasks, multi-agent workflows, and configuration
 - [Vision](./docs/vision.md) - why ORC exists and the problem it solves
 - [Roadmap](./docs/roadmap.md) - what shipped and what's next
 - [Agent Orchestration Design](./docs/agent-orchestration-design.md) - architecture spec for the task loop and multi-agent workflow
 - [Task Flows](./docs/task-flows.md) - flow graphs: nodes, conditional edges, bounded loops, fan-out and joins, and how to author your own
+
+### Knowledge learning
+
+Session review and a daily digest compile verified notes into wiki lessons and edited skills. Reuse them through ordinary wiki/KB search and skill reads. The dashboard shows learning history, audit records and manual skill revert. See [Knowledge learning loop](docs/knowledge-loop.md) for scopes, scheduling and validation limits.