Codebase to Obsidian Wiki

Convert codebases into structured, navigable Obsidian knowledge graphs through iterative collaboration with the user.

Table of Contents

• Key Principles
• Core Mechanism: State Persistence
• Phase Detection
• Wiki Hierarchy
• Node Types
• Phase Workflows
• Index Paragraph Pattern
• Mermaid Requirements
• Test Coverage (Optional)

---

Key Principles

1. Human-in-the-loop: Never proceed past a checkpoint without user confirmation
2. Incremental persistence: Record every decision immediately to .wiki-progress.md
3. Top-down refinement: Hierarchy emerges through dialogue; user defines levels iteratively
4. Composable narratives: Module narratives are referenceable from higher levels
5. Graceful degradation: For large codebases (50+ units), create stubs first, fill iteratively
6. No line-level tracking: Minimum granularity is function/class/component

---

Core Mechanism: State Persistence

The .wiki-progress.md file captures all decisions immediately after they are made. This enables continuation from any interruption point. After each checkpoint: record the decision, update status fields, log the session action.

---

Phase Detection

On every invocation, determine the current phase:

1. Check: Does wiki exist at target path?
   ├─ NO  → PHASE: Fresh (Planning)
   └─ YES → Check: .wiki-progress.md exists and valid?
            ├─ YES, status: debugging   → PHASE: Debug (Fix)
            ├─ YES, status: complete    → Ask user intent (extend? debug?)
            └─ OTHERWISE                → PHASE: Midway (Continue)

Midway handles all continuation scenarios: valid in-progress state, missing progress file, or malformed progress file. Read whatever state exists (or infer from wiki structure) and continue.

---

Wiki Hierarchy

User-defined depth (not enforced to 3 levels). Work top-down: define higher levels first, approach granularity iteratively.

wiki-root/
├── HOME.md                    # Codebase level (mermaid + index paragraph)
├── .wiki-progress.md          # Progress tracking (hidden)
├── ModuleA/
│   ├── ModuleA.md             # Module narrative (mermaid + index paragraph)
│   ├── node1.md               # Atomic node
│   └── SubModule/             # Optional deeper nesting
│       ├── SubModule.md       # Sub-narrative
│       └── subnode.md
└── ModuleB/
    └── ...

Rules:

• Non-atomic levels: MUST have mermaid graph + index paragraph
• Atomic nodes: NO mermaid required
• Narrative files: Named <Module>.md in their folder
• Minimum granularity: Function, class, or component level (NEVER line numbers)

---

Node Types

Four node kinds exist. See references/templates.md for full frontmatter schemas.

Kind	Description	Source Field
code-bound	1:1 mapping to file/function/class	path + function/class
code-spanning	Concept across multiple files	Multiple path entries
conceptual	No direct code (math, architecture)	Optional related_code globs
external	Third-party dependencies	package + version

---

Phase Workflows

Fresh Wiki (Planning)

STEP 1: Initial Scan

• Scan codebase structure (dirs, key files, package.json/requirements.txt)
• Identify stack and dependencies
• Present findings to user
• CHECKPOINT: "Is this overview accurate?"
• On confirm: Record stack, codebase_path in .wiki-progress.md

STEP 2: Module Definition (Top-Down)

• Propose initial high-level module breakdown
• CHECKPOINT: "Does this grouping make sense?"
  • User can merge, split, rename, nest deeper
• On confirm: Record module structure in .wiki-progress.md

STEP 3: Granularity Calibration

• Pick ONE module, propose atomic breakdown
• CHECKPOINT: "Is this the right atomic level?"
  • Iterate until agreed (minimum: function/class level)
• Apply pattern to remaining modules
• On confirm: Record atomic_granularity in .wiki-progress.md

STEP 4: Configuration Options

• CHECKPOINT: "Include code snippets?" (default: yes)
• CHECKPOINT: "Document tests? If yes, to what granularity?"
  • Options: none | per-module | per-node
• CHECKPOINT: "Custom frontmatter properties to track?"
  • e.g., tested_by, last_reviewed, complexity
• CHECKPOINT: "Batch size per session?" (default: 5 nodes)
• On confirm: Record all options in .wiki-progress.md

STEP 5: Generate Plan

• Create HOME.md with structure
• Finalize .wiki-progress.md with full checklist (status: in-progress)
• CHECKPOINT: "Ready to start? Adjust priority?"

---

Midway Wiki (Continue)

STEP 1: Load State

IF .wiki-progress.md exists and valid:

• Read progress file
• Identify next batch (default: 5 nodes)
• Show user what's next

ELSE (missing or malformed):

• Scan wiki folder structure
• Read HOME.md frontmatter for original settings
• Identify which modules/nodes exist vs. missing
• CHECKPOINT: "Found existing wiki without valid progress tracking. Inferred state: [summary]. Continue from here?"
• Regenerate .wiki-progress.md from inferred state

STEP 2: Document Batch

• Create/update nodes from queue
• Update parent narrative if batch completes a module
• Update .wiki-progress.md after each node

STEP 3: Checkpoint

• CHECKPOINT: "Continue, pause, or adjust scope?"

---

Debug Wiki (Fix)

STEP 1: Diagnosis

• Scan existing wiki structure
• Cross-reference with current codebase
• Identify issues:
  • broken_links: Note references non-existent note
  • orphan_notes: Not linked from any parent
  • stale_notes: Source file no longer exists or was renamed
  • missing_notes: Code exists, no documentation
  • structural: Wrong hierarchy level

STEP 2: Plan Proposal

• Present categorized issue list
• CHECKPOINT: "Which issues to address?"
• Add debug queue to .wiki-progress.md (status: debugging)

STEP 3: Execute

• Fix issues one-by-one
• Update .wiki-progress.md after each fix

STEP 4: Completion

• CHECKPOINT: "All selected issues resolved. Delete progress file or keep for future maintenance?"

---

Index Paragraph Pattern

Non-atomic notes MUST include a narrative paragraph with embedded wikilinks serving as both documentation AND navigation:

## Overview

The Authentication module handles user identity verification and session
management. It consists of [[validateToken]] for JWT verification,
[[refreshSession]] for token renewal, [[logout]] for session termination,
and [[authMiddleware]] which guards protected routes. This module depends
on [[Database]] for user lookups and [[Config]] for secret management.

Narratives are composable: module narratives can be referenced from higher levels (e.g., [[Vision Module|visual perception]] in HOME.md).

---

Mermaid Requirements

All non-atomic levels MUST include a mermaid graph. External dependencies MUST be visually distinguished using CSS class + subgraph.

See references/mermaid-patterns.md for:

• Standard external dependency marking pattern
• HOME level (TB direction) examples
• Module level (LR direction) examples
• Deep nesting patterns
• Cross-module reference notation
• Node shape conventions
• Color-blind friendly styling

---

Test Coverage (Optional)

When user enables test coverage:

• Tests are subsections within existing nodes, NOT separate nodes
• Tests do not help understand code logic; they verify behavior
• Include only when user explicitly requests

## Tests

| Test | Description | Status |
|------|-------------|--------|
| `test_validate_valid_token` | Accepts well-formed JWT | ✅ |
| `test_validate_expired` | Rejects expired tokens | ✅ |

---

References

• references/templates.md - Frontmatter schemas and note templates
• references/mermaid-patterns.md - Diagram patterns and conventions