wikifier 0.3.0__tar.gz

wikifier-0.3.0/Basis-v0.3.md

@@ -0,0 +1,130 @@
+# Basis-v0.3 — Implementation Reference & Design Notes
+
+This document captures the concrete design decisions and data formats for Wikifier v0.3. It is the "how" that supports the immutable "what" in `spec.md`.
+
+## 1. Health Matrix (`file_health.md`)
+
+Format (Markdown table, append-only with latest state wins):
+
+```markdown
+# Documentation Health Matrix
+
+| File | Status | Last Updated | Reason / Intent |
+|------|--------|--------------|-----------------|
+| src/main.py | 🟢 Green | 2026-05-15 14:32 | Initial summary complete. No pending edits. |
+| src/utils.py | 🟡 Yellow | 2026-05-15 14:28 | LLM added new helper. Pending summary update. |
+| src/legacy/old.js | 🔴 Red | 2026-05-14 09:10 | File modified but wiki summary missing. |
+```
+
+**Status Rules**:
+- 🟢 Green: Summary in corresponding MD file is accurate and up-to-date.
+- 🟡 Yellow: Change detected (mtime or `record-change`). Requires LLM review + `mark-green`.
+- 🔴 Red: Critical gap — file exists in monitored tree but has no wiki entry at all.
+
+`wikifier.sh` commands maintain this table automatically.
+
+## 2. Semantic Logging — `record-change` and `record-deletion`
+
+These are the primary ways LLMs/agents communicate intent:
+
+```bash
+wikifier record-change "src/feature.py" "Added retry decorator because external API is flaky under load. Removed synchronous fallback path."
+wikifier record-deletion "src/dead_code.py" "Dead code after migration to async client. Safe to remove per audit in journal/2026/05/15.md"
+```
+
+Effects:
+- Appends a structured entry to `journal/YYYY/MM/DD.md`
+- Appends a Yellow health row to `file_health.md`
+- Adds item to `pending_updates.md`
+- (Future) Can trigger `prepare-edit` diff capture
+
+This gives the system rich self-review material later ("why did we do X?").
+
+## 3. Journal System
+
+Location: `journal/<YYYY>/<MM>/<DD>.md`
+
+Each day file is append-only. Example entry:
+
+```markdown
+## [2026-05-15 14:28:03 UTC] LLM record-change
+**File:** src/utils.py
+**Action:** modified
+**Reason:** Added exponential backoff helper. Needed because the payment gateway returns 429s during sales events.
+```
+
+Automated entries are also written by `check-changes` for mtime-detected modifications.
+
+Optional Obsidian-friendly export: `wikifier journal --obsidian` produces a single `journal-obsidian.md` with proper `[[wikilinks]]`.
+
+## 4. Logged Issues Hierarchy
+
+```
+Logged_issues/
+├── map.md                 # Overview + quick links
+├── simple/
+│   ├── frontend/
+│   ├── backend/
+│   ├── security/
+│   └── ...
+├── moderate/
+├── high/
+└── critical/
+```
+
+`map.md` contains a categorized index. LLMs are instructed to consult historical issues before debugging.
+
+## 5. Library & Import Map (`library.md`)
+
+Contains:
+- A generated Mermaid `graph TD` showing import/dependency relationships.
+- A flat list of every monitored file with its direct imports/exports.
+- Token-efficient: only filenames + arrows, no code.
+
+Generated by `wikifier update-maps` which runs language-aware grep (Python `import`, JS `require`/`import`, Go `import`, etc.).
+
+## 6. Background Heartbeat (`monitor`)
+
+```bash
+./wikifier.sh monitor &
+# or
+nohup ./wikifier.sh monitor > .wikifier_staging/monitor.log 2>&1 &
+```
+
+Runs `check-changes` every 30s (configurable via env `WIKIFIER_POLL_INTERVAL`).
+
+On any Yellow/Red flip, it can optionally `touch .wikifier_staging/ALERT` so an external watcher (or the LLM when it wakes) knows work is waiting.
+
+## 7. Skills / MCP Interface (`skills/run.md`)
+
+Every command in `wikifier.sh` is exposable as an MCP tool. The `run.md` file contains the exact prompt fragment agents must include at the start of every session.
+
+## 8. Zero-Dependency Philosophy
+
+- No node, python packages, docker, or external binaries.
+- `wikifier.bat` on Windows uses PowerShell + built-in `Get-ChildItem`, `Select-String`, etc.
+- All state lives in plain `.md` files + a few dot-files for timestamps (`.wikifier_last_check`).
+
+## 9. Target Monitored Codebase
+
+Wikifier is designed to document **any** other project. You point it at your real codebase by editing:
+
+- `monitored_paths.txt` — one path per line (can be outside the wikifier tree)
+- `exclude_patterns.txt` — globs to ignore
+
+Example for documenting a sibling project:
+
+```
+monitored_paths.txt
+../my-other-repo/src
+../my-other-repo/tests
+```
+
+## 10. Future v0.4 Ideas (not in current scope)
+
+- Language-specific summary generators (tree-sitter or simple regex)
+- Git hook integration for automatic record-change on commit
+- Diff storage in `.wikifier_staging/diffs/`
+- TUI dashboard (optional, still zero-dep via `dialog` or pure bash)
+
+This Basis document + `spec.md` + the working `wikifier.sh` implementation form the complete contract for v0.3.

wikifier-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# Contributing to Wikifier
+
+Thank you for your interest in Wikifier! This project is intentionally **agent-first** and ultra-light. We want contributions that keep it that way.
+
+## Our Philosophy
+
+- **Zero external dependencies** is sacred. No new Python packages, Node modules, Docker images, or heavy CLIs.
+- **Agent-first design** comes first. If something makes life harder for LLMs/Grok Build/Cline/etc., we probably shouldn't do it.
+- **Semantic logging** (`record-change`) is the heart of the system. Changes without intent are less valuable.
+- Keep it simple. This is a shell + Markdown tool, not a full framework.
+
+## How to Contribute
+
+### 1. Reporting Issues
+
+Please use the appropriate GitHub issue template:
+
+- **🐛 Bug Report** — Something is broken in the CLI, health matrix, journal, or dashboard.
+- **✨ Feature Request** — New command, better behavior, or quality-of-life improvement.
+- **📋 Documentation / Wiki Health Issue** — Problems with file summaries, missing coverage, or incorrect health status.
+- **🤖 Agent / LLM Finding** — You (as an LLM) discovered something while using Wikifier on another project. This is highly encouraged.
+
+### 2. Making Changes
+
+1. **Fork** the repository and create a feature branch from `main`.
+2. **Follow the rules yourself**:
+   ```bash
+   ./wikifier.sh check-changes
+   # Read file_health.md and pending_updates.md
+   # Prioritise Red → Yellow
+   ```
+3. For **any** code or documentation change you make:
+   ```bash
+   ./wikifier.sh record-change "path/to/your/file" "I changed X because Y. This improves Z for agents."
+   ```
+4. After you update the corresponding wiki summary (if applicable):
+   ```bash
+   ./wikifier.sh mark-green "path/to/your/file"
+   ```
+5. Run `./wikifier.sh validate` and `./wikifier.sh update-maps` before opening a PR.
+
+### 3. Pull Request Guidelines
+
+- Keep PRs focused. One logical change per PR.
+- Update documentation (`README.md`, `Basis-v0.3.md`, `skills/run.md`) when behavior changes.
+- If you add a new command, document it in `skills/run.md` and the help text in `wikifier.sh`.
+- All shell changes must remain POSIX-compatible where possible (or clearly PowerShell-only).
+- Add yourself to the journal if you want (`wikifier record-change` is the proper way).
+
+### 4. Code Style
+
+- **Shell**: Keep it readable. Use functions. Prefer clarity over cleverness.
+- **Markdown**: Short paragraphs. Use tables for commands. Use emojis sparingly and consistently.
+- **No new dependencies**. If your idea requires one, it probably doesn't belong here.
+- Test on at least one Unix-like system and (ideally) Windows.
+
+### 5. Documentation Contributions
+
+Wikifier is self-documenting. The best documentation contributions usually come in the form of:
+
+- Improving file summaries in the monitored codebase
+- Better `record-change` reasons that future agents will find useful
+- Improvements to `skills/run.md` (the agent contract)
+
+## Development Workflow (Meta)
+
+When working on Wikifier itself, treat this repository as a Wikifier project:
+
+```bash
+./wikifier.sh check-changes
+# Work
+./wikifier.sh record-change "wikifier.sh" "Added support for X because..."
+./wikifier.sh mark-green "wikifier.sh"
+./wikifier.sh update-maps
+```
+
+## Questions?
+
+Open an issue with the **Agent / LLM Finding** template or just start a discussion.
+
+We especially welcome contributions from other agents and LLM users who have used Wikifier in real projects.
+
+---
+
+*Remember: every good `record-change` you write makes the system more valuable for the next agent that comes along.*

wikifier-0.3.0/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/MANIFEST.in

@@ -0,0 +1,16 @@
+include wikifier/scripts/*
+include README.md
+include LICENSE
+include CONTRIBUTING.md
+include spec.md
+include Basis-v0.3.md
+include TRADEOFFS.md
+include skills/run.md
+include index.html
+global-exclude *.pyc
+global-exclude __pycache__
+prune .github
+prune journal
+prune Logged_issues
+prune .wikifier_staging
+prune .chisel

wikifier-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,107 @@
+# 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/TRADEOFFS.md

@@ -0,0 +1,68 @@
+# TRADEOFFS.md — Design Decisions in Wikifier v0.3
+
+## Passive Polling vs Filesystem Events
+
+**Choice**: Simple mtime polling via `find -newermt` + timestamp file (`.wikifier_last_check`).
+
+**Why**:
+- Zero dependencies and works identically on Linux, macOS, Windows (via WSL or PowerShell equivalent).
+- No `inotifywait`, `fswatch`, or `watchdog` required.
+- LLMs can sleep; the monitor loop just keeps the health matrix fresh.
+
+**Downside**: 30s latency on average. Acceptable for documentation/wiki use case.
+
+## Static HTML Dashboard vs Dynamic SPA
+
+**Choice**: Single self-contained `index.html` with embedded JS that fetches/parses local `.md` files (via `fetch` + marked.js or simple regex, or pre-generated JSON).
+
+**Why**:
+- No build step, no server, no npm.
+- Can be opened directly from disk (`file://`).
+- Extremely fast to render even for thousands of files.
+
+**Future option**: A small Node script can be added later to pre-render the dashboard into a richer `dist/index.html` without changing the core zero-dep contract.
+
+## Semantic `record-change` vs Pure Git History
+
+**Choice**: We still encourage `record-change` even when the user is also using git.
+
+**Why**:
+- Git tells you *what* changed.
+- `record-change` tells the LLM *why* the change was made and the reasoning at decision time.
+- This "intent log" is gold for future agents doing archaeology or refactoring.
+
+## Health Matrix as Single Markdown Table
+
+**Choice**: One `file_health.md` with a Markdown table rather than per-file frontmatter or a JSON blob.
+
+**Why**:
+- LLMs read Markdown natively with perfect fidelity.
+- Humans can read it directly in any editor.
+- Easy to append with `>>` in shell.
+- Git diffs are human-readable.
+
+## Directory-Based Logged Issues
+
+**Choice**: Nested folders `Logged_issues/{severity}/{category}/` instead of tags or a single SQLite DB.
+
+**Why**:
+- Pure filesystem navigation — works in every tool.
+- LLMs can `ls` or `find` to discover issues quickly.
+- Easy to split large files when a category grows.
+
+## No Code in Wiki MD Files
+
+**Choice**: Wiki summary files contain only filename + imports + prose purpose. Zero source code.
+
+**Why**:
+- Massive token savings.
+- Prevents the LLM from being distracted by implementation details when it only needs architecture.
+- The real source of truth remains the original files.
+
+## Heartbeat Wakes the LLM (Conceptual)
+
+The monitor loop can create a sentinel file `.wikifier_staging/work_ready`. When an LLM starts a new session it sees this and knows to run `check-changes` + triage Yellow/Red items immediately. This is the "LLM can sleep" pattern requested in the spec.
+
+---
+
+These tradeoffs keep Wikifier true to its core promise: **maximum compatibility + agent autonomy + zero external dependencies**.