@dujavi/ai-md 0.4.0 → 0.6.0

package/README.md

@@ -1,61 +1,73 @@
-# ai-md
+# @dujavi/ai-md
 
 Public **AXI-shaped** CLI for a **private** personal AI config directory (`~/.ai-md`).
 
-| Layer | Path | Purpose |
-|-------|------|---------|
-| **System** | `skills/`, `rules/` | Global base — linked to `~/.cursor/{skills,rules}` |
-| **Templates** | `templates/<type>/` | Project-type starters (`base`, later `forms`, …) |
-| **Projects** | `projects/<name>/` | Per-app overlays (repo `.cursor` → here) |
+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.
 
-No personal content ships in this package. Reads default to TOON + `help[]` (`--json` available).
+## Layout (private repo)
 
-## New machine
+| 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 |
+
+## Unique vs shared live roots
+
+| 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 |
+
+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
-ai-md setup --remote https://github.com/<you>/.ai-md.git --tools
-# persists ~/.config/ai-md/config.json then clones + links (+ optional grok/quota-axi)
-```
 
-Or step by step:
+# A) No private remote yet
+ai-md init
 
-```bash
-ai-md config set --remote https://github.com/<you>/.ai-md.git --dir ~/.ai-md
-ai-md install
-ai-md ensure-tools
+# B) Existing private git repo
+ai-md setup --remote https://github.com/<you>/.ai-md.git
+
+ai-md pull
+# edit shared/ or agents/<id>/ only
+ai-md build
+ai-md push -m "why"
 ```
 
-Precedence: `--remote`/`--dir` flags > `AI_MD_*` env > `~/.config/ai-md/config.json` > defaults.
+## Commands
 
-## Layout idea
+| 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 |
 
-```text
-~/.ai-md/
-  skills/                 # system — all agents see these
-  rules/
-  templates/
-    base/                 # default project starter (customizable stubs only)
-    # forms/ …            # other use cases
-  projects/
-    presenter/
-    sendfolio/
-```
+Flags: `--agents cursor,claude`, `--force-link`, `--force` (discard dirty dist), `--dry-run`, `--json`.
 
-Put shared agentic skills/rules in **system** folders. Put only type-specific or per-project starters under **templates/**.
+## Platforms
 
-## Commands
+| OS | Default `linkMode` |
+|----|-------------------|
+| Linux / macOS / WSL | `symlink` |
+| Windows | `junction` (fallback symlink → `copy`) |
 
-```bash
-ai-md                                      # status
-ai-md init-project --repo ~/app --from base
-ai-md apply-template --project app --from base
-ai-md doctor --fix --agents cursor,claude
-ai-md pull | push -m "why"
-ai-md ensure-tools
-```
+Run `ai-md` in the **same** environment as the IDE/CLI (Windows Cursor → Windows Node). WSL home ≠ Windows `%USERPROFILE%`.
 
-## Environment
+## Edit policy
 
-- `AI_MD_DIR` / `AI_MD_REMOTE` — override for one shot (also set by the CLI after reading config)
-- `AI_MD_CONFIG` — path to machine config JSON (default `~/.config/ai-md/config.json`)
+Never edit live harness dirs or `dist/`. See seeded `shared/rules/edit-source-not-dist.mdc` and skill `ai-md-config`.