md4ai 0.10.2 → 0.10.4

package/README.md

@@ -0,0 +1,167 @@
+<p align="center">
+  <strong><span style="color:#38bdf8">MD4</span>AI</strong><br/>
+  <em>See what Claude actually reads</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/md4ai"><img src="https://img.shields.io/npm/v/md4ai?color=38bdf8&label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/md4ai"><img src="https://img.shields.io/npm/dm/md4ai?color=10b981" alt="monthly downloads"></a>
+  <a href="https://github.com/Media-HQ-2-Ltd/MD4AI/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Media-HQ-2-Ltd/MD4AI" alt="licence"></a>
+  <a href="https://www.md4ai.com"><img src="https://img.shields.io/badge/dashboard-md4ai.com-38bdf8" alt="web dashboard"></a>
+</p>
+
+---
+
+Scan your Claude Code configuration, visualise the dependency graph, catch orphan files, and track software versions — across every device and every project.
+
+**Free for individual developers.** Teams get shared dashboards and invite-based collaboration.
+
+<p align="center">
+  <img src="https://www.md4ai.com/screenshots/project-overview.png" alt="MD4AI project dashboard" width="700"/>
+</p>
+
+## Why MD4AI?
+
+As your Claude Code setup grows — CLAUDE.md, skills, hooks, MCP servers, memory files, plan docs — it becomes hard to see the full picture. MD4AI scans everything and shows you:
+
+- **Dependency graph** — which files reference which, interactively
+- **Orphan detection** — config files nothing points to
+- **Broken references** — links to files that don't exist
+- **Skills catalogue** — project-specific, machine-wide, and marketplace plugins
+- **Stale files** — anything untouched for 90+ days
+- **Environment drift** — compare `.env`, Vercel, and GitHub Secrets
+- **Software versions** — frameworks and tools detected vs latest releases
+
+## Quick Start
+
+```bash
+npm install -g md4ai
+```
+
+> Requires **Node.js 22** or later. Works on **Windows (WSL2)**, **Linux**, and **macOS**.
+
+```bash
+# 1. Create an account at md4ai.com and set your API key
+export MD4AI_SUPABASE_ANON_KEY="your-anon-key"
+
+# 2. Log in
+md4ai login
+
+# 3. Link a project (get the ID from the dashboard URL)
+cd /path/to/your-claude-project
+md4ai link <project-id>
+
+# 4. That's it — your scan results are live at md4ai.com
+```
+
+Or scan without an account:
+
+```bash
+md4ai scan --offline    # generates output/index.html
+```
+
+## What You Get
+
+### Dependency Graph
+
+See how your CLAUDE.md, skills, hooks, and config files connect. Search, zoom, and print wall sheets.
+
+<p align="center">
+  <img src="https://www.md4ai.com/screenshots/dependency-graph.png" alt="Dependency graph" width="600"/>
+</p>
+
+### Orphan Detection
+
+Find configuration files not reachable from any root. Grouped by folder with modification dates.
+
+<p align="center">
+  <img src="https://www.md4ai.com/screenshots/orphan-files.png" alt="Orphan files" width="600"/>
+</p>
+
+### Skills Comparison
+
+Every skill and plugin at a glance — machine-wide vs project-specific, with current status.
+
+<p align="center">
+  <img src="https://www.md4ai.com/screenshots/skills-table.png" alt="Skills comparison" width="600"/>
+</p>
+
+### Software Versions
+
+Track detected tool versions compared against latest stable and beta releases.
+
+<p align="center">
+  <img src="https://www.md4ai.com/screenshots/software-versions.png" alt="Software versions" width="600"/>
+</p>
+
+## Commands
+
+### Scanning & Syncing
+
+| Command | Description |
+|---------|-------------|
+| `md4ai scan [path]` | Scan a Claude project and push results to the dashboard |
+| `md4ai scan --offline` | Scan locally — generates `output/index.html` without pushing |
+| `md4ai sync --all` | Re-scan and sync all linked projects on this device |
+| `md4ai link <project-id>` | Link cwd to a dashboard project and run initial scan |
+
+### Analysis
+
+| Command | Description |
+|---------|-------------|
+| `md4ai simulate <prompt>` | Show which files Claude would load for a given prompt |
+| `md4ai print <title>` | Generate a printable A3 wall-chart HTML |
+| `md4ai init-manifest` | Scaffold an `env-manifest.md` from detected `.env` files |
+
+### Account & Devices
+
+| Command | Description |
+|---------|-------------|
+| `md4ai login` | Authenticate with email and password |
+| `md4ai status` | Show login status, linked folders, and last sync |
+| `md4ai list-devices` | List all devices and their linked projects |
+| `md4ai mcp-watch` | Monitor MCP server status (runs until Ctrl+C) |
+
+### One Command to Rule Them All
+
+```bash
+md4ai start    # or just: md4ai
+```
+
+Checks for updates, scans the current project, and starts MCP monitoring — all in one go.
+
+## Scan Output
+
+```
+Files found:   41
+References:    41
+Broken refs:   2
+Orphans:       3
+Stale files:   0
+Skills:        19
+Toolings:      55
+Env Vars:      24 (manifest found)
+Plugins:       17 (17 skills)
+Data hash:     9868c4a8b50f...
+```
+
+## Web Dashboard
+
+All scan data syncs to [md4ai.com](https://www.md4ai.com) where you can:
+
+- Browse the dependency graph interactively
+- View file contents with structure navigation
+- Track environment variable drift across local, Vercel, and GitHub
+- Monitor MCP server status per device
+- Share projects with team members
+- Compare skills across machines
+
+## Support
+
+Questions, feedback, or bugs: [richard@mediahq2.com](mailto:richard@mediahq2.com)
+
+Built by [Testate Technologies Ltd](https://www.md4ai.com) · [Changelog](https://www.md4ai.com/changelog)
+
+## Licence
+
+MIT — see [LICENCE](https://github.com/Media-HQ-2-Ltd/MD4AI/blob/main/LICENSE) for details.