docs: include grep and agent examples in extension publications

.docs/marketplace-cli-examples-20261014/README.md

@@ -0,0 +1,24 @@
+# Marketplace CLI examples — actual output verification
+
+The VS Code package README and Continue bundle README now contain runnable examples for both `terraphim-grep` and `terraphim-agent`, with separate installation instructions, clients v1.21.20 links, `synonyms::` concept Markdown, and the public search, memory and hooks tutorials. This is a documentation amendment; extension/integration versions and runtime code are unchanged.
+
+## Executed examples
+
+Both new README command blocks were executed on macOS ARM64 using exact released clients **1.21.20**, with isolated child profiles so authored fixture captures did not enter the user's memory. The user-facing commands intentionally use the current user's OS-local memory store; their working directory does not establish memory isolation.
+
+- The existing editor-exported `integrations/continue/risk-concern.exported.json` was supplied as an input. It is not a newly authored graph from these runs.
+- The corpus contains only `Risk: supplier delays require a backup plan.` An explicit empty graph returns zero passages; the exported Risk/Concern graph returns one actual Risk passage for `concern` with `answer: null`.
+- Both exact capture/Python-ID-extraction/show blocks persisted and read back `Risk requires a Decision: approve a second supplier as the mitigation.` with the `provenance:public-project-brief` tag and matching generated ID. Capturing authored text does not import the editor graph or configure an agent retrieval role.
+- The VS Code `--answer` example was also executed on the single-passage corpus and correctly returned no generated answer. The README explains this insufficient-evidence result and that synthesis requires a configured provider. These runs do not claim provider synthesis; the linked tutorial shows the fuller comparison.
+
+[receipt.json](receipt.json) preserves exact shell blocks, binary versions/digests and output filenames. Its original execution-document hashes are retained; `finalDocumentSha256` additionally binds the final explanatory prose, and every executed block was verified unchanged. The adjacent stdout/JSON files are actual outputs. Empty stderr files are intentional; grep's harmless fresh-directory/no-Git warning is retained where emitted.
+
+## Existing integration tests
+
+All six Continue tests passed, including real SDK/CLI transport, installer preservation, package determinism and immutable tag/source checks. The existing real transport test now also proves graph-restart behavior: changing graph bytes is refused by the running process; restarting the same server arguments admits the reviewed graph's new digest and retrieves Risk for the added Hazard alias. The changed graph is a labelled test input, not an editor operation. See [continue-transport.json](continue-transport.json) and [continue-tests.txt](continue-tests.txt).
+
+The binary digest is explicitly pinned in generated Continue arguments. The graph digest is captured at process startup. A new graph path requires an explicit config edit; the installer refuses existing configuration. No existing profile or model configuration was overwritten.
+
+## Publication scope
+
+Microsoft/Open VSX consume the packaged VS Code README. Continue packages its own README via the explicit existing allowlist, and future CI release notes now reference both separately installed CLIs. A repository merge alone does not update existing marketplace package bytes. A subsequent versioned CI release, registry readback and package inspection are required; this change does not republish or replace any immutable release.

.docs/marketplace-cli-examples-20261014/SHA256SUMS.json

@@ -0,0 +1,25 @@
+{
+  "README.md": "c05cee5cf386877417c6fbde98fbb2abd33410494c0b654c6156af67db41a760",
+  "continue-baseline.json": "fc56c1d4a44f506af409eee56121a46f3cc8477672d2dc34607a5559e163d617",
+  "continue-capture-show.stderr": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "continue-capture-show.stdout": "e5fd1c5aa1783a0da04fbed0b389e1ecb7344f6ac1cb20ecedfb557e92026103",
+  "continue-captured-memory.json": "04598be71f4ef9f78535258588944e67303e7a270b743f77d4a583dc5c10dd12",
+  "continue-search.stderr": "fd9b782d80809409e53acc3a49dbe0fc009d41b235cf153389437d6806223ef9",
+  "continue-search.stdout": "27e0cb3fb1ce06daf373ce34d71e2fe5b8ba4a08ee2f727c8308a3035c3cba2e",
+  "continue-tests.txt": "91261bedbe9c06eae4ae6c74caafb74732d2d9be76392df488b9d358d82fce82",
+  "continue-transport.json": "ea01b415502a8effa682d6eca4d44a7f1b9795727fa3e5a38d679e96c1691e0c",
+  "continue-versions.stderr": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "continue-versions.stdout": "6d96d08f85b37470dca867aae9df25ed2fb4d1ccc25f8539b324c570f9d1a49f",
+  "receipt.json": "85e150bc097f740f3a9dcb25ac805b91972682b7b872ab2092dcfe841e5620f1",
+  "static-checks.json": "87d7be0ce01887f0e50b383b28428aa20b60707f02d958561a3c6dad5c8833b3",
+  "vscode-answer-insufficient.stderr": "b55d7f29bf9762191acbc3f70d2905006a6d059f57a8d47c2dc5d7fc1235f7f5",
+  "vscode-answer-insufficient.stdout": "623221ece392aeed5ac519a6ff483c6e8921c7b855ef2cf90808330d1749f7bf",
+  "vscode-baseline.json": "92332236148e9dc48f88fb18c15cf5fdbec30a89ada1b7d73643d2f59fbc1594",
+  "vscode-capture-show.stderr": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "vscode-capture-show.stdout": "31c7e3c2ebf571379de99f5a76eaa1a93726e65d06aa87d72c993ef701cb983c",
+  "vscode-captured-memory.json": "d83d41daa409a962d3347ce3a062b51c8b88a7031c818bf1ac6571a0dfda886e",
+  "vscode-search.stderr": "016a2974e7e5485ec65cce01cf92f24fb4cbbb1b0683b597a48d336ba6f6041e",
+  "vscode-search.stdout": "27e0cb3fb1ce06daf373ce34d71e2fe5b8ba4a08ee2f727c8308a3035c3cba2e",
+  "vscode-versions.stderr": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "vscode-versions.stdout": "6d96d08f85b37470dca867aae9df25ed2fb4d1ccc25f8539b324c570f9d1a49f"
+}

.docs/marketplace-cli-examples-20261014/continue-baseline.json

@@ -0,0 +1,13 @@
+{
+  "chunks": [],
+  "answer": null,
+  "concepts": [],
+  "sufficiency": "RlmInsufficient",
+  "sufficiency_explanation": "No chunks or knowledge-graph concepts matched the query; there is nothing to synthesise an answer from.",
+  "stats": {
+    "search_latency_ms": 3,
+    "rlm_latency_ms": null,
+    "chunks_returned": 0,
+    "kg_hits": 0
+  }
+}

.docs/marketplace-cli-examples-20261014/continue-capture-show.stdout

@@ -0,0 +1,19 @@
+{
+  "action": "show",
+  "id": "a95a88a6-4d17-4359-a7be-5231f26ea724",
+  "lesson": null,
+  "memory_item": {
+    "access_count": 0,
+    "associations": {},
+    "content": "Risk requires a Decision: approve a second supplier as the mitigation.",
+    "created_at": "2026-10-14T18:36:58.842432Z",
+    "id": "a95a88a6-4d17-4359-a7be-5231f26ea724",
+    "importance": "Medium",
+    "item_type": "Experience",
+    "last_accessed": null,
+    "tags": [
+      "provenance:public-project-brief"
+    ]
+  },
+  "status": "ok"
+}

.docs/marketplace-cli-examples-20261014/continue-captured-memory.json

@@ -0,0 +1 @@
+{"action":"capture","memory_id":"a95a88a6-4d17-4359-a7be-5231f26ea724","provenance_tag":"public-project-brief","status":"ok"}

.docs/marketplace-cli-examples-20261014/continue-search.stderr

@@ -0,0 +1 @@
+2026-10-14T18:36:57.313842Z  WARN fff_search::file_picker: No git repository found for path: ./briefs

.docs/marketplace-cli-examples-20261014/continue-search.stdout

@@ -0,0 +1,35 @@
+{
+  "chunks": [
+    {
+      "content": "Risk: supplier delays require a backup plan.",
+      "source": "decision.md",
+      "line_start": 1,
+      "line_end": 1,
+      "relevance_score": 2.0,
+      "haystack": "code"
+    }
+  ],
+  "answer": null,
+  "concepts": [
+    {
+      "id": 0,
+      "name": "concern",
+      "display_value": null,
+      "score": 1.0
+    },
+    {
+      "id": 0,
+      "name": "risk",
+      "display_value": null,
+      "score": 1.0
+    }
+  ],
+  "sufficiency": "RlmInsufficient",
+  "sufficiency_explanation": "Only 1 chunk(s) and 2 KG concept(s) were retrieved; the minimum for a meaningful answer is 3 chunks, and coverage was 1.00. Too little evidence to synthesise -- try broadening the query or the searched paths.",
+  "stats": {
+    "search_latency_ms": 3,
+    "rlm_latency_ms": null,
+    "chunks_returned": 1,
+    "kg_hits": 2
+  }
+}

.docs/marketplace-cli-examples-20261014/continue-tests.txt

@@ -0,0 +1,13 @@
+test_project_install_preserves_existing_configuration (test_install.InstallTests.test_project_install_preserves_existing_configuration) ... ok
+test_symlink_directory_refused (test_install.InstallTests.test_symlink_directory_refused) ... ok
+test_complete_allowlisted_bundle_and_refuse_overwrite (test_package.PackageTests.test_complete_allowlisted_bundle_and_refuse_overwrite) ... ok
+test_actual_git_tag_gate_and_moved_tag_refusal (test_source.SourceTests.test_actual_git_tag_gate_and_moved_tag_refusal) ... ok
+test_lightweight_and_annotated_tag_identity (test_source.SourceTests.test_lightweight_and_annotated_tag_identity) ... ok
+test_real_retrieval_and_refusals (test_transport.TransportTests.test_real_retrieval_and_refusals) ... 2026-10-14T18:39:03.186811Z  WARN fff_search::file_picker: No git repository found for path: /var/folders/rb/l4_6j2nx0lnfhysk974ldpg40000gn/T/tmp28vhpcy7/corpus
+Tool 'terraphim_answer' not listed, no validation will be performed
+ok
+
+----------------------------------------------------------------------
+Ran 6 tests in 2.325s
+
+OK

.docs/marketplace-cli-examples-20261014/continue-transport.json

@@ -0,0 +1,128 @@
+{
+  "baseline": {
+    "chunks": [],
+    "answer": null,
+    "concepts": [],
+    "sufficiency": "RlmInsufficient",
+    "sufficiency_explanation": "No chunks or knowledge-graph concepts matched the query; there is nothing to synthesise an answer from.",
+    "stats": {
+      "search_latency_ms": 3,
+      "rlm_latency_ms": null,
+      "chunks_returned": 0,
+      "kg_hits": 0
+    }
+  },
+  "retrieval": {
+    "mode": "retrieval-only",
+    "binarySha256": "95491857b6a115ce7f4ec2a9d24bd0f7b8efcc1a52bd1403b34a62dd704012ab",
+    "graphSha256": "f8648b16470e764bdff5c95064078419d71e8d41d2ca30d4b1508017c166a45d",
+    "argv": [
+      "/private/tmp/published-continue-skills-audit-20261014/clients-1.21.20/extracted/terraphim-grep",
+      "--search-only",
+      "--json",
+      "--thesaurus",
+      "/private/var/folders/rb/l4_6j2nx0lnfhysk974ldpg40000gn/T/tmp28vhpcy7/graph.json",
+      "--paths",
+      "/private/var/folders/rb/l4_6j2nx0lnfhysk974ldpg40000gn/T/tmp28vhpcy7/corpus",
+      "-n",
+      "8",
+      "--",
+      "Concern"
+    ],
+    "output": {
+      "chunks": [
+        {
+          "content": "Risk: supplier delays require a backup plan.",
+          "source": "brief.md",
+          "line_start": 1,
+          "line_end": 1,
+          "relevance_score": 2.0,
+          "haystack": "code"
+        }
+      ],
+      "answer": null,
+      "concepts": [
+        {
+          "id": 0,
+          "name": "concern",
+          "display_value": null,
+          "score": 1.0
+        },
+        {
+          "id": 0,
+          "name": "risk",
+          "display_value": null,
+          "score": 1.0
+        }
+      ],
+      "sufficiency": "RlmInsufficient",
+      "sufficiency_explanation": "Only 1 chunk(s) and 2 KG concept(s) were retrieved; the minimum for a meaningful answer is 3 chunks, and coverage was 1.00. Too little evidence to synthesise -- try broadening the query or the searched paths.",
+      "stats": {
+        "search_latency_ms": 2,
+        "rlm_latency_ms": null,
+        "chunks_returned": 1,
+        "kg_hits": 2
+      }
+    }
+  },
+  "changedGraphRefused": "Admitted binary or graph changed; restart after reviewing new inputs",
+  "reviewedGraphAfterRestart": {
+    "mode": "retrieval-only",
+    "binarySha256": "95491857b6a115ce7f4ec2a9d24bd0f7b8efcc1a52bd1403b34a62dd704012ab",
+    "graphSha256": "fb637650f150f1db0b71537956ddcc07655888bb286f378624cca06013b101e2",
+    "argv": [
+      "/private/tmp/published-continue-skills-audit-20261014/clients-1.21.20/extracted/terraphim-grep",
+      "--search-only",
+      "--json",
+      "--thesaurus",
+      "/private/var/folders/rb/l4_6j2nx0lnfhysk974ldpg40000gn/T/tmp28vhpcy7/graph.json",
+      "--paths",
+      "/private/var/folders/rb/l4_6j2nx0lnfhysk974ldpg40000gn/T/tmp28vhpcy7/corpus",
+      "-n",
+      "8",
+      "--",
+      "Hazard"
+    ],
+    "output": {
+      "chunks": [
+        {
+          "content": "Risk: supplier delays require a backup plan.",
+          "source": "brief.md",
+          "line_start": 1,
+          "line_end": 1,
+          "relevance_score": 2.0,
+          "haystack": "code"
+        }
+      ],
+      "answer": null,
+      "concepts": [
+        {
+          "id": 0,
+          "name": "concern",
+          "display_value": null,
+          "score": 1.0
+        },
+        {
+          "id": 0,
+          "name": "hazard",
+          "display_value": null,
+          "score": 1.0
+        },
+        {
+          "id": 0,
+          "name": "risk",
+          "display_value": null,
+          "score": 1.0
+        }
+      ],
+      "sufficiency": "RlmInsufficient",
+      "sufficiency_explanation": "Only 1 chunk(s) and 3 KG concept(s) were retrieved; the minimum for a meaningful answer is 3 chunks, and coverage was 1.00. Too little evidence to synthesise -- try broadening the query or the searched paths.",
+      "stats": {
+        "search_latency_ms": 2,
+        "rlm_latency_ms": null,
+        "chunks_returned": 1,
+        "kg_hits": 3
+      }
+    }
+  }
+}

.docs/marketplace-cli-examples-20261014/continue-versions.stdout

@@ -0,0 +1,2 @@
+terraphim-grep 1.21.20
+terraphim-agent 1.21.20

.docs/marketplace-cli-examples-20261014/receipt.json

@@ -0,0 +1,89 @@
+{
+  "checkedAt": "2026-10-14T18:36:54.066022+00:00",
+  "host": {
+    "system": "Darwin",
+    "architecture": "arm64"
+  },
+  "release": "https://github.com/terraphim/terraphim-clients/releases/tag/v1.21.20",
+  "binaries": {
+    "terraphim-grep": {
+      "sha256": "95491857b6a115ce7f4ec2a9d24bd0f7b8efcc1a52bd1403b34a62dd704012ab",
+      "version": "terraphim-grep 1.21.20"
+    },
+    "terraphim-agent": {
+      "sha256": "bff31dc42d6d1a99bf51291039d7719c6a48c2326e582e5e24eaa1eaf11e17ec",
+      "version": "terraphim-agent 1.21.20"
+    }
+  },
+  "cases": [
+    {
+      "name": "vscode",
+      "sourceDocument": "vs-code-terraphim-it/README.md",
+      "sourceSha256": "c14dfef1378e99015bb8a921fa186be7be1ce732d308302f7d1c830b4378d8ea",
+      "graphSha256": "f8648b16470e764bdff5c95064078419d71e8d41d2ca30d4b1508017c166a45d",
+      "graphProvenance": "Existing editor-exported graph at integrations/continue/risk-concern.exported.json; labelled input.",
+      "profileIsolation": "Dedicated child HOME/config/data directories; no real user memory used; provider/credential environment names omitted.",
+      "commands": [
+        {
+          "block": "terraphim-grep --version\nterraphim-agent --version",
+          "exitCode": 0,
+          "stdout": "vscode-versions.stdout",
+          "stderr": "vscode-versions.stderr"
+        },
+        {
+          "block": "terraphim-grep concern --search-only --haystack all \\\n  --paths ./briefs --thesaurus ./brief.knowledge-graph.json --json -n 3",
+          "exitCode": 0,
+          "stdout": "vscode-search.stdout",
+          "stderr": "vscode-search.stderr"
+        },
+        {
+          "block": "terraphim-grep concern --answer --haystack all \\\n  --paths ./briefs --thesaurus ./brief.knowledge-graph.json --json -n 3",
+          "exitCode": 0,
+          "stdout": "vscode-answer-insufficient.stdout",
+          "stderr": "vscode-answer-insufficient.stderr"
+        },
+        {
+          "block": "terraphim-agent --format json memory capture \\\n  --content 'Risk requires a Decision: approve a second supplier as the mitigation.' \\\n  --provenance-tag 'public-project-brief' > captured-memory.json\nmemory_id=\"$(python3 -c 'import json; print(json.load(open(\"captured-memory.json\"))[\"memory_id\"])')\"\nterraphim-agent memory show \"$memory_id\" --json",
+          "exitCode": 0,
+          "stdout": "vscode-capture-show.stdout",
+          "stderr": "vscode-capture-show.stderr"
+        }
+      ],
+      "baseline": "Zero passages with explicit empty graph; one Risk passage with existing editor export.",
+      "finalDocumentSha256": "065ac3ecaaf3f9d92873b245edd39fae5102dcca79ca6cc02f89b78616fac06f",
+      "executedBlocksUnchangedInFinalDocument": true
+    },
+    {
+      "name": "continue",
+      "sourceDocument": "integrations/continue/README.md",
+      "sourceSha256": "898de9de9b482123ae30ff0b8c22810342f7d17e463ee1ca6b402e29a00d2dc4",
+      "graphSha256": "f8648b16470e764bdff5c95064078419d71e8d41d2ca30d4b1508017c166a45d",
+      "graphProvenance": "Existing editor-exported graph at integrations/continue/risk-concern.exported.json; labelled input.",
+      "profileIsolation": "Dedicated child HOME/config/data directories; no real user memory used; provider/credential environment names omitted.",
+      "commands": [
+        {
+          "block": "terraphim-grep --version\nterraphim-agent --version",
+          "exitCode": 0,
+          "stdout": "continue-versions.stdout",
+          "stderr": "continue-versions.stderr"
+        },
+        {
+          "block": "mkdir briefs\nprintf '%s\\n' 'Risk: supplier delays require a backup plan.' > briefs/decision.md\nterraphim-grep concern --search-only --haystack all \\\n  --paths ./briefs --thesaurus ./risk-concern.exported.json --json -n 3",
+          "exitCode": 0,
+          "stdout": "continue-search.stdout",
+          "stderr": "continue-search.stderr"
+        },
+        {
+          "block": "terraphim-agent --format json memory capture \\\n  --content 'Risk requires a Decision: approve a second supplier as the mitigation.' \\\n  --provenance-tag 'public-project-brief' > captured-memory.json\nmemory_id=\"$(python3 -c 'import json; print(json.load(open(\"captured-memory.json\"))[\"memory_id\"])')\"\nterraphim-agent memory show \"$memory_id\" --json",
+          "exitCode": 0,
+          "stdout": "continue-capture-show.stdout",
+          "stderr": "continue-capture-show.stderr"
+        }
+      ],
+      "baseline": "Zero passages with explicit empty graph; one Risk passage with existing editor export.",
+      "finalDocumentSha256": "ca2e1f9e5e87e1e863e5015f4d6847bfda222ddb8d3b0abcf79f5063a1adc66b",
+      "executedBlocksUnchangedInFinalDocument": true
+    }
+  ],
+  "scope": "Exact new README shell blocks executed with released binaries in fresh child-only local profiles. The graph is an existing editor export supplied as labelled input; these CLI runs do not claim a new editor operation or provider synthesis."
+}

.docs/marketplace-cli-examples-20261014/static-checks.json

@@ -0,0 +1,16 @@
+{
+  "changedTest": "integrations/continue/test_transport.py",
+  "current": {
+    "critical": 2,
+    "warning": 5,
+    "exitCode": 1
+  },
+  "base": {
+    "critical": 2,
+    "warning": 3,
+    "exitCode": 1
+  },
+  "review": "The two taint findings identify the pre-existing intentionally selected released test executable from TERRAPHIM_GREP_BINARY, passed as argv without shell. Existing unbounded baseline subprocess is unchanged. Two new warnings identify json.loads calls on test fixture/actual MCP output: malformed JSON must fail this assertion-based integration test, not be swallowed. No production runtime changed.",
+  "actionlint": "PASS .github/workflows/continue-integration.yml",
+  "diffCheck": "PASS"
+}

.docs/marketplace-cli-examples-20261014/vscode-answer-insufficient.stderr

@@ -0,0 +1 @@
+2026-10-14T18:36:54.150537Z  WARN fff_search::file_picker: No git repository found for path: ./briefs