Mykg

mykg — single slash command, intent-driven CLI dispatcher

This skill is the agent-mode driver for mykg. The user types /mykg <free text> describing what they want; the skill parses the intent, assembles the matching mykg CLI command (with live --help as ground truth for flags), confirms expensive actions, and executes. For LLM-bearing subcommands (extract-graph), it then drives the inbox/outbox watch loop. For synchronous subcommands (walkthrough, approve-schema, parse-docs), it shells out and reports. For the read-only query verb, it prefers MCP tools when the mykg MCP server is online, falling back to reading session files directly when MCP is unavailable, with the mykg query CLI as a last-resort fallback.

The pipeline code, the orchestrator, all prompts, all 12 pipeline steps, and the inbox/outbox contract are unchanged. This skill only changes how mykg is invoked from inside Claude Code.

Read before answering — discipline rule

Before answering any domain question about the corpus this project's mykg sessions cover, read the latest session's graph files first. Your training data is not grounded in this project's source documents; the graph is. Use /mykg query <question> (Stage 4d below) to do this — it returns the relevant nodes/edges/notes into your context so you can answer from them rather than guessing.

This rule applies to every /mykg query … invocation and to every domain question asked outside the skill when the project's CLAUDE.md carries the managed mykg-section block (installed by mykg init --profile agent-claude-code).

Default behaviour — fresh session unless told otherwise

The default is to create a NEW session for every extract-graph invocation. Pass no --session flag to mykg extract-graph and let mykg auto-create a fresh timestamped session under mykg_sessions/.

Only reuse an existing session when the user explicitly signals it. Explicit signals are any of:

• The verbs resume, continue, redo, append, sync, reconcile, approve, walkthrough.
• A direct reference: "the last session", "the existing session", "the same session", or a literal session name (typed as --session <name> or "session ").
• A flag whose semantics require a session: --append, --sync, --update, --from-step <step>.
• A subcommand that inherently targets a completed session: approve-schema, walkthrough.

For anything else — including bare /mykg <dir>, /mykg extract <dir>, /mykg extract more from <dir>, "extract this folder" — pass NO --session flag. Words like "more", "again", "now", "next" are NOT explicit signals; they trigger a fresh session like every other plain extract command.

Never auto-detect-most-recent purely because a previous skill turn produced a session. The previous-turn signal only matters when the current user message also contains one of the explicit signals above.

When in doubt, default to fresh and surface the choice in the Stage 2 confirmation.

When to invoke — intent examples

Trigger this skill whenever the user types /mykg <anything>. Map the intent to a mykg CLI command using the table below as a guide; for anything not covered, fall back to the closest match and confirm before running.

Discovering CLI flags

The skill MUST NOT hand-code flag tables. The single source of truth is the live --help output. Once at the top of each skill turn, run the help commands for the subcommands you might dispatch and cache the output in shell variables for the rest of the turn:

EXTRACT_HELP=$(uv run mykg extract-graph --help 2>&1)
WALKTHROUGH_HELP=$(uv run mykg walkthrough --help 2>&1)
APPROVE_HELP=$(uv run mykg approve-schema --help 2>&1)
PARSE_HELP=$(uv run mykg parse-docs --help 2>&1)
FETCH_HELP=$(uv run mykg fetch-web --help 2>&1)

Use these cached values to:

• validate that any flag the user mentioned actually exists,
• complain if the user typed a non-existent flag,
• automatically pick up new flags (e.g. tomorrow a --use-cache flag is added) with zero skill changes.

MCP configuration — ensure .mcp.json exists

At the start of every skill turn, check whether the project has a .mcp.json file that configures the mykg MCP server for Claude Code. If it does not exist, ask the user for approval before creating it:

I noticed this project doesn't have a .mcp.json file to configure the mykg
MCP server for Claude Code. The MCP server provides 14 structured read-only
tools (search, neighbors, shortest path, hub nodes, subgraph queries, etc.)
that are faster and more precise than manual grep/Read for graph queries.

Shall I create .mcp.json with this content?

{
  "mcpServers": {
    "mykg": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/project",
        "run",
        "mykg",
        "mcp-serve"
      ]
    }
  }
}

This tells Claude Code to start `mykg mcp-serve` as an MCP subprocess,
making the `mcp__mykg__*` tools available in this session. The server
auto-discovers the latest session on startup.

If the user approves, write the file. If the user declines, proceed without it — the skill falls back to manual grep/Read in Stage 4d as before.

If .mcp.json already exists but does not contain a mykg server entry, ask the user whether to add one (preserve the existing entries). If it already has a mykg entry, do nothing.

Do not create .mcp.json without user approval. This file affects the Claude Code session and the user must consent.

Stage 1 — parse intent

From the user's /mykg <free text> message extract:

1. Verb — extract / append / approve / walkthrough / parse / fetch / download / resume / init / merge / query → maps to a CLI subcommand, a refusal, or the read-only file-read path (query). Fetch / download (URL or GitHub repo) maps to fetch-web — no session, same category as parse-docs.
2. Input dir — the path the user named, or . if they said "this folder", or absent for session-only commands (including query).
3. Session — default: do not pass --session at all so mykg auto-creates a fresh timestamped session. Only override the default when the current user message contains an explicit reuse signal (see "Default behaviour" above). Resolution order:
   1. Literal session name. User typed --session <name> or "session " → use that exact name.
   2. Explicit reuse verb / phrase. User said one of: resume, continue, redo, append, approve, walkthrough, query, "the last session", "the existing session", "the same session" → auto-detect the most-recent session: list $SESSIONS_DIR (read sessions_dir from mykg_config.yaml, default mykg_sessions), sort by mtime, pick newest.
   3. Reuse-implying flag. User specified --append or --from-step <step> → auto-detect-most-recent (these flags only make sense against an existing session).
   4. Session-only verb. Verb is approve-schema, walkthrough, or query → auto-detect-most-recent. (query is read-only and always operates against an existing session.)
   5. Otherwise. Do NOT pass --session. mykg creates a fresh session. This is the path for bare /mykg <dir>, /mykg extract <dir>, /mykg extract more from <dir>, "extract this folder", etc.
   6. Reuse required but missing. If rules 2/3/4 fire but no session exists under $SESSIONS_DIR, fail clearly: "No existing sessions under <SESSIONS_DIR>. Run /mykg extract <dir> first to create one."

Never auto-detect-most-recent purely because a previous skill turn produced a session. The previous-turn memory only matters when the current user message also contains one of the explicit signals in rules 1-4. A bare /mykg ./more_docs after a prior session must still create a fresh session. 4. Flags — anything the user named that maps to a flag the cached --help confirms (--review, --append, --sync, --update, --from-step <step>, --workers <N>, --obsidian-vault, --base-schema, --freeze-schema, --thesaurus, --verbose, --confidence-agg, --append-with-grow-schema, etc.). Forward verbatim.

extract-graph without --append or --from-step does not need a pre-existing session — it auto-creates one.

--sync — reconciling modifications and deletions (D58)

--append adds; --sync reconciles. Four supported combinations:

--update is shorthand for --append --sync — prefer it when the user's intent is "make the graph match the folder". --sync on its own requires --append (a ClickException otherwise). Detection always runs, so a plain --append that finds modified or deleted files logs a warning naming them and pointing at --sync — the graph is left untouched.

⚠️ Behaviour change: before D58, plain --append re-extracted modified files. It no longer does. If a user says their edits "aren't showing up", the answer is almost always --sync.

Intent triggers — use --update (or --append --sync) when the user says: "update", "sync", "reconcile", "remove deleted", "pick up my edits", "my changes aren't showing", "make the graph match the folder", "clean up files I deleted".

Nothing to reconcile is free. With no modifications and no deletions, --append --sync degrades to exactly plain --append — no prune, no shard eviction, no extra LLM calls. It is safe to leave in a script permanently.

Deletion accuracy depends on pass2.prep_mode. Exact under per_file or batch_chunks + batch_per_file: true. On the shipped default a co-batched sibling may retain over-attributed nodes (the pre-existing D53 limitation) — mention this if the user reports a node that "won't go away".

Multiple source folders. Each folder appended to a session is registered with its own mirror subtree, so two crawls that both produce index.md no longer overwrite each other. --sync is scoped to the folder named on the command line: reconciling one folder can never delete another's files.

--append-with-grow-schema — expanding the schema incrementally (D52)

Use case: you have an existing session with an induced schema (e.g. Project, Person, Organization) and you add new documents that introduce entity types or relationships the current schema doesn't cover (e.g. a tech-stack document that describes technologies). Plain --append freezes the schema — Pass 1 is skipped, so new concept types and properties are never induced, and the new documents are extracted against the old vocabulary. --append-with-grow-schema solves this: it implies --append and runs a locked Pass 1 over the changed files only, allowing the LLM to propose new concepts and properties while preserving everything already in the schema. Since D58 "changed files" means NEW files unless --sync is also passed — add --sync when the new vocabulary lives in a document the user edited rather than added.

How it works:

1. The session's existing schema.ttl is auto-loaded as a locked base schema — existing classes and properties cannot be renamed, removed, or re-parented.
2. Pass 1 runs over only the changed files (not the whole corpus), so cost is O(changed files).
3. The LLM may add new concepts, new properties, or new attributes to existing types. It cannot modify locked entries.
4. Pass 2 extracts the new files against the grown schema. If new properties were added, a surgical back-fill may re-extract old chunks that contain nodes of the new properties' domain/range types (configurable via append.grow_schema_backfill_top_k_chunks_per_type, default 10; set 0 to disable).
5. All downstream steps (assemble, orphan pass, validate) re-run over the full corpus so the graph stays consistent.

When the schema delta is empty (the new documents don't introduce new types), the run collapses to a plain --append — no wasted LLM cost. And when there is nothing to reconcile at all, the locked Pass 1 is skipped entirely (zero LLM calls) rather than dispatched over the whole corpus.

Intent triggers — use --append-with-grow-schema when the user says any of: "grow schema", "expand schema", "grow the schema", "expand the vocabulary", "add new types", "learn new concepts from", "update the schema with". The flag implies --append (no need to pass both). --append-with-grow-schema is mutually exclusive with --from-step and --base-schema.

Confirmation note: in Stage 2, mention that locked Pass 1 will run (costs LLM calls) vs plain --append which skips Pass 1:

About to run: uv run mykg extract-graph ./docs --append-with-grow-schema --session 2026-06-21T11-22-38

This will run a locked Pass 1 over the new files (LLM calls) to expand the schema,
then extract. Plain --append would skip Pass 1 and keep the schema frozen.

Reply "yes" to run, or "just append" to skip schema growth.

--freeze-schema — bring-your-own-schema extraction

Use case: you have a complete ontology (RDFS or OWL TTL) and want the LLM to extract instances against exactly those types — no LLM-invented concepts, no surprise properties. Pass 1 is skipped entirely, saving 3 LLM calls.

mykg extract-graph ./docs --base-schema ontology.ttl --freeze-schema

Rules:

• --freeze-schema requires --base-schema <path>. If the user says "freeze schema" without providing a TTL file, ask for it.
• Mutually exclusive with --append and --append-with-grow-schema.
• The output graph will only contain the concept types and relationship properties declared in the TTL — nothing else.

Intent triggers — use --freeze-schema when the user says any of: "freeze schema", "frozen schema", "use this schema exactly", "no LLM schema", "skip schema induction", "extract with my ontology only", "strict schema", "use only my types". Always pair with --base-schema.

fetch-web flags and special cases

fetch-web is a no-session verb, same category as parse-docs — Stage 1 item 3's session-resolution logic never fires for it. Forward --url-list, --output, --max-pages, --max-depth, --strategy, --download-assets/--no-download-assets, --delay, --concurrency, --no-robots, --force, -v/--verbose verbatim when the user names them, validated against $FETCH_HELP.

--output: when the user names a destination folder ("into ./X", "save to ./X", "output ./X"), pass --output ./X verbatim — do not rewrite or normalize the path beyond what the user typed. When the user doesn't name one and the intent is single-seed, omit --output and let the CLI default (./mykg_web_fetch/<domain>/) apply. For --url-list (including the inline-tempfile case below), --output is required by the CLI — if the user didn't name one, default to ./mykg_web_fetch/batch.

Inline URL list → temp file. If the user pastes multiple URLs directly in the message (not a path to an existing file), --url-list can't be used as-is — it requires a file. Write each URL on its own line to mykg_urls.txt (cwd), one URL per line, no comments/blank lines needed since the skill controls the content, then pass --url-list mykg_urls.txt. Mention the temp file's path to the user in the Stage 5 report so they know it was created (it is not auto-deleted — leaving it is harmless and lets the user re-run/edit the list).

Special --from-step values for the orphan-connect step

--from-step accepts every pipeline step name (preprocess, ingest, pass1, schema_validate, human_review, schema_flatten, pass2, normalize_names, assemble, orphan_score, orphan_connect, validate_graph) plus two aliases specific to the orphan-connection step. When the user describes intent that maps to either of these, pick the alias rather than bare orphan_connect:

If the user is ambiguous (e.g. "rerun orphans"), confirm in Stage 2 which one they want by presenting both options in one line.

Precondition — schema_max_restarts must be ≥ 1 for orphan_connect_fullsweep and orphan_connect_incremental to fully exercise the schema-gap auto-proposal loop. With schema_max_restarts: 0 (the shipped default in every profile) the aliases still execute, but the LLM is never asked to propose new schema properties for orphans the current schema cannot connect — those orphans remain orphans. The skill MUST handle this transparently via the auto-bump procedure below.

Auto-bump procedure (applies whenever Stage 1 lands on orphan_connect_fullsweep or orphan_connect_incremental)

Before launching the run, check the active profile's schema_max_restarts and temporarily bump it to 1 if needed:

# Resolve active profile (top-of-file `profile:` line).
ACTIVE_PROFILE=$(grep -E '^profile:\s' mykg_config.yaml | awk '{print $2}')

# Read schema_max_restarts inside the active profile block.
CURRENT=$(awk "/^  ${ACTIVE_PROFILE}:/,/^  [a-z]/" mykg_config.yaml \
  | grep -E '^\s+schema_max_restarts:' | head -1 | awk '{print $2}')

NEEDS_BUMP=0
if [ "$CURRENT" = "0" ]; then
  NEEDS_BUMP=1
fi

If NEEDS_BUMP=1, edit mykg_config.yaml in-place to set the active profile's schema_max_restarts: 1, then surface the change to the user as part of the Stage 2 confirmation:

About to run: uv run mykg extract-graph --session 2026-06-02T17-30-00 --from-step orphan_connect_fullsweep

Note: schema_max_restarts is currently 0 in profile `${ACTIVE_PROFILE}`. I will:
  1. Temporarily bump it to 1 (so the LLM may propose new schema properties for unconnected orphans).
  2. Run the alias.
  3. Revert schema_max_restarts back to 0 after the run finishes.

Reply "yes" to proceed, "no" to skip, or "keep at 1" to leave the value bumped permanently.

After the run finishes (success OR failure), always revert schema_max_restarts: 1 → 0 in the same profile unless the user explicitly said "keep at 1". The bump is per-invocation; the configured behaviour returns to baseline. Emit a final line: [skill] Restored schema_max_restarts: 0 in profile '${ACTIVE_PROFILE}'.

The YAML edit is scoped to the active profile block only — there are multiple schema_max_restarts: lines in the file (one per profile). Use a Python sub-shell with a regex anchored on ^ ${ACTIVE_PROFILE}: and looking inside the block until the next sibling ^ [a-z] to target the right line:

python3 - <<PYEOF
import re, pathlib
p = pathlib.Path("mykg_config.yaml")
txt = p.read_text()
profile = "$ACTIVE_PROFILE"
new_value = "$NEW_VALUE"   # 1 to bump, 0 to revert
pat = re.compile(
    rf"(^  {re.escape(profile)}:.*?^\s+schema_max_restarts:\s*)\d+(\s*(?:#[^\n]*)?$)",
    re.MULTILINE | re.DOTALL,
)
out, n = pat.subn(rf"\g<1>{new_value}\g<2>", txt, count=1)
if n != 1:
    raise SystemExit(f"Could not patch schema_max_restarts in profile '{profile}'")
p.write_text(out)
PYEOF

After every YAML edit, show git diff --no-color mykg_config.yaml | head -8 to the user as proof of the change. Never edit YAML without surfacing the diff.

Stage 2 — confirm intent before running

For destructive or expensive actions (anything that calls LLMs, anything --from-step, anything --append, and especially anything --sync — it REMOVES nodes), restate the parsed command in one line and ask the user to confirm. For --sync, run the command once without it first if you are unsure: the warning names exactly which files would be reconciled, so you can show the user that list before anything is removed:

About to run: uv run mykg extract-graph ./docs --append --session 2026-06-02T17-30-00

Reply "yes" to run, or correct me.

For obviously safe actions (walkthrough, parse-docs, fetch-web), skip the confirmation and run.

fetch-web chained with extract-graph: when the user's intent is "fetch and extract" (single seed or --url-list), run fetch-web directly (no confirmation — same as above), then confirm once before the extract-graph step(s), since those are the expensive/LLM-bearing part:

Fetched → <output dir> (N pages / GitHub clone).
About to run: uv run mykg extract-graph <output dir>  (fresh session)

Reply "yes" to extract, or "no" to stop here.

For the multi-seed chained intent (--url-list, including the inline-URL-list-to-tempfile case), confirm once listing every per-seed subdir that will get its own extract-graph run:

Fetched 3 seeds → ./mykg_web_fetch/batch/{a.com, b.com, github.com_owner_repo/input}
About to run, one fresh session each:
  uv run mykg extract-graph ./mykg_web_fetch/batch/a.com
  uv run mykg extract-graph ./mykg_web_fetch/batch/b.com
  uv run mykg extract-graph ./mykg_web_fetch/batch/github.com_owner_repo/input

Reply "yes" to extract all, "no" to stop here, or name which ones to run.

Fresh-vs-reuse ambiguity: when the user's intent is plausibly either a fresh extract or a continuation of a recent session (e.g. they typed /mykg ./more_docs and a session exists from earlier today), the proposed command MUST use a fresh session (no --session). Surface the alternative explicitly in the confirmation line so the user can correct it in one word:

About to run (fresh session): uv run mykg extract-graph ./more_docs

Reply "yes" to run, or say "resume the last session" / "append to the last session" to reuse session <most-recent>.

Never silently inherit a prior session.

Orphan re-entry aliases require an extra check: if Stage 1 resolved the command to --from-step orphan_connect_fullsweep or --from-step orphan_connect_incremental, follow the auto-bump procedure in the "Special --from-step values for the orphan-connect step" subsection of Stage 1 before running. That procedure temporarily sets the active profile's schema_max_restarts to 1, surfaces the change in this Stage 2 confirmation, and always reverts the value after the run unless the user explicitly says "keep at 1".

Stage 3 — verify agent mode is active

Two-step check. The first one catches the common "user installed mykg but never ran init" case before we waste a confusing CLI error.

Step 3a — does mykg_config.yaml exist at all?

if [ ! -f mykg_config.yaml ]; then
  echo "No mykg_config.yaml found in $(pwd)."
  echo "Run \`mykg init --profile agent-claude-code\` from a shell first, then re-invoke /mykg."
  exit 1
fi

If the file is missing, stop and tell the user to run mykg init --profile agent-claude-code from a shell. Do not try to call the CLI.

Step 3b — is the active profile agent-claude-code?

grep -E '^profile:\s' mykg_config.yaml

The output must be profile: agent-claude-code. If it is not, stop and tell the user:

Active profile is not agent-claude-code. Edit mykg_config.yaml and set profile: agent-claude-code, or run mykg <subcommand> from a shell directly.

Stage 4 — execute

Three execution paths depending on the subcommand the parser landed on.

Stage 4a — LLM-bearing path (extract-graph)

For a fresh run:

SESSIONS_DIR=$(grep -E '^\s+sessions_dir:' mykg_config.yaml | head -1 | awk '{print $2}' || echo sessions)
mkdir -p "$SESSIONS_DIR"

nohup uv run mykg extract-graph "$INPUT_DIR" $EXTRA_FLAGS \
  > /tmp/mykg_run.out 2>&1 &
echo $! > /tmp/mykg.pid

# Wait briefly for the session folder to materialise.
for i in $(seq 1 30); do
  SESSION_ROOT=$(ls -td "$SESSIONS_DIR"/* 2>/dev/null | head -1)
  if [ -n "$SESSION_ROOT" ] && [ -d "$SESSION_ROOT/intermediate/agent_inbox" ]; then
    echo "Session: $SESSION_ROOT"
    break
  fi
  sleep 1
done

For a resume / append / from-step run on an existing session:

SESSION_ROOT="$SESSIONS_DIR/$SESSION_NAME"
if [ ! -d "$SESSION_ROOT" ]; then
  echo "Session $SESSION_NAME not found under $SESSIONS_DIR" >&2
  exit 1
fi
nohup uv run mykg extract-graph "$INPUT_DIR" --session "$SESSION_NAME" $EXTRA_FLAGS \
  > /tmp/mykg_run.out 2>&1 &
echo $! > /tmp/mykg.pid

Capture:

• SESSION_ROOT — absolute path of the session directory.
• INBOX_DIR=$SESSION_ROOT/intermediate/agent_inbox
• OUTBOX_DIR=$SESSION_ROOT/intermediate/agent_outbox
• MYKG_PID=$(cat /tmp/mykg.pid)

Then enter the watch loop. Up to 20 waves, each wave does:

1. Scan the inbox for *.task.json files that do not have a matching .done in the outbox.
2. For each task (up to MAX_TASKS_PER_WAVE = 8), make one Agent-tool subagent call in parallel within a single message.
3. Check MYKG_PID is still alive. If not, exit.
4. Sleep 2 seconds before the next wave.

# Once per wave:
ls -1 "$INBOX_DIR"/*.task.json 2>/dev/null | while read TASK_PATH; do
  TASK_ID=$(basename "$TASK_PATH" .task.json)
  DONE_PATH="$OUTBOX_DIR/$TASK_ID.done"
  if [ ! -f "$DONE_PATH" ]; then
    echo "$TASK_PATH"
  fi
done | head -8

For every line printed above, dispatch one Agent tool call using the subagent prompt template at the bottom of this file. All dispatches in a single wave must go in the same assistant message so they run in parallel.

Between waves:

if ! kill -0 "$MYKG_PID" 2>/dev/null; then
  echo "Pipeline subprocess exited."
  break
fi
if [ -f "$SESSION_ROOT/output/knowledge_graph.ttl" ]; then
  echo "Pipeline produced knowledge_graph.ttl — done."
  break
fi
sleep 2

Track the wave count yourself. After 20 waves, tell the user:

Watch budget exhausted after 20 waves. Pipeline is still running (PID $MYKG_PID). Re-invoke /mykg resume the last session (or /mykg --session <name> --continue) to keep draining the inbox.

Stage 4b — synchronous path (walkthrough, approve-schema, parse-docs, fetch-web)

These subcommands do not write to the inbox. Run them in the foreground and report the resulting file path.

walkthrough:

uv run mykg walkthrough $ARGS
echo "Walkthrough: $SESSION_ROOT/walkthrough.md"

approve-schema:

uv run mykg approve-schema $ARGS
echo "Approved: $SESSION_ROOT/intermediate/schema_approved.flag"

parse-docs:

uv run mykg parse-docs $ARGS
echo "Converted markdown under: $OUTPUT_DIR"

fetch-web:

uv run mykg fetch-web $ARGS
# Single-seed: output ends with "Next: mykg extract-graph <path>" — capture <path>.
# Multi-seed (--url-list): read fetch_manifest.json["seeds"][*]["output_subdir"]
# under --output to get one <path> per seed.

Report the printed output directory (or all per-seed subdirs, for --url-list) and page/asset counts to the user. If the user's intent was the chained "fetch and extract" form (see Stage 1 intent table), proceed to Stage 4a for each captured path (extract-graph <path>, fresh session per path, after the Stage 2 confirmation) using the captured path(s) as INPUT_DIR.

Capture stdout/stderr; surface any non-zero exit to the user verbatim.

Stage 4b2 — MCP server path (mcp-serve)

MCP server commands are synchronous — run in the foreground and report.

Start:

uv run mykg mcp-serve $ARGS

This blocks — the server runs until stopped. For streamable HTTP, the server writes a PID file to ~/.mykg/mcp-serve.pid. Report the transport and port to the user.

Stop:

uv run mykg mcp-serve --stop

Reports whether the server was stopped or was not running.

Status:

ps aux | grep "mcp-serve" | grep -v grep

Report whether a server is running and on which transport/port.

No confirmation needed — MCP server commands are safe (no LLM cost, no data writes).

Stage 4c — refused (init, merge-graphs)

• /mykg init → reply: "Run mykg init from a shell. It is interactive."
• /mykg merge ... → reply: "Skill support is planned in a follow-up. Run from a shell."

Do not dispatch anything.

Stage 4d — read-only query path (query)

No CLI call, no subprocess, no LLM call from inside the skill. The skill answers the user's question using the target session's graph data (latest unless the user named one).

Source-attribution discipline — NO training-data contamination

Every claim in a query answer must be traceable to a specific session artifact (a node ID, an edge record, a vault note filename, an MCP tool response). If the session data does not contain the information, say so — do not fill gaps with your training knowledge.

Concrete rules:

1. Never state a fact about the domain unless the session data supports it. If the graph has Owen Lars with two edges (located_at Tatooine, member_of Jedi Knight), report exactly those two edges. Do not add "Owen is Luke's uncle" or "he was a moisture farmer" — those facts are not in the graph.

2. Never judge correctness of graph data using training knowledge. Do not say an edge is "correct" or "incorrect" based on what you know from pre-training. You may say an edge has confidence 0.0 (that is a graph fact), but not that the edge is "wrong because Owen was never a Jedi" (that is training-data reasoning).

3. Never list "missing relationships" sourced from training data. If the user asks "what's missing?", answer only from what the graph does contain and what structural signals suggest (orphan status, low confidence, absent attributes). Do not invent expected relationships from general knowledge.

4. If you must use training data, label it explicitly. Occasionally the user asks a question that genuinely requires outside knowledge (e.g., "is this graph accurate?"). In that case, separate the answer into two clearly labelled sections:

   **From the graph (session <name>):**
   <facts with node IDs, edge types, confidence scores, source files>
   
   **From training data (not in the graph — may be inaccurate):**
   <any claims sourced from pre-training, with a caveat>
   

   The graph section always comes first. The training-data section must carry the caveat that it may be inaccurate or outdated. If the user did not ask for an accuracy judgment, omit the training-data section entirely.

5. Cite sources for every fact. Every claim must end with a parenthetical citation: a node ID (person-owen-lars), an edge record (located_at, confidence 1.0, method: orphan_inferred), a vault note filename (Owen Lars.md), or an MCP tool call name. No uncited claims.

This rule is non-negotiable. It is better to give a short, accurate, graph-only answer than a rich answer contaminated with ungrounded training-data assertions.

Routing priority: MCP first, then file-read, then the mykg query CLI as a last resort.

If mcp__mykg__* tools are available in the current session (configured via .mcp.json), use them to answer the query. The MCP tools are indexed, return structured JSON, and support graph algorithms (shortest path, hub analysis, traversal, subgraph filtering) that manual file reading cannot do. Pick whichever MCP tool fits the question — the tool names and descriptions are self-documenting.

If MCP tools are not available or the call fails, fall back to reading session files directly as described below.

There is also a terminal command mykg query "<question>" [--session NAME] [--mode bfs|dfs] [--depth N] [--token-budget N] that mirrors the MCP mykg_query_graph tool: it finds seed nodes matching the question, traverses the graph, and prints a bounded text context of nodes plus relationships. Treat it as a last-resort fallback — reach for it only when MCP tools are unavailable and the raw session files are too large to read comfortably (e.g. a >50k-edge graph where the jsonl-path guidance below already suggests dropping into Python). It runs on the latest completed session unless --session is passed. Because its output is a pre-bundled summary rather than the raw node/edge records, it is weaker for citation: when you answer from it, still cite the specific node IDs and edge records it names (they appear in the text block as (node-id) and from-id --[type]--> to-id), and never let its summarization substitute for the source-attribution discipline above. Prefer MCP or raw file-reads whenever feasible.

File-read fallback — vault vs. jsonl

Pick the read source from the wording of the user's question:

• Prefer obsidian_vault/ (wiki path) when the user says or implies:
  • "wiki", "notes", "what does the wiki say", "tell me about X"
  • A named entity ("who is Alice", "what is project Phoenix")
  • Prose / explanatory questions
• Prefer nodes.jsonl + edges.jsonl (graph path) when the user says or implies:

…(truncated)