docs(skill): keep extract roots explicit

[Ha1baraA11]

What does this PR do?

Addresses the documented failure mode in #3727 by making the Step 3 AST extraction example pass root and cache_root explicitly, and explaining that root anchors source paths and node IDs while cache_root only controls cache storage. This prevents adapting the example to a relocated graphify-out/ directory from silently renaming code-node IDs.

Related issue: #3727

Type of change

• Bug fix
• New feature
• Documentation
• Tests or CI
• Refactor
• Security fix

How was this tested?

skillgen --bless
skillgen --check (134 artifacts)
skillgen --audit-coverage
git diff --check

Graphify-specific checklist

• I added or updated tests for behavior changes.
• I updated documentation or confirmed that no documentation is needed.
• I updated generated skill artifacts when changing their source fragments.
• I considered compatibility across supported Python versions.
• I confirmed that no API keys, generated graph data, or local-only files are included.

[graphify-labs]

Graphify reviewed this change.

Looks safe to merge — no coupling regressions and no blocking issues, checked against the code graph (not a self-assessment).

---

Graphify review — findings

Passes root=Path('INPUT_PATH') alongside cache_root in the extract call across all graphify/skill-*.md variants (and the generated tools/skillgen fragments/expected outputs), so code node IDs and source paths anchor to the scanned corpus rather than the cache location. Adds a note explaining that root anchors node IDs while cache_root only controls cache storage, so relocating graphify-out/ no longer renames code nodes.

No blocking issues surfaced.

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 730 functions depend on the 730 functions this change touches.

Health — grade A; no new coupling hotspots.

Verification — 730 functions in the blast radius were not formally verified this run (proofs are advisory here).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

• verification_scope: 730 function(s) in the blast radius were not formally verified this run

Test selection

Test selection

290 of 290 test file(s) selected (100%) via static blast radius.

Escalated to a full run for safety — the selection is not trustworthy on its own (see below). CI should run the whole suite.

• tests/test_affected_cli.py — full-run-safety
• tests/test_affected_member_seed.py — full-run-safety
• tests/test_agents_platform.py — full-run-safety
• tests/test_analyze.py — full-run-safety
• tests/test_anthropic_custom_endpoint.py — full-run-safety
• tests/test_antigravity_install.py — full-run-safety
• tests/test_apm_fallback_version.py — full-run-safety
• tests/test_architecture_doc.py — full-run-safety
• tests/test_astro_extraction.py — full-run-safety
• tests/test_astro_import_ids.py — full-run-safety
• tests/test_atomic_canvas_export.py — full-run-safety
• tests/test_atomic_version_stamp.py — full-run-safety
• tests/test_atomic_writes.py — full-run-safety
• tests/test_backend_env_isolation.py — full-run-safety
• tests/test_backend_extras.py — full-run-safety
• tests/test_benchmark.py — full-run-safety
• tests/test_benchmark_raw_graph.py — full-run-safety
• tests/test_build.py — full-run-safety
• tests/test_build_merge_dedup_scope.py — full-run-safety
• tests/test_build_merge_hyperedges_and_prune.py — full-run-safety
• tests/test_build_merge_shrink_guard.py — full-run-safety
• tests/test_builtin_global_type_refs.py — full-run-safety
• tests/test_cache.py — full-run-safety
• tests/test_callflow_html.py — full-run-safety
• tests/test_cargo_introspect.py — full-run-safety
• tests/test_carried_hyperedge_remap.py — full-run-safety
• tests/test_case_sensitive_resolution.py — full-run-safety
• tests/test_charmap_encoding.py — full-run-safety
• tests/test_chunking.py — full-run-safety
• tests/test_cjs_module_extension.py — full-run-safety
• tests/test_claude_cli_backend.py — full-run-safety
• tests/test_claude_md.py — full-run-safety
• tests/test_cli_broken_pipe.py — full-run-safety
• tests/test_cli_export.py — full-run-safety
• tests/test_cli_help.py — full-run-safety
• tests/test_cluster.py — full-run-safety
• tests/test_codebuddy.py — full-run-safety
• tests/test_community_hub_labels.py — full-run-safety
• tests/test_community_labels_skill.py — full-run-safety
• tests/test_confidence.py — full-run-safety
• tests/test_corrupt_graph_json.py — full-run-safety
• tests/test_cpp_nested_and_cli.py — full-run-safety
• tests/test_cpp_objc_cross_file_calls.py — full-run-safety
• tests/test_cpp_preprocess.py — full-run-safety
• tests/test_cross_extension_reexport_self_cycle.py — full-run-safety
• tests/test_cross_language_call_resolution.py — full-run-safety
• tests/test_cross_repo_external_call_guards.py — full-run-safety
• tests/test_cross_repo_member_calls.py — full-run-safety
• tests/test_cross_repo_shared_types.py — full-run-safety
• tests/test_csharp_call_site_generic_args.py — full-run-safety
• … and 240 more

non-code file(s) changed (graphify/skill-agents.md, graphify/skill-amp.md, graphify/skill-claw.md, graphify/skill-codex.md, graphify/skill-copilot.md …) → running the full suite for safety (a code graph can't see config/fixture/data deps)

changed code file(s) with no mapped test (graphify/skill-agents.md, graphify/skill-amp.md, graphify/skill-claw.md, graphify/skill-codex.md, graphify/skill-copilot.md …) — a coverage gap or a missing link — running the full suite rather than only the selected tests

Selection is safe under the controlled-regression assumption; always-run tests + a periodic full run are the backstops. Advisory — it never changes the check verdict.