Wiki Update

Wiki Update — Sync Any Project to Your Wiki

You are distilling knowledge from the current project into the user's Obsidian wiki. This skill works from any project directory, not just the obsidian-wiki repo.

Before You Start

Writing profile: Before drafting or rewriting natural-language Markdown, read and apply the Writing Profile Resolution section in llm-wiki/SKILL.md. Framework schema, provenance, safety, and operation-specific requirements take precedence. WRITING.md preferences apply only to newly drafted or rewritten natural-language Markdown; preserve source content and structured records.

1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → global config → prompt setup). This gives OBSIDIAN_VAULT_PATH, OBSIDIAN_WIKI_REPO, OBSIDIAN_LINK_FORMAT (wikilink default or markdown), and optional QMD settings such as QMD_WIKI_COLLECTION. Works from any project directory.
2. Read $OBSIDIAN_VAULT_PATH/.manifest.json to check if this project has been synced before.
3. Read $OBSIDIAN_VAULT_PATH/index.md to know what the wiki already contains.

When writing internal links in Steps 4–5, apply the link format from llm-wiki/SKILL.md (Link Format section) using the OBSIDIAN_LINK_FORMAT value.

Step 1: Understand the Project

Figure out what this project is by scanning the current working directory:

• README.md, docs/, any markdown files
• Source structure (frameworks, languages, key abstractions)
• package.json, pyproject.toml, go.mod, Cargo.toml or whatever defines the project
• Git log (focus on commit messages that signal decisions, not "fix typo" stuff)
• Claude memory files if they exist (.claude/ in the project)

Derive a clean project name from the directory name.

Step 2: Compute the Delta

Check .manifest.json for this project:

• First time? Full scan. Everything is new.
• Synced before? Look at last_commit_synced. Before computing the delta, verify the stored SHA is still reachable: ``bash git merge-base --is-ancestor <last_commit_synced> HEAD ``
• Exit 0 (ancestor): Safe. Run git log <last_commit_synced>..HEAD --oneline to see what changed.
• Exit 1 (not an ancestor — rebase or force-push occurred): The stored SHA is no longer in this branch's history. Warn the user: "Stored commit `<sha>` is no longer reachable — branch may have been rebased or force-pushed. Falling back to full scan." Then treat as first-time sync: re-scan everything and update last_commit_synced to the current HEAD SHA at the end of Step 6.

If nothing meaningful changed since last sync, tell the user and stop.

Step 3: Decide What to Distill

This is the core question from Karpathy's pattern: what would you want to know about this project if you came back in 3 months with zero context?

Worth distilling:

• Architecture decisions and why they were made
• Patterns discovered while building (things you'd Google again otherwise)
• What tools, services, APIs the project depends on and how they're wired together
• Key abstractions, how they connect, what the mental model is
• Trade-offs that were evaluated, what was picked and why
• Things learned while building that aren't obvious from reading the code

Not worth distilling:

• File listings, boilerplate, config that's obvious
• Individual bug fixes with no broader lesson
• Dependency versions, lock file contents
• Implementation details the code already says clearly
• Routine changes anyone could read from the diff

The heuristic: if reading the codebase answers the question, don't wiki it. If you'd have to re-derive the reasoning by reading git blame across 20 commits, wiki it.

Step 3b: Build a code-understanding focus map (optional)

GUARD: If the `obsidian-wiki code-understand` command fails or is unavailable, skip this step and continue — it is an optimisation, not a requirement.

When this project contains code, run the local code-understanding extractor before distilling. It parses the codebase locally and returns a focus map — the ranked files and symbols the architecture hangs on — so you read the load-bearing parts instead of scanning everything.

obsidian-wiki code-understand --project "$(pwd)" --pretty

When this is not the first sync (Step 2 computed last_commit_synced), seed the focus map from the delta:

obsidian-wiki code-understand --project "$(pwd)" --since <last_commit_synced> --pretty

(First sync: omit --since.)

What to do with the focus-map output

1. Read the output selectively — when backend: codegraph, treat focus-map entries as structural facts with file:line citations; when backend: builtin, treat defines/imports entries as facts but treat rg-reference entries as weaker evidence — open the file and verify before citing. Open only the ranked files/file:lines the focus map points at; never paste the JSON into the wiki or the vault.
2. Cite the evidence — every architectural claim written to a page references its evidence as (file:lines) from the focus map or from the opened source; keep using the existing provenance markers.
3. Prune stale relationships (required) — when updating an existing projects/<name>/ page, cross-check each previously recorded code relationship against the current focus map (or obsidian-wiki ast-extract for a symbol-level recheck). Remove relationships whose target symbol no longer exists or is no longer reachable; update the page and record the removals in log.md. This keeps false positives from accumulating.
4. Never write .codegraph/ or the code-understand JSON into $OBSIDIAN_VAULT_PATH — the graph is a cache/sidecar in the project repo, not wiki knowledge.
5. Offer CodeGraph when it's missing (optional) — if the output reports backend: builtin because codegraph is unavailable and the user wants the enhanced backend, offer to install it for them: npm install -g @colbymchenry/codegraph (or set CODE_UNDERSTANDING_CODEGRAPH_BIN to an existing binary), then re-run this step so the focus map uses the graph. Never install without the user's go-ahead, and never let a missing codegraph block the sync.

If obsidian-wiki is not installed or the command fails, skip this step and proceed to Step 4 as normal — it is an optimisation, not a requirement.

Step 4: Distill into Wiki Pages

Project-specific knowledge

Goes under $VAULT/projects/<project-name>/:

projects/<project-name>/
├── <project-name>.md          ← project overview (named after the project, NOT _project.md)
├── concepts/                  ← project-specific ideas, architectures
├── skills/                    ← project-specific how-tos, patterns
└── references/                ← project-specific source summaries

The overview page (<project-name>.md) should have:

• What the project is (one paragraph)
• Key concepts and how they connect
• Links to project-specific and global wiki pages

Global knowledge

Things that aren't project-specific go in the global categories:

Page format

Every page needs YAML frontmatter:

---
title: >-
    Page Title
category: concepts
tags: [tag1, tag2]
sources: [projects/<project-name>]
summary: >-
    One or two sentences (≤200 chars) describing what this page covers.
provenance:
  extracted: 0.6
  inferred: 0.35
  ambiguous: 0.05
base_confidence: 0.59
lifecycle: draft
lifecycle_changed: TIMESTAMP_DATE
created: TIMESTAMP
updated: TIMESTAMP
---

Use folded scalar syntax (summary: >-) for title and summary to keep frontmatter parser-safe across punctuation (:, #, quotes) without escaping rules.