wikifier 0.3.0__py3-none-any.whl

wikifier/__init__.py

@@ -0,0 +1,9 @@
+"""
+Wikifier - Agent-first, zero-dependency, self-maintaining codebase documentation system.
+
+This package provides cross-platform access to the Wikifier tool.
+"""
+
+__version__ = "0.3.0"
+__author__ = "Aron Amos"
+__license__ = "MIT"

wikifier/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

wikifier/cli.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""
+Wikifier CLI Entry Point
+
+Detects the current platform and launches the appropriate Wikifier script.
+This allows users to run `wikifier` after `pip install wikifier`.
+"""
+
+import os
+import sys
+import platform
+import subprocess
+from pathlib import Path
+
+def get_script_path() -> Path:
+    """Return the path to the correct platform-specific Wikifier script."""
+    package_dir = Path(__file__).parent
+    scripts_dir = package_dir / "scripts"
+
+    system = platform.system().lower()
+
+    if system == "windows":
+        # Prefer PowerShell on Windows
+        ps_script = scripts_dir / "wikifier.ps1"
+        if ps_script.exists():
+            return ps_script
+        return scripts_dir / "wikifier.bat"
+    else:
+        # Linux, macOS, etc.
+        return scripts_dir / "wikifier.sh"
+
+
+def main():
+    script_path = get_script_path()
+
+    if not script_path.exists():
+        print(f"Error: Could not find Wikifier script at {script_path}", file=sys.stderr)
+        sys.exit(1)
+
+    system = platform.system().lower()
+
+    if system == "windows":
+        # On Windows, use PowerShell to execute .ps1 or fall back to .bat
+        if script_path.suffix == ".ps1":
+            cmd = ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", str(script_path)] + sys.argv[1:]
+        else:
+            cmd = [str(script_path)] + sys.argv[1:]
+    else:
+        # Unix-like: execute the shell script directly
+        cmd = [str(script_path)] + sys.argv[1:]
+
+    try:
+        result = subprocess.run(cmd, check=False)
+        sys.exit(result.returncode)
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except Exception as e:
+        print(f"Failed to launch Wikifier: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

wikifier/scripts/wikifier.bat

@@ -0,0 +1,27 @@
+@echo off
+REM wikifier.bat — Wikifier v0.3 Windows launcher
+REM Delegates to PowerShell for the real implementation (zero external deps).
+
+setlocal
+
+set SCRIPT_DIR=%~dp0
+
+echo Wikifier v0.3 (Windows)
+echo.
+
+if exist "%SCRIPT_DIR%wikifier.ps1" (
+    powershell -NoProfile -ExecutionPolicy Bypass -File "%SCRIPT_DIR%wikifier.ps1" %*
+) else (
+    echo [WARNING] wikifier.ps1 not found.
+    echo Falling back to basic help...
+    echo.
+    echo Recommended: Use WSL / Git Bash / MSYS2 and run ./wikifier.sh directly.
+    echo Full cross-platform support is in wikifier.sh (bash).
+    echo.
+    echo Available via PowerShell:
+    echo   .\wikifier.ps1 help
+    echo   .\wikifier.ps1 check-changes
+    echo   .\wikifier.ps1 record-change "path\to\file" "reason here"
+)
+
+endlocal

wikifier/scripts/wikifier.ps1

@@ -0,0 +1,166 @@
+# wikifier.ps1 — Wikifier v0.3 PowerShell implementation (Windows)
+# Zero-dependency. Mirrors the most important commands from wikifier.sh
+
+param(
+    [Parameter(Position=0)]
+    [string]$Command = "help",
+
+    [Parameter(ValueFromRemainingArguments=$true)]
+    [string[]]$Arguments
+)
+
+$ErrorActionPreference = "Stop"
+$WikifierRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
+$Staging = Join-Path $WikifierRoot ".wikifier_staging"
+$JournalRoot = Join-Path $WikifierRoot "journal"
+$HealthFile = Join-Path $WikifierRoot "file_health.md"
+$PendingFile = Join-Path $WikifierRoot "pending_updates.md"
+$LastCheck = Join-Path $Staging ".last_check"
+$Monitored = Join-Path $WikifierRoot "monitored_paths.txt"
+$Excludes = Join-Path $WikifierRoot "exclude_patterns.txt"
+
+New-Item -ItemType Directory -Path $Staging -Force | Out-Null
+
+function Write-Log { param([string]$m) Write-Host "[wikifier] $m" }
+function Write-Err { param([string]$m) Write-Host "[wikifier ERROR] $m" -ForegroundColor Red }
+
+function Get-Timestamp { Get-Date -Format "yyyy-MM-dd HH:mm:ss" }
+
+function Upsert-Health {
+    param([string]$file, [string]$status, [string]$reason = "")
+    $now = Get-Timestamp
+
+    if (-not (Test-Path $HealthFile)) {
+        @"
+# Documentation Health Matrix
+
+| File | Status | Last Updated | Reason / Intent |
+|------|--------|--------------|-----------------|
+"@ | Set-Content $HealthFile
+    }
+
+    $content = Get-Content $HealthFile -Raw
+    $pattern = [regex]::Escape("| $file |")
+
+    if ($content -match $pattern) {
+        $newLine = "| $file | $status | $now | $reason |"
+        $content = [regex]::Replace($content, "\| $file \| .*? \| .*? \| .*? \|", $newLine, 1)
+        Set-Content $HealthFile $content
+    } else {
+        Add-Content $HealthFile "| $file | $status | $now | $reason |"
+    }
+}
+
+function Add-Pending {
+    param([string]$file, [string]$msg)
+    if (-not (Test-Path $PendingFile)) { " # Pending Updates" | Set-Content $PendingFile }
+    Add-Content $PendingFile "- $file`: $msg"
+}
+
+function Write-Journal {
+    param([string]$action, [string]$file, [string]$reason)
+    $datePath = Join-Path $JournalRoot (Get-Date -Format "yyyy/MM")
+    New-Item -ItemType Directory -Path $datePath -Force | Out-Null
+    $dayFile = Join-Path $datePath ("{0:dd}.md" -f (Get-Date))
+    @"
+
+## [$(Get-Timestamp)] $action
+**File:** $file
+**Reason:** $reason
+
+"@ | Add-Content $dayFile
+}
+
+# ---------------- Commands ----------------
+
+switch ($Command.ToLower()) {
+    "help" {
+        Write-Host @"
+Wikifier v0.3 (PowerShell/Windows)
+
+Core:
+  check-changes
+  record-change <file> "<reason>"
+  mark-green <file>
+  health
+  monitor
+  update-maps
+  init
+
+See wikifier.sh for the full Unix implementation (recommended on WSL/macOS/Linux).
+"@
+    }
+    "init" {
+        if (-not (Test-Path $Monitored)) { "." | Set-Content $Monitored }
+        if (-not (Test-Path $Excludes)) {
+            @"
+node_modules
+.git
+build
+dist
+"@ | Set-Content $Excludes
+        }
+        if (-not (Test-Path $HealthFile)) {
+            @"
+# Documentation Health Matrix
+
+| File | Status | Last Updated | Reason / Intent |
+|------|--------|--------------|-----------------|
+"@ | Set-Content $HealthFile
+        }
+        Upsert-Health "wikifier.ps1" "🟢 Green" "Windows PowerShell CLI initialised."
+        Write-Log "Wikifier Windows state initialised."
+    }
+    "check-changes" {
+        Write-Log "Running change detection (PowerShell)..."
+        $last = if (Test-Path $LastCheck) { Get-Content $LastCheck } else { "1970-01-01" }
+        $roots = if (Test-Path $Monitored) { Get-Content $Monitored | Where-Object { $_ -notmatch '^\s*#' } } else { @(".") }
+
+        $changed = 0
+        foreach ($root in $roots) {
+            if (-not (Test-Path $root)) { continue }
+            Get-ChildItem -Path $root -Recurse -File -ErrorAction SilentlyContinue |
+                Where-Object { $_.LastWriteTime -gt [datetime]$last } |
+                ForEach-Object {
+                    $rel = $_.FullName.Replace($WikifierRoot, "").TrimStart('\','/')
+                    if ($rel -match '(\.git|node_modules|Logged_issues|journal|\.wikifier)') { return }
+                    Upsert-Health $rel "🟡 Yellow" "mtime changed (PowerShell auto-detect)"
+                    Add-Pending $rel "Auto-detected change on Windows"
+                    $changed++
+                }
+        }
+        Get-Date -Format "yyyy-MM-dd HH:mm:ss" | Set-Content $LastCheck
+        Write-Log "Detected $changed file(s) changed."
+    }
+    "record-change" {
+        $file = $Arguments[0]
+        $reason = if ($Arguments.Count -gt 1) { $Arguments[1] } else { "No reason" }
+        if (-not $file) { Write-Err "Usage: wikifier record-change <file> <reason>"; exit 1 }
+        Upsert-Health $file "🟡 Yellow" $reason
+        Add-Pending $file "record-change: $reason"
+        Write-Journal "record-change" $file $reason
+        Write-Log "Recorded change for $file"
+    }
+    "mark-green" {
+        $file = $Arguments[0]
+        if (-not $file) { Write-Err "Usage: wikifier mark-green <file>"; exit 1 }
+        Upsert-Health $file "🟢 Green" "Verified on Windows."
+        if (Test-Path $PendingFile) {
+            (Get-Content $PendingFile) | Where-Object { $_ -notmatch [regex]::Escape($file) } | Set-Content $PendingFile
+        }
+        Write-Log "🟢 $file marked Green."
+    }
+    "health" {
+        if (Test-Path $HealthFile) { Get-Content $HealthFile } else { Write-Host "Run init or check-changes first." }
+    }
+    "monitor" {
+        Write-Log "Starting heartbeat monitor (Windows PowerShell)..."
+        while ($true) {
+            & $PSCommandPath check-changes
+            Start-Sleep -Seconds 30
+        }
+    }
+    default {
+        Write-Err "Unknown command '$Command'. Try 'wikifier help'."
+    }
+}

wikifier/scripts/wikifier.sh

@@ -0,0 +1,498 @@
+#!/bin/bash
+# wikifier.sh — Wikifier v0.3 Core CLI (Zero-Dependency)
+# Agent-first shell tool for codebase documentation health & semantic change tracking.
+#
+# Usage:
+#   ./wikifier.sh <command> [args]
+#   (Optionally symlink or alias as 'wikifier' in your PATH)
+#
+# Commands implemented:
+#   help, check-changes, health, record-change, record-deletion,
+#   prepare-edit, mark-green, monitor, update-maps, validate,
+#   journal, issues, init
+
+set -euo pipefail
+
+# ----------------------------- Configuration -----------------------------
+WIKIFIER_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LAST_CHECK_FILE="$WIKIFIER_ROOT/.wikifier_staging/.last_check"
+STAGING_DIR="$WIKIFIER_ROOT/.wikifier_staging"
+JOURNAL_ROOT="$WIKIFIER_ROOT/journal"
+LOGGED_ISSUES_ROOT="$WIKIFIER_ROOT/Logged_issues"
+MONITORED_PATHS_FILE="$WIKIFIER_ROOT/monitored_paths.txt"
+EXCLUDE_PATTERNS_FILE="$WIKIFIER_ROOT/exclude_patterns.txt"
+FILE_HEALTH="$WIKIFIER_ROOT/file_health.md"
+PENDING_UPDATES="$WIKIFIER_ROOT/pending_updates.md"
+LIBRARY_MD="$WIKIFIER_ROOT/library.md"
+POLL_INTERVAL="${WIKIFIER_POLL_INTERVAL:-30}"
+
+mkdir -p "$STAGING_DIR" "$JOURNAL_ROOT/$(date +%Y/%m)" "$LOGGED_ISSUES_ROOT"
+
+# ----------------------------- Helper Functions -----------------------------
+
+log() {
+    echo "[wikifier] $*"
+}
+
+error() {
+    echo "[wikifier ERROR] $*" >&2
+}
+
+# Get current timestamp in consistent format
+timestamp() {
+    date '+%Y-%m-%d %H:%M:%S %Z'
+}
+
+# Read monitored paths (one per line, ignore comments/blank)
+get_monitored_paths() {
+    if [[ -f "$MONITORED_PATHS_FILE" ]]; then
+        grep -vE '^\s*(#|$)' "$MONITORED_PATHS_FILE" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//'
+    else
+        echo "."
+    fi
+}
+
+# Build find exclude expression from exclude_patterns.txt
+build_exclude_expr() {
+    local expr=""
+    if [[ -f "$EXCLUDE_PATTERNS_FILE" ]]; then
+        while IFS= read -r pat; do
+            [[ -z "$pat" || "$pat" =~ ^\s*# ]] && continue
+            pat=$(echo "$pat" | xargs)
+            [[ -z "$pat" ]] && continue
+            if [[ -n "$expr" ]]; then
+                expr="$expr -o -path \"*/$pat/*\" -o -path \"*/$pat\""
+            else
+                expr="-path \"*/$pat/*\" -o -path \"*/$pat\""
+            fi
+        done < "$EXCLUDE_PATTERNS_FILE"
+    fi
+    if [[ -n "$expr" ]]; then
+        echo "! ( $expr )"
+    else
+        echo ""
+    fi
+}
+
+# Upsert a row in the Markdown health table (very simple but effective)
+# We treat file_health.md as the single source of truth.
+upsert_health() {
+    local file="$1"
+    local status="$2"          # 🟢 or 🟡 or 🔴
+    local reason="${3:-}"
+
+    local now
+    now=$(timestamp)
+
+    # Ensure file exists with header
+    if [[ ! -f "$FILE_HEALTH" ]]; then
+        cat > "$FILE_HEALTH" << 'EOT'
+# Documentation Health Matrix
+
+| File | Status | Last Updated | Reason / Intent |
+|------|--------|--------------|-----------------|
+EOT
+    fi
+
+    # Escape for sed (basic)
+    local safe_file
+    safe_file=$(printf '%s' "$file" | sed 's/[\/&]/\\&/g')
+
+    # Check if file already has an entry
+    if grep -qF "| $file |" "$FILE_HEALTH" 2>/dev/null; then
+        # Update existing row (replace the whole line)
+        local new_line="| $file | $status | $now | $reason |"
+        sed -i.bak "s#| $safe_file | .* | .* | .* |#$new_line#" "$FILE_HEALTH" && rm -f "$FILE_HEALTH.bak"
+    else
+        # Append new row
+        echo "| $file | $status | $now | $reason |" >> "$FILE_HEALTH"
+    fi
+}
+
+# Mark a file Green (convenience)
+mark_green() {
+    local file="$1"
+    local reason="${2:-Summary updated and verified accurate.}"
+    upsert_health "$file" "🟢 Green" "$reason"
+    # Remove from pending if present
+    if [[ -f "$PENDING_UPDATES" ]]; then
+        grep -vF "$file" "$PENDING_UPDATES" > "$PENDING_UPDATES.tmp" || true
+        mv "$PENDING_UPDATES.tmp" "$PENDING_UPDATES"
+    fi
+}
+
+# Append to pending_updates.md
+add_pending() {
+    local file="$1"
+    local msg="$2"
+    echo "- $file: $msg" >> "$PENDING_UPDATES"
+}
+
+# Write a journal entry
+write_journal() {
+    local action="$1"   # "record-change", "record-deletion", "auto-detected", etc.
+    local file="$2"
+    local reason="$3"
+
+    local day_dir
+    day_dir="$JOURNAL_ROOT/$(date +%Y/%m)"
+    mkdir -p "$day_dir"
+    local journal_file="$day_dir/$(date +%d).md"
+
+    cat >> "$journal_file" << EOM
+## [$(timestamp)] $action
+**File:** $file
+**Reason:** $reason
+
+EOM
+}
+
+# Simple cross-language import discovery (extendable)
+discover_imports() {
+    local target="$1"
+    # Very lightweight — only common patterns. Real projects can extend.
+    grep -rE \
+        '^(import |from .* import |require\(|#include |import .* from |using |package )' \
+        "$target" 2>/dev/null | head -200 || true
+}
+
+# ----------------------------- Command Implementations -----------------------------
+
+cmd_help() {
+    cat << 'EOF'
+Wikifier v0.3 — Agent-First Codebase Wiki (Zero Dependencies)
+
+Usage: wikifier <command> [arguments]
+
+Core Commands:
+  check-changes              Scan monitored paths for mtime changes since last run.
+                             Marks changed files Yellow + adds to pending_updates.
+  health                     Pretty-print the current Documentation Health Matrix.
+  record-change <file> "<reason>"
+                             Log a semantic change (why you edited). Updates health to Yellow.
+  record-deletion <file> "<reason>"
+                             Log intentional deletion with reasoning.
+  prepare-edit <file>        Stage a file for diff capture (captures current mtime).
+  mark-green <file> [reason]
+                             Mark a wiki summary as accurate (Green). Clears pending entry.
+  update-maps                Rebuild library.md with import/dependency Mermaid graph.
+  validate                   Check that every monitored file has at least a stub wiki entry.
+  monitor                    Background heartbeat: runs check-changes every 30s forever.
+
+Information Commands:
+  journal [date]             Show today's (or given YYYY-MM-DD) journal entries.
+  issues [severity]          List Logged_issues (simple|moderate|high|critical).
+  help                       This message.
+
+Workflow (for LLMs / new sessions):
+  1. wikifier check-changes
+  2. Read file_health.md + pending_updates.md
+  3. Prioritise 🔴 Red → 🟡 Yellow
+  4. After editing a file: wikifier record-change "path/to/file" "reason"
+  5. After updating the wiki summary: wikifier mark-green "path/to/file"
+  6. wikifier update-maps (when imports change)
+
+Configuration files (edit these):
+  monitored_paths.txt        Paths to scan (one per line). Default: "."
+  exclude_patterns.txt       Glob patterns to ignore (node_modules, .git, dist, etc.)
+
+The system is fully usable from the shell or exposed as MCP tools via skills/run.md.
+EOF
+}
+
+cmd_check_changes() {
+    log "Running incremental change detection..."
+
+    local last_ts
+    if [[ -f "$LAST_CHECK_FILE" ]]; then
+        last_ts=$(cat "$LAST_CHECK_FILE")
+    else
+        last_ts="1970-01-01 00:00:00"
+        echo "$last_ts" > "$LAST_CHECK_FILE"
+    fi
+
+    local exclude
+    exclude=$(build_exclude_expr)
+
+    local changed=0
+
+    # For each monitored root, find files newer than last check
+    while IFS= read -r root; do
+        [[ -z "$root" ]] && continue
+        [[ ! -e "$root" ]] && { log "Warning: monitored path does not exist: $root"; continue; }
+
+        # shellcheck disable=SC2086
+        while IFS= read -r -d '' file; do
+            # Skip the wikifier tool's own internal files
+            if [[ "$file" == *"/.wikifier_staging/"* || "$file" == *"/journal/"* || \
+                  "$file" == *"/Logged_issues/"* || "$file" == *"/.git/"* ]]; then
+                continue
+            fi
+
+            local rel_file
+            rel_file=$(realpath --relative-to="$WIKIFIER_ROOT" "$file" 2>/dev/null || echo "$file")
+
+            upsert_health "$rel_file" "🟡 Yellow" "mtime changed since last check-changes (auto-detected)"
+            add_pending "$rel_file" "Auto-detected modification — review and run mark-green after wiki update"
+            write_journal "auto-detected" "$rel_file" "File mtime changed (check-changes)"
+
+            ((changed++))
+        done < <(find "$root" -type f -newermt "$last_ts" -print0 2>/dev/null || true)
+    done < <(get_monitored_paths)
+
+    date '+%Y-%m-%d %H:%M:%S' > "$LAST_CHECK_FILE"
+
+    if (( changed > 0 )); then
+        log "Detected $changed changed file(s). See pending_updates.md and file_health.md."
+    else
+        log "No new changes detected."
+    fi
+}
+
+cmd_health() {
+    if [[ -f "$FILE_HEALTH" ]]; then
+        cat "$FILE_HEALTH"
+    else
+        echo "Health matrix not initialised yet. Run 'wikifier check-changes' or 'wikifier init'."
+    fi
+}
+
+cmd_record_change() {
+    local file="${1:-}"
+    local reason="${2:-No reason provided.}"
+
+    if [[ -z "$file" ]]; then
+        error "Usage: wikifier record-change <file> \"<concise reason>\""
+        exit 1
+    fi
+
+    upsert_health "$file" "🟡 Yellow" "$reason"
+    add_pending "$file" "LLM/agent edit — $reason"
+    write_journal "record-change" "$file" "$reason"
+
+    log "✅ Recorded semantic change for $file"
+    log "   Reason: $reason"
+    log "   → file_health.md updated to Yellow. Run mark-green after wiki summary is refreshed."
+}
+
+cmd_record_deletion() {
+    local file="${1:-}"
+    local reason="${2:-No reason provided.}"
+
+    if [[ -z "$file" ]]; then
+        error "Usage: wikifier record-deletion <file> \"<reason>\""
+        exit 1
+    fi
+
+    upsert_health "$file" "🔴 Red" "DELETED — $reason"
+    add_pending "$file" "File was deleted. Consider removing wiki entry or marking archival."
+    write_journal "record-deletion" "$file" "$reason"
+
+    log "🗑️ Recorded deletion for $file"
+}
+
+cmd_prepare_edit() {
+    local file="${1:-}"
+    if [[ -z "$file" || ! -f "$file" ]]; then
+        error "Usage: wikifier prepare-edit <existing-file>"
+        exit 1
+    fi
+
+    local mtime
+    mtime=$(stat -c %Y "$file" 2>/dev/null || stat -f %m "$file" 2>/dev/null || echo "0")
+    echo "$mtime" > "$STAGING_DIR/$(basename "$file").mtime"
+    log "Staged $file for later diff (mtime=$mtime)"
+}
+
+cmd_mark_green() {
+    local file="${1:-}"
+    local reason="${2:-Wiki summary verified accurate after change.}"
+    if [[ -z "$file" ]]; then
+        error "Usage: wikifier mark-green <file> [optional reason]"
+        exit 1
+    fi
+    mark_green "$file" "$reason"
+    log "🟢 $file marked Green. Pending entry cleared."
+}
+
+cmd_monitor() {
+    log "Starting Wikifier heartbeat monitor (interval: ${POLL_INTERVAL}s). Press Ctrl+C to stop."
+    log "Logs will be written to .wikifier_staging/monitor.log if run with nohup."
+
+    while true; do
+        cmd_check_changes
+        sleep "$POLL_INTERVAL"
+    done
+}
+
+cmd_update_maps() {
+    log "Rebuilding library.md (import map + Mermaid)..."
+
+    cat > "$LIBRARY_MD" << 'EOT'
+# Library & Imports Map (auto-generated by wikifier update-maps)
+
+> This file is regenerated. Manual edits will be overwritten.
+> Run `wikifier record-change library.md "..."` if you need to annotate.
+
+## Dependency Graph (Mermaid)
+
+```mermaid
+graph TD
+EOT
+
+    # Very basic discovery — can be greatly improved per language
+    local paths
+    paths=$(get_monitored_paths)
+
+    echo "    %% Auto-detected imports (lightweight scan)" >> "$LIBRARY_MD"
+
+    # Placeholder nodes for now; real impl would parse and connect
+    echo "    Main[\"(root)\"] --> Wikifier[\"wikifier.sh\"]" >> "$LIBRARY_MD"
+
+    # Add a few real files if they exist in the tree
+    find $paths -type f \( -name "*.py" -o -name "*.sh" -o -name "*.js" -o -name "*.ts" -o -name "*.md" \) \
+        ! -path "*/.git/*" ! -path "*/node_modules/*" 2>/dev/null | head -30 | while read -r f; do
+        local base
+        base=$(basename "$f")
+        echo "    $base[\"$base\"]" >> "$LIBRARY_MD"
+    done
+
+    cat >> "$LIBRARY_MD" << 'EOT'
+
+```
+
+## Files with Imports (summary)
+
+| File | Detected Import Lines (truncated) |
+|------|-----------------------------------|
+EOT
+
+    # Append a few example import lines
+    discover_imports "." | head -30 | while IFS= read -r line; do
+        echo "| $(echo "$line" | cut -c1-60) |" >> "$LIBRARY_MD"
+    done
+
+    echo "" >> "$LIBRARY_MD"
+    log "✅ library.md updated. You can now embed the Mermaid diagram in index.html or any Markdown viewer."
+}
+
+cmd_validate() {
+    log "Validating that every monitored file has a health entry..."
+
+    local missing=0
+    local exclude
+    exclude=$(build_exclude_expr)
+
+    while IFS= read -r root; do
+        [[ -z "$root" ]] && continue
+        find "$root" -type f ! -path "*/.git/*" ! -path "*/.wikifier_staging/*" 2>/dev/null | while read -r f; do
+            local rel
+            rel=$(realpath --relative-to="$WIKIFIER_ROOT" "$f" 2>/dev/null || echo "$f")
+            if ! grep -qF "| $rel |" "$FILE_HEALTH" 2>/dev/null; then
+                echo "🔴 MISSING WIKI ENTRY: $rel"
+                ((missing++)) || true
+            fi
+        done
+    done < <(get_monitored_paths)
+
+    if (( missing == 0 )); then
+        log "✅ All monitored files have health entries."
+    else
+        log "⚠️  $missing file(s) lack wiki entries. Run update-maps + create summaries."
+    fi
+}
+
+cmd_journal() {
+    local date_spec="${1:-$(date +%Y-%m-%d)}"
+    local year month day
+    year=$(date -d "$date_spec" +%Y 2>/dev/null || date +%Y)
+    month=$(date -d "$date_spec" +%m 2>/dev/null || date +%m)
+    day=$(date -d "$date_spec" +%d 2>/dev/null || date +%d)
+
+    local jf="$JOURNAL_ROOT/$year/$month/$day.md"
+    if [[ -f "$jf" ]]; then
+        cat "$jf"
+    else
+        echo "No journal entries for $date_spec yet."
+    fi
+}
+
+cmd_issues() {
+    local sev="${1:-all}"
+    echo "=== Logged Issues (severity: $sev) ==="
+    if [[ "$sev" == "all" ]]; then
+        find "$LOGGED_ISSUES_ROOT" -type f -name "*.md" | sort
+    else
+        find "$LOGGED_ISSUES_ROOT/$sev" -type f -name "*.md" 2>/dev/null | sort
+    fi
+    echo ""
+    echo "See Logged_issues/map.md for the categorised overview."
+}
+
+cmd_init() {
+    log "Initialising fresh Wikifier state..."
+
+    [[ ! -f "$MONITORED_PATHS_FILE" ]] && echo "." > "$MONITORED_PATHS_FILE"
+    [[ ! -f "$EXCLUDE_PATTERNS_FILE" ]] && cat > "$EXCLUDE_PATTERNS_FILE" << 'EOT'
+node_modules
+.git
+build
+dist
+__pycache__
+*.pyc
+EOT
+
+    [[ ! -f "$FILE_HEALTH" ]] && cat > "$FILE_HEALTH" << 'EOT'
+# Documentation Health Matrix
+
+| File | Status | Last Updated | Reason / Intent |
+|------|--------|--------------|-----------------|
+EOT
+
+    [[ ! -f "$PENDING_UPDATES" ]] && cat > "$PENDING_UPDATES" << 'EOT'
+# Pending Updates
+
+(no pending items — run check-changes after making edits)
+EOT
+
+    [[ ! -f "$LIBRARY_MD" ]] && cat > "$LIBRARY_MD" << 'EOT'
+# Library & Imports Map
+
+Run `wikifier update-maps` to populate.
+EOT
+
+    # Seed a first health entry for the tool itself
+    upsert_health "wikifier.sh" "🟢 Green" "Core CLI implemented and documented."
+
+    log "✅ Wikifier initialised. Edit monitored_paths.txt to point at your real codebase."
+}
+
+# ----------------------------- Main Dispatcher -----------------------------
+
+main() {
+    local cmd="${1:-help}"
+    shift || true
+
+    case "$cmd" in
+        help|--help|-h)          cmd_help ;;
+        check-changes)           cmd_check_changes ;;
+        health)                  cmd_health ;;
+        record-change)           cmd_record_change "$@" ;;
+        record-deletion)         cmd_record_deletion "$@" ;;
+        prepare-edit)            cmd_prepare_edit "$@" ;;
+        mark-green)              cmd_mark_green "$@" ;;
+        monitor)                 cmd_monitor ;;
+        update-maps)             cmd_update_maps ;;
+        validate)                cmd_validate ;;
+        journal)                 cmd_journal "$@" ;;
+        issues)                  cmd_issues "$@" ;;
+        init)                    cmd_init ;;
+        *)
+            error "Unknown command: $cmd"
+            echo "Run 'wikifier help' for the full list."
+            exit 1
+            ;;
+    esac
+}
+
+main "$@"

wikifier-0.3.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: wikifier
+Version: 0.3.0
+Summary: Agent-first, zero-dependency, self-maintaining codebase documentation & change tracking system
+Author-email: Aron Amos <aron@example.com>
+Maintainer: Aron Amos
+License: MIT
+Project-URL: Homepage, https://github.com/IronAdamant/wikifier
+Project-URL: Repository, https://github.com/IronAdamant/wikifier
+Project-URL: Documentation, https://github.com/IronAdamant/wikifier#readme
+Project-URL: Bug Tracker, https://github.com/IronAdamant/wikifier/issues
+Keywords: wiki,documentation,llm,agent,mcp,codebase,health-matrix,zero-dependency,shell
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Version Control
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Wikifier v0.3
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub Stars](https://img.shields.io/github/stars/IronAdamant/wikifier?style=social)](https://github.com/IronAdamant/wikifier/stargazers)
+
+**Agent-first • Zero-dependency • LLM-operated codebase wiki**
+
+Wikifier turns any codebase (tiny scripts → large monorepos) into a living, token-efficient map that LLMs/agents operate autonomously.
+
+> **GitHub**: https://github.com/IronAdamant/wikifier  
+> **PyPI**: `pip install wikifier` (coming very soon)
+
+---
+
+## 🚀 Get Started in 30 Seconds
+
+### Option 1: Via pip (Recommended)
+
+```bash
+pip install wikifier
+
+# Then run
+wikifier init
+wikifier check-changes
+```
+
+### Option 2: From source
+
+```bash
+git clone https://github.com/IronAdamant/wikifier.git
+cd wikifier
+chmod +x wikifier.sh
+
+# Point it at your codebase
+nano monitored_paths.txt
+
+./wikifier.sh init
+./wikifier.sh check-changes
+```
+
+Then open `index.html` in your browser for the live dashboard.
+
+### Mandatory Rule for Every LLM / Grok Build Session
+
+Copy this into the **start of every new prompt** when working in a Wikifier-managed project:
+
+```text
+You are operating inside a Wikifier v0.3 project.
+
+MANDATORY FIRST STEPS:
+1. Run: wikifier check-changes
+2. Read file_health.md + pending_updates.md
+3. Prioritise 🔴 Red → 🟡 Yellow items
+4. For every code edit: wikifier record-change "path/to/file" "I did X because Y"
+5. After updating the wiki summary: wikifier mark-green "path/to/file"
+6. Re-validate before finishing
+```
+
+---
+
+## What Wikifier Gives You
+
+- **Per-file Documentation Health Matrix** — 🟢 Green / 🟡 Yellow / 🔴 Red status with reasons
+- **Semantic Change Logging** — `record-change "file" "I did X because Y"` (the "why", not just the "what")
+- **Background Heartbeat Monitor** — Passive `monitor &` loop keeps everything fresh while you sleep
+- **Automated Journal + Categorized Issues** — Dated entries + `Logged_issues/{simple,moderate,high,critical}/...`
+- **Beautiful Static Dashboard** — `index.html` with live health lights, Mermaid graphs, and one-click command reference
+- **MCP / Agent Ready** — Full `skills/run.md` contract so Grok, Claude, Cline, etc. can drive it natively
+- **True Zero Dependencies** — Pure Bash + PowerShell. Works on any machine, no Docker, no Node, no Python packages.
+
+**This is agent-first.** LLMs operate the system via shell commands. Humans just watch the dashboard.
+
+## Core Commands
+
+| Command                    | Purpose                                      |
+|---------------------------|----------------------------------------------|
+| `wikifier check-changes`  | Incremental mtime scan + health update       |
+| `wikifier record-change <file> "reason"` | Log *why* you made an edit (required) |
+| `wikifier mark-green <file>` | Mark wiki summary as accurate after editing |
+| `wikifier monitor &`      | Background heartbeat (30s polling)           |
+| `wikifier update-maps`    | Rebuild `library.md` + Mermaid dependency graph |
+| `wikifier health`         | Show current Documentation Health Matrix     |
+
+Full reference → [`skills/run.md`](skills/run.md)
+
+## Quick Links
+
+- [spec.md](spec.md) — Immutable user requirements
+- [Basis-v0.3.md](Basis-v0.3.md) — Implementation reference & data formats
+- [TRADEOFFS.md](TRADEOFFS.md) — Why we made the design choices we did
+- [index.html](index.html) — Open this in a browser for the live dashboard
+
+## Differentiation
+
+Unlike heavy "LLM Wiki" approaches (e.g. Karpathy-style personal knowledge bases), Wikifier is the **ultra-light, shell-native** implementation:
+
+- Per-file health matrix with clear Red/Yellow/Green workflow
+- Semantic `record-change` intent logging for future self-review
+- True background monitor + zero external dependencies
+- Native cross-platform (Linux/macOS/Windows via PowerShell)
+- Designed from day one to be driven by LLMs via MCP/tools
+
+**License**: MIT — fork freely and use in any project.
+
+---
+
+*Built for agents, by agents, with just `bash` and stubbornness.*

wikifier-0.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+wikifier/__init__.py,sha256=-vs1e2uzVbyNyn_o2_SKu0WUAllCbtPn0A4AY833xYc,232
+wikifier/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
+wikifier/cli.py,sha256=41Xpl0bYEM7OkCx6ooN484R4d7_lASUoZuReef-0I1E,1789
+wikifier/scripts/wikifier.bat,sha256=nJbmn_HwZtmIJ4IOwkBwekjC2DITUPceQHmPUxXv7to,775
+wikifier/scripts/wikifier.ps1,sha256=dD66CY1gpLJboUgpcxx2fS67MvurMOiPU5EswUnm7Uk,5778
+wikifier/scripts/wikifier.sh,sha256=NQtwUgp6MYf7O5Ngsph8xKj5ZwKjRBPqHxHBu5IliXY,16025
+wikifier-0.3.0.dist-info/licenses/LICENSE,sha256=2gWF8A-6q5_o_h1JrDhvE5yXow_mC0S9aeK1JR43rFg,1066
+wikifier-0.3.0.dist-info/METADATA,sha256=qUORaho7oEO4bf5CU_neDjCWqwuhUAXw9eu2I9afi0M,5467
+wikifier-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+wikifier-0.3.0.dist-info/entry_points.txt,sha256=LA9ZFMcXAo1_uEOA8DSLwqoiVCVq7zg4iPK2VBgD9IM,47
+wikifier-0.3.0.dist-info/top_level.txt,sha256=pkXHR-6vEAXPAWzFbj3p0vn6k5rDRFFVD9CtVgmi6e0,9
+wikifier-0.3.0.dist-info/RECORD,,

wikifier-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

wikifier-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+wikifier = wikifier.cli:main

wikifier-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aron Amos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wikifier-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+wikifier