@dujavi/ai-md 0.2.0 → 0.3.0

package/README.md

@@ -1,69 +1,49 @@
 # 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
 
 ```bash
 npm i -g @dujavi/ai-md
-# binary: ai-md
 ```
 
-## New machine
-
-```bash
-export AI_MD_REMOTE=https://github.com/<you>/.ai-md.git
-ai-md install
-ai-md ensure-tools
-```
-
-Optional multi-agent skill links:
-
-```bash
-ai-md install --agents cursor,claude,agents
+## Layout idea
+
+```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/
 ```
 
-## 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
-```
+Put shared agentic skills/rules in **system** folders. Put only type-specific or per-project starters under **templates/**.
 
-## Projects (templating)
+## Commands
 
 ```bash
-# Seed from projects/template + link repo/.cursor + gitignore
-ai-md init-project --repo ~/my-app
-
-# 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
+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_REMOTE` → private content git URL

package/bin/ai-md.js

@@ -35,7 +35,7 @@ function parseArgs(argv) {
     repo: null,
     name: null,
     project: null,
-    from: "template",
+    from: "base",
     agents: ["cursor"],
     rest: [],
   };
@@ -117,20 +117,25 @@ 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)
+
 Commands:
   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
 
@@ -141,23 +146,18 @@ Options:
   --repo <path>      App repository root
   --name <id>        Project id under projects/ (default: basename)
   --project <id>     Target project for apply-template
-  --from <id>        Template folder (default: template)
+  --from <id>        Template under templates/ (default: base)
   --force            Replace non-symlink .cursor / re-merge
   --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 init-project --repo ~/presenter --from base
+  ai-md apply-template --project presenter --from base
   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"
 `);
 }
 
@@ -184,7 +184,11 @@ function main() {
   try {
     switch (opts.cmd) {
       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 +229,7 @@ function main() {
       case "apply-template": {
         const data = applyTemplate({
           project: opts.project || opts.name,
+          from: opts.from,
           dryRun: opts.dryRun,
         });
         emit({

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

@@ -12,6 +12,7 @@ function resolveConfig(env = process.env) {
     env.AI_MD_REMOTE ||
     env.CURSOR_MD_REMOTE ||
     "https://github.com/dujavi/.ai-md.git";
+  const templatesDir = path.join(dir, "templates");
   return {
     home,
     dir,
@@ -19,12 +20,27 @@ function resolveConfig(env = process.env) {
     cursorSkills: path.join(home, ".cursor", "skills"),
     cursorRules: path.join(home, ".cursor", "rules"),
     projectsDir: path.join(dir, "projects"),
-    templateDir: path.join(dir, "projects", "template"),
+    templatesDir,
+    /** @deprecated use templatePath(cfg, name) */
+    templateDir: path.join(templatesDir, "base"),
     skillsDir: path.join(dir, "skills"),
     rulesDir: path.join(dir, "rules"),
   };
 }
 
+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 +104,24 @@ function agentSkillTargets(home, agents) {
     .map((name) => ({ name, path: map[name] }));
 }
 
+/** One-time: projects/template → templates/base */
+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 = {
   resolveConfig,
+  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,6 +127,9 @@ 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(),
@@ -135,10 +138,17 @@ function collectStatus(opts = {}) {
     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 +163,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,
   };
 }
@@ -177,17 +178,20 @@ function statusHelp(data) {
   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 +199,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.3.0",
+  "description": "AXI-shaped CLI for ~/.ai-md system skills/rules, templates/, and projects/",
   "bin": {
     "ai-md": "bin/ai-md.js"
   },