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.
3. Read `$OBSIDIAN_VAULT_PATH/.manifest.json` to check if this project has been synced before.
4. 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.

```bash
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:

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