@dujavi/ai-md 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dujavi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# ai-md
+
+Public CLI for syncing a **private** personal AI config directory (`~/.ai-md`) and installing agent CLIs.
+
+| Layer | What | Where |
+|-------|------|--------|
+| **Public** | This package (`ai-md`) — sync/link/ensure-tools scripts only | npm + [github.com/dujavi/ai-md](https://github.com/dujavi/ai-md) |
+| **Private** | Your skills, rules, projects | `~/.ai-md` git repo (e.g. `github.com/<you>/.ai-md`) |
+
+No personal rules or skills ship in this package.
+
+## Install
+
+```bash
+npm i -g @dujavi/ai-md
+# or one-shot:
+npx @dujavi/ai-md --help
+```
+
+## New machine
+
+```bash
+npm i -g @dujavi/ai-md
+export AI_MD_REMOTE=https://github.com/<you>/.ai-md.git   # your private content repo
+ai-md install
+ai-md ensure-tools   # grok + quota-axi
+```
+
+Defaults (override with env):
+
+- `AI_MD_DIR` → `~/.ai-md`
+- `AI_MD_REMOTE` → `https://github.com/dujavi/.ai-md.git`
+
+## Commands
+
+```bash
+ai-md install
+ai-md pull
+ai-md push -m "why"
+ai-md status
+ai-md doctor --fix
+ai-md ensure-tools          # alias: tools
+ai-md link-project --repo ~/my-app
+```
+
+`install` / `pull` / `doctor` keep:
+
+- `~/.cursor/skills` → `$AI_MD_DIR/skills`
+- `~/.cursor/rules` → `$AI_MD_DIR/rules`
+
+## Agent-friendly
+
+Non-interactive flags only (`--dry-run`, `--force`, `--fix`, `-m`). No prompts. Prefer `npx -y @dujavi/ai-md <cmd>` when not installed globally.

package/bin/ai-md.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("child_process");
+const os = require("os");
+const path = require("path");
+
+const scriptsDir = path.join(__dirname, "..", "scripts");
+const home = os.homedir();
+
+const env = {
+  ...process.env,
+  AI_MD_DIR:
+    process.env.AI_MD_DIR ||
+    process.env.CURSOR_MD_DIR ||
+    path.join(home, ".ai-md"),
+  AI_MD_REMOTE:
+    process.env.AI_MD_REMOTE ||
+    process.env.CURSOR_MD_REMOTE ||
+    "https://github.com/dujavi/.ai-md.git",
+};
+
+// Keep legacy env names in sync for older wrappers.
+env.CURSOR_MD_DIR = env.AI_MD_DIR;
+env.CURSOR_MD_REMOTE = env.AI_MD_REMOTE;
+
+const COMMANDS = {
+  install: { script: "sync-config.sh", prefix: ["install"] },
+  pull: { script: "sync-config.sh", prefix: ["pull"] },
+  push: { script: "sync-config.sh", prefix: ["push"] },
+  status: { script: "sync-config.sh", prefix: ["status"] },
+  doctor: { script: "sync-config.sh", prefix: ["doctor"] },
+  "ensure-tools": { script: "ensure-agent-tools.sh", prefix: [] },
+  tools: { script: "ensure-agent-tools.sh", prefix: [] },
+  "link-project": { script: "link-project.sh", prefix: [] },
+  link: { script: "link-project.sh", prefix: [] },
+};
+
+function printHelp() {
+  console.log(`ai-md — sync private ~/.ai-md skills/rules; install agent CLIs
+
+Usage:
+  ai-md <command> [options]
+  npx @dujavi/ai-md <command> [options]
+
+Commands:
+  install          Clone AI_MD_REMOTE → ~/.ai-md (if needed); link ~/.cursor/{skills,rules}
+  pull             git pull private config; refresh symlinks
+  push             commit + push private config (-m/--message)
+  status           repo + symlink health
+  doctor           diagnose; --fix repairs symlinks
+  ensure-tools     install/update grok + quota-axi (alias: tools)
+  link-project     link a repo .cursor/ → ~/.ai-md/projects/<name>/
+  help             show this help
+
+Environment:
+  AI_MD_DIR        Private config dir (default: ~/.ai-md)
+  AI_MD_REMOTE     Git remote if clone needed (default: https://github.com/dujavi/.ai-md.git)
+
+Examples:
+  npm i -g @dujavi/ai-md
+  ai-md install
+  ai-md ensure-tools
+  ai-md pull
+  ai-md push -m "Add routing rule"
+  ai-md link-project --repo ~/presenter
+  ai-md doctor --fix
+
+Private skills/rules live in each person's AI_MD_DIR repo.
+This package ships tooling only — no personal content.
+`);
+}
+
+const [cmd, ...args] = process.argv.slice(2);
+
+if (!cmd || cmd === "help" || cmd === "-h" || cmd === "--help") {
+  printHelp();
+  process.exit(0);
+}
+
+const mapped = COMMANDS[cmd];
+if (!mapped) {
+  console.error(`error: unknown command: ${cmd}`);
+  console.error(`  ai-md --help`);
+  process.exit(2);
+}
+
+const scriptPath = path.join(scriptsDir, mapped.script);
+const result = spawnSync("bash", [scriptPath, ...mapped.prefix, ...args], {
+  stdio: "inherit",
+  env,
+});
+
+if (result.error) {
+  console.error(`error: failed to run ${mapped.script}: ${result.error.message}`);
+  process.exit(1);
+}
+
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@dujavi/ai-md",
+  "version": "0.1.0",
+  "description": "CLI to sync private ~/.ai-md Cursor skills/rules and install agent tools (grok, quota-axi)",
+  "bin": {
+    "ai-md": "bin/ai-md.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node bin/ai-md.js --help"
+  },
+  "keywords": [
+    "cursor",
+    "ai",
+    "skills",
+    "rules",
+    "quota-axi",
+    "grok",
+    "cli",
+    "axi"
+  ],
+  "author": "dujavi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dujavi/ai-md.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dujavi/ai-md/issues"
+  },
+  "homepage": "https://github.com/dujavi/ai-md#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/ensure-agent-tools.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# Ensure Grok Build CLI + quota-axi are installed on this machine.
+# Safe to re-run (idempotent). Does not print secrets.
+set -euo pipefail
+
+DRY_RUN=0
+
+usage() {
+  cat <<'EOF'
+Usage: ensure-agent-tools.sh [--dry-run]
+
+Installs or updates:
+  - grok   (Grok Build CLI) via https://x.ai/cli/install.sh
+  - quota-axi via volta (if present) or npm -g
+
+Then prints version + auth/quota smoke checks (no secrets).
+EOF
+}
+
+log() { printf '%s\n' "$*"; }
+err() { printf 'error: %s\n' "$*" >&2; }
+run() {
+  if [[ "$DRY_RUN" -eq 1 ]]; then
+    log "dry-run: $*"
+  else
+    "$@"
+  fi
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run) DRY_RUN=1; shift ;;
+    -h|--help|help) usage; exit 0 ;;
+    *) err "unknown argument: $1"; usage; exit 1 ;;
+  esac
+done
+
+ensure_path_hint() {
+  local need=0
+  case ":$PATH:" in
+    *":$HOME/.local/bin:"*) ;;
+    *) need=1; log "note: add \$HOME/.local/bin to PATH" ;;
+  esac
+  case ":$PATH:" in
+    *":$HOME/.grok/bin:"*) ;;
+    *) need=1; log "note: add \$HOME/.grok/bin to PATH (grok installer usually does)" ;;
+  esac
+  return 0
+}
+
+install_grok() {
+  if command -v grok >/dev/null 2>&1; then
+    log "grok present: $(grok --version 2>/dev/null || echo unknown)"
+    log "Updating grok via official installer…"
+  else
+    log "Installing grok via official installer…"
+  fi
+  if [[ "$DRY_RUN" -eq 1 ]]; then
+    log "dry-run: curl -fsSL https://x.ai/cli/install.sh | bash"
+    return 0
+  fi
+  curl -fsSL https://x.ai/cli/install.sh | bash
+}
+
+install_quota_axi() {
+  if command -v quota-axi >/dev/null 2>&1; then
+    log "quota-axi present: $(quota-axi --version 2>/dev/null || echo unknown)"
+  else
+    log "Installing quota-axi…"
+  fi
+  if command -v volta >/dev/null 2>&1; then
+    run volta install quota-axi
+  elif command -v npm >/dev/null 2>&1; then
+    run npm install -g quota-axi
+  else
+    err "Need volta or npm to install quota-axi"
+    return 1
+  fi
+}
+
+smoke() {
+  log ""
+  log "=== smoke checks ==="
+  if command -v grok >/dev/null 2>&1; then
+    log "grok: $(command -v grok)"
+    grok --version 2>&1 || true
+    if [[ -f "$HOME/.grok/auth.json" ]]; then
+      log "grok auth: ~/.grok/auth.json present"
+    else
+      log "grok auth: missing — run \`grok\` (browser) or set XAI_API_KEY"
+    fi
+  else
+    err "grok not on PATH after install"
+  fi
+
+  if command -v quota-axi >/dev/null 2>&1; then
+    log "quota-axi: $(command -v quota-axi)"
+    quota-axi auth 2>&1 || true
+    quota-axi --provider grok 2>&1 || true
+  else
+    err "quota-axi not on PATH after install"
+  fi
+
+  if ! command -v sqlite3 >/dev/null 2>&1; then
+    log "note: sqlite3 not found — Cursor quota via quota-axi may fail (install sqlite3)"
+  fi
+}
+
+ensure_path_hint
+install_grok
+install_quota_axi
+smoke
+log ""
+log "Done. Re-run anytime; pair with: ai-md install"

package/scripts/link-project.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# Link a repo's .cursor/ to ~/.ai-md/projects/<name>/ (project rules/skills).
+set -euo pipefail
+
+REPO_MD="${AI_MD_DIR:-${CURSOR_MD_DIR:-$HOME/.ai-md}}"
+DRY_RUN=0
+FORCE=0
+NAME=""
+TARGET=""
+
+usage() {
+  cat <<'EOF'
+Usage: ai-md link-project --repo <path> [--name <id>] [options]
+
+Point a repository's .cursor/ at ~/.ai-md/projects/<name>/ so project
+rules and skills live in the private AI_MD_DIR repo (not committed to the app).
+
+Options:
+  --repo <path>   Repository root to link (required)
+  --name <id>     Project id under projects/ (default: basename of --repo)
+  --force         Replace an existing non-symlink .cursor/
+  --dry-run       Print actions without changing anything
+  -h, --help      Show this help
+
+Examples:
+  ai-md link-project --repo ~/presenter
+  ai-md link-project --repo ~/code/app --name my-app
+  ai-md link --repo . --force
+  npx -y @dujavi/ai-md link-project --repo ~/presenter
+
+After linking, add .cursor/ to the app repo's .gitignore.
+EOF
+}
+
+log() { printf '%s\n' "$*"; }
+err() { printf 'error: %s\n' "$*" >&2; }
+run() {
+  if [[ "$DRY_RUN" -eq 1 ]]; then
+    log "dry-run: $*"
+  else
+    "$@"
+  fi
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo)
+      TARGET="${2:?--repo requires a path}"
+      shift 2
+      ;;
+    --name)
+      NAME="${2:?--name requires a value}"
+      shift 2
+      ;;
+    --force)
+      FORCE=1
+      shift
+      ;;
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    -h|--help|help)
+      usage
+      exit 0
+      ;;
+    *)
+      err "unknown argument: $1"
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$TARGET" ]]; then
+  err "missing --repo <path>"
+  err "  ai-md link-project --repo ~/presenter"
+  exit 1
+fi
+
+if [[ ! -d "$TARGET" ]]; then
+  err "not a directory: $TARGET"
+  exit 1
+fi
+
+TARGET="$(cd "$TARGET" && pwd)"
+if [[ -z "$NAME" ]]; then
+  NAME="$(basename "$TARGET")"
+fi
+
+PROJECT_DIR="$REPO_MD/projects/$NAME"
+LINK="$TARGET/.cursor"
+
+if [[ ! -d "$REPO_MD/.git" ]]; then
+  err "$REPO_MD is not a git repo; run ai-md install first"
+  exit 1
+fi
+
+run mkdir -p "$PROJECT_DIR/rules" "$PROJECT_DIR/skills"
+
+if [[ -L "$LINK" ]]; then
+  current="$(readlink "$LINK")"
+  if [[ "$current" == "$PROJECT_DIR" ]]; then
+    log "ok: $LINK → $PROJECT_DIR"
+  else
+    log "repair: $LINK (was → $current)"
+    run ln -sfn "$PROJECT_DIR" "$LINK"
+  fi
+elif [[ -e "$LINK" ]]; then
+  if [[ "$FORCE" -ne 1 ]]; then
+    err "$LINK exists and is not a symlink (use --force after backing up)"
+    exit 1
+  fi
+  log "replace: $LINK (--force)"
+  run rm -rf "$LINK"
+  run ln -sfn "$PROJECT_DIR" "$LINK"
+else
+  run ln -sfn "$PROJECT_DIR" "$LINK"
+  log "linked: $LINK → $PROJECT_DIR"
+fi
+
+gitignore="$TARGET/.gitignore"
+if [[ -f "$gitignore" ]] && grep -qxF '.cursor/' "$gitignore" 2>/dev/null; then
+  log "ok: .cursor/ already in .gitignore"
+elif [[ -f "$gitignore" ]]; then
+  if [[ "$DRY_RUN" -eq 1 ]]; then
+    log "dry-run: append .cursor/ to $gitignore"
+  else
+    printf '\n# Personal Cursor config (symlink to ~/.ai-md)\n.cursor/\n' >>"$gitignore"
+    log "appended .cursor/ to .gitignore"
+  fi
+else
+  log "note: no .gitignore at $TARGET — add .cursor/ manually"
+fi
+
+log "Project config: $PROJECT_DIR"
+log "  rules:  $(find "$PROJECT_DIR/rules" -maxdepth 1 -type f 2>/dev/null | wc -l | tr -d ' ')"
+log "  skills: $(find "$PROJECT_DIR/skills" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l | tr -d ' ')"

package/scripts/sync-config.sh

@@ -0,0 +1,295 @@
+#!/usr/bin/env bash
+# Sync global personal Cursor skills/rules via ~/.ai-md (git + symlinks).
+# Invoked by the public `ai-md` npm package. Private content stays in AI_MD_DIR.
+set -euo pipefail
+
+REPO="${AI_MD_DIR:-${CURSOR_MD_DIR:-$HOME/.ai-md}}"
+REMOTE_URL="${AI_MD_REMOTE:-${CURSOR_MD_REMOTE:-https://github.com/dujavi/.ai-md.git}}"
+DRY_RUN=0
+FORCE=0
+COMMIT_MSG="Update personal AI skills/rules"
+
+usage() {
+  cat <<'EOF'
+Usage: ai-md <command> [options]
+
+Sync private ~/.ai-md skills and rules (git). Tooling-only package — no personal content.
+
+Commands:
+  install   Create/repair ~/.cursor/{skills,rules} symlinks into AI_MD_DIR
+  pull      git pull, then refresh symlinks (run before editing)
+  push      Commit dirty changes and git push (run after editing)
+  status    Show repo state, symlink health, and rule/skill counts
+  doctor    Diagnose problems; with --fix, repair symlinks
+
+Also: ai-md ensure-tools  (grok + quota-axi)
+
+Options:
+  -m, --message <msg>  Commit message for push (default: generic update)
+  --dry-run            Print actions without changing anything
+  --force              Replace existing non-symlink paths (install/doctor --fix)
+  -h, --help           Show this help
+
+Environment:
+  AI_MD_DIR     Private config path (default: ~/.ai-md)
+  AI_MD_REMOTE  Clone URL if repo missing (default: https://github.com/dujavi/.ai-md.git)
+
+Examples:
+  ai-md install
+  ai-md pull
+  ai-md push -m "Add grafana rule"
+  ai-md status
+  ai-md doctor --fix
+  npx -y @dujavi/ai-md pull
+EOF
+}
+
+log() { printf '%s\n' "$*"; }
+err() { printf 'error: %s\n' "$*" >&2; }
+run() {
+  if [[ "$DRY_RUN" -eq 1 ]]; then
+    log "dry-run: $*"
+  else
+    "$@"
+  fi
+}
+
+ensure_repo() {
+  if [[ ! -d "$REPO/.git" ]]; then
+    err "$REPO is not a git repo."
+    err "  git clone $REMOTE_URL $REPO"
+    err "  or: ai-md install"
+    exit 1
+  fi
+}
+
+clone_if_missing() {
+  if [[ -d "$REPO/.git" ]]; then
+    return 0
+  fi
+
+  # One-time migration from the old ~/.cursor-md layout.
+  local legacy="$HOME/.cursor-md"
+  if [[ "$REPO" == "$HOME/.ai-md" ]] && [[ -d "$legacy/.git" ]] && [[ ! -e "$REPO" ]]; then
+    log "Migrating $legacy → $REPO"
+    run mv "$legacy" "$REPO"
+    return 0
+  fi
+
+  if [[ -e "$REPO" ]] && [[ ! -d "$REPO" ]]; then
+    err "$REPO exists and is not a directory"
+    exit 1
+  fi
+  if [[ -d "$REPO" ]] && [[ -n "$(ls -A "$REPO" 2>/dev/null || true)" ]]; then
+    err "$REPO exists but is not a git repo (and is not empty)"
+    exit 1
+  fi
+  log "Cloning $REMOTE_URL → $REPO"
+  run git clone "$REMOTE_URL" "$REPO"
+}
+
+link_path() {
+  local target="$1"
+  local link="$2"
+  local link_dir
+
+  mkdir -p "$(dirname "$link")"
+  mkdir -p "$target"
+
+  if [[ -L "$link" ]]; then
+    local current
+    current="$(readlink "$link")"
+    if [[ "$current" == "$target" ]]; then
+      log "ok: $link → $target"
+      return 0
+    fi
+    log "repair: $link (was → $current)"
+    run ln -sfn "$target" "$link"
+    return 0
+  fi
+
+  if [[ -e "$link" ]]; then
+    if [[ "$FORCE" -ne 1 ]]; then
+      err "$link exists and is not a symlink (use --force to replace)"
+      err "  expected → $target"
+      return 1
+    fi
+    log "replace: $link (was a real path; --force)"
+    run rm -rf "$link"
+  fi
+
+  link_dir="$(dirname "$link")"
+  run mkdir -p "$link_dir"
+  run ln -sfn "$target" "$link"
+  log "linked: $link → $target"
+}
+
+ensure_symlinks() {
+  local rc=0
+  link_path "$REPO/skills" "$HOME/.cursor/skills" || rc=1
+  link_path "$REPO/rules" "$HOME/.cursor/rules" || rc=1
+  return "$rc"
+}
+
+count_rules() {
+  find "$REPO/rules" -maxdepth 1 -type f \( -name '*.mdc' -o -name '*.md' \) 2>/dev/null | wc -l | tr -d ' '
+}
+
+count_skills() {
+  find "$REPO/skills" -mindepth 1 -maxdepth 1 -type d ! -name '.*' 2>/dev/null | wc -l | tr -d ' '
+}
+
+cmd_install() {
+  clone_if_missing
+  ensure_repo
+  ensure_symlinks
+  log "Install complete."
+  log "  rules:  $(count_rules)"
+  log "  skills: $(count_skills)"
+  log "Next: ai-md ensure-tools  # grok + quota-axi"
+}
+
+cmd_pull() {
+  ensure_repo
+  if [[ "$DRY_RUN" -eq 1 ]]; then
+    log "dry-run: git -C $REPO pull --rebase --autostash"
+  else
+    git -C "$REPO" pull --rebase --autostash
+  fi
+  ensure_symlinks
+  log "Pulled $REPO; symlinks refreshed."
+}
+
+cmd_push() {
+  ensure_repo
+  ensure_symlinks
+  if [[ "$DRY_RUN" -eq 1 ]]; then
+    git -C "$REPO" status -sb
+    log "dry-run: would add/commit/push with message: $COMMIT_MSG"
+    return 0
+  fi
+  git -C "$REPO" add -A
+  if git -C "$REPO" diff --cached --quiet; then
+    log "Nothing to commit in $REPO."
+  else
+    git -C "$REPO" commit -m "$COMMIT_MSG"
+  fi
+  git -C "$REPO" push
+  log "Pushed $REPO."
+}
+
+cmd_status() {
+  ensure_repo
+  log "Repo: $REPO"
+  log "Branch: $(git -C "$REPO" rev-parse --abbrev-ref HEAD)"
+  log "Remote: $(git -C "$REPO" remote get-url origin 2>/dev/null || echo '(none)')"
+  log ""
+  log "Global symlinks:"
+  for name in skills rules; do
+    local path="$HOME/.cursor/$name"
+    if [[ -L "$path" ]]; then
+      log "  $path → $(readlink "$path")"
+    elif [[ -e "$path" ]]; then
+      log "  $path  (exists, NOT a symlink)"
+    else
+      log "  $path  (missing)"
+    fi
+  done
+  log ""
+  log "Counts: $(count_rules) rules, $(count_skills) skills"
+  log ""
+  git -C "$REPO" status -sb
+}
+
+cmd_doctor() {
+  ensure_repo
+  local problems=0
+
+  for name in skills rules; do
+    local path="$HOME/.cursor/$name"
+    local expected="$REPO/$name"
+    if [[ ! -L "$path" ]]; then
+      err "symlink missing or wrong type: $path"
+      problems=$((problems + 1))
+    elif [[ "$(readlink "$path")" != "$expected" ]]; then
+      err "symlink target wrong: $path → $(readlink "$path") (want $expected)"
+      problems=$((problems + 1))
+    fi
+  done
+
+  if ! git -C "$REPO" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    err "not a git work tree: $REPO"
+    problems=$((problems + 1))
+  fi
+
+  if [[ "$problems" -eq 0 ]]; then
+    log "doctor: healthy ($(count_rules) rules, $(count_skills) skills)"
+    return 0
+  fi
+
+  log "doctor: $problems issue(s)"
+  if [[ "${1:-}" == "--fix" ]] || [[ "$FORCE" -eq 1 ]]; then
+    ensure_symlinks
+    log "doctor: attempted repair"
+  else
+    err "Re-run with: ai-md doctor --fix"
+    return 1
+  fi
+}
+
+# --- arg parse ---
+CMD=""
+FIX=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    install|pull|push|status|doctor)
+      CMD="$1"
+      shift
+      ;;
+    -m|--message)
+      COMMIT_MSG="${2:?--message requires a value}"
+      shift 2
+      ;;
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    --force)
+      FORCE=1
+      shift
+      ;;
+    --fix)
+      FIX=1
+      FORCE=1
+      shift
+      ;;
+    -h|--help|help)
+      usage
+      exit 0
+      ;;
+    *)
+      err "unknown argument: $1"
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$CMD" ]]; then
+  usage
+  exit 1
+fi
+
+case "$CMD" in
+  install) cmd_install ;;
+  pull)    cmd_pull ;;
+  push)    cmd_push ;;
+  status)  cmd_status ;;
+  doctor)
+    if [[ "$FIX" -eq 1 ]]; then
+      cmd_doctor --fix
+    else
+      cmd_doctor
+    fi
+    ;;
+esac