wikifier 4.6.7__tar.gz → 4.6.8__tar.gz

{wikifier-4.6.7/wikifier.egg-info → wikifier-4.6.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.6.7
+Version: 4.6.8
 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
@@ -52,7 +52,14 @@ Works from small scripts to large monorepos. **Deep import/include maps** (zero-
 | C# | `.cs` | `using` namespaces |
 | Java | `.java` | `import` / `import static` |
 
-Health/journal still work for any monitored path. Parsers are **pragmatic regex** (not full cargo/`go.mod`/classpath/`-I` resolution). Prefer **lean `monitored_paths.txt`** on huge monorepos; raise dirty cap with `WIKIFIER_CHECK_CHANGES_MAX` (default 2000) only when needed.
+Health/journal still work for any monitored path. Parsers are **pragmatic regex** (not full cargo/`go.mod`/classpath/`-I` resolution). On huge monorepos, split scope deliberately:
+
+| File | Surface |
+|------|---------|
+| **`map_paths.txt`** | Package roots for **import maps** (`update-maps` walk). Prefer package dirs (`src/`, `packages/foo/`) — not a wiki-only file list. |
+| **`monitored_paths.txt`** | **Wiki / health** watch list (can be individual `.md` files). Does **not** define the map. |
+
+Or pass `--directory=pkg/` / `--max-files=N` per run. Raise dirty cap with `WIKIFIER_CHECK_CHANGES_MAX` (default 2000) only when needed. Never set `project_root` to a multi-repo parent of clones.
 
 ## Why
 
@@ -74,7 +81,8 @@ pip install wikifier            # pure Python stdlib core — no runtime deps
 pip install wikifier[mcp]       # optional Model Context Protocol (MCP) server
 
 cd /path/to/your/project
-wikifier init                   # seeds + human index.html
+wikifier init                   # seeds index.html + lean path-list templates
+# Edit monitored_paths.txt + map_paths.txt to package roots (not bare ".") on real trees
 wikifier update-maps            # full structural map → library.md + import cache
 wikifier health --summary       # matrix counts
 wikifier suggest-next           # or MCP suggest_next_actions — 🔴/🟡 only
@@ -82,6 +90,8 @@ wikifier suggest-next           # or MCP suggest_next_actions — 🔴/🟡 only
 
 Always set an explicit root for external trees: `WIKIFIER_PROJECT_ROOT=/abs/path wikifier …`
 
+**MCP `session_bootstrap` → `readiness: blocked`?** That means lean scope and/or the map are missing (often bare `.` monitor + never ran `update-maps`) — not a broken install. Fix: write lean `monitored_paths.txt` / `map_paths.txt`, then `update-maps`. Agent contract: **`skills/run.md`** § *Readiness blocked*; dogfood: `Findings/readiness-blocked-bare-monitor-2026-07.md`.
+
 ## Steady state (only touch what needs it)
 
 Full protocol: [`skills/run.md`](skills/run.md) (Agent Protocol v0.6 — package **4.6.x**).
@@ -109,11 +119,11 @@ Advanced intel as needed: `get_dependencies`, `get_dependents`, `get_cycles`, ba
 
 - **Import analysis** — Python, JS/TS (ESM/CJS, barrels), Rust (`use`/`mod` + best-effort `crate::` paths), Go, C/C++ includes, C# usings; per-edge confidence; barrel expansion for TS/JS
 - **Incremental pipeline** — pure-Python `update-maps`: dirty parse → import cache → reverse deps → cycles → `library.md`
-- **Warm agent maps (4.6.3–4.6.6)** — zero-dirty + **index-first** candidates (re-list only on fingerprint/index disagreement); **stdlib SQLite**; content-hash dirty
-- **Two path lists** — `map_paths.txt` = map package roots; `monitored_paths.txt` = wiki/health watch (independent)
+- **Warm agent maps (4.6.3–4.6.7)** — zero-dirty + **index-first** candidates (re-list only when fingerprint / map-scoped index / live count disagree); **MapScope** keeps collect, live count, index filter, and prune aligned; **stdlib SQLite**; content-hash dirty
+- **Two path lists** — `map_paths.txt` = map package roots; `monitored_paths.txt` = wiki/health watch (**independent** — wiki file lists never collapse the map)
 - **Partial-map honesty** — `map_coverage` on `update_maps` / bootstrap / **`suggest_next`**; `update_maps_until_complete` when incomplete
-- **Cache ops** — `wikifier cache-status`; JSON dual-write **opt-in only** (`WIKIFIER_CACHE_JSON=1`); dual-read for migrate
-- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal`; prefer `actionable_low_conf_edges` + reason codes — **never** raw `low_conf_edges` alone
+- **Cache ops** — `wikifier cache-status`; JSON dual-write **deprecated default-off** (`WIKIFIER_CACHE_JSON=1` opt-in); dual-read for migrate
+- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal`; prefer `actionable_low_conf_edges` + reason codes — **never** raw `low_conf_edges` averages alone
 - **Scale** — reverse index + barrel invalidation so one edit doesn’t re-scan the monorepo
 - **MCP tools** — optional server for Claude, Cursor, Cline, and other MCP clients
 - **Zero core dependencies** — stdlib only; forks can add their own stack on top
@@ -127,18 +137,21 @@ Full / heavy runs (historical order-of-magnitude):
 |---------|-------|----------------------------|
 | llama_index | ~3.8k Python files | ~8.5s class full |
 | Babylon.js | ~3.9k TS files, barrel-heavy | minutes full; scoped re-runs tens of seconds |
-| Large trees (e.g. LLVM-scale) | tens of thousands of files | use lean monitor + `--directory` / `--max-files` |
+| Large trees (e.g. LLVM-scale) | tens of thousands of files | `map_paths` / `--directory` / `--max-files` — never unscoped one-shot |
+
+Warm **0-dirty** re-runs after **4.6.7** (same machine class; scoped; candidates **reused** — agent session path):
 
-Warm **0-dirty** re-runs after 4.6.3 (same machine; scoped where noted) — agent session path:
+| Project | Scope | Warm `update-maps` | n |
+|---------|-------|--------------------|---|
+| Wikifier (self) | `map_paths`: `wikifier/` + `tests/` | **~30 ms** | 50 |
+| llama_index | `llama-index-core` | **~76 ms** | 724 |
+| rust | `library/std` | **~79 ms** | 719 |
+| airflow | `airflow-core` | **~180 ms** | 1920 |
+| Babylon.js | `packages` | **~400 ms** | 3895 |
 
-| Project | Scope | Warm2 `update-maps` |
-|---------|-------|---------------------|
-| Wikifier (self) | incremental full | ~43 ms |
-| redox | `src` | ~17 ms |
-| llama_index | `llama-index-core` | ~0.6 s |
-| rust | `library/std/src` (budgeted) | ~0.7 s (vs multi-second full-tree walk before scoped collect) |
+Residual floor on large scopes is mtime/stat + live count under MapScope (not full JSON re-walk). Sub-100ms is not a hard SLA on every 1k+ tree.
 
-Tests: `python -m unittest discover tests` (stdlib only; 86+ cases including agent-scale edges).
+Tests: `python -m unittest discover tests` (stdlib only; **125** cases including MapScope / index-first / dual-write).
 
 ## Commands
 
@@ -152,7 +165,8 @@ Tests: `python -m unittest discover tests` (stdlib only; 86+ cases including age
 | `wikifier mark-green <file>` | Mark wiki current + source content-hash baseline |
 | `wikifier record-deletion <file> "reason"` | Mark removed paths 🔴 + prune barrel refs |
 | `wikifier suggest-next` | Next actions (🔴/actionable 🟡 only; `--json` for `actions[]`) |
-| `wikifier update-maps [--directory=src/] [--max-files=N]` | Rebuild graph + `library.md` (warm 0-dirty is fast) |
+| `wikifier update-maps [--directory=src/] [--max-files=N]` | Rebuild graph + `library.md` (warm 0-dirty is fast; honors `map_paths.txt`) |
+| `wikifier cache-status` | SQLite/JSON backend, dual-write policy, coverage snapshot (no full pair load) |
 | `wikifier health [--summary\|--json]` | Health matrix (machine-friendly flags) |
 | `wikifier validate` | Missing wiki rows + ghost paths |
 | `wikifier cycles` | Circular deps + break hints |

{wikifier-4.6.7 → wikifier-4.6.8}/README.md

@@ -20,7 +20,14 @@ Works from small scripts to large monorepos. **Deep import/include maps** (zero-
 | C# | `.cs` | `using` namespaces |
 | Java | `.java` | `import` / `import static` |
 
-Health/journal still work for any monitored path. Parsers are **pragmatic regex** (not full cargo/`go.mod`/classpath/`-I` resolution). Prefer **lean `monitored_paths.txt`** on huge monorepos; raise dirty cap with `WIKIFIER_CHECK_CHANGES_MAX` (default 2000) only when needed.
+Health/journal still work for any monitored path. Parsers are **pragmatic regex** (not full cargo/`go.mod`/classpath/`-I` resolution). On huge monorepos, split scope deliberately:
+
+| File | Surface |
+|------|---------|
+| **`map_paths.txt`** | Package roots for **import maps** (`update-maps` walk). Prefer package dirs (`src/`, `packages/foo/`) — not a wiki-only file list. |
+| **`monitored_paths.txt`** | **Wiki / health** watch list (can be individual `.md` files). Does **not** define the map. |
+
+Or pass `--directory=pkg/` / `--max-files=N` per run. Raise dirty cap with `WIKIFIER_CHECK_CHANGES_MAX` (default 2000) only when needed. Never set `project_root` to a multi-repo parent of clones.
 
 ## Why
 
@@ -42,7 +49,8 @@ pip install wikifier            # pure Python stdlib core — no runtime deps
 pip install wikifier[mcp]       # optional Model Context Protocol (MCP) server
 
 cd /path/to/your/project
-wikifier init                   # seeds + human index.html
+wikifier init                   # seeds index.html + lean path-list templates
+# Edit monitored_paths.txt + map_paths.txt to package roots (not bare ".") on real trees
 wikifier update-maps            # full structural map → library.md + import cache
 wikifier health --summary       # matrix counts
 wikifier suggest-next           # or MCP suggest_next_actions — 🔴/🟡 only
@@ -50,6 +58,8 @@ wikifier suggest-next           # or MCP suggest_next_actions — 🔴/🟡 only
 
 Always set an explicit root for external trees: `WIKIFIER_PROJECT_ROOT=/abs/path wikifier …`
 
+**MCP `session_bootstrap` → `readiness: blocked`?** That means lean scope and/or the map are missing (often bare `.` monitor + never ran `update-maps`) — not a broken install. Fix: write lean `monitored_paths.txt` / `map_paths.txt`, then `update-maps`. Agent contract: **`skills/run.md`** § *Readiness blocked*; dogfood: `Findings/readiness-blocked-bare-monitor-2026-07.md`.
+
 ## Steady state (only touch what needs it)
 
 Full protocol: [`skills/run.md`](skills/run.md) (Agent Protocol v0.6 — package **4.6.x**).
@@ -77,11 +87,11 @@ Advanced intel as needed: `get_dependencies`, `get_dependents`, `get_cycles`, ba
 
 - **Import analysis** — Python, JS/TS (ESM/CJS, barrels), Rust (`use`/`mod` + best-effort `crate::` paths), Go, C/C++ includes, C# usings; per-edge confidence; barrel expansion for TS/JS
 - **Incremental pipeline** — pure-Python `update-maps`: dirty parse → import cache → reverse deps → cycles → `library.md`
-- **Warm agent maps (4.6.3–4.6.6)** — zero-dirty + **index-first** candidates (re-list only on fingerprint/index disagreement); **stdlib SQLite**; content-hash dirty
-- **Two path lists** — `map_paths.txt` = map package roots; `monitored_paths.txt` = wiki/health watch (independent)
+- **Warm agent maps (4.6.3–4.6.7)** — zero-dirty + **index-first** candidates (re-list only when fingerprint / map-scoped index / live count disagree); **MapScope** keeps collect, live count, index filter, and prune aligned; **stdlib SQLite**; content-hash dirty
+- **Two path lists** — `map_paths.txt` = map package roots; `monitored_paths.txt` = wiki/health watch (**independent** — wiki file lists never collapse the map)
 - **Partial-map honesty** — `map_coverage` on `update_maps` / bootstrap / **`suggest_next`**; `update_maps_until_complete` when incomplete
-- **Cache ops** — `wikifier cache-status`; JSON dual-write **opt-in only** (`WIKIFIER_CACHE_JSON=1`); dual-read for migrate
-- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal`; prefer `actionable_low_conf_edges` + reason codes — **never** raw `low_conf_edges` alone
+- **Cache ops** — `wikifier cache-status`; JSON dual-write **deprecated default-off** (`WIKIFIER_CACHE_JSON=1` opt-in); dual-read for migrate
+- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal`; prefer `actionable_low_conf_edges` + reason codes — **never** raw `low_conf_edges` averages alone
 - **Scale** — reverse index + barrel invalidation so one edit doesn’t re-scan the monorepo
 - **MCP tools** — optional server for Claude, Cursor, Cline, and other MCP clients
 - **Zero core dependencies** — stdlib only; forks can add their own stack on top
@@ -95,18 +105,21 @@ Full / heavy runs (historical order-of-magnitude):
 |---------|-------|----------------------------|
 | llama_index | ~3.8k Python files | ~8.5s class full |
 | Babylon.js | ~3.9k TS files, barrel-heavy | minutes full; scoped re-runs tens of seconds |
-| Large trees (e.g. LLVM-scale) | tens of thousands of files | use lean monitor + `--directory` / `--max-files` |
+| Large trees (e.g. LLVM-scale) | tens of thousands of files | `map_paths` / `--directory` / `--max-files` — never unscoped one-shot |
+
+Warm **0-dirty** re-runs after **4.6.7** (same machine class; scoped; candidates **reused** — agent session path):
 
-Warm **0-dirty** re-runs after 4.6.3 (same machine; scoped where noted) — agent session path:
+| Project | Scope | Warm `update-maps` | n |
+|---------|-------|--------------------|---|
+| Wikifier (self) | `map_paths`: `wikifier/` + `tests/` | **~30 ms** | 50 |
+| llama_index | `llama-index-core` | **~76 ms** | 724 |
+| rust | `library/std` | **~79 ms** | 719 |
+| airflow | `airflow-core` | **~180 ms** | 1920 |
+| Babylon.js | `packages` | **~400 ms** | 3895 |
 
-| Project | Scope | Warm2 `update-maps` |
-|---------|-------|---------------------|
-| Wikifier (self) | incremental full | ~43 ms |
-| redox | `src` | ~17 ms |
-| llama_index | `llama-index-core` | ~0.6 s |
-| rust | `library/std/src` (budgeted) | ~0.7 s (vs multi-second full-tree walk before scoped collect) |
+Residual floor on large scopes is mtime/stat + live count under MapScope (not full JSON re-walk). Sub-100ms is not a hard SLA on every 1k+ tree.
 
-Tests: `python -m unittest discover tests` (stdlib only; 86+ cases including agent-scale edges).
+Tests: `python -m unittest discover tests` (stdlib only; **125** cases including MapScope / index-first / dual-write).
 
 ## Commands
 
@@ -120,7 +133,8 @@ Tests: `python -m unittest discover tests` (stdlib only; 86+ cases including age
 | `wikifier mark-green <file>` | Mark wiki current + source content-hash baseline |
 | `wikifier record-deletion <file> "reason"` | Mark removed paths 🔴 + prune barrel refs |
 | `wikifier suggest-next` | Next actions (🔴/actionable 🟡 only; `--json` for `actions[]`) |
-| `wikifier update-maps [--directory=src/] [--max-files=N]` | Rebuild graph + `library.md` (warm 0-dirty is fast) |
+| `wikifier update-maps [--directory=src/] [--max-files=N]` | Rebuild graph + `library.md` (warm 0-dirty is fast; honors `map_paths.txt`) |
+| `wikifier cache-status` | SQLite/JSON backend, dual-write policy, coverage snapshot (no full pair load) |
 | `wikifier health [--summary\|--json]` | Health matrix (machine-friendly flags) |
 | `wikifier validate` | Missing wiki rows + ghost paths |
 | `wikifier cycles` | Circular deps + break hints |

{wikifier-4.6.7 → wikifier-4.6.8}/skills/run.md

@@ -9,7 +9,8 @@
 
 **Package 4.5.x + gap-closure notes (additive; protocol still v0.6):**
 - File Tree + `wikifier serve`; MCP status/attention use library + emoji (not `[GREEN]` tags).
-- **First-run:** `init` → `update-maps` → `health --summary` → `suggest_next_actions`. Map is automatic; wiki *prose* is agent-filled over time.
+- **First-run:** `init` → lean `monitored_paths.txt` + `map_paths.txt` (not bare `.`) → `update-maps` → `health --summary` → `suggest_next_actions`. Map is automatic; wiki *prose* is agent-filled over time.
+- **`session_bootstrap` readiness `blocked`:** not a crash — see **§ Readiness blocked** below. Typical causes: bare `.` monitor and/or no map/health yet. Fix scope → `update-maps` before treating the project as map-ready.
 - **Map-first ≠ wiki-done:** `health_score` **Map Ready** + many 🟡 *Initial stubs* means structural coverage only. Do **not** bulk-wiki stubs. Wiki a file when you edit it, then `mark-green`. Prefer `actionable_yellow` / 🔴 over raw yellow counts.
 - **Steady-state selective work:** only 🔴 and *actionable* 🟡 (never re-wiki 🟢; never re-wiki the whole stub set). **ACS v1.3:** use `actionable_low_conf_edges` + `reason_code_counts` / `agent_signal` (`skip`|`investigate`). Do **not** thrash on raw `low_conf_edges` (includes external/bare scores ~0.48). Prefer `map_coverage.complete` / `files_remaining_dirty` after budgeted `update-maps` — `success: true` ≠ map complete.
 - **Warm maps:** SQLite primary; zero-dirty uses mtime index + meta. **Index-first:** re-list candidates only when fingerprint / map-scoped index / live count disagree (`index_first_dirty` / `candidates_reused` on `update_maps`). Prefer `--directory=` or `map_paths.txt` package roots (not bare `.`). Collect, live count, index filter, and prune share **MapScope** so full-tree→`map_paths` narrow does not thrash.
@@ -45,8 +46,9 @@ Do **not** open megamodules (`javascript.py`, `import_cache.py`, `bree.py`) to d
 
 | Need | Use |
 |------|-----|
-| First-run map | `init` → `update-maps` → `health --summary` → `suggest-next` |
-| **Session start (4.6+)** | `session_bootstrap` (or CLI `session-bootstrap`) — one shot: root, health, attention, `actions[]` |
+| First-run map | `init` → lean paths (not bare `.`) → `update-maps` → `health --summary` → `suggest-next` |
+| **Session start (4.6+)** | `session_bootstrap` (or CLI `session-bootstrap`) — one shot: root, health, attention, `actions[]`. If `readiness` is `blocked`, fix `actions[]` / `blockers[]` first (usually scope + maps). |
+| **Unblock readiness** | Write lean `monitored_paths.txt` + `map_paths.txt` → `update_maps` (full once) → re-`session_bootstrap` until `ready_for_daemon` / Map Ready |
 | **Core tool list** | `list_core_tools` / bootstrap `core_surface` — prefer Core 6; advanced is non-core |
 | Steady-state | `check-changes` (content-honest) → edit 🔴/actionable 🟡 only → `record-change` → wiki → `mark-green` |
 | **Hash migration** | `seed_source_content_hashes` / CLI `seed-source-hashes` — baseline Greens without mass Yellow |
@@ -65,6 +67,62 @@ Do **not** open megamodules (`javascript.py`, `import_cache.py`, `bree.py`) to d
 **Scope:** `monitored_paths` = change detection; `exclude_patterns` + optional `--directory` = map walk.  
 **Human HTML** is secondary observation only.
 
+## Readiness blocked (`session_bootstrap` / external projects)
+
+When MCP `session_bootstrap` (or CLI `session-bootstrap`) returns:
+
+```text
+readiness: "blocked"
+scope.ok: false
+blockers: [ ... ]
+actions: [ { "action": "fix_scope", ... }, ... ]
+```
+
+**this is expected on a project that has never been scoped/mapped**, not a Wikifier install failure.
+
+### Why it happens (Grok-Bevy 2026-07 dogfood)
+
+On **Grok-Bevy** (Rust workspace), first bootstrap reported:
+
+| Blocker | Meaning |
+|---------|---------|
+| `monitored_paths is bare '.'` | Default/missing lean list → `check-changes` would walk the whole tree (`target/`, caches, etc.) and thrash. Action: **`fix_scope`**. |
+| `No import map (run update-maps first)` | No dependency/import map yet → map-first tools have nothing to trust. |
+| `No file_health` | Health matrix not seeded (comes with map/health pipeline). |
+
+Also: `bare_dot_monitor: true` and `scope.ok: false` until `monitored_paths.txt` lists **lean package roots**, not bare `.`.
+
+### Fix once per project (agents must do this, not ignore blockers)
+
+1. **Scope (wiki/health thrash bound)** — create/edit **`monitored_paths.txt`** at project root with *specific* dirs/files, e.g.:
+   ```text
+   crates/foo/src/
+   crates/bar/src/
+   README.md
+   docs/
+   ```
+   Never leave only `.` on non-tiny trees.
+2. **Map roots** — create/edit **`map_paths.txt`** (import-map package roots; independent of monitored):
+   ```text
+   crates/foo/src/
+   crates/bar/src/
+   ```
+3. **Build map + health** — from the target project (or with `project_root=` / `WIKIFIER_PROJECT_ROOT=`):
+   ```bash
+   wikifier update-maps --full    # or MCP update_maps full=true
+   # re-run session_bootstrap until readiness is ready_for_daemon / Map Ready
+   ```
+4. **Do not** bulk-re-wiki 🟡 *Initial stubs* after maps land — stubs = map coverage only.
+
+After a successful fix, bootstrap looks like: `scope.ok: true`, `blockers: []`, `health_score: Map Ready` (stubs OK), `readiness: ready_for_daemon`.
+
+### Product note for Wikifier maintainers
+
+- Default bare `.` is convenient for tiny toys and a footgun for real repos; agents must treat **`fix_scope` as P0** when `session_bootstrap` says blocked.
+- **`wikifier init` (4.6.8+)** seeds comment-guided lean templates for `monitored_paths.txt` and `map_paths.txt` (examples for `src/`, `crates/*/src/`, etc.) instead of a silent single-dot file. Tiny toys may keep `.`; multi-crate / monorepo agents must replace with package roots before map-ready work.
+
+See also: Findings note `Findings/readiness-blocked-bare-monitor-2026-07.md`.
+
 ## Mandatory New-Session Rule
 
 **Copy this exact block into the system prompt or the very first instruction of every new LLM session that uses Wikifier:**

wikifier-4.6.8/tests/test_init_seed.py

@@ -0,0 +1,114 @@
+"""Real-path tests for `wikifier init` lean path-list templates (4.6.8+).
+
+Drives the shipped shell launcher (`./wikifier.sh init --target …`) so a
+silent bare-`.` seed cannot regress without failing the suite.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import unittest
+from pathlib import Path
+
+from tests._base import REPO_ROOT, TempProjectTestCase
+
+
+class TestInitSeedTemplates(TempProjectTestCase):
+    """Acceptance: init must not leave only silent bare '.' without guidance."""
+
+    def _run_init(self, target: Path) -> subprocess.CompletedProcess:
+        script = REPO_ROOT / "wikifier.sh"
+        self.assertTrue(script.is_file(), f"missing shipped launcher: {script}")
+        # Isolated env: do not inherit WIKIFIER_PROJECT_ROOT from the test harness
+        # (init --target should write into the given directory, not the harness root).
+        env = os.environ.copy()
+        env.pop("WIKIFIER_PROJECT_ROOT", None)
+        return subprocess.run(
+            ["bash", str(script), "init", "--target", str(target), "--no-copy"],
+            cwd=str(REPO_ROOT),
+            env=env,
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+
+    def test_init_seeds_guided_monitored_and_map_paths(self):
+        target = self.root / "fresh_project"
+        target.mkdir()
+        proc = self._run_init(target)
+        self.assertEqual(
+            proc.returncode,
+            0,
+            f"init failed:\nstdout:\n{proc.stdout}\nstderr:\n{proc.stderr}",
+        )
+
+        mon = target / "monitored_paths.txt"
+        maps = target / "map_paths.txt"
+        self.assertTrue(mon.is_file(), "init must create monitored_paths.txt")
+        self.assertTrue(maps.is_file(), "init must create map_paths.txt")
+
+        mon_text = mon.read_text(encoding="utf-8")
+        map_text = maps.read_text(encoding="utf-8")
+
+        # Must not be the old silent single-character default.
+        stripped = mon_text.strip()
+        self.assertNotEqual(
+            stripped,
+            ".",
+            "monitored_paths.txt must not be silent bare '.' only",
+        )
+        self.assertIn("#", mon_text, "monitored_paths.txt must include guidance comments")
+        self.assertRegex(
+            mon_text,
+            r"(?i)(lean|package root|thrash|map_paths)",
+            "monitored_paths.txt should mention lean roots / thrash / map_paths",
+        )
+        # Active path may still be bare "." for tiny toys, but only with comments above.
+        active_mon = [
+            ln.strip()
+            for ln in mon_text.splitlines()
+            if ln.strip() and not ln.strip().startswith("#")
+        ]
+        self.assertTrue(active_mon, "expected at least one non-comment monitored path")
+
+        self.assertIn("#", map_text, "map_paths.txt must include guidance comments")
+        self.assertRegex(
+            map_text,
+            r"(?i)(import-map|package root|update-maps|monitored_paths)",
+            "map_paths.txt should document independent map package roots",
+        )
+        # Template should not seed bare "." as the only map root.
+        active_map = [
+            ln.strip()
+            for ln in map_text.splitlines()
+            if ln.strip() and not ln.strip().startswith("#")
+        ]
+        self.assertNotIn(
+            ".",
+            active_map,
+            "map_paths template must not activate bare '.' as map root",
+        )
+
+        excl = target / "exclude_patterns.txt"
+        self.assertTrue(excl.is_file())
+        excl_text = excl.read_text(encoding="utf-8")
+        self.assertIn("target", excl_text.splitlines())
+
+    def test_packaged_launcher_matches_root_init_seed(self):
+        """Root and packaged wikifier.sh must stay in sync for init templates."""
+        root_sh = (REPO_ROOT / "wikifier.sh").read_text(encoding="utf-8")
+        pkg_sh = (REPO_ROOT / "wikifier" / "scripts" / "wikifier.sh").read_text(
+            encoding="utf-8"
+        )
+        self.assertIn("map_paths.txt", root_sh)
+        self.assertIn("lean package roots", root_sh)
+        self.assertEqual(
+            root_sh,
+            pkg_sh,
+            "wikifier/scripts/wikifier.sh must match root wikifier.sh (init templates)",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

{wikifier-4.6.7 → wikifier-4.6.8}/wikifier/__init__.py

@@ -79,4 +79,4 @@ from .contracts import (
     compute_acs_confidence,
 )
 
-__version__ = "4.6.7"
+__version__ = "4.6.8"

{wikifier-4.6.7 → wikifier-4.6.8}/wikifier/scripts/wikifier.sh

@@ -303,7 +303,8 @@ Workflow (for LLMs / new sessions):
   6. wikifier update-maps (when imports change)
 
 Configuration files (edit these):
-  monitored_paths.txt        Paths to scan (one per line). Default: "."
+  monitored_paths.txt        Wiki/health watch list (lean roots; init seeds guided template)
+  map_paths.txt              Import-map package roots (independent of monitored_paths)
   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.
@@ -674,7 +675,45 @@ cmd_init() {
     LIBRARY_MD="$PROJECT_ROOT/library.md"
     mkdir -p "$STAGING_DIR" "$JOURNAL_ROOT/$(date +%Y/%m)" "$LOGGED_ISSUES_ROOT"
 
-    [[ ! -f "$MONITORED_PATHS_FILE" ]] && echo "." > "$MONITORED_PATHS_FILE"
+    # Lean path templates (4.6.8+): not a silent bare "." — agents must replace on real trees.
+    # Comments are ignored by get_monitored_paths / Python path readers.
+    if [[ ! -f "$MONITORED_PATHS_FILE" ]]; then
+        cat > "$MONITORED_PATHS_FILE" << 'EOT'
+# monitored_paths.txt — wiki / health watch list (check-changes thrash bound)
+# Prefer lean package roots so check-changes does not thrash on target/,
+# node_modules, build/, dist/, caches, etc.
+# This is NOT the import map — see map_paths.txt for package roots used by update-maps.
+#
+# Examples (uncomment or add paths that match THIS project):
+# src/
+# lib/
+# crates/my_crate/src/
+# packages/core/src/
+# README.md
+# docs/
+#
+# Tiny single-package toys only may keep bare "." below.
+# Multi-crate / monorepo / anything with build output: REPLACE with lean roots first
+# (session_bootstrap readiness "blocked" / fix_scope until you do).
+.
+EOT
+    fi
+    MAP_PATHS_FILE="$PROJECT_ROOT/map_paths.txt"
+    if [[ ! -f "$MAP_PATHS_FILE" ]]; then
+        cat > "$MAP_PATHS_FILE" << 'EOT'
+# map_paths.txt — import-map package roots for update-maps (independent of monitored_paths)
+# List directories that contain parseable source for the dependency map.
+# Do not use bare "." on large trees; do not list only wiki/docs files here.
+#
+# Examples (uncomment or add paths that match THIS project):
+# src/
+# crates/my_crate/src/
+# packages/core/src/
+#
+# Leave empty (comments only) to fall back to monitored directory roots / full collect.
+# After editing: wikifier update-maps  (then session_bootstrap until ready_for_daemon)
+EOT
+    fi
     [[ ! -f "$EXCLUDE_PATTERNS_FILE" ]] && cat > "$EXCLUDE_PATTERNS_FILE" << 'EOT'
 node_modules
 .git
@@ -682,6 +721,7 @@ build
 dist
 __pycache__
 *.pyc
+target
 EOT
 
     [[ ! -f "$FILE_HEALTH" ]] && cat > "$FILE_HEALTH" << 'EOT'
@@ -748,12 +788,13 @@ EOT
 
     PROJECT_ROOT="$old_project"
 
-    log "✅ Wikifier initialised in $target_dir . Edit monitored_paths.txt (change detection scope; map uses excludes + optional --directory)."
+    log "✅ Wikifier initialised in $target_dir . Edit lean monitored_paths.txt + map_paths.txt (templates seeded; not silent bare-only)."
     log "   Recommended: export WIKIFIER_PROJECT_ROOT=$target_dir  (or cd there and use ./wikifier.sh)"
     log "   Agent first-run (map first, wiki prose later):"
-    log "     1) wikifier update-maps"
-    log "     2) wikifier health --summary"
-    log "     3) wikifier suggest-next   # or MCP suggest_next_actions — 🔴/🟡 only"
+    log "     1) edit monitored_paths.txt + map_paths.txt to package roots on real trees"
+    log "     2) wikifier update-maps"
+    log "     3) wikifier health --summary / session-bootstrap until ready_for_daemon"
+    log "     4) wikifier suggest-next   # or MCP suggest_next_actions — 🔴/🟡 only"
     log "   Steady-state: check-changes → edit red/yellow only → record-change → wiki → mark-green → update-maps if imports changed."
     log "   Deep import maps: Python + JS/TS. journal/pending = audit queue (not an issue tracker)."
     log "   Human layer (secondary): wikifier serve → http://localhost:8787/index.html (not file://)."

{wikifier-4.6.7 → wikifier-4.6.8/wikifier.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.6.7
+Version: 4.6.8
 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
@@ -52,7 +52,14 @@ Works from small scripts to large monorepos. **Deep import/include maps** (zero-
 | C# | `.cs` | `using` namespaces |
 | Java | `.java` | `import` / `import static` |
 
-Health/journal still work for any monitored path. Parsers are **pragmatic regex** (not full cargo/`go.mod`/classpath/`-I` resolution). Prefer **lean `monitored_paths.txt`** on huge monorepos; raise dirty cap with `WIKIFIER_CHECK_CHANGES_MAX` (default 2000) only when needed.
+Health/journal still work for any monitored path. Parsers are **pragmatic regex** (not full cargo/`go.mod`/classpath/`-I` resolution). On huge monorepos, split scope deliberately:
+
+| File | Surface |
+|------|---------|
+| **`map_paths.txt`** | Package roots for **import maps** (`update-maps` walk). Prefer package dirs (`src/`, `packages/foo/`) — not a wiki-only file list. |
+| **`monitored_paths.txt`** | **Wiki / health** watch list (can be individual `.md` files). Does **not** define the map. |
+
+Or pass `--directory=pkg/` / `--max-files=N` per run. Raise dirty cap with `WIKIFIER_CHECK_CHANGES_MAX` (default 2000) only when needed. Never set `project_root` to a multi-repo parent of clones.
 
 ## Why
 
@@ -74,7 +81,8 @@ pip install wikifier            # pure Python stdlib core — no runtime deps
 pip install wikifier[mcp]       # optional Model Context Protocol (MCP) server
 
 cd /path/to/your/project
-wikifier init                   # seeds + human index.html
+wikifier init                   # seeds index.html + lean path-list templates
+# Edit monitored_paths.txt + map_paths.txt to package roots (not bare ".") on real trees
 wikifier update-maps            # full structural map → library.md + import cache
 wikifier health --summary       # matrix counts
 wikifier suggest-next           # or MCP suggest_next_actions — 🔴/🟡 only
@@ -82,6 +90,8 @@ wikifier suggest-next           # or MCP suggest_next_actions — 🔴/🟡 only
 
 Always set an explicit root for external trees: `WIKIFIER_PROJECT_ROOT=/abs/path wikifier …`
 
+**MCP `session_bootstrap` → `readiness: blocked`?** That means lean scope and/or the map are missing (often bare `.` monitor + never ran `update-maps`) — not a broken install. Fix: write lean `monitored_paths.txt` / `map_paths.txt`, then `update-maps`. Agent contract: **`skills/run.md`** § *Readiness blocked*; dogfood: `Findings/readiness-blocked-bare-monitor-2026-07.md`.
+
 ## Steady state (only touch what needs it)
 
 Full protocol: [`skills/run.md`](skills/run.md) (Agent Protocol v0.6 — package **4.6.x**).
@@ -109,11 +119,11 @@ Advanced intel as needed: `get_dependencies`, `get_dependents`, `get_cycles`, ba
 
 - **Import analysis** — Python, JS/TS (ESM/CJS, barrels), Rust (`use`/`mod` + best-effort `crate::` paths), Go, C/C++ includes, C# usings; per-edge confidence; barrel expansion for TS/JS
 - **Incremental pipeline** — pure-Python `update-maps`: dirty parse → import cache → reverse deps → cycles → `library.md`
-- **Warm agent maps (4.6.3–4.6.6)** — zero-dirty + **index-first** candidates (re-list only on fingerprint/index disagreement); **stdlib SQLite**; content-hash dirty
-- **Two path lists** — `map_paths.txt` = map package roots; `monitored_paths.txt` = wiki/health watch (independent)
+- **Warm agent maps (4.6.3–4.6.7)** — zero-dirty + **index-first** candidates (re-list only when fingerprint / map-scoped index / live count disagree); **MapScope** keeps collect, live count, index filter, and prune aligned; **stdlib SQLite**; content-hash dirty
+- **Two path lists** — `map_paths.txt` = map package roots; `monitored_paths.txt` = wiki/health watch (**independent** — wiki file lists never collapse the map)
 - **Partial-map honesty** — `map_coverage` on `update_maps` / bootstrap / **`suggest_next`**; `update_maps_until_complete` when incomplete
-- **Cache ops** — `wikifier cache-status`; JSON dual-write **opt-in only** (`WIKIFIER_CACHE_JSON=1`); dual-read for migrate
-- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal`; prefer `actionable_low_conf_edges` + reason codes — **never** raw `low_conf_edges` alone
+- **Cache ops** — `wikifier cache-status`; JSON dual-write **deprecated default-off** (`WIKIFIER_CACHE_JSON=1` opt-in); dual-read for migrate
+- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal`; prefer `actionable_low_conf_edges` + reason codes — **never** raw `low_conf_edges` averages alone
 - **Scale** — reverse index + barrel invalidation so one edit doesn’t re-scan the monorepo
 - **MCP tools** — optional server for Claude, Cursor, Cline, and other MCP clients
 - **Zero core dependencies** — stdlib only; forks can add their own stack on top
@@ -127,18 +137,21 @@ Full / heavy runs (historical order-of-magnitude):
 |---------|-------|----------------------------|
 | llama_index | ~3.8k Python files | ~8.5s class full |
 | Babylon.js | ~3.9k TS files, barrel-heavy | minutes full; scoped re-runs tens of seconds |
-| Large trees (e.g. LLVM-scale) | tens of thousands of files | use lean monitor + `--directory` / `--max-files` |
+| Large trees (e.g. LLVM-scale) | tens of thousands of files | `map_paths` / `--directory` / `--max-files` — never unscoped one-shot |
+
+Warm **0-dirty** re-runs after **4.6.7** (same machine class; scoped; candidates **reused** — agent session path):
 
-Warm **0-dirty** re-runs after 4.6.3 (same machine; scoped where noted) — agent session path:
+| Project | Scope | Warm `update-maps` | n |
+|---------|-------|--------------------|---|
+| Wikifier (self) | `map_paths`: `wikifier/` + `tests/` | **~30 ms** | 50 |
+| llama_index | `llama-index-core` | **~76 ms** | 724 |
+| rust | `library/std` | **~79 ms** | 719 |
+| airflow | `airflow-core` | **~180 ms** | 1920 |
+| Babylon.js | `packages` | **~400 ms** | 3895 |
 
-| Project | Scope | Warm2 `update-maps` |
-|---------|-------|---------------------|
-| Wikifier (self) | incremental full | ~43 ms |
-| redox | `src` | ~17 ms |
-| llama_index | `llama-index-core` | ~0.6 s |
-| rust | `library/std/src` (budgeted) | ~0.7 s (vs multi-second full-tree walk before scoped collect) |
+Residual floor on large scopes is mtime/stat + live count under MapScope (not full JSON re-walk). Sub-100ms is not a hard SLA on every 1k+ tree.
 
-Tests: `python -m unittest discover tests` (stdlib only; 86+ cases including agent-scale edges).
+Tests: `python -m unittest discover tests` (stdlib only; **125** cases including MapScope / index-first / dual-write).
 
 ## Commands
 
@@ -152,7 +165,8 @@ Tests: `python -m unittest discover tests` (stdlib only; 86+ cases including age
 | `wikifier mark-green <file>` | Mark wiki current + source content-hash baseline |
 | `wikifier record-deletion <file> "reason"` | Mark removed paths 🔴 + prune barrel refs |
 | `wikifier suggest-next` | Next actions (🔴/actionable 🟡 only; `--json` for `actions[]`) |
-| `wikifier update-maps [--directory=src/] [--max-files=N]` | Rebuild graph + `library.md` (warm 0-dirty is fast) |
+| `wikifier update-maps [--directory=src/] [--max-files=N]` | Rebuild graph + `library.md` (warm 0-dirty is fast; honors `map_paths.txt`) |
+| `wikifier cache-status` | SQLite/JSON backend, dual-write policy, coverage snapshot (no full pair load) |
 | `wikifier health [--summary\|--json]` | Health matrix (machine-friendly flags) |
 | `wikifier validate` | Missing wiki rows + ghost paths |
 | `wikifier cycles` | Circular deps + break hints |

{wikifier-4.6.7 → wikifier-4.6.8}/wikifier.egg-info/SOURCES.txt

@@ -48,6 +48,7 @@ tests/test_gap_closure.py
 tests/test_health.py
 tests/test_import_cache.py
 tests/test_index_map_paths.py
+tests/test_init_seed.py
 tests/test_multi_lang_parsers.py
 tests/test_parsers.py
 tests/test_selftest_wrappers.py