Project Wiki
Maintain local wikis for a code project under .wiki by default, with optional language-specific roots such as .wiki-cn, .wiki-fr, or an exact user-named wiki directory such as wiki-cn.
Source of truth is always the current git-tracked repository files at HEAD, including tracked documentation in .docs/ and docs/, not the wiki.
The wiki files themselves may be untracked; read and update the live selected wiki root from the working tree when present.
Rules
- Operate only on git-tracked files and git history
- Ignore staged and unstaged uncommitted changes; ingest and query verification use committed content at
HEAD only
- Select exactly one wiki root per request. Use
.wiki by default; use the explicit root or language the user names, such as .wiki-cn, wiki-cn, .wiki-fr, "Chinese wiki", or "French wiki"
- Each wiki root is independent. Do not sync, compare, translate, merge, or copy pages between language roots unless the user explicitly asks
- Exclude all wiki roots from git-based source selection:
.wiki/**, .wiki-*/**, and wiki-*/**
- Do not assume any wiki root is git-tracked; use the selected root's current
index.md checkpoint when it exists
- Target Open Knowledge Format (OKF) v0.1: Markdown files, YAML frontmatter on concept documents, standard Markdown links, reserved
index.md listings, and reserved log.md update history
- Every non-reserved concept page must have parseable YAML frontmatter with a non-empty
type
- The selected root's
index.md and log.md must be updated on every ingest
- Keep ingest checkpoint metadata in the selected root's
index.md frontmatter; do not introduce .wiki/.wiki-state.md or another hidden state file
- Do not ask the user before ingesting
- Export reads the live working-tree files under the selected wiki root, not the git-tracked repository at
HEAD
- Do not let every source file generate a page. The wiki should be selective memory, not a second filesystem.
Wiki Layout
Required:
<wiki-root>/index.md — human entry point and master catalog (tracks last ingest commit for that root only)
<wiki-root>/log.md — chronological update history for the selected wiki root
Optional (create as needed):
<wiki-root>/overview/ — orientation pages that explain the project, startup path, storage, and reading path
<wiki-root>/features/ — one page per significant product capability or implementation area
<wiki-root>/decisions/ — one page per system-impactful change, compatibility discovery, or behavior that must not regress
<wiki-root>/concepts/ — cross-cutting ideas and patterns
<wiki-root>/entities/ — data models, schemas, types
<wiki-root>/flows/ — sequences, pipelines, request lifecycles
<wiki-root>/risks/ — invariants, compatibility contracts, fragile behavior, and things not to break
<wiki-root>/reference/ — code-shaped reference pages when a source path needs focused explanation
<wiki-root>/open-questions/ — unresolved findings, missing context, suspected issues, and things needing human review
Human understanding structure
The wiki is for a human to understand the codebase, not for the repository to describe itself. Organize the front door around the reader's questions before the code's folders.
<wiki-root>/index.md must answer these questions, in this order:
- What is this?
- Get started
- Why does it exist?
- What happens when I run it?
- Where is data saved?
- What are the important moving parts?
- What should I avoid breaking?
- Where do I look first?
Use these questions as the primary navigation. features/, entities/, flows/, and reference/ are supporting evidence, not the first mental model.
The Get Started section is for codebase orientation, not a duplicate README. It should give a smart newcomer the first 10 minutes:
- the main command to run
- required environment or services
- expected successful output
- the first files to read
- one safe first change
- one tempting dangerous change
When a repo already has setup instructions in README.md or docs/, link to them and summarize only what helps the reader understand the code.
OKF compatibility
Generated wikis must target OKF v0.1 with one deliberate root-index extension: the bundle root index.md keeps frontmatter so the wiki can declare okf_version: "0.1" and preserve the last_commit ingest checkpoint. Do not add frontmatter to nested index.md files. Use log.md for update history, not hidden state files.
Use standard Markdown links with relative paths. Do not create new Obsidian-style [[wiki-links]].
Wiki root selection
- Default wiki root:
.wiki
- Language-specific roots: prefer
.wiki-<language-code> when creating a new language wiki, for example .wiki-cn for Chinese and .wiki-fr for French
- If the user names an exact directory, such as
wiki-cn, use that exact root instead of normalizing it
- Language roots do not inherit checkpoints, pages, links, or stale status from each other
- When the user asks for a language wiki by language name, write page prose in that language and keep code identifiers, file paths, and API names unchanged
Page Conventions
Root index.md frontmatter
The selected root's index.md is the human entry point and carries the ingest checkpoint:
---
okf_version: "0.1"
title: "Project Wiki"
language: "<language-code|default>"
last_commit: "<full-sha>"
timestamp: "YYYY-MM-DDTHH:mm:ssZ"
---
last_commit is the full git commit SHA at the time of the most recent full-repository ingest for the selected wiki root. This checkpoint lives in the selected root's current index.md file whether or not that root is git-tracked. On the next ingest for the same root, prefer this saved last_commit to find changed files with git diff --name-status -M <last_commit> HEAD.
If git metadata is unavailable, do not fall back to filesystem scanning. Ingest and lint are unavailable until git access works again.
Nested index.md files, if created, are OKF directory listings and must not have frontmatter. They should group child concepts with Markdown links and short descriptions.
log.md update history
log.md records wiki update history for the selected root. It must use newest-first date groups:
# Directory Update Log
## YYYY-MM-DD
* **Update**: Updated [Startup Flow](flows/startup-flow.md) from `src/main.ts`.
* **Creation**: Created [Data Storage](overview/data-storage.md).
Use log.md for human-readable update history only. Keep the machine checkpoint in root index.md:last_commit.
Other pages
---
type: "Overview|Feature|Decision|Concept|Entity|Flow|Risk|Reference|Open Question"
title: "Page Title"
description: "One sentence explaining what this page helps the reader understand."
resource: "repo://path/to/source-or-empty"
tags: ["short-tag"]
timestamp: "YYYY-MM-DDTHH:mm:ssZ"
status: "draft|active|stale"
language: "<language-code|default>"
source_paths: []
---
Set language to default for .wiki, cn for .wiki-cn or wiki-cn, fr for .wiki-fr, and the matching language code for other language-specific roots.
Use type values that are short and self-explanatory. title, description, resource, tags, and timestamp are OKF-recommended fields; status, language, and source_paths are producer-defined extensions.
Use status: "stale" when the source file has changed significantly since the page was last updated, or when the page describes something that no longer exists. During ingest, pages whose source_paths changed since last_commit should be updated or marked stale. Do not delete stale pages automatically — mark them and note the drift so the user can decide.
Decision pages
Use <wiki-root>/decisions/ for system-impactful changes, not routine bug diaries. A decision page must answer:
- What changed?
- Why did it change?
- What old behavior must not come back?
- What compatibility issue was discovered?
- What lesson should future developers remember?
Do not create a decision page for every commit. Create one when a change reveals a lasting product, architecture, compatibility, migration, or operational lesson.
Open question pages
Use <wiki-root>/open-questions/ for unresolved findings, missing context, suspected issues, and things that need human review. State what is known, what is inferred, what evidence is missing, and what decision or verification would close the question.
Page naming
- Use lowercase, hyphenated filenames:
auth-middleware.md, user-schema.md
- Name pages for the human idea first:
login-check.md, saved-data-shape.md, startup-flow.md
- Use source-path names only for reference pages or when there is no clearer reader-facing name:
src/api/routes.ts → <wiki-root>/reference/src-api-routes.md
- Use descriptive names for concepts and flows:
<wiki-root>/concepts/request-lifecycle.md
Wiki links
Use standard Markdown links with relative paths between pages whenever a page references something covered on another page:
See [Startup Flow](../flows/startup-flow.md).
Do not create new [[page-slug]] links. When updating an existing wiki, upgrade old links:
[[startup-flow]] -> [Startup Flow](../flows/startup-flow.md)
[[startup-flow|how startup works]] -> [how startup works](../flows/startup-flow.md)
Compute the link target relative to the page being written. Resolve targets by matching the destination filename stem within the selected wiki root; prefer a same-directory match, then a unique match elsewhere. If no target exists yet, use the best expected relative path and let lint report it as a warning rather than blocking OKF consumption.
Ingest
Trigger on:
ingest
ingest [file]
ingest [folder]
ingest wiki-cn
ingest .wiki-fr
refresh wiki
update wiki
update Chinese wiki
Workflow:
- Select the wiki root from the request. Default to
.wiki; use an explicit root or language-specific root when named
- Read
<wiki-root>/index.md from the working tree if it exists, even when the wiki root is untracked — note last_commit from frontmatter
- Missing
<wiki-root>/index.md or a missing last_commit means there is no prior ingest checkpoint for that root
- Run
git rev-parse HEAD to get the current HEAD commit SHA
- Detect changed files:
- If
last_commit is set: git diff --name-status -M <last_commit> HEAD and exclude all wiki roots (.wiki/**, .wiki-*/**, wiki-*/**)
- Use the saved
last_commit even if the selected wiki root is untracked; do not treat an untracked wiki root as a fresh ingest from HEAD
- Use the git status codes to distinguish added, modified, deleted, and renamed paths when updating wiki pages
- If no prior ingest: build a broad ingest candidate set from
git ls-files at HEAD, excluding all wiki roots (see Ingest Priorities below)
- Resolve scope:
- If a file or folder is specified, prioritize it — limit the tracked candidate set to that scope
- For a scoped ingest, do not advance
<wiki-root>/index.md:last_commit unless the scoped ingest also covers every file changed since last_commit
- Otherwise ingest changed files first, then fill in missing coverage
- Read relevant tracked repository files — understand their role. Select pages by lasting reader value, not by file count.
- Update or create wiki pages under the selected wiki root using OKF-compatible concept frontmatter and Markdown relative links
- Scan Markdown files in the selected wiki root and upgrade existing Obsidian-style links to Markdown relative links:
- Convert
[[slug]] to [Title](relative/path.md)
- Convert
[[slug|label]] to [label](relative/path.md)
- Resolve
relative/path.md from the current page to the target page inside the selected wiki root
- Mark pages in the selected wiki root for deleted source files as
status: "stale" with a note in the page body, and update moved or renamed pages based on rename information from git
- Update
<wiki-root>/index.md:
- Always set
timestamp to the current ISO 8601 datetime
- Set
last_commit to the current HEAD SHA only after a full ingest or after processing the complete changed-file set from the previous last_commit
- If a broad ingest stops early after partial coverage, leave
last_commit unchanged and note in index.md that bootstrap coverage is still partial
- Never discard an existing saved
last_commit merely because the selected wiki root is untracked
- Update
<wiki-root>/log.md with a newest-first YYYY-MM-DD entry summarizing created, updated, stale, renamed, and link-migrated pages
Ingest is automatic. Do not ask the user for confirmation.
If git commands fail, report that the wiki skill cannot ingest until git access is restored. Do not substitute directory walking.
Export
Trigger on:
export wiki
bundle wiki
archive wiki
one-page wiki
prepare wiki for notebooklm
send wiki to notebooklm
Workflow:
- Select the wiki root from the request. Default to
.wiki; use an explicit root or language-specific root when named
- Check whether
<wiki-root>/index.md exists in the working tree
- If the selected wiki root is missing or clearly incomplete, run ingest first without asking
- Export the live selected wiki from the working tree, not from
HEAD
- Use the bundled zero-dependency CLI:
node skills/git-wiki/scripts/export-wiki-bundle.mjs \
--input-dir <wiki-root>
- Default output is
index-{simple-timestamp}.md in the selected wiki root
- If the user wants a different destination, pass
--output-file <path>
- If the user wants a custom label in the export header, pass
--root-name <name>
- The export must produce:
- a repository/wiki header with generation date
- a table of contents covering every bundled page
- one section per wiki file with selected frontmatter preserved
- explicit file start/end markers so the bundle works as an archive artifact or NotebookLM source
- When the request is specifically about NotebookLM, export first, then hand the produced bundle file to the
notebooklm skill as the source artifact
Export expectations:
- Prefer bundling
<wiki-root>/**/*.md
- Preserve only useful frontmatter fields such as
okf_version, type, title, description, resource, tags, timestamp, status, language, source_paths, and last_commit
- Do not emit Obsidian-style links; if legacy
[[wiki-links]] remain, normalize them to Markdown links or plain text so downstream tools do not need Obsidian semantics
- Strip Obsidian image embeds such as
![[image.png]]
- Keep the output deterministic by sorting files by relative path
- Use a simple timestamp in the default filename, for example
.wiki-fr/index-20260510-143522.md
- Do not treat export as a substitute for ingest; export packages the current wiki, it does not rebuild it
Ingest Priorities
When doing a broad ingest from git-tracked files, build the human entry point first, then add supporting code pages. Work in this order and stop when you have good coverage (typically 10–20 pages for a medium project). Do not let every source file generate a page; the wiki should be selective memory, not a second filesystem.
- Root readme and tracked documentation under
.docs/ and docs/
- Package/build/workspace config (
package.json, pyproject.toml, Cargo.toml, etc.) to determine how the project runs
- Entry points (
main.ts, index.ts, app.py, cmd/, etc.) to explain startup and runtime behavior
- Storage, generated outputs, config, secrets, caches, logs, and persistence boundaries →
<wiki-root>/overview/ or <wiki-root>/entities/
- Core user/system workflows →
<wiki-root>/flows/
- Important moving parts, concepts, and subsystem boundaries →
<wiki-root>/concepts/ or <wiki-root>/features/
- Contracts and fragile areas the reader should avoid breaking →
<wiki-root>/risks/
- API definitions, schemas, and persistence layers →
<wiki-root>/features/ or <wiki-root>/entities/
- Jobs, queues, background workers →
<wiki-root>/features/
- UI structure (if present) →
<wiki-root>/features/
- Tests (summarize behavior expectations and safety nets, don't document every test file)
- System-impactful changes and compatibility lessons visible in git history →
<wiki-root>/decisions/
For large repos (100+ files), focus on depth over breadth: deeply document the 10 most important modules rather than shallowly touching 50.
Query
When asked a project question:
- Select the wiki root from the request. Default to
.wiki; use an explicit root or language-specific root when named
- Read
<wiki-root>/index.md if it exists
- Read relevant wiki pages in the selected root if they exist
- If the selected wiki is missing, the relevant page is missing, or a page is marked stale, verify directly against git-tracked repository source before answering
- Prefer tracked documentation in
.docs/ and docs/ when it is relevant to the question, then confirm against code or config when needed
- Verify against git-tracked repository source when the answer involves specific values (counts, names, configs)
- Answer in the selected wiki's language when the user named a language root, with concise explanation and Markdown links to relevant wiki pages when they exist
- If you created new understanding not yet in the selected wiki root, mention it — the user can ask you to save it
Lint
Trigger on:
lint
lint wiki
check wiki
lint .wiki-fr
check Chinese wiki
Checks:
- OKF conformance errors:
- Root
index.md missing okf_version: "0.1" or the last_commit checkpoint
- Non-reserved
.md concept pages missing parseable YAML frontmatter
- Non-reserved
.md concept pages missing a non-empty type
- Reserved
index.md files that are not root index.md but contain frontmatter
log.md files that contain frontmatter
log.md files whose date headings are not ISO 8601 YYYY-MM-DD
- Contradictions between pages (two pages making conflicting claims)
- Orphan pages with no inbound Markdown links
- Concepts mentioned across multiple pages but lacking their own page
- Stale pages (
status: "stale") that may have drifted from current source
- Missing coverage for major changed modules (files changed since
last_commit with no wiki page)
- Legacy
[[wiki-links]] that should be upgraded to Markdown relative links
- Broken Markdown links where the target page doesn't exist; report these as warnings, not errors, because OKF consumers must tolerate partial bundles
Lint Output Format
## Wiki Lint Report — YYYY-MM-DD
### Errors
- [page] description of malformed frontmatter, missing type, invalid reserved file structure, or contradiction
### Warnings
- [page] description of potential issue
### Suggestions
- description of missing coverage or improvement
### Next Questions
- open questions worth investigating
Do not auto-fix unless explicitly asked.
Writing Guidance
- Write for a smart newcomer, not a maintainer. Use layman's terms first, then add the exact code term only when it helps: "the login check" before "auth middleware", "saved data shape" before "schema", "background task" before "worker"
- Structure pages around the reader's question, then ground the answer in files. Do not lead with a directory tour unless the page is explicitly reference material
- Explain why a file matters in the product or workflow before naming implementation details
- Avoid unexplained acronyms, framework jargon, and internal shorthand. If a technical term is necessary, define it in the same sentence
- Summarize; do not reproduce large code blocks — a few lines of example code is fine, but explain patterns rather than paste implementations
- Use concrete file paths as anchors (
src/api/routes.ts:42)
- Separate facts (directly read from source) from inferences (your interpretation)
- Cross-link related pages with standard Markdown relative links
- Add a
# Citations section when a page makes claims from external material, tracked docs, issues, specs, or other source artifacts that are not obvious from the linked source paths
- Keep pages under ~500 words; create additional pages rather than growing one page long
- Prefer useful coverage over exhaustive coverage — a good wiki is navigable, not encyclopedic
- Do not create a page merely because a source file exists; create a page when it preserves a concept, workflow, decision, risk, or unresolved question a future reader would otherwise rediscover the hard way
Quality Bar
The wiki succeeds when:
<wiki-root>/index.md helps a new reader navigate the project in under 2 minutes
- A newcomer can answer what the project is, why it exists, what happens when it runs, where data is saved, what matters, what not to break, and where to look first
- Answers can start from wiki pages and be verified in code
- The wiki targets OKF v0.1 for generic Markdown/YAML consumers, with the documented root-index checkpoint extension: concept pages have
type, root index.md declares okf_version, links are Markdown, and update history lives in log.md
- Ingest detects changed files automatically using the saved
last_commit
- Lint catches drift before the wiki becomes misleading
1---2name: git-wiki-23description: Build and maintain local code-project wikis under .wiki or language-specific wiki roots such as .wiki-cn and .wiki-fr. Use this skill whenever the user mentions "wiki", "ingest", "refresh wiki", "update wiki", "lint wiki", "check wiki", "document the codebase", "export wiki", "bundle wiki", "archive wiki", or asks a question that can be answered from wiki pages. Also use it when the user asks how something works in the project and a wiki page could capture the answer for future reference.4---56# Project Wiki78Maintain local wikis for a code project under `.wiki` by default, with optional language-specific roots such as `.wiki-cn`, `.wiki-fr`, or an exact user-named wiki directory such as `wiki-cn`.910Source of truth is always the current git-tracked repository files at `HEAD`, including tracked documentation in `.docs/` and `docs/`, not the wiki.11The wiki files themselves may be untracked; read and update the live selected wiki root from the working tree when present.1213## Rules1415* Operate only on git-tracked files and git history16* Ignore staged and unstaged uncommitted changes; ingest and query verification use committed content at `HEAD` only17* Select exactly one wiki root per request. Use `.wiki` by default; use the explicit root or language the user names, such as `.wiki-cn`, `wiki-cn`, `.wiki-fr`, "Chinese wiki", or "French wiki"18* Each wiki root is independent. Do not sync, compare, translate, merge, or copy pages between language roots unless the user explicitly asks19* Exclude all wiki roots from git-based source selection: `.wiki/**`, `.wiki-*/**`, and `wiki-*/**`20* Do not assume any wiki root is git-tracked; use the selected root's current `index.md` checkpoint when it exists21* Target Open Knowledge Format (OKF) v0.1: Markdown files, YAML frontmatter on concept documents, standard Markdown links, reserved `index.md` listings, and reserved `log.md` update history22* Every non-reserved concept page must have parseable YAML frontmatter with a non-empty `type`23* The selected root's `index.md` and `log.md` must be updated on every ingest24* Keep ingest checkpoint metadata in the selected root's `index.md` frontmatter; do not introduce `.wiki/.wiki-state.md` or another hidden state file25* Do not ask the user before ingesting26* Export reads the live working-tree files under the selected wiki root, not the git-tracked repository at `HEAD`27* Do not let every source file generate a page. The wiki should be selective memory, not a second filesystem.2829## Wiki Layout3031Required:3233* `<wiki-root>/index.md` — human entry point and master catalog (tracks last ingest commit for that root only)34* `<wiki-root>/log.md` — chronological update history for the selected wiki root3536Optional (create as needed):3738* `<wiki-root>/overview/` — orientation pages that explain the project, startup path, storage, and reading path39* `<wiki-root>/features/` — one page per significant product capability or implementation area40* `<wiki-root>/decisions/` — one page per system-impactful change, compatibility discovery, or behavior that must not regress41* `<wiki-root>/concepts/` — cross-cutting ideas and patterns42* `<wiki-root>/entities/` — data models, schemas, types43* `<wiki-root>/flows/` — sequences, pipelines, request lifecycles44* `<wiki-root>/risks/` — invariants, compatibility contracts, fragile behavior, and things not to break45* `<wiki-root>/reference/` — code-shaped reference pages when a source path needs focused explanation46* `<wiki-root>/open-questions/` — unresolved findings, missing context, suspected issues, and things needing human review4748### Human understanding structure4950The wiki is for a human to understand the codebase, not for the repository to describe itself. Organize the front door around the reader's questions before the code's folders.5152`<wiki-root>/index.md` must answer these questions, in this order:53541. What is this?552. Get started563. Why does it exist?574. What happens when I run it?585. Where is data saved?596. What are the important moving parts?607. What should I avoid breaking?618. Where do I look first?6263Use these questions as the primary navigation. `features/`, `entities/`, `flows/`, and `reference/` are supporting evidence, not the first mental model.6465The `Get Started` section is for codebase orientation, not a duplicate README. It should give a smart newcomer the first 10 minutes:6667* the main command to run68* required environment or services69* expected successful output70* the first files to read71* one safe first change72* one tempting dangerous change7374When a repo already has setup instructions in `README.md` or `docs/`, link to them and summarize only what helps the reader understand the code.7576### OKF compatibility7778Generated wikis must target OKF v0.1 with one deliberate root-index extension: the bundle root `index.md` keeps frontmatter so the wiki can declare `okf_version: "0.1"` and preserve the `last_commit` ingest checkpoint. Do not add frontmatter to nested `index.md` files. Use `log.md` for update history, not hidden state files.7980Use standard Markdown links with relative paths. Do not create new Obsidian-style `[[wiki-links]]`.8182### Wiki root selection8384* Default wiki root: `.wiki`85* Language-specific roots: prefer `.wiki-<language-code>` when creating a new language wiki, for example `.wiki-cn` for Chinese and `.wiki-fr` for French86* If the user names an exact directory, such as `wiki-cn`, use that exact root instead of normalizing it87* Language roots do not inherit checkpoints, pages, links, or stale status from each other88* When the user asks for a language wiki by language name, write page prose in that language and keep code identifiers, file paths, and API names unchanged8990## Page Conventions9192### Root index.md frontmatter9394The selected root's `index.md` is the human entry point and carries the ingest checkpoint:9596```yaml97---98okf_version: "0.1"99title: "Project Wiki"100language: "<language-code|default>"101last_commit: "<full-sha>"102timestamp: "YYYY-MM-DDTHH:mm:ssZ"103---104```105106`last_commit` is the full git commit SHA at the time of the most recent full-repository ingest for the selected wiki root. This checkpoint lives in the selected root's current `index.md` file whether or not that root is git-tracked. On the next ingest for the same root, prefer this saved `last_commit` to find changed files with `git diff --name-status -M <last_commit> HEAD`.107108If git metadata is unavailable, do not fall back to filesystem scanning. Ingest and lint are unavailable until git access works again.109110Nested `index.md` files, if created, are OKF directory listings and must not have frontmatter. They should group child concepts with Markdown links and short descriptions.111112### log.md update history113114`log.md` records wiki update history for the selected root. It must use newest-first date groups:115116```markdown117# Directory Update Log118119## YYYY-MM-DD120121* **Update**: Updated [Startup Flow](flows/startup-flow.md) from `src/main.ts`.122* **Creation**: Created [Data Storage](overview/data-storage.md).123```124125Use `log.md` for human-readable update history only. Keep the machine checkpoint in root `index.md:last_commit`.126127### Other pages128129```yaml130---131type: "Overview|Feature|Decision|Concept|Entity|Flow|Risk|Reference|Open Question"132title: "Page Title"133description: "One sentence explaining what this page helps the reader understand."134resource: "repo://path/to/source-or-empty"135tags: ["short-tag"]136timestamp: "YYYY-MM-DDTHH:mm:ssZ"137status: "draft|active|stale"138language: "<language-code|default>"139source_paths: []140---141```142143Set `language` to `default` for `.wiki`, `cn` for `.wiki-cn` or `wiki-cn`, `fr` for `.wiki-fr`, and the matching language code for other language-specific roots.144145Use `type` values that are short and self-explanatory. `title`, `description`, `resource`, `tags`, and `timestamp` are OKF-recommended fields; `status`, `language`, and `source_paths` are producer-defined extensions.146147Use `status: "stale"` when the source file has changed significantly since the page was last updated, or when the page describes something that no longer exists. During ingest, pages whose `source_paths` changed since `last_commit` should be updated or marked stale. Do not delete stale pages automatically — mark them and note the drift so the user can decide.148149### Decision pages150151Use `<wiki-root>/decisions/` for system-impactful changes, not routine bug diaries. A decision page must answer:152153* What changed?154* Why did it change?155* What old behavior must not come back?156* What compatibility issue was discovered?157* What lesson should future developers remember?158159Do not create a decision page for every commit. Create one when a change reveals a lasting product, architecture, compatibility, migration, or operational lesson.160161### Open question pages162163Use `<wiki-root>/open-questions/` for unresolved findings, missing context, suspected issues, and things that need human review. State what is known, what is inferred, what evidence is missing, and what decision or verification would close the question.164165### Page naming166167* Use lowercase, hyphenated filenames: `auth-middleware.md`, `user-schema.md`168* Name pages for the human idea first: `login-check.md`, `saved-data-shape.md`, `startup-flow.md`169* Use source-path names only for reference pages or when there is no clearer reader-facing name: `src/api/routes.ts` → `<wiki-root>/reference/src-api-routes.md`170* Use descriptive names for concepts and flows: `<wiki-root>/concepts/request-lifecycle.md`171172### Wiki links173174Use standard Markdown links with relative paths between pages whenever a page references something covered on another page:175176```markdown177See [Startup Flow](../flows/startup-flow.md).178```179180Do not create new `[[page-slug]]` links. When updating an existing wiki, upgrade old links:181182* `[[startup-flow]]` -> `[Startup Flow](../flows/startup-flow.md)`183* `[[startup-flow|how startup works]]` -> `[how startup works](../flows/startup-flow.md)`184185Compute the link target relative to the page being written. Resolve targets by matching the destination filename stem within the selected wiki root; prefer a same-directory match, then a unique match elsewhere. If no target exists yet, use the best expected relative path and let lint report it as a warning rather than blocking OKF consumption.186187## Ingest188189Trigger on:190191* `ingest`192* `ingest [file]`193* `ingest [folder]`194* `ingest wiki-cn`195* `ingest .wiki-fr`196* `refresh wiki`197* `update wiki`198* `update Chinese wiki`199200Workflow:2012021. Select the wiki root from the request. Default to `.wiki`; use an explicit root or language-specific root when named2032. Read `<wiki-root>/index.md` from the working tree if it exists, even when the wiki root is untracked — note `last_commit` from frontmatter204 * Missing `<wiki-root>/index.md` or a missing `last_commit` means there is no prior ingest checkpoint for that root2053. Run `git rev-parse HEAD` to get the current HEAD commit SHA2064. Detect changed files:207 * If `last_commit` is set: `git diff --name-status -M <last_commit> HEAD` and exclude all wiki roots (`.wiki/**`, `.wiki-*/**`, `wiki-*/**`)208 * Use the saved `last_commit` even if the selected wiki root is untracked; do not treat an untracked wiki root as a fresh ingest from `HEAD`209 * Use the git status codes to distinguish added, modified, deleted, and renamed paths when updating wiki pages210 * If no prior ingest: build a broad ingest candidate set from `git ls-files` at `HEAD`, excluding all wiki roots (see Ingest Priorities below)2115. Resolve scope:212 * If a file or folder is specified, prioritize it — limit the tracked candidate set to that scope213 * For a scoped ingest, do not advance `<wiki-root>/index.md:last_commit` unless the scoped ingest also covers every file changed since `last_commit`214 * Otherwise ingest changed files first, then fill in missing coverage2156. Read relevant tracked repository files — understand their role. Select pages by lasting reader value, not by file count.2167. Update or create wiki pages under the selected wiki root using OKF-compatible concept frontmatter and Markdown relative links2178. Scan Markdown files in the selected wiki root and upgrade existing Obsidian-style links to Markdown relative links:218 * Convert `[[slug]]` to `[Title](relative/path.md)`219 * Convert `[[slug|label]]` to `[label](relative/path.md)`220 * Resolve `relative/path.md` from the current page to the target page inside the selected wiki root2219. Mark pages in the selected wiki root for deleted source files as `status: "stale"` with a note in the page body, and update moved or renamed pages based on rename information from git22210. Update `<wiki-root>/index.md`:223 * Always set `timestamp` to the current ISO 8601 datetime224 * Set `last_commit` to the current HEAD SHA only after a full ingest or after processing the complete changed-file set from the previous `last_commit`225 * If a broad ingest stops early after partial coverage, leave `last_commit` unchanged and note in `index.md` that bootstrap coverage is still partial226 * Never discard an existing saved `last_commit` merely because the selected wiki root is untracked22711. Update `<wiki-root>/log.md` with a newest-first `YYYY-MM-DD` entry summarizing created, updated, stale, renamed, and link-migrated pages228229Ingest is automatic. Do not ask the user for confirmation.230231If git commands fail, report that the wiki skill cannot ingest until git access is restored. Do not substitute directory walking.232233## Export234235Trigger on:236237* `export wiki`238* `bundle wiki`239* `archive wiki`240* `one-page wiki`241* `prepare wiki for notebooklm`242* `send wiki to notebooklm`243244Workflow:2452461. Select the wiki root from the request. Default to `.wiki`; use an explicit root or language-specific root when named2472. Check whether `<wiki-root>/index.md` exists in the working tree248 * If the selected wiki root is missing or clearly incomplete, run ingest first without asking2493. Export the live selected wiki from the working tree, not from `HEAD`2504. Use the bundled zero-dependency CLI:251252```bash253node skills/git-wiki/scripts/export-wiki-bundle.mjs \254 --input-dir <wiki-root>255```2562575. Default output is `index-{simple-timestamp}.md` in the selected wiki root2586. If the user wants a different destination, pass `--output-file <path>`2597. If the user wants a custom label in the export header, pass `--root-name <name>`2608. The export must produce:261 * a repository/wiki header with generation date262 * a table of contents covering every bundled page263 * one section per wiki file with selected frontmatter preserved264 * explicit file start/end markers so the bundle works as an archive artifact or NotebookLM source2659. When the request is specifically about NotebookLM, export first, then hand the produced bundle file to the `notebooklm` skill as the source artifact266267Export expectations:268269* Prefer bundling `<wiki-root>/**/*.md`270* Preserve only useful frontmatter fields such as `okf_version`, `type`, `title`, `description`, `resource`, `tags`, `timestamp`, `status`, `language`, `source_paths`, and `last_commit`271* Do not emit Obsidian-style links; if legacy `[[wiki-links]]` remain, normalize them to Markdown links or plain text so downstream tools do not need Obsidian semantics272* Strip Obsidian image embeds such as `![[image.png]]`273* Keep the output deterministic by sorting files by relative path274* Use a simple timestamp in the default filename, for example `.wiki-fr/index-20260510-143522.md`275* Do not treat export as a substitute for ingest; export packages the current wiki, it does not rebuild it276277### Ingest Priorities278279When doing a broad ingest from git-tracked files, build the human entry point first, then add supporting code pages. Work in this order and stop when you have good coverage (typically 10–20 pages for a medium project). Do not let every source file generate a page; the wiki should be selective memory, not a second filesystem.2802811. Root readme and tracked documentation under `.docs/` and `docs/`2822. Package/build/workspace config (`package.json`, `pyproject.toml`, `Cargo.toml`, etc.) to determine how the project runs2833. Entry points (`main.ts`, `index.ts`, `app.py`, `cmd/`, etc.) to explain startup and runtime behavior2844. Storage, generated outputs, config, secrets, caches, logs, and persistence boundaries → `<wiki-root>/overview/` or `<wiki-root>/entities/`2855. Core user/system workflows → `<wiki-root>/flows/`2866. Important moving parts, concepts, and subsystem boundaries → `<wiki-root>/concepts/` or `<wiki-root>/features/`2877. Contracts and fragile areas the reader should avoid breaking → `<wiki-root>/risks/`2888. API definitions, schemas, and persistence layers → `<wiki-root>/features/` or `<wiki-root>/entities/`2899. Jobs, queues, background workers → `<wiki-root>/features/`29010. UI structure (if present) → `<wiki-root>/features/`29111. Tests (summarize behavior expectations and safety nets, don't document every test file)29212. System-impactful changes and compatibility lessons visible in git history → `<wiki-root>/decisions/`293294For large repos (100+ files), focus on depth over breadth: deeply document the 10 most important modules rather than shallowly touching 50.295296## Query297298When asked a project question:2993001. Select the wiki root from the request. Default to `.wiki`; use an explicit root or language-specific root when named3012. Read `<wiki-root>/index.md` if it exists3023. Read relevant wiki pages in the selected root if they exist3034. If the selected wiki is missing, the relevant page is missing, or a page is marked stale, verify directly against git-tracked repository source before answering3045. Prefer tracked documentation in `.docs/` and `docs/` when it is relevant to the question, then confirm against code or config when needed3056. Verify against git-tracked repository source when the answer involves specific values (counts, names, configs)3067. Answer in the selected wiki's language when the user named a language root, with concise explanation and Markdown links to relevant wiki pages when they exist3078. If you created new understanding not yet in the selected wiki root, mention it — the user can ask you to save it308309## Lint310311Trigger on:312313* `lint`314* `lint wiki`315* `check wiki`316* `lint .wiki-fr`317* `check Chinese wiki`318319Checks:320321* OKF conformance errors:322 * Root `index.md` missing `okf_version: "0.1"` or the `last_commit` checkpoint323 * Non-reserved `.md` concept pages missing parseable YAML frontmatter324 * Non-reserved `.md` concept pages missing a non-empty `type`325 * Reserved `index.md` files that are not root `index.md` but contain frontmatter326 * `log.md` files that contain frontmatter327 * `log.md` files whose date headings are not ISO 8601 `YYYY-MM-DD`328* Contradictions between pages (two pages making conflicting claims)329* Orphan pages with no inbound Markdown links330* Concepts mentioned across multiple pages but lacking their own page331* Stale pages (`status: "stale"`) that may have drifted from current source332* Missing coverage for major changed modules (files changed since `last_commit` with no wiki page)333* Legacy `[[wiki-links]]` that should be upgraded to Markdown relative links334* Broken Markdown links where the target page doesn't exist; report these as warnings, not errors, because OKF consumers must tolerate partial bundles335336### Lint Output Format337338```339## Wiki Lint Report — YYYY-MM-DD340341### Errors342- [page] description of malformed frontmatter, missing type, invalid reserved file structure, or contradiction343344### Warnings345- [page] description of potential issue346347### Suggestions348- description of missing coverage or improvement349350### Next Questions351- open questions worth investigating352```353354Do not auto-fix unless explicitly asked.355356## Writing Guidance357358* Write for a smart newcomer, not a maintainer. Use layman's terms first, then add the exact code term only when it helps: "the login check" before "auth middleware", "saved data shape" before "schema", "background task" before "worker"359* Structure pages around the reader's question, then ground the answer in files. Do not lead with a directory tour unless the page is explicitly reference material360* Explain why a file matters in the product or workflow before naming implementation details361* Avoid unexplained acronyms, framework jargon, and internal shorthand. If a technical term is necessary, define it in the same sentence362* Summarize; do not reproduce large code blocks — a few lines of example code is fine, but explain patterns rather than paste implementations363* Use concrete file paths as anchors (`src/api/routes.ts:42`)364* Separate facts (directly read from source) from inferences (your interpretation)365* Cross-link related pages with standard Markdown relative links366* Add a `# Citations` section when a page makes claims from external material, tracked docs, issues, specs, or other source artifacts that are not obvious from the linked source paths367* Keep pages under ~500 words; create additional pages rather than growing one page long368* Prefer useful coverage over exhaustive coverage — a good wiki is navigable, not encyclopedic369* Do not create a page merely because a source file exists; create a page when it preserves a concept, workflow, decision, risk, or unresolved question a future reader would otherwise rediscover the hard way370371## Quality Bar372373The wiki succeeds when:374375* `<wiki-root>/index.md` helps a new reader navigate the project in under 2 minutes376* A newcomer can answer what the project is, why it exists, what happens when it runs, where data is saved, what matters, what not to break, and where to look first377* Answers can start from wiki pages and be verified in code378* The wiki targets OKF v0.1 for generic Markdown/YAML consumers, with the documented root-index checkpoint extension: concept pages have `type`, root `index.md` declares `okf_version`, links are Markdown, and update history lives in `log.md`379* Ingest detects changed files automatically using the saved `last_commit`380* Lint catches drift before the wiki becomes misleading