Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

docs/plugins/oc-path.md

@@ -0,0 +1,168 @@
+---
+summary: "Bundled `oc-path` plugin: ships the `openclaw path` CLI for the `oc://` workspace-file addressing scheme"
+read_when:
+  - You want to inspect or edit a single leaf inside a workspace file from the terminal
+  - You are scripting against workspace state and need a stable, kind-agnostic addressing scheme
+  - You are deciding whether to enable the optional `oc-path` plugin on a self-hosted Gateway
+title: "OC Path plugin"
+---
+
+The bundled `oc-path` plugin adds the [`openclaw path`](/cli/path) CLI for the
+`oc://` workspace-file addressing scheme. It ships in the OpenClaw repo under
+`extensions/oc-path/` but is opt-in: install/build leaves it dormant until you
+enable it.
+
+`oc://` addresses point at a single leaf (or a wildcard set of leaves) inside
+a workspace file. The plugin understands four file kinds:
+
+- **markdown** (`.md`): frontmatter, sections, items, fields
+- **jsonc** (`.jsonc`, `.json`): comments and formatting preserved
+- **jsonl** (`.jsonl`, `.ndjson`): line-oriented records
+- **yaml** (`.yaml`, `.yml`, `.lobster`): map/sequence/scalar nodes through the
+  `yaml` package's `Document` API
+
+Self-hosters and editor extensions use the CLI to read or write a single leaf
+without scripting against the SDK directly; agents and hooks treat it as a
+deterministic substrate so byte-fidelity round-trips and the redaction
+sentinel guard apply uniformly across kinds. See the
+[CLI reference](/cli/path) for the full grammar, verb-by-verb flag list, and
+worked examples per file kind; this page covers why and how to enable the
+plugin.
+
+## Why enable it
+
+Enable `oc-path` when scripts, hooks, or local agent tooling need to point at
+a precise piece of workspace state without a bespoke parser per file shape. A
+single `oc://` address can name a markdown frontmatter key, a section item, a
+JSONC config leaf, a JSONL event field, or a YAML workflow step.
+
+That matters for maintainer workflows where the change should stay small,
+auditable, and repeatable: inspect one value, find matching records, dry-run
+a write, then apply only that leaf while leaving comments, line endings, and
+nearby formatting alone.
+
+Common reasons to enable it:
+
+- **Local automation**: shell scripts resolve or update one workspace value
+  with `openclaw path … --json` instead of carrying separate markdown, JSONC,
+  JSONL, and YAML parsing code.
+- **Agent-visible edits**: an agent shows a dry-run diff for one addressed
+  leaf before writing, which is easier to review than a free-form file
+  rewrite.
+- **Editor integrations**: an editor maps `oc://AGENTS.md/tools/gh` to the
+  exact markdown node and line number without guessing from heading text.
+- **Diagnostics**: `emit` round-trips a file through the parser and emitter,
+  so you can check whether a file kind is byte-stable before relying on
+  automated edits.
+
+```bash
+# Is the GitHub plugin enabled in this config?
+openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --json
+
+# Which tool-call names appear in this session log?
+openclaw path find 'oc://session.jsonl/[event=tool_call]/name' --json
+
+# What bytes would this tiny config edit write?
+openclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run
+```
+
+`oc-path` is intentionally not the owner of higher-level semantics. Memory
+plugins still own memory writes, config commands still own full config
+management, and last-known-good (LKG) config recovery still owns
+restore/promotion. `oc-path` is the narrow addressing and byte-preserving
+file operation layer those higher-level tools can build around.
+
+## Where it runs
+
+The plugin runs **in-process inside the `openclaw` CLI** on the host where you
+invoke the command. It does not need a running Gateway and does not open any
+network sockets; every verb is a pure transform over a file you point it at.
+
+Plugin metadata lives in `extensions/oc-path/openclaw.plugin.json`:
+
+```json
+{
+  "id": "oc-path",
+  "name": "OC Path",
+  "activation": {
+    "onStartup": false,
+    "onCommands": ["path"]
+  },
+  "commandAliases": [{ "name": "path", "kind": "cli" }]
+}
+```
+
+`onStartup: false` keeps the plugin out of the Gateway startup path.
+`commandAliases` and `activation.onCommands` tell the CLI to load the plugin
+lazily the first time you run `openclaw path …`, so installs that never use
+the verb pay no cost.
+
+## Enable
+
+```bash
+openclaw plugins enable oc-path
+```
+
+Restart the Gateway (if you run one) so the manifest snapshot picks up the new
+state. Bare `openclaw path` invocations work immediately on the same host;
+the CLI loads the plugin on demand.
+
+Disable with:
+
+```bash
+openclaw plugins disable oc-path
+```
+
+## Dependencies
+
+All parser dependencies are plugin-local; enabling `oc-path` does not pull
+new packages into the core runtime:
+
+| Dependency     | Purpose                                                                |
+| -------------- | ---------------------------------------------------------------------- |
+| `commander`    | Subcommand wiring for `resolve`, `find`, `set`, `validate`, `emit`.    |
+| `jsonc-parser` | JSONC parse and leaf edits with comments and trailing commas kept.     |
+| `markdown-it`  | Markdown tokenization for the section / item / field model.            |
+| `yaml`         | YAML `Document` parse / emit / edit with comments and flow style kept. |
+
+JSONL stays hand-rolled: line-oriented parsing is simpler than any
+dependency, and the per-line parse already goes through `jsonc-parser`.
+
+## What it provides
+
+| Surface                        | Provided by                                             |
+| ------------------------------ | ------------------------------------------------------- |
+| `openclaw path` CLI            | `extensions/oc-path/cli-registration.ts`                |
+| `oc://` parser / formatter     | `extensions/oc-path/src/oc-path/oc-path.ts`             |
+| Per-kind parse / emit / edit   | `extensions/oc-path/src/oc-path/{md,jsonc,jsonl,yaml}`  |
+| Universal resolve / find / set | `extensions/oc-path/src/oc-path/{resolve,find,edit}.ts` |
+| Redaction-sentinel guard       | `extensions/oc-path/src/oc-path/sentinel.ts`            |
+
+The CLI is the only public surface today. The substrate verbs are private to
+the plugin; consumers use the CLI (or build their own plugin against the
+SDK).
+
+## Relationship to other plugins
+
+- **`memory-*`**: memory writes go through the memory plugins, not
+  `oc-path`. `oc-path` is a generic file substrate; memory plugins layer
+  their own semantics on top.
+- **LKG**: `path` does not know about last-known-good config restore. If a
+  file you edit through `path` is also LKG-tracked, the next config observe
+  cycle decides whether to promote or recover it; treat a `path` edit the
+  same as any other direct write to that file.
+
+## Safety
+
+`set` writes raw bytes through the substrate's emit path, which applies the
+redaction-sentinel guard automatically. A leaf carrying
+`__OPENCLAW_REDACTED__` (verbatim or as a substring) is refused at write time
+with `OC_EMIT_SENTINEL`. The CLI also scrubs the literal sentinel from any
+human or JSON output it prints, replacing it with `[REDACTED]` so terminal
+captures and pipelines never leak the marker.
+
+## Related
+
+- [`openclaw path` CLI reference](/cli/path)
+- [Manage plugins](/plugins/manage-plugins)
+- [Building plugins](/plugins/building-plugins)