W
Wikifier Human Layer
HUMAN DEV EXPERIENCE
AGENT-FIRST + HUMAN PARITY

For Human Refactors & Porters

P4 DELIVERABLE

Genuinely valuable experience for developers opening the dashboard to refactor code or port Wikifier to another agent platform. Aligns with frozen P1 architecture + P7 wiring. All within P6 budget/scale constraints. Pure static HTML + vanilla JS.

ZERO DEP • STATIC • FORKABLE
R1 SCALE AWARE (5k–20k+)
Links to all *.wiki.md
1. Architecture at a Glance (condensed from frozen P1)
Two-Page Model (current)
  • index.html — Clean *human* investigation view (copied to every target). Prominent code structure chart (Mermaid) as hero, "Files & descriptions" with short wiki summaries, folder browser, copy buttons for tree + snapshot. Purely data-driven from the *host project's* file_health + library.md. Generic for any project.
  • diagnostics.html — This heavy maintainer/refactor/porter hub. Wikifier's own architecture, exhaustive command map, porting checklist, *this tool's* source tree with purposes. Not copied to targets (would show the wrong folder).
Binding Constraints
  • Zero external runtime deps (Tailwind + Mermaid CDN only at load)
  • Total visual assets < 85 KB uncompressed
  • Large monorepo resilience mandatory (R1 degradation, caps, delegation)
  • All changes recorded via Wikifier process (record-change → wiki → mark-green)
  • Dual audience: agent-first with full human parity
See README.md scaling table + P6 performance budget.
Data flow: pure client fetch of file_health.{json,md}, library.md, pending_updates.md, journal/*.md. Vanilla parsers + R1 detection on "LARGE_SCALE_MODE" / "R1 Scale Degradation". No server, no mutation.
2. Project File Map — Visual Tree with Purposes
Human Refactor / Port View

⚠ This map describes the Wikifier *tool's own source* (for people refactoring or porting Wikifier itself). It is *not* the file tree or wiki of whatever project you may have opened this file in.

Key implementation files + one-line purposes (from *.wiki.md + current structure after org + human layer work). For the *current project's* agent wiki (chart + files + descriptions), use index.html after running wikifier update-maps / check-changes in that project. diagnostics.html is deliberately not copied into target project roots.

/ (Wikifier source root)
├── index.html ................ Clean human investigation dashboard (chart hero + files+short-descriptions + folder browser + copy exports). Data-driven from host project's artifacts. Copied to targets.
├── diagnostics.html ............ This page — heavy maintainer/refactor hub (arch, full maps, porting checklist, *this* tool's tree). Wikifier source only.
├── wikifier.sh (+.ps1/.bat) ... Launcher + init (copies only the human index.html to targets) + all cmd_*

├── wikifier/ (the package)
│ ├── cli.py .................. CLI entry, init, copy_human_dashboards (now index.html only), health wrappers, runCommand surface
│ ├── health.py ............... Health matrix SSOT (load/upsert, _coerce_root for str|Path/MCP, SUPERSEDED_PATTERNS prune for lean agent view, BRC)
│ ├── contracts.py ............. Frozen P1 shared shapes (versioned _vN, dataclasses, RICH_KEYS, defensive decode)
│ ├── locking.py .............. Advisory project locks for concurrent agents + monitor (fcntl + mkdir fallback)
│ ├── resolution.py ............ Canonical path resolution (exports, tsconfig, workspace, bare heuristic)
│ ├── import_cache.py ........ Dep graph, Tarjan cycles, barrel reports, import analysis cache
│ ├── diagnostics.py .......... Aggregates, reports, health helpers
│ ├── daemon.py ................ Monitor daemon (30s heartbeat, incremental check-changes)
│ │
│ ├── parsers/
│ │ ├── python.py (+.wiki.md) ... Rich Python import parser (relatives, metadata, confidence)
│ │ ├── javascript.py (+.wiki.md) JS/TS + barrel following + CDIA
│ │ ├── bree.py ................ Barrel re-export expansion (BREE)
│ │ └── cdia.py ................ Conditional & dynamic import analysis
│ │
│ └── mcp/
│ └── server.py (+.wiki.md) . 23 @mcp.tool() (thin to lib/CLI for heavy ops; project_root= support; external-safe)

├── skills/run.md .............. Mandatory agent protocol (FRESH, record-change + mark-green, human layer note, 9GPs/DF)
├── README.md .................. Intended use (agent-to-agent primary), human layer (secondary), init examples
├── pyproject.toml + MANIFEST.in Zero-dep declaration, packaging (includes the two .html for distribution)
└── docs/ ........................ Historical non-core .md moved here (structure cleanup); still shipped
Useful *.wiki.md (next to sources): health.py.wiki.mdpython.py.wiki.mdjavascript.py.wiki.mdserver.py.wiki.md
3. Porting Checklist (ready-to-use for real work)
Porting Wikifier to Another Agent Platform
  1. Start with contracts.py (FROZEN): all versioned shapes (_vN), dataclasses, to_dict/from_dict, RICH_KEYS. Never break additive contract.
  2. Study existing high-quality *.wiki.md as source of truth + living docs: health.py.wiki.md, server.py.wiki.md, python.py.wiki.md, javascript.py.wiki.md (and create for others).
  3. locking.py: adopt or replicate advisory project-level locks (fcntl + mkdir fallback) for concurrent agents + monitor on state files (health.json, import_cache.json, pending, journal).
  4. resolution.py: single source for canonical paths, strategies (TsPaths, Workspace, PackageExports, BareHeuristic). Parsers delegate to it.
  5. Parsers: implement uniform rich Dict return (see python parser contract). Python + JS examples show best-effort + confidence.
  6. MCP surface (server.py): primary integration point. Replicate @mcp.tool() surface (check_changes, record_*, get_dependencies, get_project_status, suggest_next_actions, get_file_wiki, etc.). Use Pydantic/FastMCP or equiv.
  7. CLI / shell: wikifier.sh (cmd_* fns + launcher copy on init) + wikifier/cli.py as reference/fallback. Support WIKIFIER_PROJECT_ROOT + --project-root for external monorepos.
  8. Health & cache: health.py (JSON primary + MD generation), import_cache.py. Use prepare_edit / record_change / mark_green workflow always.
  9. Agent protocol: enforce skills/run.md mandatory rule in new platform (record-change after every edit).
  10. Test at scale: 5k–15k files using dir filters + incremental only + get_* queries (never full rebuilds).
Porting / Adapting the Visual Layer (index + diagnostics)
  1. Pure static: copy HTML + inline <style> + <script> (Tailwind + Mermaid CDNs). No build, no new deps. Target <85KB total.
  2. Duplicate minimal shared helpers with /* SHARED: ... */ and /* HUMAN PORT NOTE: duplicate this fn for your project */ markers (see JS below).
  3. Wire to your artifacts: safeFetch your file_health.json / library.md / pending_updates.md (or your equivalents). Reuse parseHealthMd, R1 detection logic.
  4. Command launcher: static data-driven buttons (shell + MCP strings + impl + wiki). onClick = clipboard + educational toast. Extend easily.
  5. R1 / scale: detect "R1 Scale Degradation" | LARGE_SCALE_MODE in library.md early; activate caps (HEALTH_RENDER_CAP), summaries, scale banners, delegation hints.
  6. Two-page: keep index fast (compact views + caps); diagnostics for exhaustive map + this porting hub.
  7. Wiki consumption: replicate showWikiPurpose candidate search (mirrors server.py get_file_wiki) or call MCP.
  8. Exposed wiring: window.wikifierWiring = {...} for other pages / future agents / port debugging.
  9. Record every visual change: use record-change on the .html file(s), update/create .wiki.md, mark-green.
  10. For non-Python agent platforms: the visual layer is language-agnostic. Use it as reference dashboard that calls your platform's equivalent tools.
See source comments in index.html / this file for copyable helpers. Full P1 has "duplicate minimal shared code" rule.
3. Command Implementation Map (shell ↔ MCP ↔ source:line + .wiki.md)
Cat Shell / CLI MCP Tool Source File:Line .wiki.md Scale / Port Notes
Corecheck-changescheck_changes()sh:1806 / server:319Delta; first action
Corehealth [--dir X] [json]health(dir,format="json")health.py:16 / server:481health.py.wiki.mdDir filter core; R1 essential
Coreupdate-maps [--full]update_maps(full=False)sh:1936 / server:440R1: incremental only on large
Corevalidatevalidate()server:625Health + integrity
Editrecord-change <f> "<reason>"record_change(file,reason)server:353MANDATORY after every refactor
Editmark-green <f>mark_green(file)server:396Close the loop
Editprepare-edit <f>prepare_edit(file)server:417Stage mtime (P7 robust)
Inspectjournal [date]journal(date,format="json")server:649Audit trail
Inspectissuesissues(severity="high")server:670Logged_issues/
Wiki(MCP) get_file_wikiget_file_wiki(file,format="json")server:1104server.py.wiki.mdPurpose pane + porting
Intel(MCP) get_dependenciesget_dependencies(file,format="json")server:695Forward edges
Intel(MCP) get_cyclesget_cycles(analysis=true)server:931 (Tarjan+CIABRE)Heavy; full view here
Agent(MCP) get_project_statusget_project_status()server:1328Best first call for humans
Agent(MCP) suggest_next_actionssuggest_next_actions()server:1407Top workflow per skills/run.md
Agent(MCP) get_files_needing_attentionget_files_needing_attention()server:1269Red/Yellow for refactors
Setupinit --target /pathN/Ash:2172External monorepo bootstrap
Daemonmonitor &N/Ash:1926Background heartbeat + lock
Click Copy for full invocation + wiki ref. Full parity & impl links for porting. Heavy tools (cycles) documented here; actual compute stays in Python/MCP per P1/P6.
4. Key Files for Refactors (consumes existing high-quality .wiki.md + core modules)
contracts.py (FROZEN)
Gap #1 Pre-Wave 0 shared contracts. Versioned dataclasses, to_dict, additive only. Source of truth for parsers, cache, MCP, library, resolution.
source (no .wiki.md yet — highest priority for port)
health.py + health.py.wiki.md
JSON primary truth + MD gen. load/save/upsert/get_summary/needs-attention. Dir filter built-in. Foundation for large monorepos.
source | wiki.md (Purpose, design, functions)
mcp/server.py + server.py.wiki.md
Full MCP tool surface (FastMCP). get_project_status, suggest_next_actions, deps, wiki, record_*, health, cycles, etc. Primary port target for new agent platforms.
parsers/python.py + python.py.wiki.md
Rich import parser (uniform Dict contract). Relative resolution via FS walk, docstring stripping, multi-line. Powers everything.
source | wiki.md (Purpose, return shape, limitations)
parsers/javascript.py + javascript.py.wiki.md
Sister parser, same contract + confidence + TS + bare internal resolution for real monorepos (flat + pnpm/yarn).
locking.py
Project-level advisory locks (fcntl + mkdir). Protects health.json, import_cache, pending, journal under multi-agent + monitor. Automatic in high-level tools.
source (create .wiki.md when porting)
resolution.py
Central canonical path + specifier resolver (ProjectContext, strategies, symlink policy). All parsers / cache / MCP delegate here. R4 de-dupe complete.
source (create .wiki.md — critical for port)
wikifier.sh + cli.py
Shell command impls (cmd_*), launcher, R1 LARGE_SCALE_MODE, streaming, init --target copy logic. cli.py thin dispatch. Reference for non-MCP ports.
skills/run.md + mcp/README.md + client-configs
Mandatory agent protocol + MCP setup for external monorepos. Client examples (Claude etc.). Start here for new platform integration.
protocol | mcp | client-configs/
All listed files are the minimal surface a human or porter must master. *.wiki.md files are deliberately high-signal for exactly this use-case.
5. Large Monorepo Realities (what actually changes at 5k–15k+ files)

From real dogfooding (R3, M2-Rem-08, ConsistencyHub 577-file + extrapolated) + R1 hardening in sh + contracts + visual:

  • UI never dumps full data: HEALTH_RENDER_CAP=180, slice summaries, live client filter on in-mem array. Never 5k+ rows in DOM.
  • R1 degradation in library.md: "R1 Scale Degradation" / LARGE_SCALE_MODE / ScaleNote → mermaid + full tables omitted. Rich data lives in import_cache.json + MCP get_* . Visual shows banner + "use MCP / dir filter".
  • update-maps: always incremental except after massive structural change. Use get_incremental_status() first. --full is dangerous at scale.
  • Health: --dir SUBTREE / MCP health(directory=...) is mandatory. Full table only for tiny projects.
  • Preferred interface: MCP for Large/Massive (per README table). Shell ok for tiny/medium.
  • Locking mandatory: locking.py protects shared state when monitor + N agents run together.
  • Visual layer: same rules — early R1 check, caps, delegation notes, "Query via MCP" hints. Graceful even when artifacts are summarized.
  • Porting implication: Your dashboard / tools for 5k+ must replicate: summaries + targeted queries + explicit scale UI. Do not assume "full view always available".
6. Visual Layer Porting Notes (copy-paste ready)

The visual layer (index.html + diagnostics.html) is the easiest part to port or fork for your own project dashboard:

/* SHARED (from index.html + diagnostics): defensive fetch + parsers */
async function safeFetch(path, fallback = '') { ... }  // AbortController + timeout
function parseHealthMd(md) { ... } // line-based | table tolerant of R1
/* HUMAN PORT NOTE: duplicate the above two + renderHealthTable + R1 detection
   (libraryMd.includes('R1 Scale') || rows.length > 300) then set caps + banners.
   Command surface is pure data + clipboard toasts — replace the array with your cmds.
   Expose window.yourWiring for diagnostics parity. No build step. */

Header, badges, intel-card, command-btn, status-pill styles are intentionally duplicated (small) with comments so each file is independently forkable. Tailwind script + mermaid only on load. Keyboard 'R' + '/' filter patterns are cheap wins.

For other agent platforms: keep the two-page split, command copy surface (your equivalent of shell + MCP XML), and the "For Human..." hub as-is — just re-point the data sources and command strings.

Additional Investigation Aids & Process
  • Click rows in index health for wiki-purpose pane (uses get_file_wiki logic)
  • Use MCP get_resolution_diagnostics(), get_cycles(analysis=true) for deep traces (heavy, here only)
  • journal/ + Logged_issues/ + pending_updates.md for audit during refactors
  • file_health.json (structured) preferred over .md for scale
  • monitored_paths.txt + exclude_patterns.txt for scoping large repos
  • Process (mandatory): After any edit (including these HTML files): prepare_edit → edit → record_change "reason" → update/create *.wiki.md → mark-green
This diagnostics.html + the callout in index.html are the "For Human Refactors & Porters" experience. Lightweight, actually useful, highlights every existing .wiki.md and core module.
Recorded via Wikifier process. Size impact reported to P6. Total visual layer stays inside 85 KB envelope (P6 validation required).
← Back to fast dashboard P1 Arch v1-p4 human dev experience