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, prune, drift.
• A direct reference: "the last session", "the existing session", "the same session", or a literal session name (typed as --session <name> or "session <name>").
• A flag whose semantics require a session: `--append`, `--sync`, `--update`, `--from-step <step>`.
• A subcommand that inherently targets a completed session: `approve-schema`, `walkthrough`, `detect-schema-drift`, `prune-schema`.

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)
DRIFT_HELP=$(uv run mykg detect-schema-drift --help 2>&1)
PRUNE_HELP=$(uv run mykg prune-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 / detect-drift / prune / 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:
4. Literal session name. User typed --session <name> or "session <name>" → use that exact name.
5. Explicit reuse verb / phrase. User said one of: resume, continue, redo, append, approve, walkthrough, prune, drift, 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.
6. Reuse-implying flag. User specified --append or --from-step <step> → auto-detect-most-recent (these flags only make sense against an existing session).
7. Session-only verb. Verb is approve-schema, walkthrough, detect-schema-drift, prune-schema, or query → auto-detect-most-recent. (query is read-only and always operates against an existing session.)
8. 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.
9. 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.

1. 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, detect-schema-drift, prune-schema --preview, parse-docs, fetch-web), skip the confirmation and run. prune-schema without --preview rewrites schema.json, so always confirm it, and offer the preview first if the user has not seen one.

`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, detect-schema-drift, prune-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"

`detect-schema-drift` / `prune-schema`: no LLM, no inbox. Report the command's output verbatim; after a prune, remind the user that plain --append now drops documents about a removed type and --append-with-grow-schema can re-add them. An empty plan prints Nothing to prune. and changes nothing. If the user wants to undo a prune, give the sequence the command prints (do not invent your own, and never suggest --from-step schema_flatten, which deletes Pass 2 outputs): copy intermediate/schema.pre_prune.json over schema.json; mykg approve-schema --session <S>; delete intermediate/flattened_schema.json (it is NOT regenerated automatically); mykg extract-graph <dir> --session <S> --from-step validate_graph; re-run mykg detect-schema-drift --session <S>.

uv run mykg detect-schema-drift $ARGS            # writes $SESSION_ROOT/intermediate/schema_drift.json
uv run mykg prune-schema $ARGS --preview         # writes $SESSION_ROOT/intermediate/schema_prune_plan.json
uv run mykg prune-schema $ARGS                   # applies; backup in intermediate/schema.pre_prune.json

`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.

1. 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:
• "knowledge graph", "graph", "network"
• "most connected", "central", "hub", "bridge", "blocking link", "shortest path"
• "how does X connect to Y", "what links A and B"
• Structural / topology / aggregate questions
• Both when the question genuinely needs structure and prose (e.g. "summarize what the wiki says about the most connected entity"). Read the jsonl first to identify the entity, then read the vault note for that entity.
• Ambiguous → prefer the vault if it exists (more human-readable); fall back to jsonl.

Session resolution

Same as the rest of Stage 1: latest under $SESSIONS_DIR unless the user named a session literally. query requires an existing session; if none exists, surface "No existing sessions under <SESSIONS_DIR>. Run /mykg extract <dir> first to create one." and stop.

#### Find the latest session

Don't guess the session name. Run one of these from the project root:

# Path to latest session root (use this in subsequent commands):
ls -td mykg_sessions/*/ 2>/dev/null | head -1

# One-line wiki status (node count + session path):
ls -td mykg_sessions/*/output/nodes.jsonl 2>/dev/null | head -1 \
  | xargs -I{} sh -c 'echo "mykg wiki: $(wc -l < {}) nodes in $(dirname $(dirname {}))"'

If the first command prints nothing, there is no graph yet — tell the user to run /mykg extract <dir> first instead of fabricating an answer.

#### What's in a session

Under <latest-session>/output/:

• nodes.jsonl — entities with confidence-scored attributes
• edges.jsonl — typed relationships
• knowledge_graph.ttl — RDFS/OWL view (SPARQL-queryable)
• obsidian_vault/ — markdown notes with wikilinks (when generated)

Vault path — read steps

SESSION_ROOT=$(ls -td "$SESSIONS_DIR"/*/ 2>/dev/null | head -1)
VAULT="$SESSION_ROOT/output/obsidian_vault"

# Sanity-check the vault exists. If not, fall through to the jsonl path with
# a one-line note: "vault not generated for this session — falling back to
# jsonl. Re-run extract with --obsidian-vault to enable wiki queries."
if [ ! -d "$VAULT" ]; then
  echo "[query] obsidian_vault/ not found at $VAULT — falling back to jsonl path."
fi

When the vault exists:

1. List candidate note files with ls "$VAULT".
2. Identify likely matches by stem (Obsidian note filenames are derived from canonical node names).
3. Use the Read tool to load the matching .md notes. Follow [[wikilinks]] to neighbours when the question implies a relationship.
4. Answer the user from the note content. Cite the note filenames so the user can verify.

Jsonl path — read steps

SESSION_ROOT=$(ls -td "$SESSIONS_DIR"/*/ 2>/dev/null | head -1)
NODES="$SESSION_ROOT/output/nodes.jsonl"
EDGES="$SESSION_ROOT/output/edges.jsonl"

# Sanity check.
[ -f "$NODES" ] || { echo "[query] $NODES missing"; exit 1; }
[ -f "$EDGES" ] || { echo "[query] $EDGES missing"; exit 1; }

When the files exist:

1. Use the Read tool on nodes.jsonl / edges.jsonl directly. Each line is one JSON record (the records are documented under D12 / D13 in the project's CLAUDE.md when one is present).
2. For specific lookups (single node, one-hop neighbours), grep first then Read the matched lines:

   grep -F '"name": "Alice"' "$NODES" | head -20
   grep -F '"from": "person-alice"' "$EDGES" | head -50

1. For aggregate / topology questions (most-connected node, hub identification), it is usually fine to Read the whole edges.jsonl and tally with the host LLM's reasoning — these files are typically a few hundred to a few thousand lines. For >50k-edge graphs the skill should warn the user and offer to drop into Python (networkx) via the Bash tool instead.
2. Answer the user from the records. Quote the matched ids/edge types so the user can verify.

Hybrid path — read steps

Use the jsonl path to identify the target node(s), then resolve <node>.md in the vault and Read it for prose context. Cite both.

Confirmation behaviour

query is read-only and free, so do not ask the user to confirm. Just run it. Do echo a one-line summary of the path used before answering:

[query] MCP: answered via 2 MCP tool calls.
[query] vault: read 3 notes from $VAULT (Alice.md, AcmeCorp.md, Project_Phoenix.md).
[query] jsonl: read 47 nodes + 89 edges from $SESSION_ROOT/output/.

Stage 5 — final report

When the loop exits (or the synchronous command returns), print:

echo "Session:  $SESSION_ROOT"
echo "PID:      $MYKG_PID (alive: $(kill -0 $MYKG_PID 2>/dev/null && echo yes || echo no))"
echo "Inbox:    $(ls -1 $INBOX_DIR/*.task.json 2>/dev/null | wc -l) total tasks"
echo "Answered: $(ls -1 $OUTBOX_DIR/*.done 2>/dev/null | wc -l)"
if [ -f "$SESSION_ROOT/output/knowledge_graph.ttl" ]; then
  echo "Output:   $SESSION_ROOT/output/knowledge_graph.ttl"
fi

For synchronous paths, just print the produced file path.

Notes for the implementer

• Atomicity matters (LLM-bearing path). Always write <id>.answer.json.tmp then mv it to the final name before touching <id>.done. The adapter polls the .done sentinel, not the answer file.
• Caching is automatic. If you accidentally answer the same task twice the second write overwrites — the adapter only reads the most recent answer once .done exists.
• Do not validate. The pipeline has its own retry + LLM-feedback path. If your JSON is malformed, the pipeline catches it and dispatches a corrective task on its own.
• Stay parallel (LLM-bearing path). Within a wave, multiple Agent-tool calls in one assistant message run concurrently. Sequential dispatch defeats the purpose.
• Stay bounded. 20 waves is a hard limit. If a run needs more, the user re-invokes /mykg resume the last session.
• Synchronous paths are trivial. No atomicity or parallelism concerns; just shell out and report.

Subagent prompt template

Each Agent-tool dispatch in Stage 4a uses exactly this prompt (substitute $TASK_PATH and $OUTBOX_DIR):

You are an mykg agent-mode worker. Your only job is to answer the LLM task in
the file shown below and write the result atomically to the outbox.

Task file:   $TASK_PATH
Outbox dir:  $OUTBOX_DIR

Procedure:

1. Read the JSON file at $TASK_PATH. It has these fields:
   - task_id: a 64-char sha256 hex string
   - step: which pipeline step (e.g. "pass1", "pass2", "normalize_names")
   - context_label: short label for debugging
   - system: the system prompt the pipeline wants you to respond to
   - user: the user prompt
   - max_tokens: integer
   - timeout_seconds: integer

2. Treat the `system` field as the instructions you must follow and the `user`
   field as the user message. Produce the response the pipeline expects — for
   pass1 that is a JSON object with `concepts` and `properties`; for pass2 that
   is `{nodes: [...], edges: [...]}`; for normalize_names that is a mappings
   object; for orphan_connect that is an array of edges. The `system` prompt
   itself tells you the exact schema in detail. Output **only** the JSON
   (no prose, no markdown fences).

3. Write the answer JSON to a string and build the answer envelope:
   {"task_id": "<the task_id from the task file>", "answer": "<your JSON string>"}

4. Write the answer atomically:
   a. Write the envelope JSON to $OUTBOX_DIR/<task_id>.answer.json.tmp
   b. Rename it to $OUTBOX_DIR/<task_id>.answer.json (atomic on POSIX)
   c. Touch $OUTBOX_DIR/<task_id>.done  (zero-byte sentinel)

   The pipeline polls for the `.done` sentinel — never write `.done` before
   the `.answer.json` file is fully on disk.

5. Report a one-line summary: which step, which context_label, how big the
   answer was. Do not write anything else to the outbox.

If the system+user prompt is genuinely ambiguous or you cannot produce valid
JSON, still write a best-effort response — the pipeline has its own retry +
feedback path and will repair downstream. Never leave a task unanswered: a
missing `.done` sentinel will block the pipeline until its 1800-second
timeout.