Feature Spec: Repo-Agnostic LLM Code Wiki

1. Summary

We are building a CLI-first LLM code wiki that can connect to any repository, regardless of size, language mix, or architectural complexity, and convert that repository into a persistent markdown knowledge base.

The product goal is:

• Connect to a repo once
• Scan its structure into stable source evidence
• Compile that evidence into durable markdown wiki pages
• Build deterministic local indexes from those pages
• Search and navigate the wiki offline without requiring a model at query time
• Rebuild or update the wiki incrementally when the repo changes

This is not a browser product and not a PR overlay system. It is a local knowledge layer for any codebase.

The system should behave like a compiler:

• Raw source is the input
• Wiki pages are the compiled artifact
• Deterministic indexes are the retrieval layer
• The model is used only during build or rebuild

---

2. What We Are Trying To Achieve

We want a developer to point the CLI at any repo and get a usable local knowledge base that answers questions like:

• What does this package do?
• Which API routes exist?
• Which CLI commands drive this flow?
• Which service layer handles this endpoint?
• What files define this feature?
• What pages are related to this concept?

The wiki should be generated from source, not manually authored. It should still work when the repo is very large, split across many languages, modularized into packages or services, or organized as frontend, backend, CLI, tooling, or monorepo code.

The most important product behavior is continuity:

• Once connected, the repo stays connected
• Once built, the local wiki stays searchable
• Once the source changes, the wiki is updated in place
• Search continues against the new output without reinitializing the system

---

3. Repository Reality We Are Targeting

This product is intentionally not tied to a specific repository. It must adapt to whatever repo it is pointed at.

That means the wiki generator must identify boundaries dynamically instead of depending on hardcoded paths.

Possible surfaces include:

• Application entrypoints
• Route registries
• Command registries
• Service or usecase modules
• Shared packages
• Configuration manifests
• Build and deployment files
• Tests that imply ownership or behavior

The exact shapes vary by repo, so the system must infer canonical pages from source evidence instead of assuming a fixed structure.

---

4. Core Product Shape

Generated markdown pages

• One page per meaningful architecture boundary
• Human readable, machine parseable
• Backed by frontmatter and explicit source references

Deterministic indexes

• Document registry
• Relationship graph
• Inverted search index
• Build metadata

A local CLI

• init, build, search, ask, related, status, validate, rebuild

Incremental update behavior

• Detect source changes, regenerate impacted pages, refresh indexes, preserve stable IDs

Validation and traceability

• Broken source references visible, relationship targets checked, confidence and uncertainty exposed

---

5. Exact POC Goals

---

6. What The Factory Needs To Build

A. Repo connection and build state

• Detect repo root, record current branch and commit
• Persist .codewiki state, store last built commit
• Remember output location and config

B. Wiki generation engine

• Discover candidate surfaces, build evidence bundles
• Prompt the model to generate strict markdown pages
• Validate against a fixed schema, write pages into a stable wiki folder

C. Deterministic graph and indexes

• Parse frontmatter, headings, tags, aliases, source references
• Build documents.json, graph.json, inverted-index.json

D. Local search and navigation

• Full-text search over generated pages and indexes
• Deterministic weighted ranking, one-hop related-page traversal
• Explanation of why a page matched

E. Rebuild/update pipeline

• Detect changes since last build, identify impacted pages
• Regenerate only what changed, refresh graph and search indexes

---

7. What This POC Is Not

• A browser-based wiki UI
• A live PR overlay system
• A semantic vector search product
• A chat assistant that answers from scratch every time
• A replacement for code search in the repo
• A general documentation platform
• A design system or content management system

---

8. Required User Flow

codewiki init         → connect repo, write config
codewiki build        → scan, generate pages, build indexes, validate
codewiki search <q>   → search local markdown, no model call
codewiki ask <q>      → search with explanations, no model call
codewiki related <id> → one-hop graph neighbors
codewiki status       → build commit, page counts, validation state
codewiki validate     → check frontmatter, source refs, targets, IDs
codewiki rebuild      → update in place from latest committed state

---

9. Required Generated Knowledge Structure

Page types: app, package, API, service, command, flow, config, concept

Every page must have: Stable ID · Type · Title · Aliases · Tags · source_files · Entrypoints · Relation fields · search_terms · last_built_commit · Confidence · Open questions

---

10. Deterministic Design Rules

Relationship vocabulary (fixed): imports · depends_on · calls · routes_to · implements · owns · related_to · tests

Build rules:

• Same input tree → same IDs and indexes
• Model output must be normalized before writing
• Uncertainty must be visible rather than hidden

Update rules:

• Rebuild from latest committed state or configured branch head
• Preserve stable IDs for unchanged pages
• Keep graph and search continuity intact

---

11. Success Criteria

1. Connect any repo
2. Build the wiki from source
3. Search the generated markdown locally
4. Inspect relations between pages
5. Update the wiki after repo changes
6. Keep using the same local workflow without reinitializing