@dujavi/ai-md 0.5.0 → 0.6.0

package/README.md

@@ -2,132 +2,72 @@
 
 Public **AXI-shaped** CLI for a **private** personal AI config directory (`~/.ai-md`).
 
-The npm package ships tooling only — no personal skills, rules, or secrets. Your content lives in a private git repo you point at with `--remote` (or machine config). Default reads are TOON + `help[]`; use `--json` when you need JSON.
+Build merges `shared/` + `agents/<harness>/` into `dist/<harness>/`, then links live tool dirs at dist. **Only installed AIs are linked** (detect dirs/binaries); use `--force-link` to override.
 
-![Architecture](docs/architecture.png)
+## Layout (private repo)
 
-## What it manages
+| Path | Role |
+|------|------|
+| `shared/{rules,skills}` | Cross-harness source |
+| `agents/<id>/` | Harness-specific overlays (win on name conflict) |
+| `dist/<id>/` | Generated (gitignored) — do not edit |
+| `templates/<type>/` | Project starters |
+| `projects/<name>/` | Per-app overlays (repo `.cursor` → here) |
+| `scripts/` | Private machine scripts |
 
-| Layer | Path | Purpose |
-|-------|------|---------|
-| **System** | `skills/`, `rules/` | Global base — linked into agent harnesses |
-| **Templates** | `templates/<type>/` | Project-type starters (`base`, later `forms`, …) |
-| **Projects** | `projects/<name>/` | Per-app overlays (repo `.cursor` → here) |
-| **Scripts** | `scripts/<name>` | Private machine scripts via `ai-md script` / `setup --script` |
+## Unique vs shared live roots
 
-## Supported harnesses
+| Live root | Harnesses | Notes |
+|-----------|-----------|--------|
+| `~/.cursor/{skills,rules}` | **cursor** only | Unique |
+| `~/.claude/{skills,rules}` | **claude** only | Unique |
+| `~/.gemini/skills` | **gemini** only | Unique |
+| `~/.config/opencode/skills` | **opencode** only | Unique |
+| `~/.copilot/skills` | **copilot** (stub) | Unique |
+| `~/.agents/skills` | **agents** (writer); **codex** is an **alias** | Shared — emit once |
 
-Skill (and for Cursor, rules) link targets via `--agents` (comma-separated):
-
-| Harness | Skills link | Notes |
-|---------|-------------|--------|
-| `cursor` | `~/.cursor/skills` | **Default.** Install also links `~/.cursor/rules` → `~/.ai-md/rules` |
-| `claude` | `~/.claude/skills` | Optional second harness |
-| `agents` | `~/.agents/skills` | Optional agents-skills layout |
-
-```bash
-ai-md doctor --fix --agents cursor,claude
-ai-md install --agents cursor,claude,agents
-```
-
-## Architecture
-
-```mermaid
-flowchart TB
-  subgraph publicPkg ["@dujavi/ai-md"]
-    cli["ai-md CLI"]
-    runner["lib/scripts.js"]
-  end
-  subgraph privateDir ["~/.ai-md"]
-    system["skills + rules"]
-    templates["templates/"]
-    projects["projects/"]
-    scripts["scripts/"]
-  end
-  subgraph harnesses ["Supported harnesses"]
-    cursor["cursor ~/.cursor"]
-    claude["claude ~/.claude"]
-    agents["agents ~/.agents"]
-  end
-  cli --> system
-  cli --> templates
-  cli --> projects
-  cli --> runner
-  runner --> scripts
-  system --> cursor
-  system --> claude
-  system --> agents
-```
-
-Personal installers (Grok, quota-axi, etc.) are **not** baked into this package. Put them in `~/.ai-md/scripts/` and run with `--script` / `ai-md script`.
+Cursor / Gemini / OpenCode may *also read* `~/.agents/skills`; enabling `agents` feeds them without a second copy under those tools’ unique roots (unless those harnesses are enabled too, which builds `shared/` into each unique dist).
 
 ## Quick start
 
 ```bash
 npm i -g @dujavi/ai-md
 
-# First machine: persist config, clone, link, run a private script
-ai-md setup --remote https://github.com/<you>/.ai-md.git --script ensure-tools
-
-# Or step by step
-ai-md config set --remote https://github.com/<you>/.ai-md.git --dir ~/.ai-md
-ai-md install
-ai-md script ensure-tools
-```
-
-Precedence: `--remote` / `--dir` flags > `AI_MD_*` env > `~/.config/ai-md/config.json` > defaults (`~/.ai-md`, package default remote).
+# A) No private remote yet
+ai-md init
 
-## Commands
-
-```bash
-ai-md                                      # status (AXI)
-ai-md setup --remote <url> --script <name>
-ai-md config | config set --remote <url> --dir ~/.ai-md
-ai-md install [--agents cursor,claude]
-ai-md doctor --fix
-ai-md pull | push -m "why"
-ai-md script <name> [--] [args...]         # private ~/.ai-md/scripts/
-ai-md init-project --repo ~/app --from base
-ai-md apply-template --project app --from base
-ai-md link-project --repo ~/app --name app
-```
-
-### Private scripts
+# B) Existing private git repo
+ai-md setup --remote https://github.com/<you>/.ai-md.git
 
-```bash
-ai-md script ensure-tools
-ai-md script ensure-tools -- --dry-run
-ai-md setup --remote <url> --script ensure-tools -- --dry-run
+ai-md pull
+# edit shared/ or agents/<id>/ only
+ai-md build
+ai-md push -m "why"
 ```
 
-- Resolves `$AI_MD_DIR/scripts/<name>` or `<name>.sh` (basename only; no `..` / paths).
-- Args after the script name (or after `--` on `setup` / `install`) are forwarded unchanged.
-- Repeat `--script` on setup/install; the same trailing args apply to each.
+## Commands
 
-## Machine config
+| Command | Purpose |
+|---------|---------|
+| `init` / `seed-skeleton` | Scaffold / merge recommended base rules+skills |
+| `build` | Emit `dist/` |
+| `rescue` | Promote dirty dist → `agents/<id>/` |
+| `install` / `pull` | Git + build + link **installed** harnesses |
+| `doctor --fix` | Rebuild + repair links |
+| `harness list\|show\|set\|enable\|disable` | Register or retarget any agent |
+| `config set --link-mode symlink\|junction\|copy` | Platform link mode |
 
-Persisted at `~/.config/ai-md/config.json` (override path with `AI_MD_CONFIG`):
+Flags: `--agents cursor,claude`, `--force-link`, `--force` (discard dirty dist), `--dry-run`, `--json`.
 
-```json
-{ "dir": "/home/you/.ai-md", "remote": "https://github.com/you/.ai-md.git" }
-```
+## Platforms
 
-Env one-shots: `AI_MD_DIR`, `AI_MD_REMOTE`.
+| OS | Default `linkMode` |
+|----|-------------------|
+| Linux / macOS / WSL | `symlink` |
+| Windows | `junction` (fallback symlink → `copy`) |
 
-## Layout example
-
-```text
-~/.ai-md/
-  skills/                 # system — harnesses see these
-  rules/
-  scripts/
-    ensure-tools.sh       # your private tooling
-  templates/
-    base/
-  projects/
-    my-app/
-```
+Run `ai-md` in the **same** environment as the IDE/CLI (Windows Cursor → Windows Node). WSL home ≠ Windows `%USERPROFILE%`.
 
-## License
+## Edit policy
 
-MIT
+Never edit live harness dirs or `dist/`. See seeded `shared/rules/edit-source-not-dist.mdc` and skill `ai-md-config`.