From 37b499821ad0461828649080673d74c5195489a4 Mon Sep 17 00:00:00 2001 From: ayushcodes10 Date: Wed, 9 Sep 2026 22:30:31 +0530 Subject: [PATCH 1/6] Add file based value passing to save result and add save result already had an answer file option for exactly this reason; adding equivalents for the question and correction fields makes every free text field on that command safe to pass through a file instead of a command line argument. graphify add gets a symmetric file input reading a JSON payload for url, author, and contributor. Neither command's existing positional/flag form changes. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_017qfdzgbA5KedGEjD1AayNh --- graphify/cli.py | 90 +++++++++++++++++++++++++++++++------------ tests/test_ingest.py | 72 ++++++++++++++++++++++++++++++++++ tests/test_reflect.py | 30 +++++++++++++++ 3 files changed, 167 insertions(+), 25 deletions(-) diff --git a/graphify/cli.py b/graphify/cli.py index 400cf463d..a239a66aa 100644 --- a/graphify/cli.py +++ b/graphify/cli.py @@ -1461,22 +1461,39 @@ def dispatch_command(cmd: str) -> None: elif cmd == "save-result": # graphify save-result --question Q --answer A [--type T] [--nodes N1 N2 ...] # [--outcome useful|dead_end|corrected] [--correction TEXT] + # + # --question-file/--answer-file/--correction-file read the value from a + # file instead of a command-line argument: skill instructions that build + # this command from free text (the user's verbatim question, an LLM's + # generated answer, of unbounded length and content) must not substitute + # that text directly into a shell command string, since embedded quotes, + # backticks, or $() would corrupt or escape the command entirely + # (#3439). Writing the value to a file first has no such injection + # surface at all. import argparse as _ap p = _ap.ArgumentParser(prog="graphify save-result") - p.add_argument("--question", required=True) + p.add_argument("--question", default=None) + p.add_argument("--question-file", dest="question_file", default=None) p.add_argument("--answer", default=None) p.add_argument("--answer-file", dest="answer_file", default=None) p.add_argument("--type", dest="query_type", default="query") p.add_argument("--nodes", nargs="*", default=[]) p.add_argument("--outcome", choices=("useful", "dead_end", "corrected"), default=None) p.add_argument("--correction", default=None) + p.add_argument("--correction-file", dest="correction_file", default=None) p.add_argument("--memory-dir", default=str(Path(_GRAPHIFY_OUT) / "memory")) opts = p.parse_args(sys.argv[2:]) + if opts.question_file: + opts.question = Path(opts.question_file).read_text(encoding="utf-8").strip() + elif not opts.question: + p.error("--question or --question-file is required") if opts.answer_file: opts.answer = Path(opts.answer_file).read_text(encoding="utf-8").strip() elif not opts.answer: p.error("--answer or --answer-file is required") + if opts.correction_file: + opts.correction = Path(opts.correction_file).read_text(encoding="utf-8").strip() from graphify.ingest import save_query_result as _sqr out = _sqr( @@ -1942,32 +1959,55 @@ def dispatch_command(cmd: str) -> None: print(format_diagnostic_report(summary)) elif cmd == "add": - if len(sys.argv) < 3: - print( - "Usage: graphify add [--author Name] [--contributor Name] [--dir ./raw]", - file=sys.stderr, - ) - sys.exit(1) + # --from-file reads {"url": ..., "author": ..., "contributor": ..., "dir": ...} + # (author/contributor/dir optional) instead of taking url/--author/ + # --contributor as command-line text: skill instructions that build this + # command from a user-supplied URL and name have no way to shell-quote + # values they cannot predict the content of, so substituting them + # directly into a command string risks corrupting or escaping it + # (#3439). Writing the payload to a file first has no such injection + # surface -- only the file's own (agent-controlled) path is a shell + # argument. + args = sys.argv[2:] + from_file = None + for i, a in enumerate(args): + if a == "--from-file" and i + 1 < len(args): + from_file = args[i + 1] + break + if from_file: + payload = json.loads(Path(from_file).read_text(encoding="utf-8")) + url = payload["url"] + author = payload.get("author") + contributor = payload.get("contributor") + target_dir = Path(payload.get("dir") or "raw") + else: + if len(sys.argv) < 3: + print( + "Usage: graphify add [--author Name] [--contributor Name] " + "[--dir ./raw] | graphify add --from-file payload.json", + file=sys.stderr, + ) + sys.exit(1) + url = sys.argv[2] + author = None + contributor = None + target_dir = Path("raw") + args = sys.argv[3:] + i = 0 + while i < len(args): + if args[i] == "--author" and i + 1 < len(args): + author = args[i + 1] + i += 2 + elif args[i] == "--contributor" and i + 1 < len(args): + contributor = args[i + 1] + i += 2 + elif args[i] == "--dir" and i + 1 < len(args): + target_dir = Path(args[i + 1]) + i += 2 + else: + i += 1 from graphify.ingest import ingest as _ingest - url = sys.argv[2] - author: str | None = None - contributor: str | None = None - target_dir = Path("raw") - args = sys.argv[3:] - i = 0 - while i < len(args): - if args[i] == "--author" and i + 1 < len(args): - author = args[i + 1] - i += 2 - elif args[i] == "--contributor" and i + 1 < len(args): - contributor = args[i + 1] - i += 2 - elif args[i] == "--dir" and i + 1 < len(args): - target_dir = Path(args[i + 1]) - i += 2 - else: - i += 1 try: saved = _ingest(url, target_dir, author=author, contributor=contributor) print(f"Saved to {saved}") diff --git a/tests/test_ingest.py b/tests/test_ingest.py index 6b7d1fb03..ea940f084 100644 --- a/tests/test_ingest.py +++ b/tests/test_ingest.py @@ -110,3 +110,75 @@ def test_concurrent_saves_of_the_same_question_do_not_overwrite(tmp_path): paths = list(ex.map(lambda _: save_query_result("how does auth work", "a", mem), range(20))) assert len({p.name for p in paths}) == 20 assert len(list(mem.glob("*.md"))) == 20 + + +def test_cli_add_from_file_passes_payload_through_unexecuted(tmp_path, monkeypatch): + """#3439: the skill instructions for `graphify add` used to have the + agent substitute a URL and free-text author/contributor names directly + into a `python -c "..."` heredoc calling ingest(...) as Python source -- + an embedded quote breaks it, and crafted input executes arbitrary + Python. --from-file reads the same values from a JSON payload instead, + which has no such injection surface: only the file's own path (agent- + controlled, not user content) becomes a shell argument. Mocks ingest + itself so this never touches the network; the point here is that the + adversarial author/contributor text reaches ingest() as plain string + values, verbatim, never as code.""" + import json + import sys + from pathlib import Path + from graphify.cli import dispatch_command + + captured = {} + + def fake_ingest(url, target_dir, author=None, contributor=None): + captured["url"] = url + captured["target_dir"] = target_dir + captured["author"] = author + captured["contributor"] = contributor + return Path(target_dir) / "page.md" + + monkeypatch.setattr("graphify.ingest.ingest", fake_ingest) + + payload = tmp_path / "payload.json" + payload.write_text(json.dumps({ + "url": "https://example.com/page", + "author": "O'Brien", + "contributor": "test`whoami`; rm -rf / #", + "dir": str(tmp_path / "raw"), + }), encoding="utf-8") + + monkeypatch.setattr(sys, "argv", ["graphify", "add", "--from-file", str(payload)]) + dispatch_command("add") + + assert captured["url"] == "https://example.com/page" + assert captured["author"] == "O'Brien" + assert captured["contributor"] == "test`whoami`; rm -rf / #" + assert captured["target_dir"] == Path(str(tmp_path / "raw")) + + +def test_cli_add_still_accepts_positional_url_and_flags(tmp_path, monkeypatch): + """--from-file is additive: the original `graphify add --author X + --contributor Y` form (a human typing the command directly, not a skill + substituting untrusted text into it) must keep working unchanged.""" + import sys + from pathlib import Path + from graphify.cli import dispatch_command + + captured = {} + + def fake_ingest(url, target_dir, author=None, contributor=None): + captured["url"] = url + captured["author"] = author + captured["contributor"] = contributor + return Path(target_dir) / "page.md" + + monkeypatch.setattr("graphify.ingest.ingest", fake_ingest) + monkeypatch.setattr(sys, "argv", [ + "graphify", "add", "https://example.com/x", + "--author", "Jane", "--contributor", "Jo", + ]) + dispatch_command("add") + + assert captured["url"] == "https://example.com/x" + assert captured["author"] == "Jane" + assert captured["contributor"] == "Jo" diff --git a/tests/test_reflect.py b/tests/test_reflect.py index c24cacefd..5f15954d3 100644 --- a/tests/test_reflect.py +++ b/tests/test_reflect.py @@ -499,6 +499,36 @@ def test_cli_save_result_requires_answer_or_answer_file(tmp_path): assert "--answer" in (r.stderr + r.stdout) +def test_cli_save_result_reads_question_and_correction_from_file(tmp_path): + """#3439: --question-file/--correction-file mirror --answer-file for the + same reason -- a value a skill's instructions build this command from + (the user's verbatim question, an LLM-generated correction) is free + text of unpredictable content, and substituting it directly into a + shell command string risks corruption or injection via an embedded + quote, backtick, or $(). A file has no such surface. Round-trips + adversarial content (backticks, $(), both quote styles) through both + fields at once, unexecuted and uncorrupted.""" + q = tmp_path / "question.txt" + q.write_text("what about $(whoami) and `id` and 'quotes' and \"more\"?\n", encoding="utf-8") + c = tmp_path / "correction.txt" + c.write_text("actually it's `AuthMiddleware`, not $(OldAuth); check 'both'.\n", encoding="utf-8") + r = _run(["save-result", "--question-file", str(q), "--answer", "a", + "--outcome", "corrected", "--correction-file", str(c)], tmp_path) + assert r.returncode == 0, r.stderr + docs = list((tmp_path / "graphify-out" / "memory").glob("*.md")) + assert docs, "save-result wrote no memory doc" + body = docs[0].read_text(encoding="utf-8") + assert "$(whoami)" in body and "`id`" in body + assert "`AuthMiddleware`" in body and "$(OldAuth)" in body + + +def test_cli_save_result_requires_question_or_question_file(tmp_path): + """Neither --question nor --question-file -> clean argparse error, not a crash.""" + r = _run(["save-result", "--answer", "a", "--outcome", "useful"], tmp_path) + assert r.returncode != 0 + assert "--question" in (r.stderr + r.stdout) + + def test_cli_reflect_cold_start_writes_empty_lessons(tmp_path): """First run with no graphify-out/memory/ still succeeds and writes a valid doc.""" r = _run(["reflect"], tmp_path) From 51a8fc7d86ceafd92e241230c82082694e221b1f Mon Sep 17 00:00:00 2001 From: ayushcodes10 Date: Wed, 9 Sep 2026 22:30:57 +0530 Subject: [PATCH 2/6] Stop building generated code from unsanitized free text Two of the generated skill references instructed the host agent to substitute raw, unsanitized values directly into generated Python or shell source. The add reference embedded a URL and optional author/contributor name inside a single quoted Python literal passed to python's inline script flag, so an embedded quote broke it and crafted input could run arbitrary Python. The query reference substituted the user's verbatim question and a full LLM generated answer, unbounded length, into a double quoted shell argument, where an embedded backtick or command substitution still executes. Both now write the value to a file with the agent's own file write tool first and pass only that file's path on the command line, never the content itself, so there is no injection surface left at all. Regenerated all fourteen platform skill variants and their expected fixtures from the updated shared fragments; every skillgen guard still passes. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_017qfdzgbA5KedGEjD1AayNh --- .../skills/agents/references/add-watch.md | 35 ++++++++++--------- graphify/skills/agents/references/query.md | 29 ++++++++++----- graphify/skills/amp/references/add-watch.md | 35 ++++++++++--------- graphify/skills/amp/references/query.md | 29 ++++++++++----- .../skills/claude/references/add-watch.md | 35 ++++++++++--------- graphify/skills/claude/references/query.md | 29 ++++++++++----- graphify/skills/claw/references/add-watch.md | 35 ++++++++++--------- graphify/skills/claw/references/query.md | 29 ++++++++++----- graphify/skills/codex/references/add-watch.md | 35 ++++++++++--------- graphify/skills/codex/references/query.md | 29 ++++++++++----- .../skills/copilot/references/add-watch.md | 35 ++++++++++--------- graphify/skills/copilot/references/query.md | 29 ++++++++++----- graphify/skills/droid/references/add-watch.md | 35 ++++++++++--------- graphify/skills/droid/references/query.md | 29 ++++++++++----- graphify/skills/kilo/references/add-watch.md | 35 ++++++++++--------- graphify/skills/kilo/references/query.md | 29 ++++++++++----- graphify/skills/kiro/references/add-watch.md | 35 ++++++++++--------- graphify/skills/kiro/references/query.md | 29 ++++++++++----- .../skills/opencode/references/add-watch.md | 35 ++++++++++--------- graphify/skills/opencode/references/query.md | 29 ++++++++++----- graphify/skills/pi/references/add-watch.md | 35 ++++++++++--------- graphify/skills/pi/references/query.md | 29 ++++++++++----- graphify/skills/trae/references/add-watch.md | 35 ++++++++++--------- graphify/skills/trae/references/query.md | 29 ++++++++++----- .../skills/vscode/references/add-watch.md | 35 ++++++++++--------- graphify/skills/vscode/references/query.md | 29 ++++++++++----- .../skills/windows/references/add-watch.md | 35 ++++++++++--------- graphify/skills/windows/references/query.md | 29 ++++++++++----- ...__skills__agents__references__add-watch.md | 35 ++++++++++--------- ...hify__skills__agents__references__query.md | 29 ++++++++++----- ...ify__skills__amp__references__add-watch.md | 35 ++++++++++--------- ...raphify__skills__amp__references__query.md | 29 ++++++++++----- ...__skills__claude__references__add-watch.md | 35 ++++++++++--------- ...hify__skills__claude__references__query.md | 29 ++++++++++----- ...fy__skills__claw__references__add-watch.md | 35 ++++++++++--------- ...aphify__skills__claw__references__query.md | 29 ++++++++++----- ...y__skills__codex__references__add-watch.md | 35 ++++++++++--------- ...phify__skills__codex__references__query.md | 29 ++++++++++----- ..._skills__copilot__references__add-watch.md | 35 ++++++++++--------- ...ify__skills__copilot__references__query.md | 29 ++++++++++----- ...y__skills__droid__references__add-watch.md | 35 ++++++++++--------- ...phify__skills__droid__references__query.md | 29 ++++++++++----- ...fy__skills__kilo__references__add-watch.md | 35 ++++++++++--------- ...aphify__skills__kilo__references__query.md | 29 ++++++++++----- ...fy__skills__kiro__references__add-watch.md | 35 ++++++++++--------- ...aphify__skills__kiro__references__query.md | 29 ++++++++++----- ...skills__opencode__references__add-watch.md | 35 ++++++++++--------- ...fy__skills__opencode__references__query.md | 29 ++++++++++----- ...hify__skills__pi__references__add-watch.md | 35 ++++++++++--------- ...graphify__skills__pi__references__query.md | 29 ++++++++++----- ...fy__skills__trae__references__add-watch.md | 35 ++++++++++--------- ...aphify__skills__trae__references__query.md | 29 ++++++++++----- ...__skills__vscode__references__add-watch.md | 35 ++++++++++--------- ...hify__skills__vscode__references__query.md | 29 ++++++++++----- ..._skills__windows__references__add-watch.md | 35 ++++++++++--------- ...ify__skills__windows__references__query.md | 29 ++++++++++----- .../fragments/references/query/default.md | 29 ++++++++++----- .../fragments/references/shared/add-watch.md | 35 ++++++++++--------- 58 files changed, 1160 insertions(+), 696 deletions(-) diff --git a/graphify/skills/agents/references/add-watch.md b/graphify/skills/agents/references/add-watch.md index 77844343e..baa5f3f0b 100644 --- a/graphify/skills/agents/references/add-watch.md +++ b/graphify/skills/agents/references/add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/graphify/skills/agents/references/query.md b/graphify/skills/agents/references/query.md index 56565eb78..f3eafd924 100644 --- a/graphify/skills/agents/references/query.md +++ b/graphify/skills/agents/references/query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/amp/references/add-watch.md b/graphify/skills/amp/references/add-watch.md index 77844343e..baa5f3f0b 100644 --- a/graphify/skills/amp/references/add-watch.md +++ b/graphify/skills/amp/references/add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/graphify/skills/amp/references/query.md b/graphify/skills/amp/references/query.md index 56565eb78..f3eafd924 100644 --- a/graphify/skills/amp/references/query.md +++ b/graphify/skills/amp/references/query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/claude/references/add-watch.md b/graphify/skills/claude/references/add-watch.md index 77844343e..baa5f3f0b 100644 --- a/graphify/skills/claude/references/add-watch.md +++ b/graphify/skills/claude/references/add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/graphify/skills/claude/references/query.md b/graphify/skills/claude/references/query.md index 56565eb78..f3eafd924 100644 --- a/graphify/skills/claude/references/query.md +++ b/graphify/skills/claude/references/query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/claw/references/add-watch.md b/graphify/skills/claw/references/add-watch.md index 77844343e..baa5f3f0b 100644 --- a/graphify/skills/claw/references/add-watch.md +++ b/graphify/skills/claw/references/add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/graphify/skills/claw/references/query.md b/graphify/skills/claw/references/query.md index 56565eb78..f3eafd924 100644 --- a/graphify/skills/claw/references/query.md +++ b/graphify/skills/claw/references/query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/codex/references/add-watch.md b/graphify/skills/codex/references/add-watch.md index 77844343e..baa5f3f0b 100644 --- a/graphify/skills/codex/references/add-watch.md +++ b/graphify/skills/codex/references/add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/graphify/skills/codex/references/query.md b/graphify/skills/codex/references/query.md index 56565eb78..f3eafd924 100644 --- a/graphify/skills/codex/references/query.md +++ b/graphify/skills/codex/references/query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/copilot/references/add-watch.md b/graphify/skills/copilot/references/add-watch.md index 77844343e..baa5f3f0b 100644 --- a/graphify/skills/copilot/references/add-watch.md +++ b/graphify/skills/copilot/references/add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/graphify/skills/copilot/references/query.md b/graphify/skills/copilot/references/query.md index 56565eb78..f3eafd924 100644 --- a/graphify/skills/copilot/references/query.md +++ b/graphify/skills/copilot/references/query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/droid/references/add-watch.md b/graphify/skills/droid/references/add-watch.md index 77844343e..baa5f3f0b 100644 --- a/graphify/skills/droid/references/add-watch.md +++ b/graphify/skills/droid/references/add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/graphify/skills/droid/references/query.md b/graphify/skills/droid/references/query.md index 56565eb78..f3eafd924 100644 --- a/graphify/skills/droid/references/query.md +++ b/graphify/skills/droid/references/query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/kilo/references/add-watch.md b/graphify/skills/kilo/references/add-watch.md index 77844343e..baa5f3f0b 100644 --- a/graphify/skills/kilo/references/add-watch.md +++ b/graphify/skills/kilo/references/add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/graphify/skills/kilo/references/query.md b/graphify/skills/kilo/references/query.md index 56565eb78..f3eafd924 100644 --- a/graphify/skills/kilo/references/query.md +++ b/graphify/skills/kilo/references/query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/kiro/references/add-watch.md b/graphify/skills/kiro/references/add-watch.md index 77844343e..baa5f3f0b 100644 --- a/graphify/skills/kiro/references/add-watch.md +++ b/graphify/skills/kiro/references/add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/graphify/skills/kiro/references/query.md b/graphify/skills/kiro/references/query.md index 56565eb78..f3eafd924 100644 --- a/graphify/skills/kiro/references/query.md +++ b/graphify/skills/kiro/references/query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/opencode/references/add-watch.md b/graphify/skills/opencode/references/add-watch.md index 77844343e..baa5f3f0b 100644 --- a/graphify/skills/opencode/references/add-watch.md +++ b/graphify/skills/opencode/references/add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/graphify/skills/opencode/references/query.md b/graphify/skills/opencode/references/query.md index 56565eb78..f3eafd924 100644 --- a/graphify/skills/opencode/references/query.md +++ b/graphify/skills/opencode/references/query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/pi/references/add-watch.md b/graphify/skills/pi/references/add-watch.md index 77844343e..baa5f3f0b 100644 --- a/graphify/skills/pi/references/add-watch.md +++ b/graphify/skills/pi/references/add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/graphify/skills/pi/references/query.md b/graphify/skills/pi/references/query.md index 56565eb78..f3eafd924 100644 --- a/graphify/skills/pi/references/query.md +++ b/graphify/skills/pi/references/query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/trae/references/add-watch.md b/graphify/skills/trae/references/add-watch.md index 77844343e..baa5f3f0b 100644 --- a/graphify/skills/trae/references/add-watch.md +++ b/graphify/skills/trae/references/add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/graphify/skills/trae/references/query.md b/graphify/skills/trae/references/query.md index 56565eb78..f3eafd924 100644 --- a/graphify/skills/trae/references/query.md +++ b/graphify/skills/trae/references/query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/vscode/references/add-watch.md b/graphify/skills/vscode/references/add-watch.md index 77844343e..baa5f3f0b 100644 --- a/graphify/skills/vscode/references/add-watch.md +++ b/graphify/skills/vscode/references/add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/graphify/skills/vscode/references/query.md b/graphify/skills/vscode/references/query.md index 56565eb78..f3eafd924 100644 --- a/graphify/skills/vscode/references/query.md +++ b/graphify/skills/vscode/references/query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/windows/references/add-watch.md b/graphify/skills/windows/references/add-watch.md index 77844343e..baa5f3f0b 100644 --- a/graphify/skills/windows/references/add-watch.md +++ b/graphify/skills/windows/references/add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/graphify/skills/windows/references/query.md b/graphify/skills/windows/references/query.md index 56565eb78..f3eafd924 100644 --- a/graphify/skills/windows/references/query.md +++ b/graphify/skills/windows/references/query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__agents__references__add-watch.md b/tools/skillgen/expected/graphify__skills__agents__references__add-watch.md index 77844343e..baa5f3f0b 100644 --- a/tools/skillgen/expected/graphify__skills__agents__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__agents__references__add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/tools/skillgen/expected/graphify__skills__agents__references__query.md b/tools/skillgen/expected/graphify__skills__agents__references__query.md index 56565eb78..f3eafd924 100644 --- a/tools/skillgen/expected/graphify__skills__agents__references__query.md +++ b/tools/skillgen/expected/graphify__skills__agents__references__query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__amp__references__add-watch.md b/tools/skillgen/expected/graphify__skills__amp__references__add-watch.md index 77844343e..baa5f3f0b 100644 --- a/tools/skillgen/expected/graphify__skills__amp__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__amp__references__add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/tools/skillgen/expected/graphify__skills__amp__references__query.md b/tools/skillgen/expected/graphify__skills__amp__references__query.md index 56565eb78..f3eafd924 100644 --- a/tools/skillgen/expected/graphify__skills__amp__references__query.md +++ b/tools/skillgen/expected/graphify__skills__amp__references__query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__claude__references__add-watch.md b/tools/skillgen/expected/graphify__skills__claude__references__add-watch.md index 77844343e..baa5f3f0b 100644 --- a/tools/skillgen/expected/graphify__skills__claude__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__claude__references__add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/tools/skillgen/expected/graphify__skills__claude__references__query.md b/tools/skillgen/expected/graphify__skills__claude__references__query.md index 56565eb78..f3eafd924 100644 --- a/tools/skillgen/expected/graphify__skills__claude__references__query.md +++ b/tools/skillgen/expected/graphify__skills__claude__references__query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__claw__references__add-watch.md b/tools/skillgen/expected/graphify__skills__claw__references__add-watch.md index 77844343e..baa5f3f0b 100644 --- a/tools/skillgen/expected/graphify__skills__claw__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__claw__references__add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/tools/skillgen/expected/graphify__skills__claw__references__query.md b/tools/skillgen/expected/graphify__skills__claw__references__query.md index 56565eb78..f3eafd924 100644 --- a/tools/skillgen/expected/graphify__skills__claw__references__query.md +++ b/tools/skillgen/expected/graphify__skills__claw__references__query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__codex__references__add-watch.md b/tools/skillgen/expected/graphify__skills__codex__references__add-watch.md index 77844343e..baa5f3f0b 100644 --- a/tools/skillgen/expected/graphify__skills__codex__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__codex__references__add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/tools/skillgen/expected/graphify__skills__codex__references__query.md b/tools/skillgen/expected/graphify__skills__codex__references__query.md index 56565eb78..f3eafd924 100644 --- a/tools/skillgen/expected/graphify__skills__codex__references__query.md +++ b/tools/skillgen/expected/graphify__skills__codex__references__query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__copilot__references__add-watch.md b/tools/skillgen/expected/graphify__skills__copilot__references__add-watch.md index 77844343e..baa5f3f0b 100644 --- a/tools/skillgen/expected/graphify__skills__copilot__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__copilot__references__add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/tools/skillgen/expected/graphify__skills__copilot__references__query.md b/tools/skillgen/expected/graphify__skills__copilot__references__query.md index 56565eb78..f3eafd924 100644 --- a/tools/skillgen/expected/graphify__skills__copilot__references__query.md +++ b/tools/skillgen/expected/graphify__skills__copilot__references__query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__droid__references__add-watch.md b/tools/skillgen/expected/graphify__skills__droid__references__add-watch.md index 77844343e..baa5f3f0b 100644 --- a/tools/skillgen/expected/graphify__skills__droid__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__droid__references__add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/tools/skillgen/expected/graphify__skills__droid__references__query.md b/tools/skillgen/expected/graphify__skills__droid__references__query.md index 56565eb78..f3eafd924 100644 --- a/tools/skillgen/expected/graphify__skills__droid__references__query.md +++ b/tools/skillgen/expected/graphify__skills__droid__references__query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__kilo__references__add-watch.md b/tools/skillgen/expected/graphify__skills__kilo__references__add-watch.md index 77844343e..baa5f3f0b 100644 --- a/tools/skillgen/expected/graphify__skills__kilo__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__kilo__references__add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/tools/skillgen/expected/graphify__skills__kilo__references__query.md b/tools/skillgen/expected/graphify__skills__kilo__references__query.md index 56565eb78..f3eafd924 100644 --- a/tools/skillgen/expected/graphify__skills__kilo__references__query.md +++ b/tools/skillgen/expected/graphify__skills__kilo__references__query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__kiro__references__add-watch.md b/tools/skillgen/expected/graphify__skills__kiro__references__add-watch.md index 77844343e..baa5f3f0b 100644 --- a/tools/skillgen/expected/graphify__skills__kiro__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__kiro__references__add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/tools/skillgen/expected/graphify__skills__kiro__references__query.md b/tools/skillgen/expected/graphify__skills__kiro__references__query.md index 56565eb78..f3eafd924 100644 --- a/tools/skillgen/expected/graphify__skills__kiro__references__query.md +++ b/tools/skillgen/expected/graphify__skills__kiro__references__query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__opencode__references__add-watch.md b/tools/skillgen/expected/graphify__skills__opencode__references__add-watch.md index 77844343e..baa5f3f0b 100644 --- a/tools/skillgen/expected/graphify__skills__opencode__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__opencode__references__add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/tools/skillgen/expected/graphify__skills__opencode__references__query.md b/tools/skillgen/expected/graphify__skills__opencode__references__query.md index 56565eb78..f3eafd924 100644 --- a/tools/skillgen/expected/graphify__skills__opencode__references__query.md +++ b/tools/skillgen/expected/graphify__skills__opencode__references__query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__pi__references__add-watch.md b/tools/skillgen/expected/graphify__skills__pi__references__add-watch.md index 77844343e..baa5f3f0b 100644 --- a/tools/skillgen/expected/graphify__skills__pi__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__pi__references__add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/tools/skillgen/expected/graphify__skills__pi__references__query.md b/tools/skillgen/expected/graphify__skills__pi__references__query.md index 56565eb78..f3eafd924 100644 --- a/tools/skillgen/expected/graphify__skills__pi__references__query.md +++ b/tools/skillgen/expected/graphify__skills__pi__references__query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__trae__references__add-watch.md b/tools/skillgen/expected/graphify__skills__trae__references__add-watch.md index 77844343e..baa5f3f0b 100644 --- a/tools/skillgen/expected/graphify__skills__trae__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__trae__references__add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/tools/skillgen/expected/graphify__skills__trae__references__query.md b/tools/skillgen/expected/graphify__skills__trae__references__query.md index 56565eb78..f3eafd924 100644 --- a/tools/skillgen/expected/graphify__skills__trae__references__query.md +++ b/tools/skillgen/expected/graphify__skills__trae__references__query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__vscode__references__add-watch.md b/tools/skillgen/expected/graphify__skills__vscode__references__add-watch.md index 77844343e..baa5f3f0b 100644 --- a/tools/skillgen/expected/graphify__skills__vscode__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__vscode__references__add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/tools/skillgen/expected/graphify__skills__vscode__references__query.md b/tools/skillgen/expected/graphify__skills__vscode__references__query.md index 56565eb78..f3eafd924 100644 --- a/tools/skillgen/expected/graphify__skills__vscode__references__query.md +++ b/tools/skillgen/expected/graphify__skills__vscode__references__query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__windows__references__add-watch.md b/tools/skillgen/expected/graphify__skills__windows__references__add-watch.md index 77844343e..baa5f3f0b 100644 --- a/tools/skillgen/expected/graphify__skills__windows__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__windows__references__add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) diff --git a/tools/skillgen/expected/graphify__skills__windows__references__query.md b/tools/skillgen/expected/graphify__skills__windows__references__query.md index 56565eb78..f3eafd924 100644 --- a/tools/skillgen/expected/graphify__skills__windows__references__query.md +++ b/tools/skillgen/expected/graphify__skills__windows__references__query.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/fragments/references/query/default.md b/tools/skillgen/fragments/references/query/default.md index 56565eb78..f3eafd924 100644 --- a/tools/skillgen/fragments/references/query/default.md +++ b/tools/skillgen/fragments/references/query/default.md @@ -165,15 +165,22 @@ print(output) Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains. -After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node: +After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the answer text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node. + +The question and answer are free text you do not control the content of - a +quote, backtick, or `$()` embedded in either one corrupts or escapes a +command it's substituted into. Using your file-write tool, write the +user's verbatim question to one file and your full answer text (containing +the expanded-token trace) to another, then pass only those files' paths - +not their content - on the command line: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2 +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 ``` -Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting): +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -243,10 +250,13 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B ``` --- @@ -304,8 +314,11 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back: +After writing the explanation, save it back. The explanation is free text +you do not control the content of - write it to a file with your file-write +tool and pass only that file's path, the same way as for `/graphify query` +above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/fragments/references/shared/add-watch.md b/tools/skillgen/fragments/references/shared/add-watch.md index 77844343e..baa5f3f0b 100644 --- a/tools/skillgen/fragments/references/shared/add-watch.md +++ b/tools/skillgen/fragments/references/shared/add-watch.md @@ -6,25 +6,28 @@ Load this when the user ran `/graphify add ` or passed `--watch`. Neither i Fetch a URL and add it to the corpus, then update the graph. +The URL and any author/contributor name are free text you do not control the +content of - do not build a command or inline script by substituting them +into a string; an embedded quote or shell character corrupts or escapes it. +Using your file-write tool (not a shell heredoc, which has the same quoting +problem one level down), write a JSON file with those values, then pass only +that file's path - not its content - to `graphify add`: + +```json +{"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} +``` + +Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by +the actual URL, `AUTHOR` by the user's name if provided (omit the key +entirely if not), `CONTRIBUTOR` likewise, then run: + ```bash -$(cat graphify-out/.graphify_python) -c " -import sys -from graphify.ingest import ingest -from pathlib import Path - -try: - out = ingest('URL', Path('./raw'), author='AUTHOR', contributor='CONTRIBUTOR') - print(f'Saved to {out}') -except ValueError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -except RuntimeError as e: - print(f'error: {e}', file=sys.stderr) - sys.exit(1) -" +$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json ``` -Replace `URL` with the actual URL, `AUTHOR` with the user's name if provided, `CONTRIBUTOR` likewise. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. +If the command exits with an error, tell the user what went wrong - do not +silently continue. After a successful save, automatically run the `--update` +pipeline on `./raw` to merge the new file into the existing graph. Supported URL types (auto-detected): - YouTube / any video URL → audio downloaded via yt-dlp, transcribed to `.txt` on next run (requires `pip install 'graphifyy[video]'`) From ed97a98f2b1190375d19229ba31309c4ded3473e Mon Sep 17 00:00:00 2001 From: ayushcodes10 Date: Wed, 9 Sep 2026 23:34:17 +0530 Subject: [PATCH 3/6] Give add from file clean errors instead of raw exceptions A missing operand for the from file flag fell through to the positional url branch and treated the flag's own name as the url, a confusing blocked scheme error instead of pointing at the actual mistake. A payload missing the required url key raised a raw, unhandled KeyError instead of the same clean error message every other failure in this command already produces. Both now exit with a clear, single line error, matching malformed JSON and a missing file, which already went through the same path. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_017qfdzgbA5KedGEjD1AayNh --- graphify/cli.py | 21 ++++++++++++++++---- tests/test_ingest.py | 47 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+), 4 deletions(-) diff --git a/graphify/cli.py b/graphify/cli.py index a239a66aa..b38b8af88 100644 --- a/graphify/cli.py +++ b/graphify/cli.py @@ -1970,13 +1970,26 @@ def dispatch_command(cmd: str) -> None: # argument. args = sys.argv[2:] from_file = None + from_file_requested = False for i, a in enumerate(args): - if a == "--from-file" and i + 1 < len(args): - from_file = args[i + 1] + if a == "--from-file": + from_file_requested = True + if i + 1 < len(args): + from_file = args[i + 1] break + if from_file_requested and not from_file: + print("error: --from-file requires a path argument", file=sys.stderr) + sys.exit(1) if from_file: - payload = json.loads(Path(from_file).read_text(encoding="utf-8")) - url = payload["url"] + try: + payload = json.loads(Path(from_file).read_text(encoding="utf-8")) + url = payload["url"] + except (OSError, json.JSONDecodeError) as exc: + print(f"error: could not read --from-file payload: {exc}", file=sys.stderr) + sys.exit(1) + except KeyError: + print("error: --from-file payload is missing required key 'url'", file=sys.stderr) + sys.exit(1) author = payload.get("author") contributor = payload.get("contributor") target_dir = Path(payload.get("dir") or "raw") diff --git a/tests/test_ingest.py b/tests/test_ingest.py index ea940f084..aad25b297 100644 --- a/tests/test_ingest.py +++ b/tests/test_ingest.py @@ -182,3 +182,50 @@ def fake_ingest(url, target_dir, author=None, contributor=None): assert captured["url"] == "https://example.com/x" assert captured["author"] == "Jane" assert captured["contributor"] == "Jo" + + +def test_cli_add_from_file_without_a_path_is_a_clean_error(capsys, monkeypatch): + """`--from-file` with no path operand used to fall through to the + positional-url branch and treat the literal string "--from-file" itself + as the URL (a confusing "Blocked URL scheme" error instead of pointing + at the actual mistake).""" + import sys + from graphify.cli import dispatch_command + + monkeypatch.setattr(sys, "argv", ["graphify", "add", "--from-file"]) + with pytest.raises(SystemExit) as exc_info: + dispatch_command("add") + assert exc_info.value.code != 0 + assert "--from-file" in capsys.readouterr().err + + +def test_cli_add_from_file_missing_url_key_is_a_clean_error(tmp_path, capsys, monkeypatch): + """A payload missing the required "url" key used to raise a raw, + unhandled KeyError instead of the same clean "error: ..." message + every other failure in this command produces.""" + import json + import sys + from graphify.cli import dispatch_command + + payload = tmp_path / "payload.json" + payload.write_text(json.dumps({"author": "Jane"}), encoding="utf-8") + monkeypatch.setattr(sys, "argv", ["graphify", "add", "--from-file", str(payload)]) + with pytest.raises(SystemExit) as exc_info: + dispatch_command("add") + assert exc_info.value.code != 0 + assert "url" in capsys.readouterr().err + + +def test_cli_add_from_file_malformed_json_is_a_clean_error(tmp_path, capsys, monkeypatch): + """Malformed JSON or a missing file must also produce a clean error, + not a raw traceback.""" + import sys + from graphify.cli import dispatch_command + + payload = tmp_path / "payload.json" + payload.write_text("not json", encoding="utf-8") + monkeypatch.setattr(sys, "argv", ["graphify", "add", "--from-file", str(payload)]) + with pytest.raises(SystemExit) as exc_info: + dispatch_command("add") + assert exc_info.value.code != 0 + assert "error:" in capsys.readouterr().err From cea499253ae24fa582436d2e417591d6750caafd Mon Sep 17 00:00:00 2001 From: ayushcodes10 Date: Wed, 9 Sep 2026 23:34:32 +0530 Subject: [PATCH 4/6] Reserve unique paths for the free text handoff files The prior fix wrote question/answer/payload content to a fixed, shared temp filename. Two concurrent graphify sessions, two agents or two terminal tabs on the same machine, following the same instructions at once would race on that one path: one session's write could overwrite or be read as another session's value. Each instruction now runs mktemp first to reserve a path unique to that run before writing anything, closing the race the same file based handoff was meant to avoid in the first place. Regenerated all fourteen platform skill variants and their expected fixtures. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_017qfdzgbA5KedGEjD1AayNh --- .../skills/agents/references/add-watch.md | 23 ++++++---- graphify/skills/agents/references/query.md | 43 ++++++++++++------- graphify/skills/amp/references/add-watch.md | 23 ++++++---- graphify/skills/amp/references/query.md | 43 ++++++++++++------- .../skills/claude/references/add-watch.md | 23 ++++++---- graphify/skills/claude/references/query.md | 43 ++++++++++++------- graphify/skills/claw/references/add-watch.md | 23 ++++++---- graphify/skills/claw/references/query.md | 43 ++++++++++++------- graphify/skills/codex/references/add-watch.md | 23 ++++++---- graphify/skills/codex/references/query.md | 43 ++++++++++++------- .../skills/copilot/references/add-watch.md | 23 ++++++---- graphify/skills/copilot/references/query.md | 43 ++++++++++++------- graphify/skills/droid/references/add-watch.md | 23 ++++++---- graphify/skills/droid/references/query.md | 43 ++++++++++++------- graphify/skills/kilo/references/add-watch.md | 23 ++++++---- graphify/skills/kilo/references/query.md | 43 ++++++++++++------- graphify/skills/kiro/references/add-watch.md | 23 ++++++---- graphify/skills/kiro/references/query.md | 43 ++++++++++++------- .../skills/opencode/references/add-watch.md | 23 ++++++---- graphify/skills/opencode/references/query.md | 43 ++++++++++++------- graphify/skills/pi/references/add-watch.md | 23 ++++++---- graphify/skills/pi/references/query.md | 43 ++++++++++++------- graphify/skills/trae/references/add-watch.md | 23 ++++++---- graphify/skills/trae/references/query.md | 43 ++++++++++++------- .../skills/vscode/references/add-watch.md | 23 ++++++---- graphify/skills/vscode/references/query.md | 43 ++++++++++++------- .../skills/windows/references/add-watch.md | 23 ++++++---- graphify/skills/windows/references/query.md | 43 ++++++++++++------- ...__skills__agents__references__add-watch.md | 23 ++++++---- ...hify__skills__agents__references__query.md | 43 ++++++++++++------- ...ify__skills__amp__references__add-watch.md | 23 ++++++---- ...raphify__skills__amp__references__query.md | 43 ++++++++++++------- ...__skills__claude__references__add-watch.md | 23 ++++++---- ...hify__skills__claude__references__query.md | 43 ++++++++++++------- ...fy__skills__claw__references__add-watch.md | 23 ++++++---- ...aphify__skills__claw__references__query.md | 43 ++++++++++++------- ...y__skills__codex__references__add-watch.md | 23 ++++++---- ...phify__skills__codex__references__query.md | 43 ++++++++++++------- ..._skills__copilot__references__add-watch.md | 23 ++++++---- ...ify__skills__copilot__references__query.md | 43 ++++++++++++------- ...y__skills__droid__references__add-watch.md | 23 ++++++---- ...phify__skills__droid__references__query.md | 43 ++++++++++++------- ...fy__skills__kilo__references__add-watch.md | 23 ++++++---- ...aphify__skills__kilo__references__query.md | 43 ++++++++++++------- ...fy__skills__kiro__references__add-watch.md | 23 ++++++---- ...aphify__skills__kiro__references__query.md | 43 ++++++++++++------- ...skills__opencode__references__add-watch.md | 23 ++++++---- ...fy__skills__opencode__references__query.md | 43 ++++++++++++------- ...hify__skills__pi__references__add-watch.md | 23 ++++++---- ...graphify__skills__pi__references__query.md | 43 ++++++++++++------- ...fy__skills__trae__references__add-watch.md | 23 ++++++---- ...aphify__skills__trae__references__query.md | 43 ++++++++++++------- ...__skills__vscode__references__add-watch.md | 23 ++++++---- ...hify__skills__vscode__references__query.md | 43 ++++++++++++------- ..._skills__windows__references__add-watch.md | 23 ++++++---- ...ify__skills__windows__references__query.md | 43 ++++++++++++------- .../fragments/references/query/default.md | 43 ++++++++++++------- .../fragments/references/shared/add-watch.md | 23 ++++++---- 58 files changed, 1247 insertions(+), 667 deletions(-) diff --git a/graphify/skills/agents/references/add-watch.md b/graphify/skills/agents/references/add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/graphify/skills/agents/references/add-watch.md +++ b/graphify/skills/agents/references/add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/graphify/skills/agents/references/query.md b/graphify/skills/agents/references/query.md index f3eafd924..8386ebd11 100644 --- a/graphify/skills/agents/references/query.md +++ b/graphify/skills/agents/references/query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/amp/references/add-watch.md b/graphify/skills/amp/references/add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/graphify/skills/amp/references/add-watch.md +++ b/graphify/skills/amp/references/add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/graphify/skills/amp/references/query.md b/graphify/skills/amp/references/query.md index f3eafd924..8386ebd11 100644 --- a/graphify/skills/amp/references/query.md +++ b/graphify/skills/amp/references/query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/claude/references/add-watch.md b/graphify/skills/claude/references/add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/graphify/skills/claude/references/add-watch.md +++ b/graphify/skills/claude/references/add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/graphify/skills/claude/references/query.md b/graphify/skills/claude/references/query.md index f3eafd924..8386ebd11 100644 --- a/graphify/skills/claude/references/query.md +++ b/graphify/skills/claude/references/query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/claw/references/add-watch.md b/graphify/skills/claw/references/add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/graphify/skills/claw/references/add-watch.md +++ b/graphify/skills/claw/references/add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/graphify/skills/claw/references/query.md b/graphify/skills/claw/references/query.md index f3eafd924..8386ebd11 100644 --- a/graphify/skills/claw/references/query.md +++ b/graphify/skills/claw/references/query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/codex/references/add-watch.md b/graphify/skills/codex/references/add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/graphify/skills/codex/references/add-watch.md +++ b/graphify/skills/codex/references/add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/graphify/skills/codex/references/query.md b/graphify/skills/codex/references/query.md index f3eafd924..8386ebd11 100644 --- a/graphify/skills/codex/references/query.md +++ b/graphify/skills/codex/references/query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/copilot/references/add-watch.md b/graphify/skills/copilot/references/add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/graphify/skills/copilot/references/add-watch.md +++ b/graphify/skills/copilot/references/add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/graphify/skills/copilot/references/query.md b/graphify/skills/copilot/references/query.md index f3eafd924..8386ebd11 100644 --- a/graphify/skills/copilot/references/query.md +++ b/graphify/skills/copilot/references/query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/droid/references/add-watch.md b/graphify/skills/droid/references/add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/graphify/skills/droid/references/add-watch.md +++ b/graphify/skills/droid/references/add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/graphify/skills/droid/references/query.md b/graphify/skills/droid/references/query.md index f3eafd924..8386ebd11 100644 --- a/graphify/skills/droid/references/query.md +++ b/graphify/skills/droid/references/query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/kilo/references/add-watch.md b/graphify/skills/kilo/references/add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/graphify/skills/kilo/references/add-watch.md +++ b/graphify/skills/kilo/references/add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/graphify/skills/kilo/references/query.md b/graphify/skills/kilo/references/query.md index f3eafd924..8386ebd11 100644 --- a/graphify/skills/kilo/references/query.md +++ b/graphify/skills/kilo/references/query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/kiro/references/add-watch.md b/graphify/skills/kiro/references/add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/graphify/skills/kiro/references/add-watch.md +++ b/graphify/skills/kiro/references/add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/graphify/skills/kiro/references/query.md b/graphify/skills/kiro/references/query.md index f3eafd924..8386ebd11 100644 --- a/graphify/skills/kiro/references/query.md +++ b/graphify/skills/kiro/references/query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/opencode/references/add-watch.md b/graphify/skills/opencode/references/add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/graphify/skills/opencode/references/add-watch.md +++ b/graphify/skills/opencode/references/add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/graphify/skills/opencode/references/query.md b/graphify/skills/opencode/references/query.md index f3eafd924..8386ebd11 100644 --- a/graphify/skills/opencode/references/query.md +++ b/graphify/skills/opencode/references/query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/pi/references/add-watch.md b/graphify/skills/pi/references/add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/graphify/skills/pi/references/add-watch.md +++ b/graphify/skills/pi/references/add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/graphify/skills/pi/references/query.md b/graphify/skills/pi/references/query.md index f3eafd924..8386ebd11 100644 --- a/graphify/skills/pi/references/query.md +++ b/graphify/skills/pi/references/query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/trae/references/add-watch.md b/graphify/skills/trae/references/add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/graphify/skills/trae/references/add-watch.md +++ b/graphify/skills/trae/references/add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/graphify/skills/trae/references/query.md b/graphify/skills/trae/references/query.md index f3eafd924..8386ebd11 100644 --- a/graphify/skills/trae/references/query.md +++ b/graphify/skills/trae/references/query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/vscode/references/add-watch.md b/graphify/skills/vscode/references/add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/graphify/skills/vscode/references/add-watch.md +++ b/graphify/skills/vscode/references/add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/graphify/skills/vscode/references/query.md b/graphify/skills/vscode/references/query.md index f3eafd924..8386ebd11 100644 --- a/graphify/skills/vscode/references/query.md +++ b/graphify/skills/vscode/references/query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/windows/references/add-watch.md b/graphify/skills/windows/references/add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/graphify/skills/windows/references/add-watch.md +++ b/graphify/skills/windows/references/add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/graphify/skills/windows/references/query.md b/graphify/skills/windows/references/query.md index f3eafd924..8386ebd11 100644 --- a/graphify/skills/windows/references/query.md +++ b/graphify/skills/windows/references/query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__agents__references__add-watch.md b/tools/skillgen/expected/graphify__skills__agents__references__add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/tools/skillgen/expected/graphify__skills__agents__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__agents__references__add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/tools/skillgen/expected/graphify__skills__agents__references__query.md b/tools/skillgen/expected/graphify__skills__agents__references__query.md index f3eafd924..8386ebd11 100644 --- a/tools/skillgen/expected/graphify__skills__agents__references__query.md +++ b/tools/skillgen/expected/graphify__skills__agents__references__query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__amp__references__add-watch.md b/tools/skillgen/expected/graphify__skills__amp__references__add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/tools/skillgen/expected/graphify__skills__amp__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__amp__references__add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/tools/skillgen/expected/graphify__skills__amp__references__query.md b/tools/skillgen/expected/graphify__skills__amp__references__query.md index f3eafd924..8386ebd11 100644 --- a/tools/skillgen/expected/graphify__skills__amp__references__query.md +++ b/tools/skillgen/expected/graphify__skills__amp__references__query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__claude__references__add-watch.md b/tools/skillgen/expected/graphify__skills__claude__references__add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/tools/skillgen/expected/graphify__skills__claude__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__claude__references__add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/tools/skillgen/expected/graphify__skills__claude__references__query.md b/tools/skillgen/expected/graphify__skills__claude__references__query.md index f3eafd924..8386ebd11 100644 --- a/tools/skillgen/expected/graphify__skills__claude__references__query.md +++ b/tools/skillgen/expected/graphify__skills__claude__references__query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__claw__references__add-watch.md b/tools/skillgen/expected/graphify__skills__claw__references__add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/tools/skillgen/expected/graphify__skills__claw__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__claw__references__add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/tools/skillgen/expected/graphify__skills__claw__references__query.md b/tools/skillgen/expected/graphify__skills__claw__references__query.md index f3eafd924..8386ebd11 100644 --- a/tools/skillgen/expected/graphify__skills__claw__references__query.md +++ b/tools/skillgen/expected/graphify__skills__claw__references__query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__codex__references__add-watch.md b/tools/skillgen/expected/graphify__skills__codex__references__add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/tools/skillgen/expected/graphify__skills__codex__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__codex__references__add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/tools/skillgen/expected/graphify__skills__codex__references__query.md b/tools/skillgen/expected/graphify__skills__codex__references__query.md index f3eafd924..8386ebd11 100644 --- a/tools/skillgen/expected/graphify__skills__codex__references__query.md +++ b/tools/skillgen/expected/graphify__skills__codex__references__query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__copilot__references__add-watch.md b/tools/skillgen/expected/graphify__skills__copilot__references__add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/tools/skillgen/expected/graphify__skills__copilot__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__copilot__references__add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/tools/skillgen/expected/graphify__skills__copilot__references__query.md b/tools/skillgen/expected/graphify__skills__copilot__references__query.md index f3eafd924..8386ebd11 100644 --- a/tools/skillgen/expected/graphify__skills__copilot__references__query.md +++ b/tools/skillgen/expected/graphify__skills__copilot__references__query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__droid__references__add-watch.md b/tools/skillgen/expected/graphify__skills__droid__references__add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/tools/skillgen/expected/graphify__skills__droid__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__droid__references__add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/tools/skillgen/expected/graphify__skills__droid__references__query.md b/tools/skillgen/expected/graphify__skills__droid__references__query.md index f3eafd924..8386ebd11 100644 --- a/tools/skillgen/expected/graphify__skills__droid__references__query.md +++ b/tools/skillgen/expected/graphify__skills__droid__references__query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__kilo__references__add-watch.md b/tools/skillgen/expected/graphify__skills__kilo__references__add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/tools/skillgen/expected/graphify__skills__kilo__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__kilo__references__add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/tools/skillgen/expected/graphify__skills__kilo__references__query.md b/tools/skillgen/expected/graphify__skills__kilo__references__query.md index f3eafd924..8386ebd11 100644 --- a/tools/skillgen/expected/graphify__skills__kilo__references__query.md +++ b/tools/skillgen/expected/graphify__skills__kilo__references__query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__kiro__references__add-watch.md b/tools/skillgen/expected/graphify__skills__kiro__references__add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/tools/skillgen/expected/graphify__skills__kiro__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__kiro__references__add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/tools/skillgen/expected/graphify__skills__kiro__references__query.md b/tools/skillgen/expected/graphify__skills__kiro__references__query.md index f3eafd924..8386ebd11 100644 --- a/tools/skillgen/expected/graphify__skills__kiro__references__query.md +++ b/tools/skillgen/expected/graphify__skills__kiro__references__query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__opencode__references__add-watch.md b/tools/skillgen/expected/graphify__skills__opencode__references__add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/tools/skillgen/expected/graphify__skills__opencode__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__opencode__references__add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/tools/skillgen/expected/graphify__skills__opencode__references__query.md b/tools/skillgen/expected/graphify__skills__opencode__references__query.md index f3eafd924..8386ebd11 100644 --- a/tools/skillgen/expected/graphify__skills__opencode__references__query.md +++ b/tools/skillgen/expected/graphify__skills__opencode__references__query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__pi__references__add-watch.md b/tools/skillgen/expected/graphify__skills__pi__references__add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/tools/skillgen/expected/graphify__skills__pi__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__pi__references__add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/tools/skillgen/expected/graphify__skills__pi__references__query.md b/tools/skillgen/expected/graphify__skills__pi__references__query.md index f3eafd924..8386ebd11 100644 --- a/tools/skillgen/expected/graphify__skills__pi__references__query.md +++ b/tools/skillgen/expected/graphify__skills__pi__references__query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__trae__references__add-watch.md b/tools/skillgen/expected/graphify__skills__trae__references__add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/tools/skillgen/expected/graphify__skills__trae__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__trae__references__add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/tools/skillgen/expected/graphify__skills__trae__references__query.md b/tools/skillgen/expected/graphify__skills__trae__references__query.md index f3eafd924..8386ebd11 100644 --- a/tools/skillgen/expected/graphify__skills__trae__references__query.md +++ b/tools/skillgen/expected/graphify__skills__trae__references__query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__vscode__references__add-watch.md b/tools/skillgen/expected/graphify__skills__vscode__references__add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/tools/skillgen/expected/graphify__skills__vscode__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__vscode__references__add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/tools/skillgen/expected/graphify__skills__vscode__references__query.md b/tools/skillgen/expected/graphify__skills__vscode__references__query.md index f3eafd924..8386ebd11 100644 --- a/tools/skillgen/expected/graphify__skills__vscode__references__query.md +++ b/tools/skillgen/expected/graphify__skills__vscode__references__query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__windows__references__add-watch.md b/tools/skillgen/expected/graphify__skills__windows__references__add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/tools/skillgen/expected/graphify__skills__windows__references__add-watch.md +++ b/tools/skillgen/expected/graphify__skills__windows__references__add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. diff --git a/tools/skillgen/expected/graphify__skills__windows__references__query.md b/tools/skillgen/expected/graphify__skills__windows__references__query.md index f3eafd924..8386ebd11 100644 --- a/tools/skillgen/expected/graphify__skills__windows__references__query.md +++ b/tools/skillgen/expected/graphify__skills__windows__references__query.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/fragments/references/query/default.md b/tools/skillgen/fragments/references/query/default.md index f3eafd924..8386ebd11 100644 --- a/tools/skillgen/fragments/references/query/default.md +++ b/tools/skillgen/fragments/references/query/default.md @@ -169,18 +169,27 @@ After writing the answer, save it back into the graph so it improves future quer The question and answer are free text you do not control the content of - a quote, backtick, or `$()` embedded in either one corrupts or escapes a -command it's substituted into. Using your file-write tool, write the -user's verbatim question to one file and your full answer text (containing -the expanded-token trace) to another, then pass only those files' paths - -not their content - on the command line: +command it's substituted into. Reserve two unique file paths first - a +fixed, shared filename risks a concurrent graphify session overwriting or +reading a stale value: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question-file /tmp/graphify_question.txt --answer-file /tmp/graphify_answer.txt --type query --nodes NODE1 NODE2 +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX ``` -Replace `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. +Using your file-write tool, write the user's verbatim question to the path +the first command printed and your full answer text (containing the +expanded-token trace) to the path the second one printed, then pass those +exact paths - not their content - on the command line: -**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, write what was right to a file and pass `--correction-file ` the same way): +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type query --nodes NODE1 NODE2 +``` + +Replace `QUESTION_PATH`/`ANSWER_PATH` with the paths `mktemp` printed and `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph. + +**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and, when correcting, reserve one more unique path with `mktemp`, write what was right to it, and pass `--correction-file CORRECTION_PATH` the same way): - `useful` — the cited nodes answered the question well (they become *preferred sources*). - `dead_end` — the question/path led nowhere; don't re-derive it next time. @@ -251,12 +260,14 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file /tmp/graphify_answer.txt --type path_query --nodes NODE_A NODE_B +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -315,10 +326,12 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. After writing the explanation, save it back. The explanation is free text -you do not control the content of - write it to a file with your file-write -tool and pass only that file's path, the same way as for `/graphify query` -above: +you do not control the content of - reserve a unique file path with +`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale value), write +it there with your file-write tool, then pass only that path, the same way +as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file /tmp/graphify_answer.txt --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/fragments/references/shared/add-watch.md b/tools/skillgen/fragments/references/shared/add-watch.md index baa5f3f0b..8eb3d19d9 100644 --- a/tools/skillgen/fragments/references/shared/add-watch.md +++ b/tools/skillgen/fragments/references/shared/add-watch.md @@ -9,23 +9,30 @@ Fetch a URL and add it to the corpus, then update the graph. The URL and any author/contributor name are free text you do not control the content of - do not build a command or inline script by substituting them into a string; an embedded quote or shell character corrupts or escapes it. -Using your file-write tool (not a shell heredoc, which has the same quoting -problem one level down), write a JSON file with those values, then pass only -that file's path - not its content - to `graphify add`: +Reserve a unique file path first - a fixed, shared filename risks a +concurrent graphify session overwriting or reading a stale payload: + +```bash +mktemp /tmp/graphify_add_payload.XXXXXX.json +``` + +Using your file-write tool (not a shell heredoc, which has the same +quoting problem one level down), write a JSON file with those values to +the path that command printed, then pass only that path - not its content +- to `graphify add`: ```json {"url": "URL", "author": "AUTHOR", "contributor": "CONTRIBUTOR", "dir": "./raw"} ``` -Save that as e.g. `/tmp/graphify_add_payload.json`, with `URL` replaced by -the actual URL, `AUTHOR` by the user's name if provided (omit the key -entirely if not), `CONTRIBUTOR` likewise, then run: +Replace `URL` with the actual URL, `AUTHOR` with the user's name if +provided (omit the key entirely if not), `CONTRIBUTOR` likewise, then run: ```bash -$(cat graphify-out/.graphify_python) -m graphify add --from-file /tmp/graphify_add_payload.json +$(cat graphify-out/.graphify_python) -m graphify add --from-file PAYLOAD_PATH ``` -If the command exits with an error, tell the user what went wrong - do not +Replace `PAYLOAD_PATH` with the path `mktemp` printed. If the command exits with an error, tell the user what went wrong - do not silently continue. After a successful save, automatically run the `--update` pipeline on `./raw` to merge the new file into the existing graph. From b768868bd8c10bf7c87db6216bc268ab3610338f Mon Sep 17 00:00:00 2001 From: ayushcodes10 Date: Fri, 11 Sep 2026 14:39:40 +0530 Subject: [PATCH 5/6] Reject a non object from file payload cleanly A payload that parsed as valid JSON but was not an object, a list, a bare string, a number, raised a raw TypeError from subscripting it with url, since json.JSONDecodeError alone only catches a syntax error, not a value of the wrong shape. Checks the parsed value is a dict before looking up url and names the actual type it got in the error. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_017qfdzgbA5KedGEjD1AayNh --- graphify/cli.py | 10 +++++++++- tests/test_ingest.py | 18 ++++++++++++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/graphify/cli.py b/graphify/cli.py index b38b8af88..cc7c7c755 100644 --- a/graphify/cli.py +++ b/graphify/cli.py @@ -1983,10 +1983,18 @@ def dispatch_command(cmd: str) -> None: if from_file: try: payload = json.loads(Path(from_file).read_text(encoding="utf-8")) - url = payload["url"] except (OSError, json.JSONDecodeError) as exc: print(f"error: could not read --from-file payload: {exc}", file=sys.stderr) sys.exit(1) + if not isinstance(payload, dict): + print( + "error: --from-file payload must be a JSON object with a " + "'url' key, not " + type(payload).__name__, + file=sys.stderr, + ) + sys.exit(1) + try: + url = payload["url"] except KeyError: print("error: --from-file payload is missing required key 'url'", file=sys.stderr) sys.exit(1) diff --git a/tests/test_ingest.py b/tests/test_ingest.py index aad25b297..8f2467e98 100644 --- a/tests/test_ingest.py +++ b/tests/test_ingest.py @@ -229,3 +229,21 @@ def test_cli_add_from_file_malformed_json_is_a_clean_error(tmp_path, capsys, mon dispatch_command("add") assert exc_info.value.code != 0 assert "error:" in capsys.readouterr().err + + +@pytest.mark.parametrize("body", ["[1, 2, 3]", '"just a string"', "42"]) +def test_cli_add_from_file_non_object_json_is_a_clean_error(body, tmp_path, capsys, monkeypatch): + """A payload that is syntactically valid JSON but not an object (a + list, a bare string, a number) used to raise a raw, unhandled + TypeError from subscripting it with "url" -- json.JSONDecodeError + alone does not cover this, since the JSON itself parses fine.""" + import sys + from graphify.cli import dispatch_command + + payload = tmp_path / "payload.json" + payload.write_text(body, encoding="utf-8") + monkeypatch.setattr(sys, "argv", ["graphify", "add", "--from-file", str(payload)]) + with pytest.raises(SystemExit) as exc_info: + dispatch_command("add") + assert exc_info.value.code != 0 + assert "error:" in capsys.readouterr().err From d66f2b2dbc7f5d3a7eb459c465b6a9dbc76500f6 Mon Sep 17 00:00:00 2001 From: ayushcodes10 Date: Fri, 11 Sep 2026 14:39:49 +0530 Subject: [PATCH 6/6] Treat a node label the same as free text answer content The path and explain save commands still built their question argument from a template with a node label spliced in inline. A node label is not guaranteed free of shell characters either, since it can come from extracted document content, not just a source identifier. Both now write the question to a reserved unique file the same way the answer already does, closing the gap between two fields in the same command that were treated inconsistently. Regenerated the affected platform skill variants and their expected fixtures. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_017qfdzgbA5KedGEjD1AayNh --- graphify/skills/agents/references/query.md | 45 +++++++++++++------ graphify/skills/amp/references/query.md | 45 +++++++++++++------ graphify/skills/claude/references/query.md | 45 +++++++++++++------ graphify/skills/claw/references/query.md | 45 +++++++++++++------ graphify/skills/codex/references/query.md | 45 +++++++++++++------ graphify/skills/copilot/references/query.md | 45 +++++++++++++------ graphify/skills/droid/references/query.md | 45 +++++++++++++------ graphify/skills/kilo/references/query.md | 45 +++++++++++++------ graphify/skills/kiro/references/query.md | 45 +++++++++++++------ graphify/skills/opencode/references/query.md | 45 +++++++++++++------ graphify/skills/pi/references/query.md | 45 +++++++++++++------ graphify/skills/trae/references/query.md | 45 +++++++++++++------ graphify/skills/vscode/references/query.md | 45 +++++++++++++------ graphify/skills/windows/references/query.md | 45 +++++++++++++------ ...hify__skills__agents__references__query.md | 45 +++++++++++++------ ...raphify__skills__amp__references__query.md | 45 +++++++++++++------ ...hify__skills__claude__references__query.md | 45 +++++++++++++------ ...aphify__skills__claw__references__query.md | 45 +++++++++++++------ ...phify__skills__codex__references__query.md | 45 +++++++++++++------ ...ify__skills__copilot__references__query.md | 45 +++++++++++++------ ...phify__skills__droid__references__query.md | 45 +++++++++++++------ ...aphify__skills__kilo__references__query.md | 45 +++++++++++++------ ...aphify__skills__kiro__references__query.md | 45 +++++++++++++------ ...fy__skills__opencode__references__query.md | 45 +++++++++++++------ ...graphify__skills__pi__references__query.md | 45 +++++++++++++------ ...aphify__skills__trae__references__query.md | 45 +++++++++++++------ ...hify__skills__vscode__references__query.md | 45 +++++++++++++------ ...ify__skills__windows__references__query.md | 45 +++++++++++++------ .../fragments/references/query/default.md | 45 +++++++++++++------ 29 files changed, 899 insertions(+), 406 deletions(-) diff --git a/graphify/skills/agents/references/query.md b/graphify/skills/agents/references/query.md index 8386ebd11..f859ddc37 100644 --- a/graphify/skills/agents/references/query.md +++ b/graphify/skills/agents/references/query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/amp/references/query.md b/graphify/skills/amp/references/query.md index 8386ebd11..f859ddc37 100644 --- a/graphify/skills/amp/references/query.md +++ b/graphify/skills/amp/references/query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/claude/references/query.md b/graphify/skills/claude/references/query.md index 8386ebd11..f859ddc37 100644 --- a/graphify/skills/claude/references/query.md +++ b/graphify/skills/claude/references/query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/claw/references/query.md b/graphify/skills/claw/references/query.md index 8386ebd11..f859ddc37 100644 --- a/graphify/skills/claw/references/query.md +++ b/graphify/skills/claw/references/query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/codex/references/query.md b/graphify/skills/codex/references/query.md index 8386ebd11..f859ddc37 100644 --- a/graphify/skills/codex/references/query.md +++ b/graphify/skills/codex/references/query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/copilot/references/query.md b/graphify/skills/copilot/references/query.md index 8386ebd11..f859ddc37 100644 --- a/graphify/skills/copilot/references/query.md +++ b/graphify/skills/copilot/references/query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/droid/references/query.md b/graphify/skills/droid/references/query.md index 8386ebd11..f859ddc37 100644 --- a/graphify/skills/droid/references/query.md +++ b/graphify/skills/droid/references/query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/kilo/references/query.md b/graphify/skills/kilo/references/query.md index 8386ebd11..f859ddc37 100644 --- a/graphify/skills/kilo/references/query.md +++ b/graphify/skills/kilo/references/query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/kiro/references/query.md b/graphify/skills/kiro/references/query.md index 8386ebd11..f859ddc37 100644 --- a/graphify/skills/kiro/references/query.md +++ b/graphify/skills/kiro/references/query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/opencode/references/query.md b/graphify/skills/opencode/references/query.md index 8386ebd11..f859ddc37 100644 --- a/graphify/skills/opencode/references/query.md +++ b/graphify/skills/opencode/references/query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/pi/references/query.md b/graphify/skills/pi/references/query.md index 8386ebd11..f859ddc37 100644 --- a/graphify/skills/pi/references/query.md +++ b/graphify/skills/pi/references/query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/trae/references/query.md b/graphify/skills/trae/references/query.md index 8386ebd11..f859ddc37 100644 --- a/graphify/skills/trae/references/query.md +++ b/graphify/skills/trae/references/query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/vscode/references/query.md b/graphify/skills/vscode/references/query.md index 8386ebd11..f859ddc37 100644 --- a/graphify/skills/vscode/references/query.md +++ b/graphify/skills/vscode/references/query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/graphify/skills/windows/references/query.md b/graphify/skills/windows/references/query.md index 8386ebd11..f859ddc37 100644 --- a/graphify/skills/windows/references/query.md +++ b/graphify/skills/windows/references/query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__agents__references__query.md b/tools/skillgen/expected/graphify__skills__agents__references__query.md index 8386ebd11..f859ddc37 100644 --- a/tools/skillgen/expected/graphify__skills__agents__references__query.md +++ b/tools/skillgen/expected/graphify__skills__agents__references__query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__amp__references__query.md b/tools/skillgen/expected/graphify__skills__amp__references__query.md index 8386ebd11..f859ddc37 100644 --- a/tools/skillgen/expected/graphify__skills__amp__references__query.md +++ b/tools/skillgen/expected/graphify__skills__amp__references__query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__claude__references__query.md b/tools/skillgen/expected/graphify__skills__claude__references__query.md index 8386ebd11..f859ddc37 100644 --- a/tools/skillgen/expected/graphify__skills__claude__references__query.md +++ b/tools/skillgen/expected/graphify__skills__claude__references__query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__claw__references__query.md b/tools/skillgen/expected/graphify__skills__claw__references__query.md index 8386ebd11..f859ddc37 100644 --- a/tools/skillgen/expected/graphify__skills__claw__references__query.md +++ b/tools/skillgen/expected/graphify__skills__claw__references__query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__codex__references__query.md b/tools/skillgen/expected/graphify__skills__codex__references__query.md index 8386ebd11..f859ddc37 100644 --- a/tools/skillgen/expected/graphify__skills__codex__references__query.md +++ b/tools/skillgen/expected/graphify__skills__codex__references__query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__copilot__references__query.md b/tools/skillgen/expected/graphify__skills__copilot__references__query.md index 8386ebd11..f859ddc37 100644 --- a/tools/skillgen/expected/graphify__skills__copilot__references__query.md +++ b/tools/skillgen/expected/graphify__skills__copilot__references__query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__droid__references__query.md b/tools/skillgen/expected/graphify__skills__droid__references__query.md index 8386ebd11..f859ddc37 100644 --- a/tools/skillgen/expected/graphify__skills__droid__references__query.md +++ b/tools/skillgen/expected/graphify__skills__droid__references__query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__kilo__references__query.md b/tools/skillgen/expected/graphify__skills__kilo__references__query.md index 8386ebd11..f859ddc37 100644 --- a/tools/skillgen/expected/graphify__skills__kilo__references__query.md +++ b/tools/skillgen/expected/graphify__skills__kilo__references__query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__kiro__references__query.md b/tools/skillgen/expected/graphify__skills__kiro__references__query.md index 8386ebd11..f859ddc37 100644 --- a/tools/skillgen/expected/graphify__skills__kiro__references__query.md +++ b/tools/skillgen/expected/graphify__skills__kiro__references__query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__opencode__references__query.md b/tools/skillgen/expected/graphify__skills__opencode__references__query.md index 8386ebd11..f859ddc37 100644 --- a/tools/skillgen/expected/graphify__skills__opencode__references__query.md +++ b/tools/skillgen/expected/graphify__skills__opencode__references__query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__pi__references__query.md b/tools/skillgen/expected/graphify__skills__pi__references__query.md index 8386ebd11..f859ddc37 100644 --- a/tools/skillgen/expected/graphify__skills__pi__references__query.md +++ b/tools/skillgen/expected/graphify__skills__pi__references__query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__trae__references__query.md b/tools/skillgen/expected/graphify__skills__trae__references__query.md index 8386ebd11..f859ddc37 100644 --- a/tools/skillgen/expected/graphify__skills__trae__references__query.md +++ b/tools/skillgen/expected/graphify__skills__trae__references__query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__vscode__references__query.md b/tools/skillgen/expected/graphify__skills__vscode__references__query.md index 8386ebd11..f859ddc37 100644 --- a/tools/skillgen/expected/graphify__skills__vscode__references__query.md +++ b/tools/skillgen/expected/graphify__skills__vscode__references__query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/expected/graphify__skills__windows__references__query.md b/tools/skillgen/expected/graphify__skills__windows__references__query.md index 8386ebd11..f859ddc37 100644 --- a/tools/skillgen/expected/graphify__skills__windows__references__query.md +++ b/tools/skillgen/expected/graphify__skills__windows__references__query.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ``` diff --git a/tools/skillgen/fragments/references/query/default.md b/tools/skillgen/fragments/references/query/default.md index 8386ebd11..f859ddc37 100644 --- a/tools/skillgen/fragments/references/query/default.md +++ b/tools/skillgen/fragments/references/query/default.md @@ -259,15 +259,24 @@ except nx.NodeNotFound as e: Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_A`/`NODE_B` are node +labels, which can come from extracted document content and so are not +guaranteed free of shell characters either - treat the question the same +as the explanation. Reserve two unique file paths first (a fixed, shared +filename risks a concurrent graphify session overwriting or reading a +stale value): ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Path from NODE_A to NODE_B` (with the +actual node names) to the first path and the explanation to the second, +then pass only those paths, the same way as for `/graphify query` above: + +```bash +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type path_query --nodes NODE_A NODE_B ``` --- @@ -325,13 +334,21 @@ for neighbor in G.neighbors(nid): Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations. -After writing the explanation, save it back. The explanation is free text -you do not control the content of - reserve a unique file path with -`mktemp /tmp/graphify_answer.XXXXXX` (a fixed, shared filename risks a -concurrent graphify session overwriting or reading a stale value), write -it there with your file-write tool, then pass only that path, the same way -as for `/graphify query` above: +After writing the explanation, save it back. `NODE_NAME` is a node label, +which can come from extracted document content and so is not guaranteed +free of shell characters either - treat the question the same as the +explanation. Reserve two unique file paths first (a fixed, shared filename +risks a concurrent graphify session overwriting or reading a stale value): + +```bash +mktemp /tmp/graphify_question.XXXXXX +mktemp /tmp/graphify_answer.XXXXXX +``` + +Using your file-write tool, write `Explain NODE_NAME` (with the actual +node name) to the first path and the explanation to the second, then pass +only those paths, the same way as for `/graphify query` above: ```bash -$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer-file ANSWER_PATH --type explain --nodes NODE_NAME +$(cat graphify-out/.graphify_python) -m graphify save-result --question-file QUESTION_PATH --answer-file ANSWER_PATH --type explain --nodes NODE_NAME ```