wikifier 0.3.0__tar.gz → 0.3.3__tar.gz

wikifier-0.3.3/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: wikifier
+Version: 0.3.3
+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
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Dynamic: license-file
+
+# Wikifier v0.3
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI version](https://img.shields.io/pypi/v/wikifier.svg)](https://pypi.org/project/wikifier/)
+[![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.
+
+### What's New in v0.3.3
+
+**Gap #1 (Dependency Intelligence) is now at 95%+ "set & forget" on large messy monorepos — Swarm Complete**
+
+This release marks the full closure of the 6 remaining Gap #1 last-mile items using a parallel multi-agent swarm (Grok Build 0.1 model):
+
+- Barrel_v2 + res_meta_v1 + Persistent BarrelResolutionCache + Deep Invalidation at real monorepo scale
+- Guaranteed Cycle / Graph Structure Persistence (delta short-circuit + v1 canonical default)
+- External / Packaged Full-Update Robustness (Python-primary `run_full_update` + complex monorepo discovery)
+- ACS + CIABRE Surfacing Uniformity (actionable recommendations everywhere + new low-conf filter)
+- Extremely Creative / Dynamic Import Pattern Coverage (new CDIA detectors + Layer 3.5 dataflow + Python parity)
+
+**Key Outcomes**:
+- Full `python -m wikifier.gap1_validation_harness --gap1-health` now reports **GREEN**
+- Selective barrel invalidation, real 5k+ dogfood, RecipeLab monorepo paths, and daemon integration all production-grade
+- All changes strictly zero-dependency, scalable to 50k+ files, and additive
+
+See the detailed agent diary entries in `Findings/m2_rem_08_and_v0.4_progress_tracker.md` for the complete swarm journey.
+
+### What's New in v0.3.2
+
+**Gap #1 (Dependency Intelligence Quality) is now substantially closed (~94–96%)**
+
+This release completes the major M2-Rem-08 deep closure work on dependency intelligence:
+
+- **Major Barrel Intelligence Improvements** (6 parallel specialized agents):
+  - Barrel following depth increased (2 → 3)
+  - Much smarter barrel detection (now catches real-world import-style index barrels)
+  - Full `barrel_chain` tracking and visibility across the system
+  - Modern `package.json` `"exports"` map support for resolution and barrel following
+  - Significant performance improvements for barrel probing
+  - Conditional context now properly propagates through barrel chains
+
+- **Cycle Detection (Complete Stack)**
+  - Full cycle detection with DFS + deduplication
+  - Exposed via `wikifier cycles`, `get_cycles()` MCP tool, "Circular Dependencies" section in `library.md`, and visual warnings in Mermaid graphs
+
+- **Overall**
+  - Rich dependency metadata now flows reliably everywhere
+  - `get_dependencies()` and `get_dependents()` are dramatically more trustworthy
+  - Dependency intelligence is no longer the primary blocker for autonomous agents
+
+This is a significant patch release that brings the dependency layer to a production-useful level for most real-world projects. The main remaining practical challenge is now `update-maps` performance at very large scale.
+
+**Other highlights carried from v0.3.1**:
+- Health Matrix Auto-Healing (`heal-stubs`, `healing-stats`, etc.)
+- `WIKIFIER_DEBUG=1` for first-pass transparency
+- Richer cache and reverse dependency support
+
+> **GitHub**: https://github.com/IronAdamant/wikifier  
+> **PyPI**: https://pypi.org/project/wikifier/
+
+---
+
+## 🚀 Installation
+
+**Recommended — via pip:**
+
+```bash
+pip install wikifier
+```
+
+Then run:
+
+```bash
+wikifier init
+wikifier check-changes
+```
+
+Then open `index.html` in your browser for the live dashboard.
+
+---
+
+**Alternative — from source:**
+
+```bash
+git clone https://github.com/IronAdamant/wikifier.git
+cd wikifier
+chmod +x wikifier.sh
+./wikifier.sh init
+./wikifier.sh check-changes
+```
+
+### 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
+```
+
+> **Note**: This rule applies per-project. When using Wikifier on an external codebase (not the Wikifier repo itself), the agent should be told which project root to operate on (via `WIKIFIER_PROJECT_ROOT`, `--project-root`, or the `project_root` parameter on MCP tools).
+
+---
+
+### Using Wikifier on External Projects (Packaging & Setup Clarity — M2-Rem-06)
+
+Wikifier is a **general-purpose** agent memory system. After `pip install wikifier` (or `pip install wikifier[mcp]`), the `wikifier` and `wikifier-mcp` console scripts become available globally. You can (and should) use them on **any** codebase — not just the Wikifier source tree.
+
+#### Pip Install vs Running from Source
+
+- **After `pip install wikifier`** (recommended for normal use):
+  - `wikifier` and `wikifier-mcp` commands are in your PATH.
+  - The underlying implementation is the installed package (Python + shell scripts bundled).
+  - You still need to tell Wikifier **which project** you want to document (see Root Targeting below).
+  - `wikifier init --target /path/to/project` is the correct way to bootstrap state in an external folder.
+
+- **Running from source** (development / contributing):
+  - Clone the repo, `chmod +x wikifier.sh`, and invoke `./wikifier.sh ...` or the scripts directly.
+  - Useful when you are actively modifying Wikifier itself.
+
+**First-time setup on a new external codebase after pip install** (canonical flow, R6 improved):
+```bash
+# 1. Bootstrap directly into the target (auto-creates .wikifier/ marker, state files; CLI copies launcher if possible)
+wikifier init --target /absolute/path/to/your/actual/monorepo-or-project
+
+# 2. Optional but recommended: edit monitored_paths.txt to focus on src/, packages/, app/ etc. for large monorepos
+# 3. Run the mandatory workflow (CLI auto-propagates project root from --target or env)
+wikifier check-changes
+
+# 4. For agent work / MCP (now robust, no sh-not-found even on pure pip installs)
+WIKIFIER_PROJECT_ROOT=/absolute/path/to/your/actual/monorepo wikifier-mcp
+# or pass project_root on individual tool calls
+```
+
+The R6 Monorepo & External UX wave made `init --target` fully functional (state in target, launcher copy, .wikifier marker), made CLI/MCP/sh consistently honor WIKIFIER_PROJECT_ROOT, and hardened pnpm/yarn/symlink/TS-ref edge cases in resolution. Much less manual setup for real-world large external codebases.
+
+#### How Root Targeting Works (Decision Order for Agents)
+
+Wikifier resolves the project root using this strict priority. Agents should follow it to avoid confusion:
+
+1. `WIKIFIER_PROJECT_ROOT` environment variable (strongest — works for shell + all MCP tools)
+2. Explicit `--project-root` (CLI) or `project_root` parameter on MCP tool calls
+3. Upward directory walk looking for `monitored_paths.txt` or a `.wikifier/` directory
+4. `.mcp.json` present in the workspace root (common in Grok Build, Cursor, etc.)
+
+When the MCP server is started via `wikifier-mcp` (or through `.mcp.json`), it will usually auto-detect correctly if you `cd` into the project first. For maximum reliability on external dogfooding, always pass `project_root` or set the env var.
+
+This packaging + targeting story was a major focus of M2-Rem-06 to eliminate the friction reported during RecipeLab_alt and self-dogfood.
+
+---
+
+### Scaling Wikifier — Recommended Patterns by Project Size (M2-Rem-06)
+
+Wikifier is explicitly designed to scale from tiny scripts to massive monorepos. The guidance below is **prescriptive** — follow the patterns for your project size to stay fast and reliable.
+
+#### Recommended Command Patterns
+
+| Size                  | Preferred Interface       | Health Query                              | `update-maps` Strategy                          | Key Additional Practices |
+|-----------------------|---------------------------|-------------------------------------------|-------------------------------------------------|--------------------------|
+| **Tiny / Small**<br>(< 300 files) | Shell or MCP             | `wikifier health` (full table is fine)   | `wikifier update-maps` (default incremental)   | Use `.wiki.md` files next to sources for best `get_file_wiki`. Full rebuilds are cheap. |
+| **Medium**<br>(300–2,000 files) | MCP preferred            | `health --summary` or `health --dir src/` | `update_maps()` (incremental). Use `--full` only after large refactors or suspected cache corruption. | Prefer MCP tools (`get_project_status`, `suggest_next_actions`). Use directory filtering heavily. |
+| **Large**<br>(2,000–8,000 files) | **MCP strongly recommended** | `health(format="json", directory="src/services/")` + `--summary` | Always incremental. Inspect with `get_incremental_status()`. `--full` only on major structural changes. | Enable locking (automatic via Python backend). Run background `monitor &` safely. Use `get_files_needing_attention`. |
+| **Massive**<br>(8,000–30,000+ files) | **MCP only**             | `health --summary --dir <package>/` (never full table) | Incremental + `get_incremental_status()` before/after. Never run `--full` unless cache is known stale. | Use `get_dependents` / `get_dependencies` per-file. Leverage `import_cache.json` visibility. Multiple agents + monitor is safe thanks to M2-Rem-07 locking. |
+
+**When to use `--full` (rare):**
+- After moving/renaming many packages or changing import styles across the codebase.
+- If you manually deleted `import_cache.json`.
+- When the dogfood report or `get_incremental_status` shows very low resolution health.
+
+**Root Detection Rules (to avoid confusion)**
+Wikifier finds the project root using this priority (agents should understand this):
+1. `WIKIFIER_PROJECT_ROOT` environment variable (highest priority, works for both shell + MCP).
+2. Explicit `--project-root` flag (CLI) or `project_root` parameter (MCP tools).
+3. Walk upward from CWD looking for `monitored_paths.txt` or `.wikifier/` directory.
+4. `.mcp.json` in the current workspace (common in Grok Build / Cursor sessions).
+
+When operating on an external project after `pip install wikifier`, the most reliable pattern is:
+```bash
+WIKIFIER_PROJECT_ROOT=/absolute/path/to/your/repo wikifier check-changes
+WIKIFIER_PROJECT_ROOT=/absolute/path/to/your/repo wikifier-mcp
+```
+Or pass `project_root` on every MCP tool call.
+
+This section was significantly strengthened during M2-Rem-06 based on dogfood feedback.
+
+---
+
+## 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
+- **First-Class MCP Server** — Run `wikifier-mcp` to expose Wikifier as a proper MCP server with rich tools (`get_dependents`, `get_project_status`, `suggest_next_actions`, etc.), resources, and prompts. Works great with Claude Desktop, Cline, Cursor, and other MCP clients.
+- **Legacy Skills Interface** — `skills/run.md` still available for simpler shell-based agent setups.
+- **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.3/README.md

@@ -0,0 +1,244 @@
+# Wikifier v0.3
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI version](https://img.shields.io/pypi/v/wikifier.svg)](https://pypi.org/project/wikifier/)
+[![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.
+
+### What's New in v0.3.3
+
+**Gap #1 (Dependency Intelligence) is now at 95%+ "set & forget" on large messy monorepos — Swarm Complete**
+
+This release marks the full closure of the 6 remaining Gap #1 last-mile items using a parallel multi-agent swarm (Grok Build 0.1 model):
+
+- Barrel_v2 + res_meta_v1 + Persistent BarrelResolutionCache + Deep Invalidation at real monorepo scale
+- Guaranteed Cycle / Graph Structure Persistence (delta short-circuit + v1 canonical default)
+- External / Packaged Full-Update Robustness (Python-primary `run_full_update` + complex monorepo discovery)
+- ACS + CIABRE Surfacing Uniformity (actionable recommendations everywhere + new low-conf filter)
+- Extremely Creative / Dynamic Import Pattern Coverage (new CDIA detectors + Layer 3.5 dataflow + Python parity)
+
+**Key Outcomes**:
+- Full `python -m wikifier.gap1_validation_harness --gap1-health` now reports **GREEN**
+- Selective barrel invalidation, real 5k+ dogfood, RecipeLab monorepo paths, and daemon integration all production-grade
+- All changes strictly zero-dependency, scalable to 50k+ files, and additive
+
+See the detailed agent diary entries in `Findings/m2_rem_08_and_v0.4_progress_tracker.md` for the complete swarm journey.
+
+### What's New in v0.3.2
+
+**Gap #1 (Dependency Intelligence Quality) is now substantially closed (~94–96%)**
+
+This release completes the major M2-Rem-08 deep closure work on dependency intelligence:
+
+- **Major Barrel Intelligence Improvements** (6 parallel specialized agents):
+  - Barrel following depth increased (2 → 3)
+  - Much smarter barrel detection (now catches real-world import-style index barrels)
+  - Full `barrel_chain` tracking and visibility across the system
+  - Modern `package.json` `"exports"` map support for resolution and barrel following
+  - Significant performance improvements for barrel probing
+  - Conditional context now properly propagates through barrel chains
+
+- **Cycle Detection (Complete Stack)**
+  - Full cycle detection with DFS + deduplication
+  - Exposed via `wikifier cycles`, `get_cycles()` MCP tool, "Circular Dependencies" section in `library.md`, and visual warnings in Mermaid graphs
+
+- **Overall**
+  - Rich dependency metadata now flows reliably everywhere
+  - `get_dependencies()` and `get_dependents()` are dramatically more trustworthy
+  - Dependency intelligence is no longer the primary blocker for autonomous agents
+
+This is a significant patch release that brings the dependency layer to a production-useful level for most real-world projects. The main remaining practical challenge is now `update-maps` performance at very large scale.
+
+**Other highlights carried from v0.3.1**:
+- Health Matrix Auto-Healing (`heal-stubs`, `healing-stats`, etc.)
+- `WIKIFIER_DEBUG=1` for first-pass transparency
+- Richer cache and reverse dependency support
+
+> **GitHub**: https://github.com/IronAdamant/wikifier  
+> **PyPI**: https://pypi.org/project/wikifier/
+
+---
+
+## 🚀 Installation
+
+**Recommended — via pip:**
+
+```bash
+pip install wikifier
+```
+
+Then run:
+
+```bash
+wikifier init
+wikifier check-changes
+```
+
+Then open `index.html` in your browser for the live dashboard.
+
+---
+
+**Alternative — from source:**
+
+```bash
+git clone https://github.com/IronAdamant/wikifier.git
+cd wikifier
+chmod +x wikifier.sh
+./wikifier.sh init
+./wikifier.sh check-changes
+```
+
+### 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
+```
+
+> **Note**: This rule applies per-project. When using Wikifier on an external codebase (not the Wikifier repo itself), the agent should be told which project root to operate on (via `WIKIFIER_PROJECT_ROOT`, `--project-root`, or the `project_root` parameter on MCP tools).
+
+---
+
+### Using Wikifier on External Projects (Packaging & Setup Clarity — M2-Rem-06)
+
+Wikifier is a **general-purpose** agent memory system. After `pip install wikifier` (or `pip install wikifier[mcp]`), the `wikifier` and `wikifier-mcp` console scripts become available globally. You can (and should) use them on **any** codebase — not just the Wikifier source tree.
+
+#### Pip Install vs Running from Source
+
+- **After `pip install wikifier`** (recommended for normal use):
+  - `wikifier` and `wikifier-mcp` commands are in your PATH.
+  - The underlying implementation is the installed package (Python + shell scripts bundled).
+  - You still need to tell Wikifier **which project** you want to document (see Root Targeting below).
+  - `wikifier init --target /path/to/project` is the correct way to bootstrap state in an external folder.
+
+- **Running from source** (development / contributing):
+  - Clone the repo, `chmod +x wikifier.sh`, and invoke `./wikifier.sh ...` or the scripts directly.
+  - Useful when you are actively modifying Wikifier itself.
+
+**First-time setup on a new external codebase after pip install** (canonical flow, R6 improved):
+```bash
+# 1. Bootstrap directly into the target (auto-creates .wikifier/ marker, state files; CLI copies launcher if possible)
+wikifier init --target /absolute/path/to/your/actual/monorepo-or-project
+
+# 2. Optional but recommended: edit monitored_paths.txt to focus on src/, packages/, app/ etc. for large monorepos
+# 3. Run the mandatory workflow (CLI auto-propagates project root from --target or env)
+wikifier check-changes
+
+# 4. For agent work / MCP (now robust, no sh-not-found even on pure pip installs)
+WIKIFIER_PROJECT_ROOT=/absolute/path/to/your/actual/monorepo wikifier-mcp
+# or pass project_root on individual tool calls
+```
+
+The R6 Monorepo & External UX wave made `init --target` fully functional (state in target, launcher copy, .wikifier marker), made CLI/MCP/sh consistently honor WIKIFIER_PROJECT_ROOT, and hardened pnpm/yarn/symlink/TS-ref edge cases in resolution. Much less manual setup for real-world large external codebases.
+
+#### How Root Targeting Works (Decision Order for Agents)
+
+Wikifier resolves the project root using this strict priority. Agents should follow it to avoid confusion:
+
+1. `WIKIFIER_PROJECT_ROOT` environment variable (strongest — works for shell + all MCP tools)
+2. Explicit `--project-root` (CLI) or `project_root` parameter on MCP tool calls
+3. Upward directory walk looking for `monitored_paths.txt` or a `.wikifier/` directory
+4. `.mcp.json` present in the workspace root (common in Grok Build, Cursor, etc.)
+
+When the MCP server is started via `wikifier-mcp` (or through `.mcp.json`), it will usually auto-detect correctly if you `cd` into the project first. For maximum reliability on external dogfooding, always pass `project_root` or set the env var.
+
+This packaging + targeting story was a major focus of M2-Rem-06 to eliminate the friction reported during RecipeLab_alt and self-dogfood.
+
+---
+
+### Scaling Wikifier — Recommended Patterns by Project Size (M2-Rem-06)
+
+Wikifier is explicitly designed to scale from tiny scripts to massive monorepos. The guidance below is **prescriptive** — follow the patterns for your project size to stay fast and reliable.
+
+#### Recommended Command Patterns
+
+| Size                  | Preferred Interface       | Health Query                              | `update-maps` Strategy                          | Key Additional Practices |
+|-----------------------|---------------------------|-------------------------------------------|-------------------------------------------------|--------------------------|
+| **Tiny / Small**<br>(< 300 files) | Shell or MCP             | `wikifier health` (full table is fine)   | `wikifier update-maps` (default incremental)   | Use `.wiki.md` files next to sources for best `get_file_wiki`. Full rebuilds are cheap. |
+| **Medium**<br>(300–2,000 files) | MCP preferred            | `health --summary` or `health --dir src/` | `update_maps()` (incremental). Use `--full` only after large refactors or suspected cache corruption. | Prefer MCP tools (`get_project_status`, `suggest_next_actions`). Use directory filtering heavily. |
+| **Large**<br>(2,000–8,000 files) | **MCP strongly recommended** | `health(format="json", directory="src/services/")` + `--summary` | Always incremental. Inspect with `get_incremental_status()`. `--full` only on major structural changes. | Enable locking (automatic via Python backend). Run background `monitor &` safely. Use `get_files_needing_attention`. |
+| **Massive**<br>(8,000–30,000+ files) | **MCP only**             | `health --summary --dir <package>/` (never full table) | Incremental + `get_incremental_status()` before/after. Never run `--full` unless cache is known stale. | Use `get_dependents` / `get_dependencies` per-file. Leverage `import_cache.json` visibility. Multiple agents + monitor is safe thanks to M2-Rem-07 locking. |
+
+**When to use `--full` (rare):**
+- After moving/renaming many packages or changing import styles across the codebase.
+- If you manually deleted `import_cache.json`.
+- When the dogfood report or `get_incremental_status` shows very low resolution health.
+
+**Root Detection Rules (to avoid confusion)**
+Wikifier finds the project root using this priority (agents should understand this):
+1. `WIKIFIER_PROJECT_ROOT` environment variable (highest priority, works for both shell + MCP).
+2. Explicit `--project-root` flag (CLI) or `project_root` parameter (MCP tools).
+3. Walk upward from CWD looking for `monitored_paths.txt` or `.wikifier/` directory.
+4. `.mcp.json` in the current workspace (common in Grok Build / Cursor sessions).
+
+When operating on an external project after `pip install wikifier`, the most reliable pattern is:
+```bash
+WIKIFIER_PROJECT_ROOT=/absolute/path/to/your/repo wikifier check-changes
+WIKIFIER_PROJECT_ROOT=/absolute/path/to/your/repo wikifier-mcp
+```
+Or pass `project_root` on every MCP tool call.
+
+This section was significantly strengthened during M2-Rem-06 based on dogfood feedback.
+
+---
+
+## 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
+- **First-Class MCP Server** — Run `wikifier-mcp` to expose Wikifier as a proper MCP server with rich tools (`get_dependents`, `get_project_status`, `suggest_next_actions`, etc.), resources, and prompts. Works great with Claude Desktop, Cline, Cursor, and other MCP clients.
+- **Legacy Skills Interface** — `skills/run.md` still available for simpler shell-based agent setups.
+- **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 → wikifier-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wikifier"
-version = "0.3.0"
+version = "0.3.3"
 description = "Agent-first, zero-dependency, self-maintaining codebase documentation & change tracking system"
 readme = "README.md"
 license = {text = "MIT"}
@@ -35,7 +35,7 @@ classifiers = [
     "Topic :: Text Processing :: Markup :: Markdown",
 ]
 
-dependencies = []
+dependencies = []  # Zero-dependency by default. MCP support is optional.
 
 [project.urls]
 Homepage = "https://github.com/IronAdamant/wikifier"
@@ -43,8 +43,12 @@ Repository = "https://github.com/IronAdamant/wikifier"
 Documentation = "https://github.com/IronAdamant/wikifier#readme"
 "Bug Tracker" = "https://github.com/IronAdamant/wikifier/issues"
 
+[project.optional-dependencies]
+mcp = ["mcp>=1.0.0"]
+
 [project.scripts]
 wikifier = "wikifier.cli:main"
+wikifier-mcp = "wikifier.mcp.server:main"
 
 [tool.setuptools]
 package-dir = {"" = "."}

wikifier-0.3.3/wikifier/__init__.py

@@ -0,0 +1,44 @@
+"""
+Wikifier Python Package
+
+Provides the core Python components for Wikifier, including:
+- Import parsers (Python + JavaScript/TypeScript)
+- MCP Server
+- Health Matrix (scalable implementation)
+"""
+
+from . import parsers
+from . import mcp
+from . import health
+from . import locking
+from . import import_cache
+from . import resolution  # Robust Path Normalization Layer (Limitation #3 / Gap #1)
+from . import diagnostics  # Failure Transparency & Diagnostics Layer (Limitation #5 / Gap #1) - schema, aggregates, get_resolution_diagnostics support
+
+# Gap #1 External / Packaged: unified discovery helper (CLI + MCP + shell mirror) for reliable
+# PROJECT_ROOT on external monorepos after `pip install wikifier`. Primary entry for Python consumers.
+# Wave 2: + run_full_update (Python-primary sketch for update-maps heavy path)
+from .cli import discover_project_root, run_full_update
+
+# Pre-Wave 0: Shared contracts (FROZEN foundation for all Gap #1 phases)
+from . import contracts
+from .contracts import (
+    AnalysisTraceEntry,
+    ConditionalAnalysis,
+    DynamicAnalysis,
+    ResolutionMetadata,
+    encode_v1_payload,
+    decode_v1_payload,
+    pack_cdia_v1,
+    unpack_cdia_v1,
+    parse_pipeline_line,
+    RICH_KEYS,
+    RESERVED_TOP_LEVEL_KEYS,
+    NODE_IDENTITY_VERSION_V0,
+    NODE_IDENTITY_VERSION_V1,
+    get_contracts_info,
+    # R2: canonical ACS for consistent high-quality explanations + scores
+    compute_acs_confidence,
+)
+
+__version__ = "0.3.3"