wikifier 4.1.2__tar.gz → 4.1.4__tar.gz

wikifier-4.1.4/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: wikifier
+Version: 4.1.4
+Summary: Zero-dependency agent-to-agent codebase wiki for LLMs and AI agents. Autonomously maintained via record-change and mark-green for token-efficient lookup of files, dependencies, health, and summaries — across tiny scripts to 50k+ monorepos. Optional MCP server with rich tools for agents.
+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,token-efficient,autonomous,record-change,mark-green,agent-wiki,llm-tools,dependency-graph,monorepo
+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
+
+[![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-to-Agent Codebase Wiki — Token-Efficient • Autonomous • Zero-Dependency**
+
+Wikifier gives AI agents and LLMs a living, queryable map of any codebase — from tiny scripts to 50k+ file monorepos — so they can look up files, imports, health status, and summaries without dumping full source into context.
+
+The goal is token efficiency. It works as a token-saving agent-operated wiki layer that agents maintain themselves through a strict but lightweight workflow. Primary purpose: help LLMs and agents work on real codebases without wasting context on raw files they don't need right now.
+
+Key capabilities flow naturally from this:
+- Fast, targeted lookup through small `file_health.md`, `library.md` (with Mermaid dependency graphs and summaries), per-file `*.wiki.md` notes, health matrix, barrel reports, and incremental status.
+- Autonomous maintenance: after editing source, agents use `record-change "the why"` (this is mandatory) to log intent, then `mark-green` once the wiki entry is updated.
+- Support for creating new wiki entries or docs on the fly during agent work.
+- Works great with or without MCP. There's an optional `wikifier-mcp` server that provides rich tools such as `get_project_status`, `get_dependencies`, `get_file_wiki`, `suggest_next_actions`, and `check_changes`.
+- Handles large projects well thanks to incremental updates, directory scoping, and streaming modes. Everything is zero-dependency (pure Python + Bash).
+
+**Mandatory agent protocol** (the exact loop agents should follow): `check-changes` → read the compact `file_health.md` + `pending_updates.md` → prioritize → edit → `record-change` → `mark-green` → `update-maps` when imports or structure change. The full LLM-ready details and examples live in `skills/run.md` (v0.5).
+
+This entire project (including all the M5 dogfood evidence) was built and operated by agents using exactly this mode. It is deliberately **not** a general-purpose human documentation tool or IDE replacement — agent-to-agent first, always.
+
+See `--help`, `skills/run.md`, and the MCP README for concrete usage.
+
+### Intended Use: Strictly Agent-to-Agent (Token-Saving)
+
+This is meant **strictly** as an agent-to-agent wiki layer for token saving:
+
+- Primary purpose: save tokens for agents/LLMs by letting them consult the health matrix, file wikis, barrels, and incremental status instead of re-reading full sources.
+- Agents autonomously keep everything current: edit source → `record-change "the why"` → update the corresponding wiki entry → `mark-green`.
+- You can create new wiki-maintained files or docs as part of your agent sessions.
+- Typical workflow: run `wikifier check-changes`, read the small `file_health.md` + `pending_updates.md`, prioritize (🔴 then 🟡), do the work, record the change with intent, mark it green, and run `update-maps` when the dependency picture shifts.
+- **It shouldn't be used for anything more than that.** Not general human docs, not an IDE, not for broad non-agent use.
+
+The exact loop and LLM workflow are documented in `--help` and `skills/run.md`. All the real-world M5+ evidence in `Findings/` was produced by agents following this protocol precisely.
+
+### Status & Recent Changes
+
+M5 broad real-world dogfood (85-90%+) on multiple external 5k–50k+ creative projects is complete. See `Findings/M5-Dogfood-Progress.md`, `M5-Dogfood-Assessment-Report.md`, and `p6_real_world_validation_report.md` for full agent diaries, metrics, 9 Guiding Principles traces, and the M5.3 plan.
+
+Recent focus (v4.1.x):
+- Human investigation layer separation (only the clean `index.html` viewer is deployed to targets; `diagnostics.html` is maintainer-only).
+- Mapping & update speed hygiene (faster candidate collection with scandir + git fast-path, consistent excludes, parser micro-opts).
+- Human dashboard UX: prominent Quick actions toolbar with copy-to-clipboard buttons for main commands (check-changes, update-maps, monitor &); big primary buttons in empty states for first-time setup; auto-copy of `wikifier update-maps` command on first render of "no structure map yet" (session-guarded) so it feels automatic on first run of a fresh project.
+- mcp and skills docs sync: updated the human layer descriptions in `skills/run.md` and `wikifier/mcp/README.md` (and cli.py comment) to accurately reflect the new dashboard command buttons, empty-state CTAs, and first-run auto-copy behavior. See v4.1.4 notes.
+
+Full history moved to `docs/` and `Findings/`. The project stays deliberately lean and agent-first.
+
+**v4.1.4 (2026-06)**: mcp and skills docs sync for latest human dashboard UX (very minor polish; no behaviour change).
+- Updated "Human investigation layer" section in `skills/run.md` and "Human layer in MCP projects" in `wikifier/mcp/README.md` to describe the Quick actions toolbar, prominent first-time command buttons in empty states, and session-guarded auto-copy of update-maps on first no-map render.
+- Minor update to cli.py comment on copy_human_dashboards for accuracy.
+- Ensures docs accurately describe what humans see in the secondary viewer after init, without altering agent protocol, MCP tools, or core behavior.
+- All under FRESH + record+mark-green (subid=human-dashboard-commands). Complements the v4.1.3 dashboard template changes.
+
+**v4.1.3 (2026-06)**: Human dashboard command buttons + first-run update-maps UX (very minor polish to the secondary human investigation layer).
+- Added visible "Quick actions" bar with easy one-click copy buttons for the primary commands available to humans using the dashboard (check-changes, update-maps, start monitor). Feedback includes exact pasteable command + "run in this project folder then Refresh" guidance + manual refresh link.
+- Enhanced empty states ("No structure map yet", "No files yet") with prominent primary buttons for the relevant commands (update-maps prioritized, combined first-time setup for files).
+- "Automatically on first run": when the no-map empty state first appears in a browser session, the `wikifier update-maps` command is auto-copied (guarded by sessionStorage) with a note, making the recommended first action feel automatic. Buttons + instructions guide the user to run in terminal and refresh/poll.
+- Existing "Rebuild tree" / "Update data" buttons now use the improved copy+feedback UX. Keeps the clean human view (no dense agent internals).
+- All under protocol (FRESH, record+mark-green with subid=human-dashboard-commands). No new features or scope change. Complements the existing copy snapshot buttons and guidance.
+
+**v4.1.2 (2026-06)**: Speed improvements for updates on large projects (scandir/git fast-path in collectors, richer early pruning via `exclude_patterns.txt`, regex hoisting in parsers). Complements scoping, streaming budgets, and incremental dirty + barrel reverse index. No behaviour change.
+
+**v4.1.1**: Human layer separation enforcement (only `index.html` copied on init).
+
+**v4.1.0**: Structure cleanup (historical docs to `docs/`).
+
+**v4.0 + 4.0.1 + M5**: Broad dogfood, MCP hardening, zero-dep enforcement, sustained monitor/subagent foundations. See `Findings/` for details.
+
+---
+
+## 🚀 Installation
+
+## Installation & Quick Start (for Agents & Humans)
+
+```bash
+pip install wikifier
+```
+
+For a project (recommended for agents):
+
+```bash
+# 1. In the target project (or use WIKIFIER_PROJECT_ROOT)
+wikifier init
+
+# 2. Focus monitored_paths.txt for large repos (highly recommended)
+# 3. Run the agent loop
+wikifier check-changes
+wikifier health --summary
+# ... edit ... 
+wikifier record-change "path/to/file.py" "added feature X because Y (agent task Z)"
+wikifier mark-green "path/to/file.py"
+wikifier update-maps   # when imports/structure changed
+```
+
+**For MCP / AI agents** (Claude Desktop, Cursor, Cline, etc.):
+
+```bash
+WIKIFIER_PROJECT_ROOT=/abs/path/to/your/project wikifier-mcp
+```
+
+Or pass `project_root=` on every tool call. Root detection priority: env var > explicit param > upward walk for markers > .mcp.json.
+
+Full protocol, examples, and LLM workflow: `skills/run.md` (read this first as an agent).
+
+## What You Get
+
+- Token-efficient lookup for agents (health matrix, library.md with Mermaid, file wikis, BRC, incremental status).
+- Autonomous maintenance: `record-change` (the "why") + `mark-green`.
+- Incremental + scoped + resumable for large codebases.
+- Optional MCP server with 23+ tools for agents.
+- Secondary clean `index.html` dashboard (after init) for humans browsing the agent's wiki (chart + file descriptions + copyable snapshots).
+- True zero dependencies.
+
+See `skills/run.md` for the exact agent contract and `wikifier/mcp/README.md` for MCP setup.
+
+## Core Commands
+
+| Command | Purpose |
+|---------|---------|
+| `wikifier check-changes` | Incremental scan + health/pending update |
+| `wikifier record-change <file> "reason"` | Log why (required after edits) |
+| `wikifier mark-green <file>` | Mark the wiki entry current |
+| `wikifier update-maps` | Rebuild dependency graph + library.md |
+| `wikifier health --summary` | Quick view (use for agents) |
+| `wikifier monitor &` | Background incremental heartbeat |
+
+For full power use the Python library (`from wikifier import ...`) or MCP tools directly.
+
+## Links
+
+- GitHub: https://github.com/IronAdamant/wikifier
+- PyPI: https://pypi.org/project/wikifier/
+- Agent Protocol: `skills/run.md`
+- MCP: `wikifier/mcp/README.md`
+- Evidence: `Findings/` (M5 dogfood etc.)
+
+**For AI search / agents**: Wikifier is a zero-dependency, agent-maintained, token-saving codebase wiki with autonomous `record-change` / `mark-green` updates, MCP tools, and strong support for large monorepos via scoping and streaming.

wikifier-4.1.4/README.md

@@ -0,0 +1,139 @@
+# Wikifier
+
+[![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-to-Agent Codebase Wiki — Token-Efficient • Autonomous • Zero-Dependency**
+
+Wikifier gives AI agents and LLMs a living, queryable map of any codebase — from tiny scripts to 50k+ file monorepos — so they can look up files, imports, health status, and summaries without dumping full source into context.
+
+The goal is token efficiency. It works as a token-saving agent-operated wiki layer that agents maintain themselves through a strict but lightweight workflow. Primary purpose: help LLMs and agents work on real codebases without wasting context on raw files they don't need right now.
+
+Key capabilities flow naturally from this:
+- Fast, targeted lookup through small `file_health.md`, `library.md` (with Mermaid dependency graphs and summaries), per-file `*.wiki.md` notes, health matrix, barrel reports, and incremental status.
+- Autonomous maintenance: after editing source, agents use `record-change "the why"` (this is mandatory) to log intent, then `mark-green` once the wiki entry is updated.
+- Support for creating new wiki entries or docs on the fly during agent work.
+- Works great with or without MCP. There's an optional `wikifier-mcp` server that provides rich tools such as `get_project_status`, `get_dependencies`, `get_file_wiki`, `suggest_next_actions`, and `check_changes`.
+- Handles large projects well thanks to incremental updates, directory scoping, and streaming modes. Everything is zero-dependency (pure Python + Bash).
+
+**Mandatory agent protocol** (the exact loop agents should follow): `check-changes` → read the compact `file_health.md` + `pending_updates.md` → prioritize → edit → `record-change` → `mark-green` → `update-maps` when imports or structure change. The full LLM-ready details and examples live in `skills/run.md` (v0.5).
+
+This entire project (including all the M5 dogfood evidence) was built and operated by agents using exactly this mode. It is deliberately **not** a general-purpose human documentation tool or IDE replacement — agent-to-agent first, always.
+
+See `--help`, `skills/run.md`, and the MCP README for concrete usage.
+
+### Intended Use: Strictly Agent-to-Agent (Token-Saving)
+
+This is meant **strictly** as an agent-to-agent wiki layer for token saving:
+
+- Primary purpose: save tokens for agents/LLMs by letting them consult the health matrix, file wikis, barrels, and incremental status instead of re-reading full sources.
+- Agents autonomously keep everything current: edit source → `record-change "the why"` → update the corresponding wiki entry → `mark-green`.
+- You can create new wiki-maintained files or docs as part of your agent sessions.
+- Typical workflow: run `wikifier check-changes`, read the small `file_health.md` + `pending_updates.md`, prioritize (🔴 then 🟡), do the work, record the change with intent, mark it green, and run `update-maps` when the dependency picture shifts.
+- **It shouldn't be used for anything more than that.** Not general human docs, not an IDE, not for broad non-agent use.
+
+The exact loop and LLM workflow are documented in `--help` and `skills/run.md`. All the real-world M5+ evidence in `Findings/` was produced by agents following this protocol precisely.
+
+### Status & Recent Changes
+
+M5 broad real-world dogfood (85-90%+) on multiple external 5k–50k+ creative projects is complete. See `Findings/M5-Dogfood-Progress.md`, `M5-Dogfood-Assessment-Report.md`, and `p6_real_world_validation_report.md` for full agent diaries, metrics, 9 Guiding Principles traces, and the M5.3 plan.
+
+Recent focus (v4.1.x):
+- Human investigation layer separation (only the clean `index.html` viewer is deployed to targets; `diagnostics.html` is maintainer-only).
+- Mapping & update speed hygiene (faster candidate collection with scandir + git fast-path, consistent excludes, parser micro-opts).
+- Human dashboard UX: prominent Quick actions toolbar with copy-to-clipboard buttons for main commands (check-changes, update-maps, monitor &); big primary buttons in empty states for first-time setup; auto-copy of `wikifier update-maps` command on first render of "no structure map yet" (session-guarded) so it feels automatic on first run of a fresh project.
+- mcp and skills docs sync: updated the human layer descriptions in `skills/run.md` and `wikifier/mcp/README.md` (and cli.py comment) to accurately reflect the new dashboard command buttons, empty-state CTAs, and first-run auto-copy behavior. See v4.1.4 notes.
+
+Full history moved to `docs/` and `Findings/`. The project stays deliberately lean and agent-first.
+
+**v4.1.4 (2026-06)**: mcp and skills docs sync for latest human dashboard UX (very minor polish; no behaviour change).
+- Updated "Human investigation layer" section in `skills/run.md` and "Human layer in MCP projects" in `wikifier/mcp/README.md` to describe the Quick actions toolbar, prominent first-time command buttons in empty states, and session-guarded auto-copy of update-maps on first no-map render.
+- Minor update to cli.py comment on copy_human_dashboards for accuracy.
+- Ensures docs accurately describe what humans see in the secondary viewer after init, without altering agent protocol, MCP tools, or core behavior.
+- All under FRESH + record+mark-green (subid=human-dashboard-commands). Complements the v4.1.3 dashboard template changes.
+
+**v4.1.3 (2026-06)**: Human dashboard command buttons + first-run update-maps UX (very minor polish to the secondary human investigation layer).
+- Added visible "Quick actions" bar with easy one-click copy buttons for the primary commands available to humans using the dashboard (check-changes, update-maps, start monitor). Feedback includes exact pasteable command + "run in this project folder then Refresh" guidance + manual refresh link.
+- Enhanced empty states ("No structure map yet", "No files yet") with prominent primary buttons for the relevant commands (update-maps prioritized, combined first-time setup for files).
+- "Automatically on first run": when the no-map empty state first appears in a browser session, the `wikifier update-maps` command is auto-copied (guarded by sessionStorage) with a note, making the recommended first action feel automatic. Buttons + instructions guide the user to run in terminal and refresh/poll.
+- Existing "Rebuild tree" / "Update data" buttons now use the improved copy+feedback UX. Keeps the clean human view (no dense agent internals).
+- All under protocol (FRESH, record+mark-green with subid=human-dashboard-commands). No new features or scope change. Complements the existing copy snapshot buttons and guidance.
+
+**v4.1.2 (2026-06)**: Speed improvements for updates on large projects (scandir/git fast-path in collectors, richer early pruning via `exclude_patterns.txt`, regex hoisting in parsers). Complements scoping, streaming budgets, and incremental dirty + barrel reverse index. No behaviour change.
+
+**v4.1.1**: Human layer separation enforcement (only `index.html` copied on init).
+
+**v4.1.0**: Structure cleanup (historical docs to `docs/`).
+
+**v4.0 + 4.0.1 + M5**: Broad dogfood, MCP hardening, zero-dep enforcement, sustained monitor/subagent foundations. See `Findings/` for details.
+
+---
+
+## 🚀 Installation
+
+## Installation & Quick Start (for Agents & Humans)
+
+```bash
+pip install wikifier
+```
+
+For a project (recommended for agents):
+
+```bash
+# 1. In the target project (or use WIKIFIER_PROJECT_ROOT)
+wikifier init
+
+# 2. Focus monitored_paths.txt for large repos (highly recommended)
+# 3. Run the agent loop
+wikifier check-changes
+wikifier health --summary
+# ... edit ... 
+wikifier record-change "path/to/file.py" "added feature X because Y (agent task Z)"
+wikifier mark-green "path/to/file.py"
+wikifier update-maps   # when imports/structure changed
+```
+
+**For MCP / AI agents** (Claude Desktop, Cursor, Cline, etc.):
+
+```bash
+WIKIFIER_PROJECT_ROOT=/abs/path/to/your/project wikifier-mcp
+```
+
+Or pass `project_root=` on every tool call. Root detection priority: env var > explicit param > upward walk for markers > .mcp.json.
+
+Full protocol, examples, and LLM workflow: `skills/run.md` (read this first as an agent).
+
+## What You Get
+
+- Token-efficient lookup for agents (health matrix, library.md with Mermaid, file wikis, BRC, incremental status).
+- Autonomous maintenance: `record-change` (the "why") + `mark-green`.
+- Incremental + scoped + resumable for large codebases.
+- Optional MCP server with 23+ tools for agents.
+- Secondary clean `index.html` dashboard (after init) for humans browsing the agent's wiki (chart + file descriptions + copyable snapshots).
+- True zero dependencies.
+
+See `skills/run.md` for the exact agent contract and `wikifier/mcp/README.md` for MCP setup.
+
+## Core Commands
+
+| Command | Purpose |
+|---------|---------|
+| `wikifier check-changes` | Incremental scan + health/pending update |
+| `wikifier record-change <file> "reason"` | Log why (required after edits) |
+| `wikifier mark-green <file>` | Mark the wiki entry current |
+| `wikifier update-maps` | Rebuild dependency graph + library.md |
+| `wikifier health --summary` | Quick view (use for agents) |
+| `wikifier monitor &` | Background incremental heartbeat |
+
+For full power use the Python library (`from wikifier import ...`) or MCP tools directly.
+
+## Links
+
+- GitHub: https://github.com/IronAdamant/wikifier
+- PyPI: https://pypi.org/project/wikifier/
+- Agent Protocol: `skills/run.md`
+- MCP: `wikifier/mcp/README.md`
+- Evidence: `Findings/` (M5 dogfood etc.)
+
+**For AI search / agents**: Wikifier is a zero-dependency, agent-maintained, token-saving codebase wiki with autonomous `record-change` / `mark-green` updates, MCP tools, and strong support for large monorepos via scoping and streaming.

{wikifier-4.1.2 → wikifier-4.1.4}/index.html

@@ -125,6 +125,25 @@
                 </div>
             </div>
 
+            <!-- Quick actions: buttons for the main commands (copy to clipboard so user can run in terminal) -->
+            <div class="mb-4 px-1">
+              <div class="text-[10px] text-slate-400 mb-1">Quick actions — click to copy the command, paste &amp; run in your terminal (this folder), then refresh the page</div>
+              <div class="flex flex-wrap gap-2">
+                <button onclick="copyCommandForRun('check-changes')" 
+                        class="px-3 py-1.5 text-sm rounded-xl bg-slate-800 hover:bg-slate-700 border border-slate-700 flex items-center gap-x-2">
+                  <span>Check for changes</span>
+                </button>
+                <button onclick="copyCommandForRun('update-maps')" 
+                        class="px-3 py-1.5 text-sm rounded-xl bg-emerald-800 hover:bg-emerald-700 border border-emerald-700 text-emerald-300 flex items-center gap-x-2">
+                  <span>Rebuild structure map</span>
+                </button>
+                <button onclick="copyCommandForRun('monitor &amp;')" 
+                        class="px-3 py-1.5 text-sm rounded-xl bg-slate-800 hover:bg-slate-700 border border-slate-700 flex items-center gap-x-2">
+                  <span>Start background monitor</span>
+                </button>
+              </div>
+            </div>
+
             <!-- HERO: The Chart / Tree (what humans see first and clearly) -->
             <div class="mb-8 bg-slate-900 border border-slate-800 rounded-3xl p-6">
                 <div class="flex items-center justify-between mb-3">
@@ -341,7 +360,13 @@
             if (!rows || rows.length === 0) {
                 listEl.innerHTML = `<div class="px-5 py-8 text-center">
                     <div class="text-sm text-slate-400">No files in the wiki yet.</div>
-                    <div class="text-xs mt-2 text-slate-500">Run <code class="bg-slate-900 px-1">wikifier check-changes &amp;&amp; wikifier update-maps</code> in this project folder, then refresh.</div>
+                    <div class="mt-3">
+                        <button onclick="copyCommandForRun('check-changes &amp;&amp; update-maps', 'wikifier check-changes &amp;&amp; wikifier update-maps')" 
+                                class="px-4 py-2 bg-emerald-600 hover:bg-emerald-500 text-white rounded-xl text-sm font-medium">
+                            📋 Copy first-time setup command
+                        </button>
+                    </div>
+                    <div class="mt-2 text-xs text-slate-500">Run <code class="bg-slate-900 px-1">wikifier check-changes &amp;&amp; wikifier update-maps</code> in this project folder, then refresh.</div>
                 </div>`;
                 return;
             }
@@ -524,10 +549,30 @@
                 container.innerHTML = `<div class="text-sm p-4 bg-slate-900 border border-slate-700 rounded">
                     <div class="font-semibold mb-1">No structure map yet</div>
                     <div class="text-slate-400">This project hasn't had its import/dependency tree generated yet.</div>
-                    <div class="mt-2 text-xs">Run this in the project folder:</div>
-                    <code class="block mt-1 p-2 bg-slate-950 rounded text-emerald-300">wikifier update-maps</code>
-                    <div class="mt-1 text-[10px] text-slate-500">Then refresh this page. The chart will show your codebase structure.</div>
+                    <div class="mt-3">
+                        <button onclick="copyCommandForRun('update-maps')" 
+                                class="px-4 py-2 bg-emerald-600 hover:bg-emerald-500 text-white rounded-xl text-sm font-medium w-full sm:w-auto">
+                            📋 Copy command &amp; run wikifier update-maps (first time)
+                        </button>
+                    </div>
+                    <div class="mt-2 text-[10px] text-slate-400">Run the copied command in your terminal <strong>inside this project folder</strong>, then refresh this page (or wait for the ~30s auto update). This is the recommended first step when you open the dashboard in a new project.</div>
                 </div>`;
+
+                // "Automatically on the first run": if this is the very first time the user sees the empty map state in this browser session,
+                // auto-copy the command for them so it feels automatic, with clear feedback.
+                if (!sessionStorage.getItem('wikifier_first_map_auto_copied')) {
+                    sessionStorage.setItem('wikifier_first_map_auto_copied', '1');
+                    setTimeout(() => {
+                        navigator.clipboard.writeText('wikifier update-maps').then(() => {
+                            // non-intrusive note that we helped
+                            const note = document.createElement('div');
+                            note.className = 'mt-2 text-[10px] text-emerald-400';
+                            note.textContent = '✓ update-maps command auto-copied for first run — paste it in your terminal now.';
+                            const emptyBox = container.querySelector('div');
+                            if (emptyBox) emptyBox.appendChild(note);
+                        }).catch(() => {});
+                    }, 300);
+                }
                 return;
             }
             window.libraryMdCache = md;
@@ -611,16 +656,39 @@ Open index.html in the project for the live visual version.
         // Agents and technical users: use the .md files directly, diagnostics.html, MCP, or CLI.)
 
         // Lightweight runCommand for the human dashboard (only the two we surface prominently)
+        // Helper to copy a ready-to-paste command and give clear next-step feedback
+        function copyCommandForRun(cmd, fullText) {
+            const full = fullText || `wikifier ${cmd}`;
+            navigator.clipboard.writeText(full).then(() => {
+                const msg = document.createElement('div');
+                msg.className = `fixed bottom-4 right-4 bg-emerald-900 border border-emerald-700 px-4 py-3 rounded-2xl text-sm z-50 max-w-xs`;
+                msg.innerHTML = `
+                    <div class="font-medium">Copied to clipboard:</div>
+                    <code class="block mt-1 bg-black/40 px-2 py-1 rounded text-emerald-300 break-all">${full}</code>
+                    <div class="mt-2 text-xs text-emerald-200">Paste &amp; run it in the terminal <strong>inside this project folder</strong>, then click <span class="underline">Refresh</span> above (or wait ~30s).</div>
+                    <button onclick="this.closest('.fixed').remove(); window.location.reload()" class="mt-2 text-xs underline">Refresh dashboard now</button>
+                `;
+                document.body.appendChild(msg);
+                // auto remove after a while if user doesn't interact
+                setTimeout(() => { if (msg.parentNode) msg.parentNode.removeChild(msg); }, 12000);
+            }).catch(() => {
+                // Fallback for browsers that block clipboard
+                const msg = document.createElement('div');
+                msg.className = `fixed bottom-4 right-4 bg-slate-800 border border-slate-700 px-3 py-2 rounded-2xl text-xs z-50`;
+                msg.innerHTML = `Run this in the terminal: <code class="bg-black/40 px-1">${full}</code>`;
+                document.body.appendChild(msg);
+                setTimeout(()=>{ if (msg.parentNode) msg.parentNode.removeChild(msg); }, 4000);
+            });
+
+            // Optimistic: after user likely ran it, the next poll will pick it up
+            if (cmd.includes('check') || cmd.includes('health')) setTimeout(() => loadHealthMatrix && loadHealthMatrix(), 800);
+            if (cmd.includes('update')) setTimeout(() => loadMermaid && loadMermaid(), 800);
+            if (cmd.includes('monitor')) setTimeout(() => loadMonitorStatus && loadMonitorStatus(true), 600);
+        }
+
+        // Legacy / existing buttons still work via the improved helper
         function runCommand(cmd) {
-            const msg = document.createElement('div');
-            msg.className = `fixed bottom-4 right-4 bg-slate-800 border border-slate-700 px-3 py-1.5 rounded-2xl text-xs flex items-center gap-2 z-50`;
-            msg.innerHTML = `Run <code>wikifier ${cmd}</code> (or <code>./wikifier.sh ${cmd}</code>) in this folder`;
-            document.body.appendChild(msg);
-            setTimeout(()=>{msg.style.opacity=0;setTimeout(()=>msg.remove(),900)},1600);
-
-            if (cmd.includes('check') || cmd.includes('health')) setTimeout(() => loadHealthMatrix && loadHealthMatrix(), 600);
-            if (cmd.includes('update')) setTimeout(() => loadMermaid && loadMermaid(), 500);
-            if (cmd.includes('monitor')) setTimeout(() => loadMonitorStatus && loadMonitorStatus(true), 400);
+            copyCommandForRun(cmd);
         }
 
         // Boot: only what the human view needs (chart + files+descs + tree + monitor). Poll for live feel.

{wikifier-4.1.2 → wikifier-4.1.4}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wikifier"
-version = "4.1.2"
-description = "Agent-first, zero-dependency, self-maintaining codebase documentation & change tracking system"
+version = "4.1.4"
+description = "Zero-dependency agent-to-agent codebase wiki for LLMs and AI agents. Autonomously maintained via record-change and mark-green for token-efficient lookup of files, dependencies, health, and summaries — across tiny scripts to 50k+ monorepos. Optional MCP server with rich tools for agents."
 readme = "README.md"
 license = {text = "MIT"}
 authors = [
@@ -17,7 +17,9 @@ maintainers = [
 requires-python = ">=3.8"
 keywords = [
     "wiki", "documentation", "llm", "agent", "mcp", "codebase", 
-    "health-matrix", "zero-dependency", "shell"
+    "health-matrix", "zero-dependency", "shell", "token-efficient", 
+    "autonomous", "record-change", "mark-green", "agent-wiki", 
+    "llm-tools", "dependency-graph", "monorepo"
 ]
 classifiers = [
     "Development Status :: 4 - Beta",

{wikifier-4.1.2 → wikifier-4.1.4}/skills/run.md

@@ -243,4 +243,4 @@ All support `project_root=...` and return structured data (plus side-effecting s
 
 See README.md "Intended Use" for the strict agent-to-agent wiki scope (token saving for lookup + autonomous update/create of wiki entries only). M5 dogfood validated this on real external projects with the exact patterns above. Recent 4.0.1 hygiene (health coerce + superseded prune) further improves reliability of the matrix for agents doing direct lookups/updates.
 
-**Human investigation layer (secondary, opt-in)**: `wikifier init` copies only `index.html` (the clean human wiki viewer) into the target project (the folder where MCP/CLI run). `diagnostics.html` (Wikifier maintainer hub) is no longer copied — it would show the wrong tree (Wikifier's internals) and be stale for the host project. Humans open the local `index.html` (via `python -m http.server` recommended) to see a clean visual of *that project's* agent-maintained wiki: prominent code structure / dependency chart (Mermaid) as the hero, followed by a simple "Files & descriptions" list (paths + short "what this file is about" summaries pulled from the wiki notes), and a lightweight "Browse by folder" tree derived from the health data. It auto-polls for refresh when the monitor or agents update the underlying .md files. Prominent copy buttons export "structure as text" (Mermaid source) and a clean full snapshot (tree + file list + descriptions) — exactly the compact, token-saving view agents use. The default human page is intentionally free of dense agent internals (those live in `diagnostics.html` in the Wikifier source for technical users). If an old diagnostics.html is present, it can be safely deleted. The .md files + MCP/CLI/tools remain the primary SSOT and update mechanism for agents. This layer lets humans (or teams) visually investigate and copy-paste wiki summaries for their own work / LLM chats without touching agent behavior or adding deps.
+**Human investigation layer (secondary, opt-in)**: `wikifier init` copies only `index.html` (the clean human wiki viewer) into the target project (the folder where MCP/CLI run). `diagnostics.html` (Wikifier maintainer hub) is no longer copied — it would show the wrong tree (Wikifier's internals) and be stale for the host project. Humans open the local `index.html` (via `python -m http.server` recommended) to see a clean visual of *that project's* agent-maintained wiki: prominent code structure / dependency chart (Mermaid) as the hero, followed by a simple "Files & descriptions" list (paths + short "what this file is about" summaries pulled from the wiki notes), and a lightweight "Browse by folder" tree derived from the health data. A "Quick actions" toolbar provides one-click copy buttons for the main commands (check-changes, update-maps, monitor &); empty states ("no map yet", "no files yet") have prominent buttons for first-time commands (update-maps is prioritized). On first open with no map, the update-maps command is auto-copied (sessionStorage-guarded) with guidance so initial setup feels automatic. It auto-polls for refresh when the monitor or agents update the underlying .md files. Prominent copy buttons export "structure as text" (Mermaid source) and a clean full snapshot (tree + file list + descriptions) — exactly the compact, token-saving view agents use. The default human page is intentionally free of dense agent internals (those live in `diagnostics.html` in the Wikifier source for technical users). If an old diagnostics.html is present, it can be safely deleted. The .md files + MCP/CLI/tools remain the primary SSOT and update mechanism for agents. This layer lets humans (or teams) visually investigate and copy-paste wiki summaries for their own work / LLM chats without touching agent behavior or adding deps.

{wikifier-4.1.2 → wikifier-4.1.4}/wikifier/__init__.py

@@ -62,4 +62,4 @@ from .contracts import (
     compute_acs_confidence,
 )
 
-__version__ = "4.1.2"
+__version__ = "4.1.4"

{wikifier-4.1.2 → wikifier-4.1.4}/wikifier/cli.py

@@ -1160,8 +1160,10 @@ def health(
 # Human Investigation Layer (secondary sub-project)
 # Only index.html (the clean human wiki viewer) is copied into target projects by init.
 # It provides the prominent code structure chart (Mermaid), "Files & descriptions" list with
-# short summaries, folder browser, and copy buttons for the *target project's* agent-maintained
-# wiki (data-driven from its file_health.* + library.md after check-changes + update-maps).
+# short summaries, folder browser, copy buttons for tree/snapshot, a "Quick actions" toolbar
+# with copy buttons for main commands (check-changes, update-maps, monitor &), and prominent
+# buttons + session-guarded auto-copy of update-maps in empty states for easy first-run setup.
+# (data-driven from its file_health.* + library.md after check-changes + update-maps).
 # diagnostics.html is the Wikifier-specific heavy maintainer/refactor/porter hub (architecture,
 # full command map, porting checklist, this project's own source tree with purposes). It is
 # *not* copied to foreign project roots — it would point at the wrong folder and be stale for