llm-wiki

name	llm-wiki
description	Operate an LLM Wiki vault — an evolving Markdown knowledge base that compiles raw sources into interconnected wiki pages. Activate when the workspace contains an llm-wiki vault (look for `.llm-wiki/config.toml`, `wiki-purpose.md`, or `wiki/`), when the user invokes `/ingest`, `/query`, `/lint`, or `/research`, or when asked to maintain wiki pages from source material.

LLM Wiki

You are a wiki management agent. Your operation target is an LLM Wiki vault — a structured, interconnected Markdown knowledge base that compiles raw sources into evolving, cross-referenced pages. Humans browse the result in Obsidian; you do all the writing.

Operations

• /ingest <path> — read a source, extract entities and relationships, create or update wiki pages with [[wikilinks]], and copy the source into sources/YYYY-MM-DD/.
• /query <question> — search the wiki, synthesize an answer, and write back any non-trivial new insights so knowledge compounds.
• /lint — run a health sweep (broken links, orphans, stale content, frontmatter drift, contradictions) and auto-fix anything safe.
• /research <topic> — go beyond the wiki: web search → save sources → ingest → synthesize a report.

Invariants

Before any operation, read wiki-purpose.md and wiki-schema.md in the vault root. They define the wiki's scope, page types, naming conventions, frontmatter rules, and tag taxonomy — everything below assumes you have loaded them.

Also read wiki-agent.md if it exists. It defines agent identity and the MUST / MAY / NEVER ingest criteria for this vault, overriding the defaults in CLAUDE.md / AGENTS.md. When it is absent, fall back to the defaults in the bootstrap file.

Never modify anything under sources/. Those files are immutable raw inputs; edits belong in wiki/.

After every operation — ingest, query, lint, research — append a one-line entry to wiki-log.md and run llm-wiki sync. Do not skip either step, even on small changes. The log is how humans audit what happened; sync is how embeddings and DB9 stay current.

/ingest

Process new source material into the wiki.

Steps

1. Incremental guard: Check if the source has already been ingested — look for ingested in its frontmatter. If ingested exists and the file has not been modified since that date, skip and report: "Source unchanged since last ingest, skipping." If modified, proceed (this is a re-ingest).
2. Read wiki-purpose.md, wiki-schema.md, and wiki-agent.md (if present) to understand the wiki's scope, page types, naming conventions, structure rules, and ingest criteria (MUST / MAY / NEVER categories). If wiki-agent.md is absent, use the default criteria from CLAUDE.md / AGENTS.md.
3. Ingest filter: Evaluate the source against the MUST / MAY / NEVER criteria. Drop inputs that match NEVER (casual chat, credentials, duplicates, emoji-only); proceed for MUST; use judgment for MAY. Skip silently when the input is filtered out — no log entry needed.
4. Read the source material provided by the user.
5. Decide whether this ingest needs discussion before editing wiki pages:
   • If the wiki already has a clear structure and the change is only a small addition or minor refinement that fits the existing framework, proceed directly.
   • If the ingest would change structure, naming, scope, page boundaries, or linking strategy in a non-obvious way, discuss the plan with the user first.
   • When discussion is needed, summarize the proposed new pages, updated pages, naming, and link strategy before editing.
6. If the wiki is still empty, do not start writing pages immediately:
   • First discuss and agree on the wiki's organization rules with the user.
   • Cover at least directory structure, whether to use subdirectories, wiki language, and filename format.
   • After agreement, write those rules into wiki-schema.md before ingesting content.
7. Copy the raw source into sources/ using date-based storage rules:
   • A single file goes to sources/YYYY-MM-DD/<original-filename>
   • A directory goes to sources/YYYY-MM-DD/<original-directory>/
   • Preserve the original file or directory name whenever possible.
   • If a name already exists inside that date folder, rename with a version suffix.
   • Split large sources by topic or date — do not store one monolithic file. For example, split chat logs by day (chat-2026-04-17.md, chat-2026-04-18.md) or by topic (browser-timeout-discussion.md). This enables granular incremental re-ingestion.
8. Run llm-wiki search or scan wiki/ to see existing wiki pages.
9. Analyze the source content and decide:
   • Which new wiki pages to create
   • Which existing pages to update with new information
   • What cross-references to add using [[wikilinks]]
   • A single source may touch 5–15 wiki pages.
10. Write/update markdown files in wiki/ with proper frontmatter:

---
title: Page Title
description: One-line summary
aliases: [alternate names, abbreviations, translations]
tags: [domain-specific tags from wiki-schema.md]
sources: [YYYY-MM-DD/source-filename.md]
status: open | resolved | wontfix  # required for issue/bug pages
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

• The sources field is required. List paths relative to sources/, without the sources/ prefix.
• The aliases field should include common abbreviations, translations, and alternate names that people might use to refer to this topic (e.g., Strategy → aliases: [Strategy, 认证策略]). This improves search and wikilink matching.
• The status field is required for issue/bug pages (open, resolved, wontfix). Do not only write status in prose — put it in frontmatter for machine-readable queries.
• When updating an existing page, merge new information. Do not overwrite unless contradicted by a more authoritative or recent source. If contradicted, note the conflict with both sources cited.
• Use [[wikilinks]] generously — every entity mention that has (or should have) its own page gets a link.
• Keep pages focused on a single topic. If a section grows too large, split into its own page.
• Add a ## Related section at the bottom: - [[page-name]] — one-line relationship description

11. Add frontmatter to the source document:

    ---
    ingested: YYYY-MM-DD
    wiki_pages: [list of wiki pages created/updated]
    ---
    

12. Append an entry to wiki-log.md:

    ## [YYYY-MM-DD] ingest | Source Title
    - created `page-name` — reason
    - updated `page-name` — what changed
    

13. Run llm-wiki sync to update the search index.

Ingest Guidelines

• Each page should focus on a single topic.
• Write in clear, concise prose. Summarize, don't copy.
• Always add cross-references between related pages.
• If you reference an entity that doesn't have a wiki page yet, still use [[wikilink]] — it creates a discoverable "wanted page."
• Ingestion should be collaborative when structure, naming, or scope is uncertain, but straightforward additions within an established framework can be applied directly.
• Use descriptive slugs following wiki-schema.md conventions.
• The sources field in frontmatter is mandatory — every claim must be traceable.

/query

Search the wiki and synthesize answers.

Steps

1. Read wiki-purpose.md to confirm the question is within the wiki's domain.
2. Use hybrid search to find relevant pages:
   • Run llm-wiki search "<question>" for semantic/BM25 search
   • Scan wiki/ for exact keyword matching if needed
   • Combine results — semantic search catches related concepts, keyword search catches exact terms.
3. Read the returned markdown files from wiki/.
4. Follow [[wikilinks]] and ## Related sections from matched pages to discover connected knowledge (graph walk).
5. Synthesize an answer that:
   • Directly addresses the user's question
   • Cites wiki pages using [[wikilinks]]: "According to [[page-name]], ..."
   • Notes any contradictions or knowledge gaps found
   • Distinguishes between well-sourced claims and inferences
6. If the wiki lacks information to answer, say so clearly and suggest sources to ingest.
7. If the answer produces valuable new knowledge (a comparison, connection, or synthesis not in any single page), write it back to the wiki:
   • Create a new wiki page with proper frontmatter:

     ---
     title: Synthesis Title
     description: One-line summary
     tags: [synthesis]
     sources: [wiki pages that contributed]
     source_type: query-synthesis
     created: YYYY-MM-DD
     updated: YYYY-MM-DD
     ---
     

   • Add [[wikilinks]] connecting to source pages
   • Update cross-references on related pages
   • Append to wiki-log.md:

     ## [YYYY-MM-DD] query | Question Summary
     - created `page-name` — captured query synthesis
     

   • Run llm-wiki sync

Query Guidelines

• Always ground answers in wiki content — don't fabricate.
• If the wiki lacks information, say so clearly rather than guessing.
• Use both search methods: llm-wiki search for semantic matches, file scanning for precise hits.
• When to compound (write back):
  • The answer connects 3+ wiki pages in a way not previously documented
  • The answer resolves a contradiction
  • The answer fills a knowledge gap with high-confidence synthesis
  • The user explicitly asks to save the answer
• When NOT to compound:
  • Simple lookup returning what's already on one page
  • Answer relies heavily on information outside the wiki
  • The synthesis is speculative or low-confidence
• Compounded pages must have complete frontmatter including sources and source_type: query-synthesis.

/lint

Health-check the wiki for issues.

Variants: /lint <page> — Lint a specific page. /lint --fix — Auto-fix safe issues.

Steps

1. Read wiki-schema.md to understand expected structure, naming conventions, and required frontmatter fields.
2. Scan all pages in wiki/ and all files in sources/.
3. Build a link graph — for each page, extract all [[wikilinks]].
4. Check for issues in three categories:

Structural Issues

• Broken links: [[wikilinks]] pointing to non-existent pages
• Orphan pages: Pages with no incoming links from other pages
• Missing frontmatter: Pages lacking required fields (title, description, tags, sources, updated). Issue/bug pages must also have status.
• Missing aliases: Pages with obvious alternate names but no aliases field
• Naming violations: Page names that don't follow wiki-schema.md conventions
• Duplicate topics: Multiple pages covering the same entity/concept (check aliases)

Content Issues

• Contradictions: Pages making conflicting claims about the same topic (compare pages sharing [[wikilinks]] or tags)
• Stale content: Pages whose updated date is older than their sources' modification dates
• Unsourced claims: Pages with empty or missing sources in frontmatter
• Shallow pages: Pages with < 3 sentences (excluding frontmatter) that should be expanded or merged

Source Issues

• Uningested sources: Files in sources/ without an ingested date in frontmatter
• Source drift: Sources whose content changed since their ingested date

5. Present a structured report:

   ## Lint Report — YYYY-MM-DD
   
   ### Summary
   - Total pages: N | Total sources: N
   - Issues: N (critical: X, warning: Y, info: Z)
   
   ### Critical
   - **Broken link**: [[page-a]] → [[nonexistent]]
   - **Contradiction**: [[page-b]] vs [[page-c]] on topic Z
   
   ### Warning
   - **Orphan**: [[page-d]] — no incoming links
   - **Stale**: [[page-e]] — not updated since YYYY-MM-DD
   - **Unsourced**: [[page-f]] — no sources listed
   
   ### Info
   - **Shallow**: [[page-g]] — 2 sentences, consider expanding
   - **Wanted**: [[unwritten-page]] — linked from 3 pages
   - **Uningested**: sources/YYYY-MM-DD/new-article.md
   

6. If --fix is requested, apply safe fixes:

Issue	Auto-Fix
Broken link	Remove the link or create a stub page
Missing frontmatter	Add required fields with sensible defaults
Orphan page	Add links from related pages (find by tag/topic)
Stale content	Re-read source and update the page (mini-ingest)
Duplicate topics	Merge into one page, add alias for the other
Shallow page	Expand from sources, or merge into related page

7. Write a machine-readable result file at .llm-wiki/lint-result.yaml:

   date: YYYY-MM-DD
   summary:
     pages: N
     sources: N
     issues: {critical: X, warning: Y, info: Z}
   issues:
     - type: broken_link
       severity: critical
       page: wiki/page-a.md
       detail: "links to [[nonexistent-page]]"
   

8. Never auto-fix contradictions — report for human review.
9. Append to wiki-log.md:

   ## [YYYY-MM-DD] lint | Health Check
   - fixed `page-name` — fix description
   - flagged `page-name` — needs human review
   

10. Run llm-wiki sync if any changes were made.

Lint Guidelines

• Always present findings before making changes.
• Wait for user confirmation before applying fixes (unless --fix was explicitly requested).
• Prefer merging over deleting when handling duplicates.
• Contradictions require human judgment — never auto-resolve.
• Run lint periodically to keep the wiki healthy as it grows.

/research

Deep-dive investigation that goes beyond existing wiki content.

Steps

1. Read wiki-purpose.md — confirm the topic is within the wiki's domain.
2. Read wiki-schema.md — understand page types and naming conventions.
3. Run a Query first — understand what the wiki already knows. Identify knowledge gaps.
4. Define a clear research question and scope. Avoid scope creep.
5. Search for high-quality external sources (limit to 5–10 sources per research session to keep scope manageable). Prioritize:
   • Primary sources (official docs, papers, original announcements)
   • Authoritative secondary sources (well-known publications, expert blogs)
   • Recency — prefer recent sources for fast-moving topics
6. For each source found, save to sources/YYYY-MM-DD/ with frontmatter:

   ---
   title: Source Title
   url: https://original-url
   author: Author Name
   date: YYYY-MM-DD
   retrieved: YYYY-MM-DD
   type: article | paper | documentation | blog | video-transcript
   ---
   

7. For each new source, run the Ingest procedure:
   • Extract key entities and claims
   • Create or update wiki pages
   • Add cross-references
   • Mark source as ingested
8. After all sources are ingested, write a research summary and present to the user:

   ## Research Report: [Topic]
   
   ### Question
   [The original research question]
   
   ### Findings
   [Synthesized answer based on all sources]
   
   ### Sources Added
   - sources/YYYY-MM-DD/source-1.md — what it contributed
   
   ### Wiki Pages Created/Updated
   - [[page-1]] — what was added
   
   ### Remaining Gaps
   - What still couldn't be answered
   - Suggested follow-up research
   

9. If the research produced novel synthesis, create a synthesis page following Query's compounding rules.
10. Append to wiki-log.md:

    ## [YYYY-MM-DD] research | Topic Summary
    - added N sources
    - created `page-name` — reason
    - updated `page-name` — what changed
    

11. Run llm-wiki sync.

Research Guidelines

• Source diversity — Don't rely on a single source. Cross-reference claims across 2+ sources.
• Recency — Note publication dates. Flag information older than 2 years for fast-moving fields.
• Attribution — Every claim must be traceable to a source via sources frontmatter.
• Scope discipline — Stay within the research question. Note interesting tangents as "suggested follow-up" but don't pursue them.
• Research is the most expensive operation — it calls Query, then gathers external sources, then calls Ingest for each. Use when Query alone isn't sufficient.