Wiki Structure¶

Every compiled kompend wiki comes with three auto-generated pages that serve as the entry point, activity record, and thematic overview.

index.md¶

Generated after every compile — a table of contents with wiki statistics.

Location: {output_dir}/index.md

Structure:

# Wiki Index

## Summary

- **Sources:** 12
- **Articles:** 47
- **Total words:** 12,345
- **Last compile:** 2026-06-07 14:30 UTC

## Topics

`attention` `transformer` `bert` `nlp` `sequence-modeling`

## Table of Contents

1. [[attention|Attention]]
2. [[transformer|Transformer]]
3. [[bert|BERT]]
...

Statistics¶

Stat	Source	Description
Sources count	`wiki.metadata.source_count`	Number of source files
Article count	`len(wiki.nodes)`	Number of compiled pages
Total words	Sum of `node.content`	Word count across all pages
Last compile	`datetime.utcnow()`	Timestamp of this compile
Health score	`wiki.quality_score`	Quality eval score (if N2 active)

Topics cloud¶

If the compiled wiki has metadata with a topics list, up to 30 topics are shown as inline code tags. Topics are sourced from the compilation pipeline and may include keywords extracted by the LLM.

log.md¶

Append-only activity journal — never overwritten.

Location: {output_dir}/log.md

Structure:

## [2026-06-07T14:30:00Z] compile | 3 source(s) → 12 page(s)
- Sources: attention.pdf, transformer.pdf, bert.pdf
- Created: [[self-attention]], [[multi-head-attention]]

Each entry includes:

ISO 8601 timestamp
Operation type (compile)
Source-to-page counts
Source names
Links to created pages (first 20, then ... and N more)

Note: log.md grows over time. It is append-only — entries from previous compiles are preserved. The file is intended for human review and may be truncated manually if it becomes too large.

overview.md¶

LLM-generated thematic summary — on by default; pass --no-synthesize to skip.

Location: {output_dir}/overview.md

Structure:

# Wiki Overview

This wiki covers the field of natural language processing with a focus on
transformer architectures. Key themes include attention mechanisms,
positional encoding, and pre-training objectives...

**Prominent concepts:** self-attention, multi-head attention, BERT, GPT
**Notable relationships:** Attention is the core of all transformer variants

When is it generated?¶

Generated by default (use --no-synthesize to skip)
Requires the LLM client (Q12/Q13) to be wired
If the LLM is unavailable, a message is shown and the file is skipped
Regenerated from scratch each compile (never appended)

Prompt template¶

The LLM is prompted with up to 10 source texts (first 2000 chars each) and asked to produce 2-3 paragraphs covering:

The main domain and key themes
Prominent entities and concepts
Notable relationships or open questions

File listing¶

After a full compile+synth, your output directory looks like:

project/
├── index.md               # Vault-root hub → wiki catalog (portable entry point)
├── sources/               # Raw + captured + distilled sources (user-owned)
│   ├── _captured/         # capture/learn output
│   └── _distilled/        # distill output
├── attachments/           # Durable media — per-source attachments + images
│                          # copied out of .kompend for wiki page embeds;
│                          # each page embeds the figures of ITS sources
├── wiki/                  # Compiled wiki (default: wiki/, resolved from --wiki-dir)
│   ├── index.md           # Portable catalog — links EVERYTHING the wiki generates
│   ├── log.md             # Activity journal (appended, never overwritten)
│   ├── overview.md        # LLM summary (if --synthesize)
│   ├── references.md      # Corpus sources + cited works not in corpus (always present)
│   ├── quality.md         # Claim verification summary (if a WiCER pass ran)
│   ├── summaries/         # One page per ingested source (assets, citations, backlinks)
│   ├── concepts/…         # Concept/comparison pages, routed by kind
│   ├── entities/…         # Entity pages (standards, orgs, products, people)
│   └── *.md               # Root-level pages (overview, procedures, sections)
├── exported/              # Full-source markdown exports — `kompend sources export`
│                          # without OUTPUT lands here (on demand, reference only)
└── .kompend/                 # Derived state ONLY — never required to read the wiki
    ├── kompend.db            # Single non-vector store (tier state, caches, assets,
    │                      #   references, verification, memory, attachments, …)
    ├── cache/             # Extracted images + normalized copies (regenerable)
    ├── vectors/           # Vector store sidecar (if compile.index on — default)
    └── memory.db          # Zvec query-memory collection (regenerable)

Markdown-only invariant¶

The wiki is complete in its generated pages; .kompend/ is derived state.

Every fact an LLM needs is reachable by following markdown links from wiki/index.md (concepts, references, summaries, quality). Deleting .kompend/ loses only accelerators — the wiki still reads, renders, and answers queries:

kompend query / wiki_query (MCP) build the wiki from the generated wiki/*.md files; no .kompend/ state is required.
Without the optional vector sidecar, query falls back to keyword search over the same pages — same corpus, lower recall on paraphrase.
Wiki pages never reference .kompend/ (a structural lint rule enforces this); embedded images are copied into attachments/<source-slug>/ at write time. A page embeds the figures of the sources its provenance names; the slug is derived from the image's own source, and an image that matches no provenance entry is dropped rather than linked. Copies no page references any more are reported by the unreferenced-attachments rule and removed with --fix-destructive.

exported/ holds on-demand full-source dumps (kompend sources export, default target when OUTPUT is omitted). They are reference material, linked from the per-source summary page — never part of the compiled wiki.

Input vs output: where files land¶

The directory split reflects the pipeline's directionality — sources/ is where inputs to be processed live, wiki/ is where finished artifacts land:

Command	Lands in	Role	Organize?
`capture`, `learn`	`sources/_captured/`	Raw input — the next `compile` parses, chunks, and resolves these like any other source	🚫 Protected — organize leaves them in place
`distill`	`sources/_distilled/`	Input — distilled pages are folded into the compiled wiki by the next `compile`	🚫 Protected — organize leaves them in place
`compile`	`wiki/`	Output — finished compiled wiki pages	—
`write`	`wiki/write/`	Output — a finished publication page synthesized from cached sources; not re-parsed on subsequent compiles	—

Crossing the two would break the pipeline contract: a captured note in wiki/ would never be compiled (compile scans sources/, not wiki/), and a written page in sources/ would be pointlessly re-processed through parse → chunk → resolve → compile on every run. kompend organize treats _captured/ and _distilled/ as protected tool-managed zones — it never flattens or relocates them.

```text