@mfittko/repo-wiki 0.2.1

package/docs/WHY.md

@@ -0,0 +1,61 @@
+# Why repo-wiki exists
+
+`repo-wiki` applies the LLM Wiki pattern to software repositories: compile repository knowledge into a durable, interlinked wiki instead of asking an LLM to reconstruct the same context from raw files on every question.
+
+This project is inspired by Andrej Karpathy's LLM Wiki concept note. This page is a repo-wiki-specific summary written in this project's own words, not a copy of the external note. For the original source, see:
+
+- Andrej Karpathy, "LLM Wiki": <https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>
+
+## The product lens
+
+Many repository-assistance workflows are ephemeral. A developer or coding agent searches code, reads scattered docs, reconstructs architecture, answers one question, and then loses most of that synthesis to chat history or local context. The next person or agent repeats much of the work.
+
+`repo-wiki` turns repeated investigation into a maintained artifact:
+
+- the Git repository at a pinned commit remains the source of truth;
+- generated wiki pages become the compiled knowledge layer;
+- `.llmwiki/schema.md`, `.llmwiki/config.json`, prompts, and agent pointers define how the wiki should be maintained;
+- `Index.md` routes humans and agents to relevant pages;
+- `Log.md` records ingests, compiles, lint passes, publication events, and future query/file-back events.
+
+The generated wiki does not replace source-level investigation. It is a first navigation layer that helps humans and coding agents start with repository-shaped context, then verify material claims against code, tests, configuration, and validated documentation.
+
+## Why a maintained wiki instead of only search or RAG
+
+Search and retrieval-augmented generation are useful for finding relevant fragments, but they usually perform synthesis at query time. That makes important context easy to lose:
+
+- architecture summaries are rebuilt repeatedly;
+- contradictions between documentation and code may be noticed once and forgotten;
+- useful answers remain in chat instead of becoming repository knowledge;
+- new agents begin from raw files rather than accumulated understanding.
+
+A maintained wiki lets synthesis compound. Module pages, architecture pages, documentation-debt reports, open questions, and future filed-back investigations can be updated as the repository changes. The result is a durable knowledge base that remains inspectable in ordinary markdown and publishable through GitHub Wiki.
+
+## What repo-wiki adds
+
+`repo-wiki` narrows the general LLM Wiki idea to the software-repository domain:
+
+- deterministic scanning and planning over repository files;
+- documentation ingestion with validation and debt reporting;
+- generated GitHub Wiki pages under `.llmwiki/wiki`;
+- lint gates for required pages, links, source metadata, and secret-like content;
+- a publish path to `OWNER/REPO.wiki.git`;
+- a package and CLI intended to work for this repository and for external repositories.
+
+The long-term goal is repository memory infrastructure: developers understand unfamiliar code faster, agents use the wiki before diving into source, maintainers can see documentation drift, and high-value repository answers can become durable wiki pages with provenance.
+
+## Authority model
+
+The generated wiki is derived. When evidence conflicts, `repo-wiki` treats source authority in this order:
+
+1. code at the pinned commit;
+2. tests;
+3. CI, build, and runtime configuration;
+4. generated schemas, route maps, and migrations;
+5. markdown documentation as secondary evidence;
+6. issues, PRs, and comments as contextual evidence only when explicitly ingested;
+7. existing generated wiki pages as derived evidence.
+
+This is why `repo-wiki` includes linting and documentation-debt reporting: the product should compile useful knowledge without turning stale docs or unsupported LLM output into confident generated fiction.
+
+For the full roadmap, layer mapping, and implementation plan, see [PLAN.md](./PLAN.md).

package/docs/plans/agent-integration.md

@@ -0,0 +1,85 @@
+# Epic: Agent Integration
+
+## Summary
+
+Make the generated wiki maximally useful for coding agents by producing optimized context packs, generating agent pointer files, and optionally exposing a query interface or MCP endpoint.
+
+## Architecture
+
+```mermaid
+flowchart TD
+  Wiki[Generated Wiki Pages] --> Pack[Agent-Context-Pack Generator]
+  Wiki --> Pointer[Agent Pointer Generator]
+  Wiki --> Index[Search Index Builder]
+  Pack --> AgentContext[Agent-Context-Pack.md]
+  Pointer --> AgentsFile[AGENTS.md / AGENTS.repo-wiki.md]
+  Index --> Query[repo-wiki query CLI]
+  Index --> MCP[MCP Endpoint]
+  AgentContext --> Agent[Coding Agent]
+  AgentsFile --> Agent
+  Query --> Agent
+  MCP --> Agent
+```
+
+```mermaid
+flowchart LR
+  subgraph Context Pack Contents
+    Arch[Architecture Summary]
+    ModMap[Module Map]
+    Conv[Key Conventions]
+    Pitfalls[Known Pitfalls]
+    Routes[Task Routing Table]
+  end
+  subgraph Agent Reads
+    First[1. Agent-Context-Pack]
+    Then[2. Relevant Module Page]
+    Finally[3. Cross-cutting Pages]
+  end
+  Arch --> First
+  ModMap --> First
+  Conv --> First
+  Pitfalls --> First
+  Routes --> Then
+```
+
+```mermaid
+sequenceDiagram
+  participant Agent as Coding Agent
+  participant MCP as MCP Endpoint
+  participant Graph as Wiki Graph
+  participant Wiki as Wiki Pages
+
+  Agent->>MCP: query("how does auth work?")
+  MCP->>Graph: find related nodes
+  Graph-->>MCP: [Auth-Module, Security-Page, API-Routes]
+  MCP->>Wiki: fetch page content
+  Wiki-->>MCP: page markdown
+  MCP-->>Agent: synthesized answer + sources
+```
+
+## Key Deliverables
+
+- Generate `AGENTS.md` or `AGENTS.repo-wiki.md` pointers in target repos
+- Generate `Agent-Context-Pack.md` optimized for coding agent consumption
+- Context pack includes: architecture summary, module map, key conventions, known pitfalls
+- Optional `repo-wiki query` command for targeted wiki lookups
+- Optional MCP (Model Context Protocol) endpoint for agent tool use
+- Optional local search index over generated wiki
+
+## Success Criteria
+
+- A coding agent reading Agent-Context-Pack.md gains actionable project understanding
+- Agent pointer files direct agents to the wiki without manual configuration
+- Query interface (if implemented) returns relevant wiki content for natural-language questions
+
+## Dependencies
+
+- Upstream: LLM compiler (quality wiki content), production scanner (rich source data)
+- Downstream: None (terminal epic)
+
+## Open Questions
+
+- What format should Agent-Context-Pack.md use for maximum agent utility?
+- Should the MCP endpoint serve raw wiki pages or synthesized answers?
+- How to keep agent pointers in sync with wiki structure changes?
+- Should query use embedding search, keyword search, or both?

package/docs/plans/ci-publishing.md

@@ -0,0 +1,111 @@
+# Epic: CI & Publishing
+
+## Summary
+
+Production-ready GitHub Actions workflows and publishing infrastructure that safely pushes generated wiki content, enforces security policies, and supports bootstrap, reconcile, and incremental post-merge flows.
+
+## Architecture
+
+```mermaid
+flowchart TD
+  Trigger{Trigger} --> |push to main| Incremental[Incremental Mode]
+  Trigger --> |workflow_dispatch| Bootstrap[Bootstrap Mode]
+  Trigger --> |schedule| Refresh[Full Refresh]
+
+  Incremental --> Checkout[Checkout Source]
+  Bootstrap --> Checkout
+  Refresh --> Checkout
+
+  Checkout --> Install[npm ci]
+  Install --> Test[npm test]
+  Test --> FetchWiki[Fetch Existing Wiki State]
+  FetchWiki --> Generate[repo-wiki run]
+  Generate --> DiffReport[Generate Reconcile Diff]
+  DiffReport --> SecGate{Secret Gate}
+  SecGate -->|secrets detected| Block[Block & Alert]
+  SecGate -->|clean| LintGate{Lint Gate}
+  LintGate -->|fail| Block
+  LintGate -->|pass| ReviewGate{Review Required?}
+  ReviewGate -->|sensitive pages or merge conflicts| HumanReview[Human Review]
+  ReviewGate -->|no| Publish[Push to Wiki]
+  HumanReview -->|approved| Publish
+  Publish --> Notify[Status Notification]
+```
+
+```mermaid
+flowchart LR
+  subgraph Token Management
+    App[GitHub App]
+    PAT[Fine-grained PAT]
+    OIDC[OIDC Token]
+  end
+  subgraph Publish Strategies
+    Direct[Direct Push]
+    PR[Wiki PR]
+    Atomic[Atomic All-or-Nothing]
+  end
+  App --> Direct
+  PAT --> Direct
+  App --> PR
+  OIDC --> Atomic
+```
+
+```mermaid
+sequenceDiagram
+  participant GH as GitHub Actions
+  participant Wiki as repo-wiki CLI
+  participant Lint as Lint Gates
+  participant Remote as REPO.wiki.git
+
+  GH->>Wiki: repo-wiki run --mode incremental
+  Wiki-->>GH: generated pages
+  GH->>Lint: validate (secrets, links, structure)
+  Lint-->>GH: pass/fail
+  alt pass
+    GH->>Remote: git push
+    Remote-->>GH: success
+  else fail
+    GH->>GH: upload artifact, notify
+  end
+```
+
+## Key Deliverables
+
+- GitHub Actions workflow for wiki generation on push to main
+- GitHub Actions workflow for manual/dispatch wiki bootstrap
+- Pull request and push verification workflow that runs the TypeScript build and test path before publication-oriented jobs
+- Reconcile-mode workflow for repositories with an existing wiki
+- Token management (GitHub App or fine-grained PAT)
+- Security gate: block publish on secret-like content detection
+- Optional human review gate for sensitive pages (auth, billing, deployment, security)
+- PR-based wiki publishing option (wiki PR instead of direct push)
+- Dry-run diff artifact showing created, updated, preserved, and deleted wiki pages
+- Safe deletion policy that only removes pages owned by repo-wiki
+- Artifact retention for unpublished wiki builds
+- Node dependency caching and TypeScript incremental build caching in CI
+- Status checks and notifications
+
+## Success Criteria
+
+- Wiki auto-updates on merge to main with no manual intervention
+- Pull requests and protected branches can target a build-and-test status check for the canonical `npm run check` path
+- Secrets never reach published wiki pages
+- Untrusted PRs cannot trigger wiki publication
+- Failed lint gates block publication
+- Existing human-owned wiki content is preserved during reconcile publishes
+- Publish logs make page creation, update, preserve, and delete actions auditable
+- Clear audit trail of what was published and when
+
+## Dependencies
+
+- Upstream: Incremental mode (post-merge updates), all lint gates
+- Downstream: None (terminal epic)
+
+## Open Questions
+
+- Should the publisher open a PR against the wiki repo instead of pushing directly?
+- How to handle wiki publication failures (retry, alert, rollback)?
+- Should wiki publication be atomic (all pages or nothing) or incremental?
+- How to manage wiki git history (squash or preserve per-page commits)?
+- Should reconcile mode require an explicit opt-in flag before first publish to an existing wiki?
+- How should the workflow surface preserved human sections and blocked deletes in artifacts?

package/docs/plans/doc-validation.md

@@ -0,0 +1,92 @@
+# Epic: Documentation Validation
+
+## Summary
+
+Implement deep documentation validators that go beyond the current scaffold's conservative checks, enabling reliable detection of stale, contradicted, and unvalidated documentation claims.
+
+## Architecture
+
+```mermaid
+flowchart TD
+  Docs[Markdown Documentation] --> Extract[Claim Extraction]
+  Extract --> Commands[Commands & Scripts]
+  Extract --> EnvVars[Environment Variables]
+  Extract --> FilePaths[File References]
+  Extract --> Routes[API Routes]
+  Extract --> ADRs[ADR Decisions]
+
+  Commands --> V1[Script Validator]
+  EnvVars --> V2[Env Var Validator]
+  FilePaths --> V3[File Path Validator]
+  Routes --> V4[Route Validator]
+  ADRs --> V5[ADR Validator]
+
+  PkgJson[package.json] --> V1
+  CI[CI Workflows] --> V1
+  Config[Config/Schema Files] --> V2
+  Code[Source Code] --> V2
+  Tree[Repo File Tree] --> V3
+  Scanner[Route Extractors] --> V4
+  GitLog[Git History] --> V5
+
+  V1 --> Status{Validation Status}
+  V2 --> Status
+  V3 --> Status
+  V4 --> Status
+  V5 --> Status
+
+  Status --> Validated[Validated ✓]
+  Status --> Unvalidated[Unvalidated ?]
+  Status --> Stale[Stale ⚠]
+  Status --> Contradicted[Contradicted ✗]
+```
+
+```mermaid
+flowchart LR
+  subgraph Strictness Levels
+    Strict[strict: errors block publish]
+    Standard[standard: warnings + errors]
+    Lenient[lenient: warnings only]
+    Off[off: skip validation]
+  end
+  subgraph Output
+    Report[Documentation-Debt-Report.md]
+    OpenQ[Open-Questions.md]
+    LintResult[Lint exit code]
+  end
+  Strict --> LintResult
+  Standard --> Report
+  Standard --> OpenQ
+  Lenient --> Report
+```
+
+## Key Deliverables
+
+- Package script validation against `package.json`
+- Command validation against Makefiles, task runners, and CI workflows
+- Route validation against framework-specific route extractors
+- Environment variable validation against config/schema/code usage
+- File reference validation against the repository tree
+- ADR recency and supersession detection
+- Configurable validation strictness levels
+- Rich Documentation-Debt-Report generation with actionable items
+
+## Success Criteria
+
+- Commands mentioned in docs are verified against actual scripts/CI
+- Environment variables in docs are cross-referenced with code usage
+- File paths in docs are validated against the repo tree
+- ADRs are flagged when superseded or older than threshold
+- False positive rate is low enough that teams don't disable validation
+
+## Dependencies
+
+- Upstream: Production scanner (source cards with scripts, routes, env vars)
+- Downstream: LLM compiler (validated doc cards influence wiki content)
+
+## Open Questions
+
+- How to handle commands that are valid but not in package.json (e.g., global CLIs)?
+- Should validation run against CI workflow definitions or actual CI runs?
+- How to detect ADR supersession without explicit metadata?
+- What false-positive rate is acceptable before teams lose trust?

package/docs/plans/github-action.md

@@ -0,0 +1,113 @@
+# Epic: GitHub Action
+
+## Summary
+
+Provide a reusable GitHub Action that wraps the `repo-wiki` CLI for CI/CD workflows. The action should work without publish credentials (producing local wiki artifacts only), and require explicit credentials and a safe event context for any publish step. Support PR-oriented diff output as a review artifact and enforce the security model that prevents publishing from untrusted pull requests.
+
+## Architecture
+
+```mermaid
+flowchart TD
+  Trigger["workflow_dispatch or push to main"] --> Checkout["Checkout source"]
+  Checkout --> Install["npm ci / npx repo-wiki"]
+  Install --> Run["repo-wiki run --mode bootstrap or incremental"]
+  Run --> Artifact["Upload local wiki as workflow artifact"]
+  Run --> Policy{"Publish credentials<br/>configured?"}
+  Policy -->|no| Done["Keep local wiki / no publish"]
+  Policy -->|yes| SafeEvent{"Safe event context?<br/>(push to main, not PR from fork)"}
+  SafeEvent -->|no| Skip["Skip publish / warn"]
+  SafeEvent -->|yes| Publish["repo-wiki publish --target github-wiki or github-pages"]
+```
+
+```mermaid
+flowchart LR
+  subgraph Action inputs
+    Repo["repo (default: .)"]
+    Mode["mode (bootstrap or incremental)"]
+    Target["publish-target (github-wiki, github-pages, none)"]
+    Token["token (GitHub App or PAT)"]
+    Remote["wiki-remote"]
+    DryRun["dry-run (true/false)"]
+  end
+```
+
+```mermaid
+sequenceDiagram
+  participant PR
+  participant Action
+  participant Wiki
+
+  PR->>Action: pull_request event (fork)
+  Action->>Action: Run scan + compile
+  Action->>PR: Post diff comment (pages that would change)
+  Action-->>Wiki: No publish (untrusted event)
+
+  Note over Action, Wiki: Only push to main triggers publish
+```
+
+## Key Deliverables
+
+- Reusable composite or JavaScript GitHub Action published to the Marketplace or usable via `uses: owner/repo-wiki/.github/actions/wiki@main`.
+- Inputs: `repo`, `mode`, `publish-target`, `token`, `wiki-remote`, `pages-branch`, `pages-path`, `dry-run`.
+- Outputs: `wiki-path` (local artifact path), `pages-changed` (count), `lint-errors` (count).
+- Upload local wiki directory as a workflow artifact regardless of publish step.
+- PR diff comment showing wiki pages that would change (uses `repo-wiki diff`).
+- Publish step runs only on safe event contexts (push to main/default branch, not PRs from forks).
+- Token never exposed in logs or generated wiki pages.
+- Documentation: minimal workflow snippet for adopt-in-5-minutes experience.
+
+## Success Criteria
+
+- A consumer repo can add `repo-wiki` with a workflow snippet under 20 lines.
+- The action works without publish credentials (dry-run / artifact only).
+- Publishing requires explicit credentials and safe event context (not a fork PR).
+- PR diff comment posts the list of pages that would change without publishing.
+- Action inputs are validated before any state-changing step.
+
+## Acceptance Criteria (from PLAN.md)
+
+- A consumer repo can add repo-wiki with a short workflow snippet.
+- The action works without publish credentials.
+- Publishing requires explicit credentials and safe event context.
+
+## Example Workflow
+
+```yaml
+name: Wiki
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  wiki:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: owner/repo-wiki/.github/actions/wiki@main
+        with:
+          mode: bootstrap
+          publish-target: ${{ github.event_name == 'push' && 'github-wiki' || 'none' }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+## Security Policy
+
+- Do not publish from `pull_request` events originating from forks.
+- Use a dedicated GitHub App token or fine-grained PAT for wiki or Pages push.
+- Never expose tokens in generated wiki pages, scan artifacts, logs, or publish summaries.
+- Fail publication on secret-like content (inherits trust-hardening policy).
+
+## Dependencies
+
+- Upstream: all CLI commands, trust hardening, publisher.
+- Downstream: adoption and developer experience (this is the primary adoption surface).
+
+## Open Questions
+
+- Should the action be a composite action (shell steps) or a JavaScript action?
+- Should PR diff comments be posted as new comments or as a check annotation?
+- Should `repo-wiki diff` be a separate command or an option on `run`?

package/docs/plans/incremental-mode.md

@@ -0,0 +1,98 @@
+# Epic: Incremental Mode
+
+## Summary
+
+Implement diff-based wiki maintenance that scans only changed files, identifies affected wiki pages, reconciles those pages with the current remote wiki state, and produces targeted page patches rather than full regeneration.
+
+## Architecture
+
+```mermaid
+flowchart TD
+  PrevCommit[Previous Compiled Commit] --> Diff[git diff base..head]
+  HeadCommit[Current Commit] --> Diff
+  ExistingWiki[Current Wiki Checkout] --> Ownership[Generated Page Ownership Map]
+  Diff --> Changed[Changed Files]
+  Changed --> CardMap[Source Card Mapping]
+  CardMap --> Hierarchy[Bounded Hierarchy Propagation]
+  CardMap --> ImportGraph[Import Graph Lookup]
+  ImportGraph --> Semantic[Semantic Propagation]
+  Hierarchy --> AffectedCards[Affected Source Cards]
+  Semantic --> AffectedCards
+  AffectedCards --> PageMap[Page Frontmatter Mapping]
+  PageMap --> AffectedPages[Affected Wiki Pages]
+  Ownership --> AffectedPages
+  AffectedPages --> Patch[Targeted Page Patching]
+  Patch --> Reconcile[Merge with Existing Wiki Pages]
+  Reconcile --> CrossLink[Cross-link Validation]
+  CrossLink --> DebtReport[Debt Report Update]
+  DebtReport --> Lint[Lint Gates]
+  Lint -->|pass| Publish[Safe Publish]
+  Lint -->|fail| Block[Block & Report]
+```
+
+```mermaid
+flowchart LR
+  subgraph Change Propagation
+    File[Changed File] --> DirectPage[Direct Page]
+    File --> Importer[Importing Modules]
+    Importer --> TransitivePage[Transitive Pages]
+    File --> Test[Related Tests]
+    Test --> TestPage[Testing Strategy Page]
+  end
+```
+
+```mermaid
+stateDiagram-v2
+  [*] --> DetectChanges
+  DetectChanges --> MapToCards
+  MapToCards --> FindAffectedPages
+  FindAffectedPages --> PatchPages
+  PatchPages --> ValidateCrossLinks
+  ValidateCrossLinks --> RunLint
+  RunLint --> Publish: pass
+  RunLint --> FullBootstrap: too many changes
+  Publish --> [*]
+  FullBootstrap --> [*]
+```
+
+## Key Deliverables
+
+- Store previous compiled commit reference
+- Git diff computation (base..head changed files)
+- Changed-file to source-card mapping
+- Affected-page identification via import graph and page frontmatter
+- Bounded hierarchy propagation from touched files to parent aggregate pages whose subtree summaries, page membership, public APIs, runtime behavior, or claims are affected
+- Semantic propagation to cross-cutting pages when dependency, test, route, config, security, data-model, documentation, or similar signals change
+- Targeted page patching (update only affected sections)
+- Existing wiki checkout and page ownership manifest loading
+- Safe reconciliation of mixed human/generated pages during incremental runs
+- Safe deletion of obsolete generated pages that are no longer planned
+- Rename handling for generated pages with stable page identities
+- Re-run cross-link validation after patching
+- Re-run documentation debt report for affected docs
+- Safe publish after lint gates pass
+
+## Success Criteria
+
+- Incremental run touches only pages affected by the diff, bounded hierarchy propagation, or semantic propagation rules
+- Untouched LLM-enriched pages remain byte-stable and do not incur model calls
+- Cross-links remain valid after partial updates
+- Incremental output matches what a full bootstrap would produce for affected pages
+- Untouched human-owned wiki pages remain byte-stable across incremental runs
+- Obsolete generated pages are removed without deleting human-owned content
+- Runtime scales with change size, not repository size
+
+## Dependencies
+
+- Upstream: Production scanner (import graph, affected-page graph), LLM compiler (page patching)
+- Downstream: CI publishing (post-merge incremental runs)
+
+## Open Questions
+
+- How to handle renames and moved files?
+- What triggers a full re-bootstrap vs incremental patch?
+- Should incremental mode track page staleness independently?
+- How to handle transitive dependency changes (A imports B, B changes)?
+- What thresholds should escalate from bounded propagation to full bootstrap, such as broad renames, large dependency graph shifts, or many parent aggregate pages changing?
+- Where should generated-page ownership state live: frontmatter, sidecar manifest, or graph store?
+- When should reconcile mode escalate to manual review instead of auto-merging?

package/docs/plans/karpathy-llm-wiki-alignment.md

@@ -0,0 +1,84 @@
+# Epic: Karpathy LLM Wiki Alignment
+
+## Summary
+
+Make `repo-wiki` a faithful software-repository implementation of Karpathy's LLM Wiki pattern: compile repository knowledge once into a durable, source-grounded wiki artifact that compounds over time, treat the LLM as a wiki maintainer rather than a one-shot summarizer, and validate generated content before it can influence the wiki or be published.
+
+## Operating Model
+
+```mermaid
+flowchart LR
+  subgraph Layers
+    Raw["Raw sources<br/>(Git at pinned commit)"]
+    Wiki["Wiki artifact<br/>(.llmwiki/wiki)"]
+    Schema["Schema<br/>(config, prompts, ownership)"]
+  end
+  subgraph Operations
+    Ingest["Ingest<br/>scan → plan → lint-docs → compile → lint"]
+    Query["Query<br/>read wiki first, verify in source"]
+    Lint["Lint<br/>health, orphans, stale, contradictions"]
+  end
+  Raw --> Ingest
+  Schema --> Ingest
+  Ingest --> Wiki
+  Wiki --> Query
+  Query --> FileBack["Filed-back pages"]
+  FileBack --> Wiki
+  Wiki --> Lint
+  Lint --> Wiki
+```
+
+## Architecture
+
+```mermaid
+flowchart TD
+  Source["Source at pinned commit"] --> Scanner
+  Docs["Markdown docs"] --> DocsLint["Docs linter"]
+  Scanner --> Cards["Source + doc cards"]
+  DocsLint --> Cards
+  Cards --> Planner
+  Planner --> Compiler["LLM or deterministic compiler"]
+  Compiler --> PatchGate["Structured patch gate"]
+  PatchGate --> WikiPages["Wiki pages<br/>(frontmatter + citations)"]
+  WikiPages --> Index["Index.md (agent routing)"]
+  WikiPages --> Log["Log.md (operation log)"]
+  WikiPages --> HealthLint["Health linter"]
+  HealthLint --> Publisher
+```
+
+## Key Deliverables
+
+- `Index.md` and `Log.md` as first-class, parseable operating surfaces.
+- Deterministic log entries for every ingest, compile, lint, query, and publish operation appended to `Log.md`.
+- Wiki page frontmatter with `kind`, `source_commit`, `compiled_at`, `source_paths`, `page_state`, and confidence metadata.
+- Source authority model enforced: code at pinned commit > tests > CI/config > docs > issues.
+- LLM output treated as an untrusted patch that must pass lint and citation gates before writing.
+- Query-and-file-back workflow that allows durable answers to become new wiki pages with provenance.
+- Published wiki as the flagship demo for this repository.
+
+## Success Criteria
+
+- Agents can navigate the wiki without source-file inspection for common questions.
+- `grep '^## \[' .llmwiki/wiki/Log.md | tail -5` returns the last five operations with type and commit.
+- Re-running compilation with the same inputs does not produce noisy index or log churn.
+- Every generated page cites source paths for material claims.
+- The published wiki for this repository is publicly inspectable.
+
+## Acceptance Criteria (from PLAN.md)
+
+- Agents can read `Index.md` first to route to relevant pages.
+- Generated pages include frontmatter suitable for Obsidian, Dataview, GitHub Wiki navigation, and future search.
+- Graph metadata powers both navigation and incremental maintenance.
+- LLM output treated as untrusted until it passes structured patch validation and lint.
+- This repository's own generated wiki is published as the canonical demo.
+
+## Dependencies
+
+- Upstream: deterministic compiler, wiki linter, publisher.
+- Downstream: all epics — this is the product framing that shapes scope decisions across every other plan.
+
+## Open Questions
+
+- How should confidence metadata be represented in local frontmatter while published pages hide or strip it?
+- Which query outputs should be eligible for automatic file-back vs requiring human confirmation?
+- How should private path names or environment-variable names be masked in published wikis?