Obsidian Wiki Doctor

First-Use Vault Setup

Treat root configuration as background setup, not a JSON-file task for the user. If normal resolution has no root, run python "<runtime-script>" root discover --format json. Show returned existing absolute paths as numbered candidates and ask the user to select one or provide another absolute Vault path. Resolve the selected path and state vault_root, control_center, and wiki_root. Only after the user confirms it should become the default, run root configure --root <path> --activate --confirm.

Do not read note content or scan the whole disk during discovery. Continue the user's original request after setup succeeds.

Runtime Resolution

Before running any command, resolve this skill's SKILL.md directory, take its parent as <skills-root>, and set:

<runtime-script> = <skills-root>/obsidian-wiki-runtime/scripts/llm_wiki.py

Verify that <runtime-script> exists, then invoke it by absolute path. If it is missing, stop with missing-runtime, report the expected path, and recommend:

npx skills add huajiexiewenfeng/obsidian-llm-wiki --skill '*' --copy --yes

Do not fall back to a repository-relative scripts/llm_wiki.py path.

Obsidian Wiki Doctor

Inventory Discovery

Doctor calls the shared Inventory Core on every resolved Vault and remains strictly read-only. It compares supported document metadata with .meta/inventory.json, .meta/sources.json, and .meta/pages.json.

• missing-ingest-inventory: show an initialize dry-run; never initialize automatically.
• Initial baseline documents reachable from wiki/index.md are known-existing; disconnected historical documents are unverified, not new ingest candidates.
• source-island: an unverified historical document is outside the rooted graph.
• source-coverage-lost: a known-existing document lost its rooted graph connection.
• uningested-source: a discovered post-baseline document lacks processed evidence.
• stale-ingested-source: processed source metadata changed after ingest.
• orphan-wiki-page: a Wiki page is not reachable from wiki/index.md.
• detached-wiki-component: two or more Wiki pages form a disconnected component.
• Invalid baselines, collisions, or incomplete scans block completeness claims.
• Sensitive scopes expose alias/count summaries only.

Mandatory Missing-Baseline Explanation

Whenever missing-ingest-inventory is present, the Chinese report must state these three lines verbatim. Do not merely say that all current documents need classification or tracking:

索引可达的历史文档 -> known-existing -> 不需要 ingest
不可达的历史文档 -> unverified/source-island -> 不自动 ingest
基线后新增 -> discovered/uningested-source -> 待处理

Explain that the initial baseline classifies existing history; it does not turn the current Vault into an ingest backlog. When required .meta state files are also missing, recommend state initialization first, then Inventory initialize dry-run and explicit confirmation. Never imply that the current document count equals the number of documents requiring ingest.

Use inventory inspect --format json for the complete non-sensitive candidate list. Text output groups large sets and shows at most 20 examples per directory. Graph traversal reads only ordinary Inventory documents and Wiki pages; excluded and sensitive scopes are never opened for relationship discovery.

Diagnose an Obsidian LLM Wiki with the deterministic doctor engine.

Boundary

Use this skill to look, score, validate, and explain. Do not edit vault files.

Use obsidian-wiki-maintain when the user asks to fix, repair, patch links, update index.md, add source proxies, or apply findings from a doctor report.

Wiki Root Resolution

Before reading, resolve and state vault_root, control_center, and wiki_root using the shared order: user path, nearest project .obsidian-llm-wiki.json, OBSIDIAN_LLM_WIKI_ROOT, then exactly one active Vault in user configuration. Otherwise stop with missing-config or ask the user to choose when multiple roots exist. Do not search the whole disk.

python "<runtime-script>" root resolve --cwd <working-directory> --format json

Commands

Human report:

python "<runtime-script>" doctor report --root <control-center-or-vault> --format text

Machine validation:

python "<runtime-script>" doctor validate --root <control-center-or-vault> --format json --fail-on error

Structured score:

python "<runtime-script>" doctor score --root <control-center-or-vault> --format json

<skills-root>/obsidian-wiki-runtime/scripts/obsidian_wiki_doctor.py remains compatible in v0.2.

Interpretation Rules

• Treat script findings as deterministic evidence.
• Treat score as directional guidance, not a KPI.
• Never print secret values.
• Keep Chinese-first explanations for Chinese users.
• Explain not-applicable dimensions instead of treating them as failures.
• If a sensitive-pattern finding exists, recommend verification first. Only a confirmed real credential should be rotated and prioritized ahead of state initialization; a suspected or redacted example does not block Inventory.
• If the user asks to repair, hand off to obsidian-wiki-maintain with a narrow repair scope.
• Explain archive registry/path/checksum drift, unregistered raw/ files, and orphan archive staging files as read-only findings; never repair them here.

References

• Read references/doctor-checks.md when explaining finding names.
• Read references/report-template.md when summarizing report structure.
• Read references/safety-rules.md before presenting sensitive-pattern findings.