From 58a80d3d9399294bf3bbe57e4b82d441c87898ca Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 9 May 2026 06:37:35 +0100
Subject: [PATCH] docs(oc-path): expand usage examples

---
 docs/cli/path.md        | 72 +++++++++++++++++++++++++++++++++++++++++
 docs/plugins/oc-path.md | 32 ++++++++++++++++++
 2 files changed, 104 insertions(+)

diff --git a/docs/cli/path.md b/docs/cli/path.md
index 9364ee4db69..1688c30c796 100644
--- a/docs/cli/path.md
+++ b/docs/cli/path.md
@@ -44,6 +44,78 @@ automation easier to review and safer to replay. It is especially useful when
 you want to update one leaf while preserving the rest of the file's comments,
 line endings, and surrounding formatting.
 
+Use it when the thing you want has a logical address, but the physical file
+shape varies:
+
+- A hook wants to read one setting from commented JSONC without losing comments
+  when it writes the value back.
+- A maintenance script wants to find every matching event field in a JSONL log
+  without loading the whole log into a custom parser.
+- An editor extension wants to jump to a markdown section or bullet item by
+  slug, then render the exact line it resolved to.
+- An agent wants to dry-run a tiny workspace edit before applying it, with the
+  changed bytes visible in review.
+
+You probably do not need `openclaw path` for ordinary whole-file edits, rich
+config migrations, or memory-specific writes. Those should use the owner
+command or plugin. `path` is for small, addressable file operations where a
+repeatable terminal command is clearer than another bespoke parser.
+
+## How it is used
+
+Read one value from a human-edited config file:
+
+```bash
+openclaw path resolve 'oc://config.jsonc/plugins/github/enabled'
+```
+
+Preview a write without touching disk:
+
+```bash
+openclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run
+```
+
+Find matching records in an append-only JSONL log:
+
+```bash
+openclaw path find 'oc://session.jsonl/[event=tool_call]/name'
+```
+
+Address an instruction in markdown by section and item instead of by line
+number:
+
+```bash
+openclaw path resolve 'oc://AGENTS.md/runtime-safety/openclaw-gateway'
+```
+
+Validate a path in CI or a preflight script before the script reads or writes:
+
+```bash
+openclaw path validate 'oc://AGENTS.md/tools/$last/risk'
+```
+
+Those commands are meant to be copyable into shell scripts. Use `--json` when a
+caller needs structured output and `--human` when a person is inspecting the
+result.
+
+## How it works
+
+`openclaw path` does four things:
+
+1. Parses the `oc://` address into slots: file, section, item, field, and
+   optional session.
+2. Chooses the file-kind adapter from the target extension (`.md`, `.jsonc`,
+   `.jsonl`, and related aliases).
+3. Resolves the slots against that file kind's AST: markdown headings/items,
+   JSONC object keys/array indexes, or JSONL line records.
+4. For `set`, emits edited bytes through the same adapter so the untouched
+   parts of the file keep their comments, line endings, and nearby formatting
+   where the kind supports it.
+
+`resolve` and `set` require one concrete target. `find` is the exploratory
+verb: it expands wildcards, unions, predicates, and ordinals into the concrete
+matches you can inspect before choosing one to write.
+
 ## Subcommands
 
 | Subcommand              | Purpose                                                                      |
diff --git a/docs/plugins/oc-path.md b/docs/plugins/oc-path.md
index 9fec142e90d..6b8cd04f56d 100644
--- a/docs/plugins/oc-path.md
+++ b/docs/plugins/oc-path.md
@@ -38,6 +38,38 @@ nearby formatting alone. Keeping this as an opt-in plugin gives power users the
 addressing substrate without putting parser dependencies or CLI surface into
 core for installs that never need it.
 
+Common reasons to enable it:
+
+- **Local automation**: shell scripts can resolve or update one workspace value
+  with `openclaw path … --json` instead of carrying separate markdown, JSONC,
+  and JSONL parsing code.
+- **Agent-visible edits**: an agent can show 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 can map `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.
+
+Concrete examples:
+
+```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
+```
+
+The plugin is intentionally not the owner of higher-level semantics. Memory
+plugins still own memory writes, config commands still own full config
+management, and LKG logic 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