orc-ai 0.1.35 → 0.1.37

package/README.md

@@ -28,14 +28,14 @@ ORC fixes this. Shared memory across every session. A task board where agents su
 | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
 | **Agent orchestration**   | Task loop spawns workers across backends (Claude Code, Codex, Gemini, Copilot, A2A), manages concurrency and review cycles         |
 | **Human-in-the-loop**     | Agents submit work for your approval via CLI, Telegram, or Slack before anything lands                                             |
-| **Shared memory**         | Decisions, rules, and discoveries stored once, searchable by any session via ranked full-text search                               |
+| **Shared memory**         | Short project facts (ports, conventions, gotchas, decisions), ranked by priority and loaded into every session's context           |
 | **Task board**            | `todo → queued → doing → review → done` with dependency tracking, priority, and automatic unblocking                               |
 | **Multi-backend routing** | Route to Claude (in-process, nothing to install), ACPX (14+ agents), agentapi, or remote A2A endpoints — with `orc doctor` reporting which are usable |
 | **Job runner**            | Cron, file-watch, webhook, or manual triggers with full run history                                                                |
-| **MCP server**            | 34 tools connect any [Model Context Protocol](https://modelcontextprotocol.io) (MCP) compatible agent — stdio or Streamable HTTP   |
+| **MCP server**            | 54 tools connect any [Model Context Protocol](https://modelcontextprotocol.io) (MCP) compatible agent — stdio or Streamable HTTP   |
 | **Session continuity**    | Snapshots survive context compaction so agents resume where they left off                                                          |
 | **Gateway**               | Approve work, search memory, and chat with live agents from Telegram or Slack                                                      |
-| **Knowledge search**      | Index document collections (markdown, notes, wikis) and search them via BM25 or hybrid (vector + reranking)                        |
+| **Knowledge bases**       | Upload PDFs, Office files and Markdown or copy in local folders; hybrid full-text + vector search with cited passages            |
 | **Skill library**         | Discoverable workflow templates (coder, reviewer, planner, bugfix) that encode your standards                                      |
 | **Task flows**            | Per-task graphs: conditional edges, bounded loops, parallel fan-out with joins, and human gates — with hard termination rails      |
 
@@ -112,7 +112,7 @@ orc project use my-app
 
 # 3. Add tasks and memories - everything auto-scopes to my-app
 orc task add "Fix the auth bug" --priority high
-orc mem add "Use RWMutex for token refresh" --type decision
+orc mem add token-refresh-lock -d "Check before touching token refresh" -c "Use RWMutex for token refresh" --priority 60
 orc job add nightly --command "bun run test" --trigger cron --cron "0 22 * * *"
 
 # 4. See everything
@@ -138,6 +138,8 @@ The web dashboard ships inside the `orc` binary and is served by the API process
 | `GET /mcp`                         | MCP server (streamable HTTP)                                                                                                   |
 | `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 |
 
+`/mcp?mode=meta` serves three meta-tools (`tool_search`, `tool_describe`, `tool_invoke`) instead of the full tool list, which keeps client context small; the model finds a tool, reads its schema, then calls it through `tool_invoke` with the same validation as a direct call. Stdio parity: `orc mcp --mode meta`. Any other `mode` value returns HTTP 400.
+
 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.
 
 ### Desktop app
@@ -195,6 +197,27 @@ The `--mcp-config` flag wires the host agent back to ORC's [HTTP MCP endpoint](#
 
 ## Connect your agent
 
+For coding-agent access, check the installed `spec` CLI bridge first (`spec --help`,
+`spec specs`). It can call ORC's MCP server without configuring MCP separately in
+each agent. Use an existing ORC registration or an inline endpoint for your selected
+installation:
+
+```sh
+spec call --mcp-http http://127.0.0.1:7700/mcp context --data '{"project":"my-app"}'
+spec call --mcp-http http://127.0.0.1:7700/mcp skill_read --data '{"name":"orc-sdlc","project":"my-app"}'
+```
+
+For authenticated servers, use existing secure secret references in spec configuration;
+do not put secrets in command arguments. Use `SPEC_NO_CACHE=1` when refreshing live
+context and effective skills. Direct MCP connections below remain supported when
+already configured. Check the CLI bridge before reporting ORC unavailable.
+
+Lifecycle hooks and MCP registration are separate. The hook examples below record
+session activity; also register ORC in the client's supported MCP configuration
+using `orc mcp` (stdio) or `<origin>/mcp` (HTTP). Preserve existing servers and
+configure authentication privately. Verify tool discovery and a project-scoped
+`context` call in each client; installed hooks alone do not establish MCP access.
+
 ### Claude Code
 
 Add to `~/.claude/settings.json`:
@@ -204,7 +227,7 @@ Add to `~/.claude/settings.json`:
   "hooks": {
     "PostToolUse": [
       {
-        "matcher": "Write|Edit|MultiEdit|StrReplace|EditNotebook|Bash|Shell|Agent|EnterPlanMode|ExitPlanMode|mcp__orc__task_|mcp__orc__memory_store|mcp__orc__memory_delete|mcp__orc__job_run|mcp__orc__job_create|mcp__orc__job_update",
+        "matcher": "Write|Edit|MultiEdit|StrReplace|EditNotebook|Bash|Shell|Agent|EnterPlanMode|ExitPlanMode|mcp__orc__task_|mcp__orc__memory_create|mcp__orc__memory_delete|mcp__orc__job_run|mcp__orc__job_create|mcp__orc__job_update",
         "hooks": [
           {
             "type": "command",
@@ -307,17 +330,18 @@ The task loop automatically picks up queued tasks and spawns worker agents:
 
 ```bash
 # Create a task with a workflow and backend
-orc task add "Implement user auth" --skill orc-coder --backend claude --priority high
+orc task add "Implement user auth" --skill orc-sdlc --backend claude --priority high
 
 # Or batch-create with dependencies via MCP
 task_batch_create({ tasks: [
-  { title: "Design schema", skill_name: "orc-planner" },
-  { title: "Implement API",  skill_name: "orc-coder", blocked_by: [0] },
-  { title: "Review code",    skill_name: "orc-reviewer", blocked_by: [1] }
+  { ref: "design", title: "Design schema", skill_name: "orc-sdlc" },
+  { ref: "api", title: "Implement API", skill_name: "orc-sdlc", depends_on: ["design"] },
+  { ref: "tests", title: "Verify API integration", skill_name: "orc-sdlc", depends_on: ["api"] }
 ]})
 ```
 
 The loop handles concurrency, session resume on feedback, review round limits, stale claim cleanup, and backend routing.
+Each task's configured flow handles its review; a separate review task is unnecessary.
 
 Every task runs a **flow graph** (see [Task flows](#task-flows)); `orc-default` is the build → review → done pipeline described above.
 
@@ -374,7 +398,7 @@ orc project add my-app -d "Main application"
 orc project use my-app       # set active
 
 orc task list                 # scoped to my-app
-orc mem search "auth"         # scoped to my-app
+orc mem list -q auth          # scoped to my-app
 orc task list -p infra        # override to different project
 orc task list --no-project    # see everything
 ```
@@ -385,45 +409,55 @@ MCP tools follow the same logic - pass `project: "name"` to scope, or omit to us
 
 ### Memory
 
-Store decisions, conventions, and discoveries that persist across all sessions:
+A memory is a short project fact worth knowing next session: ports, conventions, gotchas,
+decisions, pointers. Each has a lowercase-hyphenated `name` (unique per project), a
+`description` saying when it matters, `content` (up to 800 characters by default) and an
+optional `priority` from 0 to 100. `context` loads the top 30 memories by priority; agents
+then read the ones they need. Procedures and long guidance belong in skills.
 
 ```bash
-orc mem add "All IDs are ULIDs" --type rule
-orc mem add "Use PostgreSQL for concurrent writes" --type decision
-orc mem search "authentication"
+orc mem add ulid-ids -d "Check before adding a table or ID field" -c "All IDs are ULIDs" --priority 90
+orc mem list -q ids                    # search names and descriptions
+orc mem show ulid-ids
+orc mem edit ulid-ids --priority 80 -r "Narrower than we thought"
+orc mem history ulid-ids               # every change, with before/after
+orc mem revert ulid-ids <change-id> --expected-change-id <latest-change-id> -r "Undo mistaken edit"
 ```
 
-| Type        | Weight | Use for                                         |
-| ----------- | ------ | ----------------------------------------------- |
-| `rule`      | High   | Conventions: "all IDs are ULIDs"                |
-| `decision`  | High   | Choices: "use PostgreSQL for concurrent writes" |
-| `discovery` | Medium | Findings: "token refresh has a race condition"  |
-| `event`     | Low    | Things that happened: "deployed v1.0"           |
-| `fact`      | Low    | General knowledge (default)                     |
+### Knowledge bases
 
-### Knowledge
-
-Index existing document collections (markdown, notes, code docs) and make them searchable by any agent. Unlike memory (short agent-authored notes), knowledge searches pre-existing files on disk.
+Knowledge bases hold human reference documents for agents to search and cite. A knowledge base belongs to a project or is global. Add documents by uploading files (PDF, Word, PowerPoint, Excel, HTML, CSV, Markdown, text), writing Markdown in the dashboard, or registering a folder whose files are copied in. ORC never writes the folder: a copy follows its file on each scan until it is edited in ORC, and a file deleted from the folder keeps its copy. Documents have folders, labels and `[[links]]` with backlinks.
 
 ```bash
-# Add a document collection
-orc knowledge add my-docs --path ~/projects/docs --pattern "**/*.md"
+orc kb create Runbooks --project my-app
+orc kb add Runbooks ./docs/*.pdf          # upload and parse
+orc kb sources add Runbooks ./handbook    # copy a folder in, rescanned periodically
+orc kb editable-by Runbooks ui,cli,api    # agents (mcp) may read but not edit
+orc kb search "rollback procedure"        # cited passages
+orc kb evidence "how do we rotate keys"   # budgeted evidence pack
+orc kb usage Runbooks                     # reads by source (mcp, api, cli, ui)
+```
 
-# Search across indexed documents
-orc knowledge search "authentication flow"
+Comments on a knowledge base or one of its documents ask for a change: a correction, a source to digest, a lesson to record. Each has an author and source, a status (open, resolved, dismissed) and one closing reply.
 
-# List collections
-orc knowledge list
+Any knowledge base can have a digest: an agent (Claude, Codex, ...) that follows the knowledge base's own instructions on a schedule, handling open comments first and then reading memories, session summaries and audit records to add, correct and clean up documents. The schedule is an ordinary ORC job (cron or manual) with run history. In the dashboard choose **Add digest** on a knowledge base; it starts from a generic template. Scheduled runs are skipped when nothing new happened. Each active project gets a starter **Learnings** knowledge base with a daily 03:00 digest.
 
-# Re-index after files change
-orc knowledge update
+```bash
+orc kb comment add Learnings "Digest https://example.com/postmortem"
+orc kb digest template > digest.md        # edit, then:
+orc kb digest set Runbooks -b codex --cron "0 3 * * *" -i digest.md
+orc kb digest run Runbooks
 ```
 
-Knowledge uses [QMD](https://github.com/nicholasgriffintn/qmd) as the search engine. By default it runs BM25 full-text search (no LLM needed). Set `search_mode: "hybrid"` in config for vector search with reranking - embeddings are generated automatically when documents are indexed.
+Search combines title/path matches, SQLite full-text search and, when embeddings are configured (Ollama or an OpenAI-compatible API), vectors stored with sqlite-vec. Set the embedding URL, model and API key or token in Settings or with `orc kb settings`; the key is stored encrypted and never returned by the API. Results cite passages as `kb:<doc>@<rev>#<n>`. Every read is counted per document and source.
+
+The built-in parser handles all formats without extra installs. For better PDF layout, tables and OCR, install the optional [Docling](https://github.com/docling-project/docling) parser from Settings or with `orc kb docling install` (about 2 GB); in `auto` mode it is then used for PDFs and images. Each knowledge base can override the parser.
 
-Collections can be scoped to projects. When scoped, searches and listing filter to only that project's collections.
+Each knowledge base lists the call sources that may change its documents (`editable_by`: `ui`, `cli`, `api`, `mcp`; all four by default). Agents write with `kb_write` and `kb_document` (partial edits by exact text or line range) where `mcp` is allowed; every change is a revision recording its source and session. Knowledge base settings and knowledge settings cannot be changed over MCP, so an agent cannot widen its own access. Rendered Markdown shows remote images as links instead of loading them.
 
-**MCP tools:** `knowledge_search`, `knowledge_get`, `knowledge_collections`, `knowledge_collection_add`, `knowledge_collection_remove`, `knowledge_update`
+To back up knowledge bases, stop ORC and copy `~/.orc/orc.db` (with its `-wal` and `-shm` files) and `~/.orc/knowledge/originals/`, plus `~/.orc/secret.key`, without which a saved embedding API key cannot be decrypted and must be entered again. The search index, parse results and Markdown copies are rebuilt on the next start.
+
+**MCP tools:** `kb_list`, `kb_search`, `kb_evidence`, `kb_read`, `kb_documents`, `kb_write`, `kb_document`, `kb_comment`, `kb_manage`, `kb_digest`, `kb_maintenance`
 
 ### Task status flow
 
@@ -452,7 +486,7 @@ 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-default              # nodes, edges, limits
-orc task add "Fix the flaky test" --flow orc-default --skill orc-bugfix
+orc task add "Fix the flaky test" --flow orc-default --skill orc-sdlc
 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
@@ -496,6 +530,53 @@ orc job add on-change --command "bun run lint"      --trigger watch --watch "./s
 orc job add on-push   --command "bun run ci"        --trigger webhook
 ```
 
+Jobs separate **what runs** from **when it runs**. Choose **Run command**,
+**Run agent**, or **Create task** in the dashboard. Command is required only for
+Run command. Agent jobs save instructions, backend, optional model and explicit
+tool approval; each run links to its tracked session. Task jobs save a task title
+and instructions and link to the created task. **Start the task flow automatically**
+is off by default, so generated tasks wait for a manual flow start.
+The CLI accepts typed actions through `--action-config <json>`.
+
+New jobs are disabled by default. Select **Enable this job immediately** during
+creation or pass `orc job add ... --enable` to opt in. Jobs supports enable/disable
+directly in the list and for selected rows. Projects shares the selection toolbar
+for activate, pause and archive actions; select-all applies only to displayed rows.
+Failed bulk updates remain selected so you can retry them.
+
+### Webhooks
+
+Open **Activity → Webhooks** to see all configured event sources and their connected
+jobs. Create a source without a job, copy its URL and one-time signing secret, then
+register them with the provider. Sources belong to the selected project, or are
+shared across projects when created in All projects.
+
+In **Jobs → New job** (or Edit), choose **Webhook** as the trigger, select an
+existing source or create one inline, and set this job's event/action filters.
+One source can trigger multiple enabled jobs, each with its own filters and action.
+The Webhooks page shows source enablement, connected jobs and recent deliveries,
+including individual run results and links to generated tasks or agent sessions.
+Deleting a job disconnects it while preserving the reusable source.
+
+For command jobs, accepted JSON is passed unchanged on stdin; bounded metadata is
+also available as `ORC_WEBHOOK_*` environment variables. Agent and task jobs receive
+up to 50,000 characters of event data, explicitly marked as untrusted input, alongside
+the configured instructions. Delivery history stores event metadata and a payload
+hash, not the payload body or signing secret; generated tasks and agent prompts can
+contain the supplied event data.
+
+Generic endpoints verify `X-Orc-Signature-256: sha256=<HMAC-SHA256 of the raw body>`.
+Use `X-Orc-Event` for event filtering and `X-Orc-Delivery` (or
+`Idempotency-Key`) for deduplication. GitHub endpoints use
+`X-Hub-Signature-256`, `X-GitHub-Event` and `X-GitHub-Delivery` directly.
+Event names and payload `action` values are configurable, so PR lifecycle,
+reviews, workflow runs, releases, or later providers use the same job trigger.
+
+Signing secrets are encrypted at rest and shown only when an endpoint is created or
+rotated. The receiver is intentionally outside normal ORC bearer authentication;
+the per-endpoint HMAC is its authentication boundary. Management remains under the
+authenticated API.
+
 ### Gateway (Telegram / Slack)
 
 Approve agent work from your phone, search memory, or start a live AI session.
@@ -539,7 +620,7 @@ Same commands as Telegram. Create a Slack app at [api.slack.com/apps](https://ap
 
 ## Skills
 
-ORC ships with agent workflow skills and built-in skill templates for the task loop.
+ORC ships two entry-point skills. Their supporting references load only when needed; custom skills and packages remain supported.
 
 ### Install skills
 
@@ -548,20 +629,23 @@ ORC ships with agent workflow skills and built-in skill templates for the task l
 npx skills add niradler/orc --all
 
 # Or pick specific ones
-npx skills add niradler/orc --skill orc-session orc-tasks
+npx skills add niradler/orc --skill orc-platform orc-sdlc
 
 # Global install
 npx skills add niradler/orc --all -g
 ```
 
-### Agent workflow skills
+### Entry-point skills
 
-| Skill           | Triggers on                                                                |
-| --------------- | -------------------------------------------------------------------------- |
-| `orc-session`   | Session start, context compaction, resuming work                           |
-| `orc-tasks`     | Task creation, status updates, HITL review, task decomposition             |
-| `orc-knowledge` | Storing decisions, searching memory, "remember this", "what did we decide" |
-| `orc-gateway`   | Telegram/Slack setup, remote approval, live agent sessions                 |
+| Skill | Purpose |
+| --- | --- |
+| `orc-platform` | Operate ORC domains: setup/interfaces/auth, memory and maintained KBs/digests/embeddings, work/operations, sessions/SSH/Git/chat, rules and agent packages |
+| `orc-sdlc` | Requirements → risk/complexity classification → direct work or plan → implementation → tests/completeness → review/rework → authorized Git delivery, with shared learning throughout |
+
+Start with the relevant entry point and read only its selected reference. Platform
+guidance groups related domains while keeping memory, execution and rules independently
+loadable; SDLC has planning, development and review/delivery references. Clear low-risk
+work can execute directly; assigned managed nodes preserve roles and flow contracts.
 
 ### Built-in skill templates
 
@@ -572,7 +656,7 @@ On the **Skills** page, each built-in has an **Agent discovery** toggle, plus
 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.
+global/project instruction overrides of current skills 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`
@@ -582,16 +666,14 @@ omits hidden built-ins; `include_hidden=true` returns the management catalog wit
 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 |
-| `orc-main-base`    | Base     | Orchestration agent - planning, decomposition, monitoring                   |
-| `orc-coder`        | Workflow | Implementation - understand, plan, implement, verify, submit                |
-| `orc-planner`      | Workflow | Task decomposition with dependencies and workflow assignment                |
-| `orc-reviewer`     | Workflow | Structured evaluation - correctness, tests, security, conventions           |
-| `orc-bugfix`       | Workflow | Bug investigation - reproduce, root-cause, fix, regression test             |
-| `orc-requirements` | Skill    | Requirements interview - outcome, criteria, constraints, scope              |
-| `orc-report`       | Skill    | Project status report - health summary, blockers, active work               |
+Retired built-in names (such as `orc-coder` and `orc-reviewer`) remain readable
+as compatibility routes for saved tasks, authored overrides and frozen flows, but
+are not additional discovery entries. New tasks and built-in flows use
+`orc-sdlc`; the node role selects implementation versus independent review.
+Applicable authored legacy worker/coder/reviewer/knowledge instructions remain
+role-scoped supplements with revision provenance, including on resume. Other authored
+legacy domain guidance is indexed from the canonical effective read and loads by name
+when relevant. Conflicts are surfaced rather than silently rewriting stored overlays.
 
 Add custom skills by creating a `SKILL.md` in `~/.orc/skills/my-workflow/SKILL.md`.
 
@@ -657,17 +739,26 @@ The **Agents** page creates/reads specialist profiles. API `/api/agents` and `/a
 
 ## MCP tools
 
+Agents can fetch original skill scripts/assets with
+`skill_read({name: "orc-platform", ref: "scripts/upload-session.py", download: true, project: "my-app"})`.
+It returns a signed ten-minute `download_url`, `sha256`, `size_bytes` and expiry
+instead of the file body. Download to a local file and verify the hash; do not
+reconstruct scripts from tool text. The URL authorizes only that file version and
+does not contain the API secret. Keep it private. Expiry, API restart or file changes
+require a new URL. Downloading never executes scripts. The authenticated REST mint
+endpoint is `POST /api/skills/<name>/download` with `ref` and optional scope.
+
 Tools are available to any connected agent. Start every session with `context`.
 
 | Category      | Tools                                                                                                                                       |
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Project**   | `project_list`                                                                                                                              |
-| **Memory**    | `context`, `memory_search`, `memory_get`, `memory_store`, `memory_update`                                                                   |
+| **Memory**    | `context`, `memory_list`, `memory_read`, `memory_create`, `memory_update`, `memory_delete`, `memory_history`, `memory_revert`                |
 | **Task**      | `task_list`, `task_get`, `task_create`, `task_update`, `task_batch_create`                                                                  |
 | **Skill**     | `skill_list`, `skill_read`, `skill_create`                                                                                                  |
 | **Agent**     | `agent_list`, `agent_read`, `agent_create`, `agent_package_list`, `agent_package_read`, `agent_package_import`                               |
 | **Flow**      | `flow_report`, `flow_status`, `flow_list`, `flow_read`, `flow_create`, `flow_attach`                                                        |
-| **Knowledge** | `knowledge_search`, `knowledge_get`, `knowledge_collections`, `knowledge_collection_add`, `knowledge_collection_remove`, `knowledge_update` |
+| **Knowledge** | `kb_list`, `kb_search`, `kb_evidence`, `kb_read`, `kb_documents`, `kb_write`, `kb_maintenance`                                               |
 | **Search**    | `search`                                                                                                                                    |
 | **Job**       | `job_list`, `job_run`, `job_status`                                                                                                         |
 | **Session**   | `session_event`, `session_snapshot`, `session_restore`, `session_log`                                                                       |
@@ -691,8 +782,10 @@ Runs on port 7700 with auto-generated OpenAPI spec.
 | `GET/POST/PATCH/DELETE` | `/tasks`                       | CRUD tasks                     |
 | `GET/POST`              | `/tasks/{id}/notes`            | Task notes                     |
 | `GET/POST/DELETE`       | `/tasks/{id}/links`            | Task dependencies              |
-| `GET/POST/DELETE`       | `/memories`                    | CRUD memories                  |
-| `GET`                   | `/memories/search`             | BM25 search                    |
+| `GET/POST`              | `/memories`                    | List (`q`, `sort`) / create    |
+| `GET/PATCH/DELETE`      | `/memories/{name}`             | Read / update / delete by name |
+| `GET`                   | `/memories/{name}/history`     | Change history                 |
+| `POST`                  | `/memories/{name}/revert`      | Revert a change                |
 | `GET`                   | `/knowledge/search`            | Search documents (BM25/hybrid) |
 | `GET`                   | `/knowledge/documents/{id}`    | Get document by docid          |
 | `GET/POST/DELETE`       | `/knowledge/collections`       | CRUD collections               |
@@ -728,7 +821,7 @@ orc doctor                       Check which agent backends are usable here
 
 orc project list|add|show|use|update|archive
 orc task list|add|show|update|done|review|approve|reject|delete
-orc mem list|add|search
+orc mem list|show|add|edit|delete|history|revert
 orc job list|add|run|runs
 orc session list|show|log
 orc skill list|show
@@ -771,8 +864,13 @@ ORC merges config in priority order (later wins):
 | `ORC_AGENT_LOOP_DEFAULT_BACKEND` | `claude`              | Default agent backend                             |
 | `ORC_AGENT_LOOP_IDLE_TIMEOUT`    | `20`                  | Session idle timeout (minutes)                    |
 | `ORC_AGENT_LOOP_AUTO_APPROVE`    | `true`                | Auto-approve worker tool permissions              |
-| `ORC_KNOWLEDGE_DB_PATH`          | `~/.orc/knowledge.db` | Knowledge search database path                    |
-| `ORC_KNOWLEDGE_SEARCH_MODE`      | `lexical`             | `lexical` (BM25) or `hybrid` (vector + reranking) |
+| `ORC_KNOWLEDGE_ROOT`             | beside `orc.db`       | Knowledge base storage (files, index)             |
+| `ORC_KNOWLEDGE_PARSER`           | `auto`                | `auto`, `basic` or `docling`                      |
+| `ORC_KNOWLEDGE_EMBEDDING_PROVIDER` | `none`              | `none`, `ollama` or `openai`                      |
+| `ORC_KNOWLEDGE_EMBEDDING_URL`    | provider default      | Embedding endpoint                                |
+| `ORC_KNOWLEDGE_EMBEDDING_MODEL`  | provider default      | Embedding model                                   |
+| `ORC_KNOWLEDGE_EMBEDDING_API_KEY` | -                    | API key for OpenAI-compatible embeddings          |
+| `ORC_SQLITE_VEC_PATH`            | bundled               | Path to a sqlite-vec `vec0` library               |
 
 </details>
 
@@ -852,7 +950,7 @@ 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
+- [Knowledge learning loop](./docs/knowledge-loop.md) - memories, knowledge base digests and comments, skill edits, 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
@@ -862,4 +960,4 @@ See [AGENTS.md](./AGENTS.md) for the full development guide and coding conventio
 
 ### 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.
+Session review records verified lessons, and each project's Learnings knowledge base has a daily digest that turns memories, session summaries and comments into documents. Reuse them through ordinary 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.