Obsidian Wiki Init

Overview

Scaffold and then continuously grow a durable LLM Wiki inside an Obsidian vault: a read-only
raw/ source area, an AI-maintained wiki/ knowledge layer, and a Codex/ persistent-memory
area, governed by an explicit AGENTS.md.

This skill has two phases:
- Phase 1 — Initialization: create the structure (run once per vault).
- Phase 2 — Incremental maintenance: ingest newly added raw/ material into wiki/ (run repeatedly).

After Phase 1 completes, ALWAYS offer Phase 2 (see "Handoff" below). Do not assume the user knows
the second step exists.

Critical Precondition: Vault Detection (DO THIS FIRST, DO NOT SKIP)

Users frequently misstate where a folder sits relative to the vault. A sibling folder of the vault
is NOT inside the vault. Verify before writing anything.

1. Determine the active vault root. On Windows read the source-of-truth config:
   %APPDATA%/obsidian/obsidian.json (typically C:\Users\<user>\AppData\Roaming\obsidian\obsidian.json).
   It maps vault-id → { "path": "<vault-root>", "ts": ..., "open": true }.
2. Confirm which folder is the vault root by locating its .obsidian/ directory on disk
   (find <candidate> -maxdepth 2 -name .obsidian -type d). The folder that contains .obsidian/
   IS the vault; its parent is outside the vault.
3. Resolve user premises against reality. If the user says "build it in the vault's <X> folder" but
   <X> is a sibling of the vault (not inside it), the premise is wrong. Example from a real case:
   the user believed E:\base\news was "inside the vault" while the only registered vault was
   E:\base\finance — finance itself was the vault, news was a sibling.
4. If any premise cannot be confirmed, STOP and ask the user (which vault? which folder? single vs
   independent vaults?). Do not proceed. Present concrete options:
   - promote the common parent to vault root (enables cross-folder [[wikilinks]]);
   - make the target an independent new vault (isolated, no cross-vault links);
   - nest the target under the existing vault.

Critical Pitfall: obsidian.json While Obsidian Is Running

Obsidian holds obsidian.json in memory and rewrites it on exit. Editing the file from a script
while the app is open is lost at best and conflicts at worst.

• Detect running Obsidian before any config change: tasklist | grep -i obsidian (Windows).
• If running: DO NOT hand-edit obsidian.json. Instead create a minimal vault marker
  (<target>/.obsidian/app.json containing {}) and instruct the user to open it once via
  Open folder as vault in Obsidian; Obsidian registers it itself on open.
• If not running: it is safe to add the vault entry to obsidian.json, but the marker approach is
  still lower-risk and works in both cases. Prefer the marker unless the user explicitly asks
  for the config to be edited.

Phase 1 — Initialization Workflow

1. Resolve the vault/location per the precondition above; obtain explicit user decision if needed.
2. Create the directory skeleton (non-destructive — mkdir -p merges, never overwrites):
   raw/{articles,papers,books,chats,notes,meetings},
   wiki/{sources,concepts,entities,topics}, Codex/notes.
3. Write root files. For exact content use references/wiki-contents.md:
   - AGENTS.md — the maintenance rules (read-only raw/, source-page-per-raw, search-before-write,
   split concepts/entities/topics, cite sources / mark "待核实", preserve conflicting claims,
   append-only log.md, ask when uncertain).
   - index.md — global navigation entry.
   - log.md — # 变更日志 plus an init entry dated TODAY (## <YYYY-MM-DD> - 初始化 … 知识库结构).
   IMPORTANT: the user-supplied example text often says "finance 知识库结构" copied from a prior task —
   replace with the actual target name and today's date unless the user insists on verbatim.
   - Codex/TODO.md — # TODO with - [ ] 初始化知识库工作流.
4. Create four wiki templates wiki/{sources,concepts,entities,topics}/_template.md with one shared
   body (frontmatter + 摘要/核心内容/相关页面/来源/待核实问题 sections) differing ONLY in the type:
   field (source/concept/entity/topic). See references/wiki-contents.md.
5. Initialize the vault marker: mkdir -p <target>/.obsidian and write app.json = {}
   (skip if the target is already inside a registered vault — never nest .obsidian inside a vault).
6. Self-check and report:
   - every required directory exists;
   - every required file exists and non-zero;
   - the four _template.md are byte-identical except the type: line (diff after stripping ^type:);
   - log.md entry uses today's date and the right vault name;
   - report any path that already existed and was therefore preserved (never overwritten).
7. Handoff — ask about Phase 2 (REQUIRED, do not skip). The raw/ tree is empty right after
   initialization, so ask the user whether material has already been added and whether to ingest it
   now. Use an interactive question with options along these lines:
   - "已添加，现在就按 AGENTS.md 增量维护" → run Phase 2 immediately;
   - "已添加，但先只出清单不写入" → run Phase 2 in dry-run mode (report the plan, write nothing);
   - "还没添加，稍后再说" → stop, and tell the user which directory to drop files into
   (raw/articles/ for articles and web clippings; papers/ books/ chats/ notes/ meetings/
   for the other kinds).
   When resuming in a later session, skip Phase 1 entirely and go straight to Phase 2.

Phase 2 — Incremental Wiki Maintenance (Ingestion)

Trigger: new markdown files exist under raw/<subfolder>/, or the user asks to process / ingest /
增量维护 new material. The canonical reusable request text is stored in
references/ingestion-prompt.md — reuse it verbatim when handing the task to another agent/session.

Hard constraint: raw/ is read-only. Never modify, rename, move, or delete anything under raw/.

Dry-run mode: when the user picks "已添加，但先只出清单不写入" at the Handoff, run steps 1–2 in
full, then output the step-10 report structure listing exactly which pages would be CREATED and which
UPDATED — but write NOTHING to disk. This lets the user approve the plan before anything changes.

1. Scope the batch. List candidate files under the target raw/ subfolder. Determine which are
   new/unprocessed by checking whether a corresponding page already exists in wiki/sources/
   (and by consulting log.md). Report the batch to the user if it is large.
2. Search before writing (mandatory). Before creating anything, search existing wiki/ pages
   (wiki/sources/, concepts/, entities/, topics/) for the entities and concepts involved.
   This decides extend-vs-create for every page and prevents duplicates.
3. Create a source summary page in wiki/sources/ for each raw file, from _template.md.
   Fill title/type: source/created/updated, write 摘要 and 核心内容, and keep a link to the
   original file (e.g. [[raw/articles/<file>]] or a relative markdown link). One raw file → one
   source page.
4. Extract and route knowledge into separate pages — never pile everything into one note:
   - concepts / theories / methods → wiki/concepts/
   - people / companies / products / tools → wiki/entities/
   - cross-source syntheses → wiki/topics/
   For each item: if a page already exists, APPEND to it (extend 核心内容, add the new source to
   sources: and to the 来源 section); if not, create a new page from the matching _template.md.
   Never overwrite an existing conclusion.
5. Handle disagreement without overwriting. When new material conflicts with an existing page,
   keep BOTH claims side by side, each labelled with its source, time, and scope of applicability
   (适用范围). Do not silently replace the older statement.
6. Cite everything; flag the unverifiable. Every factual statement carries its source. Anything
   that cannot be confirmed from the raw material goes under the 待核实问题 section rather than being
   asserted or dropped.
7. Wire the [[wikilinks]]. Link source ↔ concepts/entities/topics bidirectionally, and fill the
   相关页面 section on each touched page so the graph is navigable from any entry point.
8. Update index.md — add newly created pages under their category so the index stays a complete
   navigation entry.
9. Append to log.md — append-only. Record the date, the raw files processed, and the pages
   created vs updated. Never rewrite earlier log entries.
10. Report to the user (this is the deliverable, not an afterthought):
    • pages CREATED (grouped by sources/concepts/entities/topics);
    • pages UPDATED, and what was added to each;
    • items needing human confirmation — the 待核实 list, detected conflicts, ambiguous
      entity identities (e.g. same name / different people), and anything deliberately skipped.
11. Review Codex/ before ending the session — update Codex/TODO.md / Codex/notes/ with
    follow-ups, and report what changed there.

Phase 2 quality bar

• One raw file → exactly one wiki/sources/ page; concepts/entities/topics are separate pages.
• No orphan pages: everything is reachable via [[wikilinks]] and listed in index.md.
• No page rewritten from scratch when it already existed — extend it.
• _template.md files are templates, not content: never treat them as ingestible material and never
  overwrite them.

Edge Cases

• Target files already exist → preserve and report; never overwrite. Existing directories → merge.
• Obsidian open → use the .obsidian/app.json marker + "open folder as vault" instruction.
• User later wants cross-vault links → requires collapsing to a single vault (promote common parent);
  [[wikilinks]] do NOT cross independent vaults.
• Empty raw/ at Phase 2 trigger → do not fabricate pages; tell the user where to put files.
• Re-running Phase 2 on already-processed files → detect via existing wiki/sources/ pages and skip
  or ask, rather than creating duplicates.
• Non-markdown files in raw/ (PDF, images) → out of scope for this workflow; report them as skipped.
• Keep the wiki template body and AGENTS.md rules in sync with references/wiki-contents.md.