@dujavi/ai-md 0.2.0 → 0.4.0

package/README.md

@@ -1,69 +1,61 @@
 # ai-md
 
-Public **AXI-shaped** CLI for a **private** personal AI config directory (`~/.ai-md`): global skills/rules, per-project templates, and agent tool bootstrap.
+Public **AXI-shaped** CLI for a **private** personal AI config directory (`~/.ai-md`).
 
-| Layer | What | Where |
-|-------|------|--------|
-| **Public** | This package (`@dujavi/ai-md`) | npm + [github.com/dujavi/ai-md](https://github.com/dujavi/ai-md) |
-| **Private** | Your skills, rules, `projects/` | `~/.ai-md` git repo |
+| 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) |
 
-No personal rules or skills ship in this package. Output defaults to [TOON](https://toonformat.dev/) with `help[]` next steps (`--json` available).
+No personal content ships in this package. Reads default to TOON + `help[]` (`--json` available).
 
-## Install
+## New machine
 
 ```bash
 npm i -g @dujavi/ai-md
-# binary: 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)
 ```
 
-## New machine
+Or step by step:
 
 ```bash
-export AI_MD_REMOTE=https://github.com/<you>/.ai-md.git
+ai-md config set --remote https://github.com/<you>/.ai-md.git --dir ~/.ai-md
 ai-md install
 ai-md ensure-tools
 ```
 
-Optional multi-agent skill links:
+Precedence: `--remote`/`--dir` flags > `AI_MD_*` env > `~/.config/ai-md/config.json` > defaults.
 
-```bash
-ai-md install --agents cursor,claude,agents
-```
+## Layout idea
 
-## Day-to-day
-
-```bash
-ai-md                    # status (content-first)
-ai-md status --json
-ai-md pull
-ai-md push -m "why"
-ai-md doctor --fix
+```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/
 ```
 
-## Projects (templating)
+Put shared agentic skills/rules in **system** folders. Put only type-specific or per-project starters under **templates/**.
 
-```bash
-# Seed from projects/template + link repo/.cursor + gitignore
-ai-md init-project --repo ~/my-app
+## Commands
 
-# Merge missing baseline files into an existing project
-ai-md apply-template --project my-app
-
-# Link only (empty rules/skills dirs if missing)
-ai-md link-project --repo ~/my-app
+```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
 ```
 
-## AXI-shaped reads
-
-| Flag | Effect |
-|------|--------|
-| (default) | TOON on stdout + `help[]` |
-| `--json` | Normalized JSON |
-| `--full` | Paths + template drift details |
-
-Mutations (`push`, `ensure-tools`) stay human/git-oriented.
-
 ## Environment
 
-- `AI_MD_DIR` → `~/.ai-md`
-- `AI_MD_REMOTE` → `https://github.com/dujavi/.ai-md.git`
+- `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`)

package/bin/ai-md.js

@@ -3,7 +3,13 @@
 
 const { spawnSync } = require("child_process");
 const path = require("path");
-const { resolveConfig } = require("../lib/config");
+const {
+  resolveConfig,
+  applyEnvFromConfig,
+  writeMachineConfig,
+  readMachineConfig,
+  expandHome,
+} = require("../lib/config");
 const { emit, fail } = require("../lib/output");
 const { collectStatus, statusHelp } = require("../lib/status");
 const {
@@ -16,12 +22,6 @@ const {
 } = require("../lib/commands");
 
 const scriptsDir = path.join(__dirname, "..", "scripts");
-const cfg = resolveConfig();
-
-process.env.AI_MD_DIR = cfg.dir;
-process.env.AI_MD_REMOTE = cfg.remote;
-process.env.CURSOR_MD_DIR = cfg.dir;
-process.env.CURSOR_MD_REMOTE = cfg.remote;
 
 function parseArgs(argv) {
   const out = {
@@ -31,11 +31,14 @@ function parseArgs(argv) {
     force: false,
     dryRun: false,
     fix: false,
+    tools: false,
     message: null,
     repo: null,
     name: null,
     project: null,
-    from: "template",
+    from: "base",
+    remote: null,
+    dir: null,
     agents: ["cursor"],
     rest: [],
   };
@@ -50,7 +53,6 @@ function parseArgs(argv) {
     return out;
   }
   if (first.startsWith("-")) {
-    // flags before command → treat as status with flags
     out.cmd = "status";
   } else {
     out.cmd = args.shift();
@@ -74,6 +76,9 @@ function parseArgs(argv) {
         out.fix = true;
         out.force = true;
         break;
+      case "--tools":
+        out.tools = true;
+        break;
       case "-m":
       case "--message":
         out.message = args.shift();
@@ -90,6 +95,12 @@ function parseArgs(argv) {
       case "--from":
         out.from = args.shift();
         break;
+      case "--remote":
+        out.remote = args.shift();
+        break;
+      case "--dir":
+        out.dir = expandHome(args.shift());
+        break;
       case "--agents":
         out.agents = String(args.shift() || "cursor")
           .split(",")
@@ -100,6 +111,11 @@ function parseArgs(argv) {
       case "--help":
         out.cmdHelp = true;
         break;
+      case "set":
+      case "show":
+        // subcommand for `ai-md config set|show`
+        out.rest.push(a);
+        break;
       default:
         if (a.startsWith("-")) {
           fail(`unknown flag: ${a}`, {
@@ -117,54 +133,63 @@ function parseArgs(argv) {
 }
 
 function printHelp() {
-  process.stdout.write(`ai-md — private ~/.ai-md skills/rules + project templates (AXI-shaped)
+  process.stdout.write(`ai-md — private ~/.ai-md: system skills/rules + templates/ + projects/ (AXI-shaped)
 
 Usage:
   ai-md [command] [options]
   npx -y @dujavi/ai-md [command] [options]
 
+Layout:
+  ~/.ai-md/skills, rules     System (global) base — linked to ~/.cursor
+  ~/.ai-md/templates/<type>  Project-type starters (default: base)
+  ~/.ai-md/projects/<name>   Per-app overlays (repo .cursor → here)
+
+Machine config (persisted):
+  ~/.config/ai-md/config.json   dir + remote (override with AI_MD_CONFIG)
+  Precedence: --flag > env > config file > defaults
+
 Commands:
+  setup              First-time machine setup: save config, install, optional --tools
+  config             Show persisted config (or: config set --remote/--dir)
   status             Snapshot (default when no command) [AXI]
   doctor             Diagnose links/projects; --fix repairs
   install            Clone remote if needed; link ~/.cursor + optional agents
   pull | push        Sync private git repo
   ensure-tools       Install/update grok + quota-axi (alias: tools)
-  init-project       Seed projects/<name> from template + link repo .cursor/
-  apply-template     Merge missing template files into an existing project
+  init-project       Seed projects/<name> from templates/<from> + link .cursor/
+  apply-template     Merge missing files from a template into a project
   link-project       Link repo .cursor/ without seeding (alias: link)
   help               Show this help
 
 Options:
-  --json             JSON instead of TOON (status/doctor/init/…)
+  --remote <url>     Private content git remote (persisted by setup/config set/install)
+  --dir <path>       Local AI_MD_DIR (default ~/.ai-md; persisted same way)
+  --json             JSON instead of TOON
   --full             Include paths and drift details
   --agents <list>    Skill link targets: cursor,claude,agents (default: cursor)
+  --tools            With setup: also run ensure-tools
   --repo <path>      App repository root
-  --name <id>        Project id under projects/ (default: basename)
+  --name <id>        Project id under projects/
   --project <id>     Target project for apply-template
-  --from <id>        Template folder (default: template)
-  --force            Replace non-symlink .cursor / re-merge
+  --from <id>        Template under templates/ (default: base)
+  --force            Replace non-symlink paths
   --dry-run          Preview without writing
   --fix             doctor: repair symlinks
   -m, --message      push commit message
 
-Environment:
-  AI_MD_DIR          Private config dir (default: ~/.ai-md)
-  AI_MD_REMOTE       Clone URL (default: https://github.com/dujavi/.ai-md.git)
-
 Examples:
-  ai-md
-  ai-md status --json
-  ai-md doctor --fix --agents cursor,claude
-  ai-md init-project --repo ~/presenter
-  ai-md apply-template --project presenter
-  ai-md push -m "Add rule"
+  ai-md setup --remote https://github.com/<you>/.ai-md.git --tools
+  ai-md config set --remote https://github.com/<you>/.ai-md.git --dir ~/.ai-md
+  ai-md config
+  ai-md install --remote https://github.com/<you>/.ai-md.git
+  ai-md init-project --repo ~/presenter --from base
 `);
 }
 
-function runBash(script, args) {
+function runBash(script, args, env) {
   const result = spawnSync("bash", [path.join(scriptsDir, script), ...args], {
     stdio: "inherit",
-    env: process.env,
+    env,
   });
   if (result.error) {
     fail(result.error.message, { exitCode: 1 });
@@ -173,6 +198,37 @@ function runBash(script, args) {
   process.exit(result.status === null ? 1 : result.status);
 }
 
+function persistIfRequested(opts) {
+  if (opts.remote == null && opts.dir == null) return null;
+  return writeMachineConfig(
+    { dir: opts.dir, remote: opts.remote },
+    process.env,
+    { dryRun: opts.dryRun }
+  );
+}
+
+function runInstall(cfg, opts) {
+  const bashArgs = ["install"];
+  if (opts.force) bashArgs.push("--force");
+  if (opts.dryRun) bashArgs.push("--dry-run");
+  const result = spawnSync(
+    "bash",
+    [path.join(scriptsDir, "sync-config.sh"), ...bashArgs],
+    { stdio: "inherit", env: process.env }
+  );
+  if (result.status !== 0) {
+    process.exit(result.status === null ? 1 : result.status);
+  }
+  const links = [
+    ...ensureCursorLinks(cfg, { force: opts.force, dryRun: opts.dryRun }),
+    ...ensureAgentSkillLinks(cfg, opts.agents, {
+      force: opts.force,
+      dryRun: opts.dryRun,
+    }),
+  ];
+  return links;
+}
+
 function main() {
   const opts = parseArgs(process.argv.slice(2));
 
@@ -181,10 +237,122 @@ function main() {
     return;
   }
 
+  // Resolve after flags so --dir/--remote apply
+  let cfg = resolveConfig(process.env, {
+    dir: opts.dir || undefined,
+    remote: opts.remote || undefined,
+  });
+  applyEnvFromConfig(cfg);
+
   try {
     switch (opts.cmd) {
+      case "config": {
+        const sub = opts.rest[0] || "show";
+        if (sub === "set") {
+          if (opts.remote == null && opts.dir == null) {
+            fail("config set requires --remote and/or --dir", {
+              exitCode: 2,
+              json: opts.json,
+              help: [
+                "ai-md config set --remote https://github.com/<you>/.ai-md.git --dir ~/.ai-md",
+              ],
+            });
+            process.exit(2);
+          }
+          const saved = writeMachineConfig(
+            { dir: opts.dir, remote: opts.remote },
+            process.env,
+            { dryRun: opts.dryRun }
+          );
+          cfg = resolveConfig(process.env);
+          emit({
+            data: { ...saved, resolved: { dir: cfg.dir, remote: cfg.remote, sources: cfg.sources } },
+            json: opts.json,
+            help: [
+              "Run `ai-md install` if ~/.ai-md is not cloned yet",
+              "Run `ai-md setup --remote <url> --tools` for first-time machine bootstrap",
+            ],
+          });
+          break;
+        }
+        const stored = readMachineConfig();
+        cfg = resolveConfig(process.env);
+        emit({
+          data: {
+            path: stored.path,
+            stored: stored.raw,
+            resolved: {
+              dir: cfg.dir,
+              remote: cfg.remote,
+              sources: cfg.sources,
+            },
+          },
+          json: opts.json,
+          help: [
+            "ai-md config set --remote <url> --dir ~/.ai-md",
+            "Flags and env override the config file",
+          ],
+        });
+        break;
+      }
+      case "setup": {
+        if (!opts.remote && !cfg.machineConfig?.remote && cfg.sources.remote === "default") {
+          // Allow default for dujavi, but recommend explicit remote for others via help
+        }
+        const saved = writeMachineConfig(
+          {
+            dir: opts.dir || cfg.dir,
+            remote: opts.remote || cfg.remote,
+          },
+          process.env,
+          { dryRun: opts.dryRun }
+        );
+        cfg = resolveConfig(process.env, {
+          dir: opts.dir || undefined,
+          remote: opts.remote || undefined,
+        });
+        applyEnvFromConfig(cfg);
+        const links = opts.dryRun
+          ? []
+          : runInstall(cfg, opts);
+        let tools = null;
+        if (opts.tools && !opts.dryRun) {
+          const tr = spawnSync(
+            "bash",
+            [path.join(scriptsDir, "ensure-agent-tools.sh")],
+            { stdio: "inherit", env: process.env }
+          );
+          tools = { exitCode: tr.status };
+        }
+        const data = collectStatus({
+          full: opts.full,
+          agents: opts.agents,
+          from: opts.from,
+        });
+        emit({
+          data: {
+            setup: "ok",
+            config: saved,
+            links,
+            tools,
+            ...data,
+          },
+          json: opts.json,
+          help: [
+            opts.tools
+              ? "Run `ai-md status` to verify"
+              : "Run `ai-md ensure-tools` (or re-run setup with --tools)",
+            "Run `ai-md init-project --repo <path> --from base` for a new app",
+          ],
+        });
+        break;
+      }
       case "status": {
-        const data = collectStatus({ full: opts.full, agents: opts.agents });
+        const data = collectStatus({
+          full: opts.full,
+          agents: opts.agents,
+          from: opts.from,
+        });
         emit({ data, json: opts.json, help: statusHelp(data) });
         process.exitCode = data.counts.problems > 0 ? 1 : 0;
         break;
@@ -225,6 +393,7 @@ function main() {
       case "apply-template": {
         const data = applyTemplate({
           project: opts.project || opts.name,
+          from: opts.from,
           dryRun: opts.dryRun,
         });
         emit({
@@ -255,28 +424,18 @@ function main() {
         break;
       }
       case "install": {
-        // clone/pull via bash, then Node links (incl. agents)
-        const bashArgs = ["install"];
-        if (opts.force) bashArgs.push("--force");
-        if (opts.dryRun) bashArgs.push("--dry-run");
-        const result = spawnSync(
-          "bash",
-          [path.join(scriptsDir, "sync-config.sh"), ...bashArgs],
-          { stdio: "inherit", env: process.env }
-        );
-        if (result.status !== 0) {
-          process.exit(result.status === null ? 1 : result.status);
+        const saved = persistIfRequested(opts);
+        if (saved) {
+          cfg = resolveConfig(process.env, {
+            dir: opts.dir || undefined,
+            remote: opts.remote || undefined,
+          });
+          applyEnvFromConfig(cfg);
         }
-        const links = [
-          ...ensureCursorLinks(cfg, { force: opts.force, dryRun: opts.dryRun }),
-          ...ensureAgentSkillLinks(cfg, opts.agents, {
-            force: opts.force,
-            dryRun: opts.dryRun,
-          }),
-        ];
+        const links = runInstall(cfg, opts);
         const data = collectStatus({ full: opts.full, agents: opts.agents });
         emit({
-          data: { install: "ok", links, ...data },
+          data: { install: "ok", config: saved, links, ...data },
           json: opts.json,
           help: [
             "Run `ai-md ensure-tools` to install grok + quota-axi",
@@ -286,23 +445,26 @@ function main() {
         break;
       }
       case "pull":
-        runBash("sync-config.sh", [
-          "pull",
-          ...(opts.dryRun ? ["--dry-run"] : []),
-        ]);
+        runBash(
+          "sync-config.sh",
+          ["pull", ...(opts.dryRun ? ["--dry-run"] : [])],
+          process.env
+        );
         break;
       case "push": {
         const args = ["push"];
         if (opts.message) args.push("-m", opts.message);
         if (opts.dryRun) args.push("--dry-run");
-        runBash("sync-config.sh", args);
+        runBash("sync-config.sh", args, process.env);
         break;
       }
       case "ensure-tools":
       case "tools":
-        runBash("ensure-agent-tools.sh", [
-          ...(opts.dryRun ? ["--dry-run"] : []),
-        ]);
+        runBash(
+          "ensure-agent-tools.sh",
+          [...(opts.dryRun ? ["--dry-run"] : [])],
+          process.env
+        );
         break;
       default:
         fail(`unknown command: ${opts.cmd}`, {

package/lib/commands.js

@@ -4,6 +4,7 @@ const fs = require("fs");
 const path = require("path");
 const {
   resolveConfig,
+  templatePath,
   symlinkState,
   agentSkillTargets,
 } = require("./config");
@@ -86,7 +87,7 @@ function copyDir(src, dest, { dryRun = false } = {}) {
 function initProject({
   repo,
   name,
-  from = "template",
+  from = "base",
   force = false,
   dryRun = false,
 } = {}) {
@@ -103,11 +104,13 @@ function initProject({
   }
   const absRepo = fs.realpathSync(repo);
   const projectName = name || path.basename(absRepo);
-  const templateDir = path.join(cfg.projectsDir, from);
+  const tmplDir = templatePath(cfg, from);
   const projectDir = path.join(cfg.projectsDir, projectName);
 
-  if (!fs.existsSync(templateDir)) {
-    const err = new Error(`template not found: ${templateDir}`);
+  if (!fs.existsSync(tmplDir)) {
+    const err = new Error(
+      `template not found: ${tmplDir} (available under ${cfg.templatesDir}/)`
+    );
     err.code = "ENOENT";
     throw err;
   }
@@ -121,11 +124,10 @@ function initProject({
     if (hasContent && !force) {
       actions.push({ action: "exists", path: projectDir });
     } else {
-      // Empty project dir, or --force: merge missing baseline files only
-      actions.push(...mergeTemplate(templateDir, projectDir, { dryRun }));
+      actions.push(...mergeTemplate(tmplDir, projectDir, { dryRun }));
     }
   } else {
-    actions.push(copyDir(templateDir, projectDir, { dryRun }));
+    actions.push(copyDir(tmplDir, projectDir, { dryRun }));
   }
 
   const link = path.join(absRepo, ".cursor");
@@ -137,6 +139,7 @@ function initProject({
     projectDir,
     repo: absRepo,
     from,
+    templateDir: tmplDir,
     actions,
   };
 }
@@ -172,7 +175,7 @@ function mergeTemplate(templateDir, projectDir, { dryRun = false } = {}) {
   return actions;
 }
 
-function applyTemplate({ project, dryRun = false } = {}) {
+function applyTemplate({ project, from = "base", dryRun = false } = {}) {
   const cfg = resolveConfig();
   if (!project) {
     const err = new Error("missing --project <name>");
@@ -185,13 +188,14 @@ function applyTemplate({ project, dryRun = false } = {}) {
     err.code = "ENOENT";
     throw err;
   }
-  if (project === "template") {
-    const err = new Error("cannot apply-template onto template itself");
-    err.code = "EINVAL";
+  const tmplDir = templatePath(cfg, from);
+  if (!fs.existsSync(tmplDir)) {
+    const err = new Error(`template not found: ${tmplDir}`);
+    err.code = "ENOENT";
     throw err;
   }
-  const actions = mergeTemplate(cfg.templateDir, projectDir, { dryRun });
-  return { project, projectDir, actions };
+  const actions = mergeTemplate(tmplDir, projectDir, { dryRun });
+  return { project, projectDir, from, templateDir: tmplDir, actions };
 }
 
 function linkProject({ repo, name, force = false, dryRun = false } = {}) {

package/lib/config.js

@@ -4,27 +4,140 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 
-function resolveConfig(env = process.env) {
+const DEFAULT_REMOTE = "https://github.com/dujavi/.ai-md.git";
+
+function expandHome(p) {
+  if (!p) return p;
+  if (p === "~") return os.homedir();
+  if (p.startsWith("~/")) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+/** Machine-local config (not inside the private content repo). */
+function machineConfigPath(env = process.env) {
+  if (env.AI_MD_CONFIG) return expandHome(env.AI_MD_CONFIG);
+  const xdg = env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  return path.join(xdg, "ai-md", "config.json");
+}
+
+function readMachineConfig(env = process.env) {
+  const configPath = machineConfigPath(env);
+  try {
+    const raw = fs.readFileSync(configPath, "utf8");
+    const data = JSON.parse(raw);
+    return {
+      path: configPath,
+      dir: data.dir ? expandHome(String(data.dir)) : null,
+      remote: data.remote ? String(data.remote) : null,
+      raw: data,
+    };
+  } catch {
+    return { path: configPath, dir: null, remote: null, raw: null };
+  }
+}
+
+function writeMachineConfig({ dir, remote }, env = process.env, { dryRun = false } = {}) {
+  const configPath = machineConfigPath(env);
+  const existing = readMachineConfig(env).raw || {};
+  const next = {
+    ...existing,
+    ...(dir != null ? { dir: expandHome(dir) } : {}),
+    ...(remote != null ? { remote: String(remote) } : {}),
+    updatedAt: new Date().toISOString(),
+  };
+  if (!next.dir && !next.remote) {
+    const err = new Error("nothing to write: provide --dir and/or --remote");
+    err.code = "EINVAL";
+    throw err;
+  }
+  if (dryRun) {
+    return { action: "would_write", path: configPath, config: next };
+  }
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, `${JSON.stringify(next, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  try {
+    fs.chmodSync(configPath, 0o600);
+  } catch {
+    /* best effort */
+  }
+  return { action: "wrote", path: configPath, config: next };
+}
+
+/**
+ * Precedence: explicit opts > env > machine config file > defaults.
+ * @param {{ dir?: string, remote?: string }} [opts]
+ */
+function resolveConfig(env = process.env, opts = {}) {
   const home = os.homedir();
-  const dir =
-    env.AI_MD_DIR || env.CURSOR_MD_DIR || path.join(home, ".ai-md");
+  const stored = readMachineConfig(env);
+  const defaultDir = path.join(home, ".ai-md");
+
+  const envDir = env.AI_MD_DIR || env.CURSOR_MD_DIR || null;
+  const envRemote = env.AI_MD_REMOTE || env.CURSOR_MD_REMOTE || null;
+
+  const dir = expandHome(
+    opts.dir || envDir || stored.dir || defaultDir
+  );
   const remote =
-    env.AI_MD_REMOTE ||
-    env.CURSOR_MD_REMOTE ||
-    "https://github.com/dujavi/.ai-md.git";
+    opts.remote || envRemote || stored.remote || DEFAULT_REMOTE;
+
+  const sources = {
+    dir: opts.dir
+      ? "flag"
+      : envDir && !(stored.dir && expandHome(envDir) === stored.dir)
+        ? "env"
+        : stored.dir
+          ? "config"
+          : "default",
+    remote: opts.remote
+      ? "flag"
+      : envRemote && !(stored.remote && envRemote === stored.remote)
+        ? "env"
+        : stored.remote
+          ? "config"
+          : "default",
+  };
+
+  const templatesDir = path.join(dir, "templates");
   return {
     home,
     dir,
     remote,
+    sources,
+    machineConfigPath: stored.path,
+    machineConfig: stored.raw,
     cursorSkills: path.join(home, ".cursor", "skills"),
     cursorRules: path.join(home, ".cursor", "rules"),
     projectsDir: path.join(dir, "projects"),
-    templateDir: path.join(dir, "projects", "template"),
+    templatesDir,
+    templateDir: path.join(templatesDir, "base"),
     skillsDir: path.join(dir, "skills"),
     rulesDir: path.join(dir, "rules"),
   };
 }
 
+function applyEnvFromConfig(cfg) {
+  process.env.AI_MD_DIR = cfg.dir;
+  process.env.AI_MD_REMOTE = cfg.remote;
+  process.env.CURSOR_MD_DIR = cfg.dir;
+  process.env.CURSOR_MD_REMOTE = cfg.remote;
+}
+
+function templatePath(cfg, name = "base") {
+  return path.join(cfg.templatesDir, name);
+}
+
+function listTemplates(cfg) {
+  if (!fs.existsSync(cfg.templatesDir)) return [];
+  return fs
+    .readdirSync(cfg.templatesDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !d.name.startsWith("."))
+    .map((d) => d.name)
+    .sort();
+}
+
 function countRules(rulesDir) {
   if (!fs.existsSync(rulesDir)) return 0;
   return fs
@@ -88,8 +201,29 @@ function agentSkillTargets(home, agents) {
     .map((name) => ({ name, path: map[name] }));
 }
 
+function migrateLegacyTemplate(cfg, { dryRun = false } = {}) {
+  const legacy = path.join(cfg.projectsDir, "template");
+  const dest = templatePath(cfg, "base");
+  if (!fs.existsSync(legacy) || fs.existsSync(dest)) {
+    return { action: "skip" };
+  }
+  if (dryRun) return { action: "would_migrate", from: legacy, to: dest };
+  fs.mkdirSync(cfg.templatesDir, { recursive: true });
+  fs.renameSync(legacy, dest);
+  return { action: "migrated", from: legacy, to: dest };
+}
+
 module.exports = {
+  DEFAULT_REMOTE,
+  machineConfigPath,
+  readMachineConfig,
+  writeMachineConfig,
   resolveConfig,
+  applyEnvFromConfig,
+  expandHome,
+  templatePath,
+  listTemplates,
+  migrateLegacyTemplate,
   countRules,
   countSkills,
   listSkillNames,

package/lib/status.js

@@ -5,6 +5,9 @@ const path = require("path");
 const { execFileSync } = require("child_process");
 const {
   resolveConfig,
+  templatePath,
+  listTemplates,
+  migrateLegacyTemplate,
   countRules,
   countSkills,
   listSkillNames,
@@ -19,17 +22,17 @@ function git(repo, args) {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
     }).trim();
-  } catch (err) {
+  } catch {
     return null;
   }
 }
 
-function templateDrift(projectDir, templateDir) {
-  if (!fs.existsSync(templateDir)) {
+function templateDrift(projectDir, tmplDir) {
+  if (!fs.existsSync(tmplDir)) {
     return { missingRules: [], missingSkills: [], extraRules: [], extraSkills: [] };
   }
-  const tRules = new Set(listRuleNames(path.join(templateDir, "rules")));
-  const tSkills = new Set(listSkillNames(path.join(templateDir, "skills")));
+  const tRules = new Set(listRuleNames(path.join(tmplDir, "rules")));
+  const tSkills = new Set(listSkillNames(path.join(tmplDir, "skills")));
   const pRules = new Set(listRuleNames(path.join(projectDir, "rules")));
   const pSkills = new Set(listSkillNames(path.join(projectDir, "skills")));
   return {
@@ -40,44 +43,38 @@ function templateDrift(projectDir, templateDir) {
   };
 }
 
-function collectProjects(cfg, { full = false } = {}) {
+function collectTemplates(cfg, { full = false } = {}) {
+  return listTemplates(cfg).map((name) => {
+    const dir = templatePath(cfg, name);
+    return {
+      name,
+      rules: countRules(path.join(dir, "rules")),
+      skills: countSkills(path.join(dir, "skills")),
+      ...(full ? { path: dir } : {}),
+    };
+  });
+}
+
+function collectProjects(cfg, { full = false, from = "base" } = {}) {
   const projects = [];
+  const tmplDir = templatePath(cfg, from);
   if (!fs.existsSync(cfg.projectsDir)) return projects;
   for (const name of fs.readdirSync(cfg.projectsDir).sort()) {
     if (name.startsWith(".")) continue;
+    // legacy leftover
+    if (name === "template") continue;
     const projectDir = path.join(cfg.projectsDir, name);
     if (!fs.statSync(projectDir).isDirectory()) continue;
-    if (name === "template") {
-      projects.push({
-        name,
-        kind: "template",
-        rules: countRules(path.join(projectDir, "rules")),
-        skills: countSkills(path.join(projectDir, "skills")),
-        missingRules: 0,
-        missingSkills: 0,
-        ...(full
-          ? {
-              path: projectDir,
-              drift: templateDrift(projectDir, cfg.templateDir),
-            }
-          : {}),
-      });
-      continue;
-    }
-    const drift = templateDrift(projectDir, cfg.templateDir);
+    const drift = templateDrift(projectDir, tmplDir);
     projects.push({
       name,
       kind: "project",
+      from,
       rules: countRules(path.join(projectDir, "rules")),
       skills: countSkills(path.join(projectDir, "skills")),
       missingRules: drift.missingRules.length,
       missingSkills: drift.missingSkills.length,
-      ...(full
-        ? {
-            path: projectDir,
-            drift,
-          }
-        : {}),
+      ...(full ? { path: projectDir, drift } : {}),
     });
   }
   return projects;
@@ -87,6 +84,9 @@ function collectStatus(opts = {}) {
   const cfg = resolveConfig();
   const full = Boolean(opts.full);
   const agents = opts.agents || ["cursor"];
+  const from = opts.from || "base";
+
+  const migration = migrateLegacyTemplate(cfg);
 
   const exists = fs.existsSync(cfg.dir);
   const isGit = exists && fs.existsSync(path.join(cfg.dir, ".git"));
@@ -103,9 +103,9 @@ function collectStatus(opts = {}) {
       ...symlinkState(t.path, cfg.skillsDir),
     }));
 
-  const projects = collectProjects(cfg, { full });
-  const linkedProjects = projects.filter((p) => p.kind === "project");
-  const drifting = linkedProjects.filter(
+  const templates = collectTemplates(cfg, { full });
+  const projects = collectProjects(cfg, { full, from });
+  const drifting = projects.filter(
     (p) => p.missingRules > 0 || p.missingSkills > 0
   );
 
@@ -127,18 +127,31 @@ function collectStatus(opts = {}) {
   for (const l of links) {
     if (l.state !== "ok") problems.push(`cursor_${path.basename(l.path)}_${l.state}`);
   }
+  if (!fs.existsSync(templatePath(cfg, "base")) && templates.length === 0) {
+    problems.push("templates_missing");
+  }
 
   return {
     generatedAt: new Date().toISOString(),
     dir: cfg.dir,
     remote: remote || cfg.remote,
+    sources: cfg.sources,
+    machineConfigPath: cfg.machineConfigPath,
+    machineConfig: cfg.machineConfig,
     branch,
     dirty,
     statusLine: aheadBehind,
+    layout: {
+      system: { rules: cfg.rulesDir, skills: cfg.skillsDir },
+      templates: cfg.templatesDir,
+      projects: cfg.projectsDir,
+    },
+    migration,
     counts: {
       rules: countRules(cfg.rulesDir),
       skills: countSkills(cfg.skillsDir),
-      projects: linkedProjects.length,
+      templates: templates.length,
+      projects: projects.length,
       drifting: drifting.length,
       problems: problems.length,
     },
@@ -153,18 +166,9 @@ function collectStatus(opts = {}) {
       state: l.state,
       ...(full ? { target: l.target, expected: l.expected } : {}),
     })),
-    projects: projects.map((p) =>
-      full
-        ? p
-        : {
-            name: p.name,
-            kind: p.kind,
-            rules: p.rules,
-            skills: p.skills,
-            missingRules: p.missingRules,
-            missingSkills: p.missingSkills,
-          }
-    ),
+    templates,
+    projects,
+    driftFrom: from,
     problems,
   };
 }
@@ -172,22 +176,32 @@ function collectStatus(opts = {}) {
 function statusHelp(data) {
   const help = [];
   if (data.problems.includes("ai_md_missing") || data.problems.includes("ai_md_not_git")) {
-    help.push("Run `ai-md install` to clone AI_MD_REMOTE → ~/.ai-md and link ~/.cursor/{skills,rules}");
+    help.push(
+      "Run `ai-md setup --remote <git-url>` (or `ai-md install --remote <git-url>`) to clone and link"
+    );
+  }
+  if (!data.machineConfig) {
+    help.push(
+      "Persist remote/dir with `ai-md setup --remote <url>` or `ai-md config set --remote <url> --dir ~/.ai-md`"
+    );
   }
   if (data.links.some((l) => l.state !== "ok")) {
     help.push("Run `ai-md doctor --fix` to repair ~/.cursor skills/rules symlinks");
   }
+  if (data.problems.includes("templates_missing")) {
+    help.push("Create ~/.ai-md/templates/base with project starters (system skills/rules stay in skills/ and rules/)");
+  }
   if (data.counts.drifting > 0) {
     help.push(
-      "Run `ai-md apply-template --project <name>` to merge missing baseline files from projects/template"
+      `Run \`ai-md apply-template --project <name> --from ${data.driftFrom || "base"}\` to merge missing template files`
     );
   }
   if (data.dirty) {
     help.push('Run `ai-md push -m "<why>"` to commit and push private config');
   } else {
-    help.push("Run `ai-md pull` before editing global skills/rules");
+    help.push("Edit system skills/rules under ~/.ai-md/{skills,rules}; project overlays under projects/");
   }
-  help.push("Run `ai-md init-project --repo <path>` to seed a project from template and link .cursor/");
+  help.push("Run `ai-md init-project --repo <path> --from base` to seed a project");
   help.push("Run `ai-md status --json` for machine-readable output");
   return help;
 }
@@ -195,6 +209,7 @@ function statusHelp(data) {
 module.exports = {
   collectStatus,
   collectProjects,
+  collectTemplates,
   templateDrift,
   statusHelp,
   git,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dujavi/ai-md",
-  "version": "0.2.0",
-  "description": "AXI-shaped CLI for private ~/.ai-md skills/rules, project templates, and agent tool bootstrap",
+  "version": "0.4.0",
+  "description": "AXI-shaped CLI for ~/.ai-md with persisted dir/remote machine config, templates/, and projects/",
   "bin": {
     "ai-md": "bin/ai-md.js"
   },