Ingest an LLM Wiki source

Turn a source into concise, attributable, interconnected wiki pages. The wiki is the maintained knowledge layer; sources/ is the immutable evidence layer.

Before editing

1. Locate the vault by finding .llm-wiki/config.toml.
2. Read wiki-purpose.md, wiki-schema.md, and wiki-agent.md when present. The latter defines vault-specific MUST / MAY / NEVER ingest criteria.
3. Skip material that the agent policy excludes, contains credentials or personal data, or duplicates existing knowledge.
4. If the vault is empty, agree with the user on language, page layout, directory structure, and filename conventions before creating pages.
5. If the material would change established scope, page boundaries, naming, or linking strategy, present the proposed structure before editing. Apply straightforward additions directly.

Workflow

1. Check wiki/, wiki-log.md, and llm-wiki search for prior ingestion of the source or its topics. Re-ingest only changed or newly useful material.

2. Copy raw input to sources/YYYY-MM-DD/, preserving its original name. Add a version suffix if needed. Once saved, never edit that copy. Split large chat logs or collections by date or topic before saving.

3. Extract claims, entities, decisions, open questions, and relationships.

4. Create or merge focused pages in wiki/. Every page needs the fields required by wiki-schema.md; normally this includes:

   ---
   title: Page Title
   description: One-line summary
   aliases: [alternate names]
   tags: [taxonomy tags]
   sources: [YYYY-MM-DD/source.md]
   created: YYYY-MM-DD
   updated: YYYY-MM-DD
   ---
   

   Bug or issue pages also need machine-readable status: open | resolved | wontfix.

5. Merge rather than overwrite. When sources conflict, preserve both claims, identify their sources, and flag the conflict rather than silently choosing one.

6. Add [[wikilinks]] for related entities, including useful not-yet-created pages, and finish each page with a ## Related section.

7. Append a concise ## [YYYY-MM-DD] ingest | … entry to wiki-log.md with pages created or updated.

8. Run llm-wiki sync after the changes.

Quality bar

• Summarize rather than copy source text.
• Keep every claim traceable through sources frontmatter.
• Keep each page about one topic; split pages that become multi-topic.
• Write in the language specified in .llm-wiki/config.toml.

Lint an LLM Wiki

Audit structural integrity and knowledge quality. Read wiki-schema.md first; it is the authority for page types, fields, naming, and tags.

Scan

Inspect all wiki/ pages and sources/ files, then use llm-wiki graph to cross-check the wikilink graph. Report these categories:

• Structural: broken links, orphan pages, wanted pages, missing required frontmatter, missing aliases, naming violations, and duplicate topics.
• Content: conflicting claims, stale pages whose sources changed, unsourced claims, and pages too shallow to be useful.
• Sources: unreferenced or untracked source material and source drift.

Report

Present the findings before changing files unless the user explicitly passed --fix. Use this structure:

## Lint Report — YYYY-MM-DD

### Summary
- Total pages: N | Total sources: N
- Issues: N (critical: X, warning: Y, info: Z)

### Critical
### Warning
### Info

Always write the same result in .llm-wiki/lint-result.yaml with date, summary counts, and issue objects (type, severity, page, detail).

Fixes

With --fix, repair only safe, evidence-preserving issues: add missing frontmatter defaults, repair or remove plainly invalid links, add clearly relevant backlinks, and merge unambiguous duplicates while retaining aliases. Never auto-resolve a contradiction. Do not edit raw files under sources/.

Record fixes and unresolved findings in wiki-log.md. Run llm-wiki sync when changes were made.

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:

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.

Query an LLM Wiki

Answer from the maintained wiki, then capture only durable synthesis that makes future queries more useful.

Workflow

1. Find the vault and read wiki-purpose.md; confirm that the question falls within its intended scope. Read wiki-schema.md for local conventions.
2. Search with llm-wiki search "<question>". Use --bm25-only only when vector search is unavailable or inappropriate. Scan wiki/ for exact terms if needed.
3. Read the matched pages and follow relevant [[wikilinks]] and ## Related sections. Use the graph as context rather than treating search ranking as the answer.
4. Give a direct answer grounded in the pages. Cite pages as [[slug]], state uncertainty, distinguish evidence from inference, and surface conflicts or gaps instead of guessing.
5. If the wiki lacks enough evidence, say so and suggest specific material to ingest. Do not fill gaps from unsaved external knowledge.

When knowledge should compound

Write back only a non-trivial, high-confidence synthesis: for example, a new connection among at least three pages, a resolved contradiction, or a useful comparison absent from all source pages. Do not create a page for a simple lookup or speculative conclusion.

For a durable synthesis, create a focused wiki page with complete frontmatter:

---
title: Synthesis Title
description: One-line summary
tags: [synthesis]
sources: [contributing-page-slugs]
source_type: query-synthesis
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

Link it to the contributing pages, append a query entry to wiki-log.md, and run llm-wiki sync. Do not modify anything under sources/.

Research for an LLM Wiki

Research fills a scoped gap in the wiki, then preserves the evidence and its useful conclusions. It combines query, source collection, and ingestion.

Workflow

1. Read wiki-purpose.md and wiki-schema.md; decline or narrow requests outside the vault's scope.

2. Run the query workflow first to determine what is known and define a precise research question.

3. Gather 5–10 high-quality sources. Prefer primary materials, official documentation, papers, and authoritative recent analysis. Seek independent confirmation for important claims.

4. Save each collected source under sources/YYYY-MM-DD/ before analysis. Include provenance when creating a research note:

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

   Treat files in sources/ as immutable after saving.

5. Apply the ingest workflow to each source: update focused, attributable wiki pages and add wikilinks rather than compiling a detached report only.

6. Present a final report with this structure:

   ## Research Report: Topic
   ### Question
   ### Findings
   ### Sources Added
   ### Wiki Pages Created/Updated
   ### Remaining Gaps
   

7. Create a query-synthesis page only when the cross-source conclusion is genuinely new and well supported. Then append a research entry to wiki-log.md and run llm-wiki sync.

Guardrails

• Keep the research question bounded; list tangents as follow-ups.
• Attribute every material claim to saved sources or cited wiki pages.
• Flag outdated evidence for fast-moving topics.
• Never invent a source, citation, or conclusion.