its-magic 0.1.2-13 → 0.1.2-15

package/README.md

@@ -69,17 +69,48 @@ its-magic --target . --mode overwrite --backup
 2. Run `/intake` with your idea
 3. Follow the workflow
 
+### CLI quick commands
+
+```bash
+# Show banner + help
+its-magic
+
+# Show version only
+its-magic --version
+
+# Install workflow files into current repo
+its-magic --target . --mode missing
+
+# Clean previously installed workflow artifacts
+its-magic --clean-repo --target .
+```
+
 ### Installer options
 
+**Install options**
+
+| Flag | Description |
+|------|-------------|
+| `--target <path>` | Path to the repository where workflow files are installed. If omitted you are prompted interactively. |
+| `--mode missing` | **Default.** Only copy files that do not exist yet. Safe for repos that already have some workflow files. |
+| `--mode overwrite` | Replace every file, even if it already exists. Combine with `--backup` to keep a snapshot first. |
+| `--mode interactive` | Ask per file whether to overwrite or skip. Useful when you want to cherry-pick updates. |
+| `--backup` | Before overwriting, save existing files to `backups/<timestamp>/`. Ignored in `missing` mode (nothing gets replaced). |
+| `--create` | Create the target directory if it does not exist. |
+
+**Clean options**
+
+| Flag | Description |
+|------|-------------|
+| `--clean-repo` | Remove all its-magic workflow artifacts from the target repo (`.cursor`, `docs/product`, `docs/engineering`, `sprints`, `handoffs`, `decisions`). Your own source code is never touched. |
+| `--yes` | Skip the confirmation prompt when cleaning. |
+
+**Info**
+
 | Flag | Description |
 |------|-------------|
-| `--target <path>` | Target repo path |
-| `--mode missing` | Copy only missing files |
-| `--mode overwrite` | Replace existing files |
-| `--mode interactive` | Prompt per file |
-| `--backup` | Save replaced files into `backups/<timestamp>/` |
-| `--create` | Create target directory |
-| `--help` | Show usage |
+| `--help`, `-h` | Show banner, version, repo URL, and full usage reference. |
+| `--version`, `-v` | Print the installed its-magic version and exit. |
 
 ## How-to
 

package/bin/its-magic.js

@@ -1,9 +1,52 @@
 #!/usr/bin/env node
 const path = require("path");
 const { spawnSync } = require("child_process");
+const packageJson = require("../package.json");
+
+const REPO_URL = "https://github.com/fl0wm0ti0n/its-magic";
+
+function printBanner() {
+  const M = "\x1b[1;35m";
+  const C = "\x1b[1;36m";
+  const Y = "\x1b[1;33m";
+  const R = "\x1b[0m";
+  console.log("");
+  console.log(`${M}  ██╗████████╗███████╗      ███╗   ███╗ █████╗  ██████╗ ██╗ ██████╗${R}`);
+  console.log(`${M}  ██║╚══██╔══╝██╔════╝      ████╗ ████║██╔══██╗██╔════╝ ██║██╔════╝${R}`);
+  console.log(`${M}  ██║   ██║   ███████╗█████╗██╔████╔██║███████║██║  ███╗██║██║     ${R}`);
+  console.log(`${C}  ██║   ██║   ╚════██║╚════╝██║╚██╔╝██║██╔══██║██║   ██║██║██║     ${R}`);
+  console.log(`${C}  ██║   ██║   ███████║      ██║ ╚═╝ ██║██║  ██║╚██████╔╝██║╚██████╗${R}`);
+  console.log(`${C}  ╚═╝   ╚═╝   ╚══════╝      ╚═╝     ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═╝ ╚═════╝${R}`);
+  console.log("");
+  console.log(`${Y}                         AI dev team${R}`);
+  console.log("");
+}
 
 function parseArgs(argv) {
-  const args = { target: process.cwd(), mode: "missing", backup: false, create: false };
+  const args = {
+    target: process.cwd(),
+    mode: "missing",
+    backup: false,
+    create: false,
+    cleanRepo: false,
+    yes: false,
+    help: false,
+    version: false,
+  };
+
+  if (argv.length === 0) {
+    args.help = true;
+    return args;
+  }
+
+  const first = argv[0];
+  if (first === "help") return { ...args, help: true };
+  if (first === "version") return { ...args, version: true };
+  if (first === "clean") {
+    args.cleanRepo = true;
+    argv = argv.slice(1);
+  }
+
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === "--target" && argv[i + 1]) {
@@ -24,24 +67,66 @@ function parseArgs(argv) {
       args.create = true;
       continue;
     }
+    if (a === "--clean-repo") {
+      args.cleanRepo = true;
+      continue;
+    }
+    if (a === "--yes") {
+      args.yes = true;
+      continue;
+    }
     if (a === "--help" || a === "-h") {
-      return { help: true };
+      args.help = true;
+      continue;
+    }
+    if (a === "--version" || a === "-v") {
+      args.version = true;
+      continue;
     }
   }
   return args;
 }
 
 function printHelp() {
-  console.log(`its-magic
+  printBanner();
+  console.log(`its-magic v${packageJson.version}
+Repository: ${REPO_URL}
+
+Install AI dev team workflow files into any Cursor repository.
 
 Usage:
-  npx its-magic --target <path> --mode missing [--backup] [--create]
+  its-magic --target <path> [--mode <mode>] [--backup] [--create]
+  its-magic --clean-repo [--target <path>] [--yes]
+  its-magic --help | --version
 
-Options:
-  --target   Target repository path (default: current directory)
-  --mode     missing | overwrite | interactive (default: missing)
-  --backup   Backup files before overwrite
-  --create   Create target directory if missing
+Install options:
+  --target <path>   Path to the repository where workflow files are installed.
+                    If omitted you will be prompted interactively.
+  --mode <mode>     How to handle files that already exist in the target:
+                      missing      Only copy files that do not exist yet (default).
+                                   Safe for repos that already have some workflow files.
+                      overwrite    Replace every file, even if it already exists.
+                                   Combine with --backup to keep a snapshot first.
+                      interactive  Ask per file whether to overwrite or skip.
+  --backup          Before overwriting, save existing files to backups/<timestamp>/.
+                    Ignored when mode is "missing" (nothing gets replaced).
+  --create          Create the target directory if it does not exist.
+
+Clean options:
+  --clean-repo      Remove all its-magic workflow artifacts from the target repo
+                    (.cursor, docs/product, docs/engineering, sprints, handoffs,
+                    decisions). Your own source code is never touched.
+  --target <path>   Repo to clean (default: current directory).
+  --yes             Skip the confirmation prompt.
+
+Info:
+  --help, -h        Show this help and exit.
+  --version, -v     Print the installed version and exit.
+
+Examples:
+  its-magic --target . --mode missing          Safe first-time setup
+  its-magic --target . --mode overwrite --backup  Update all files, keep backup
+  its-magic --clean-repo --target . --yes      Remove workflow artifacts silently
 `);
 }
 
@@ -50,6 +135,10 @@ if (args.help) {
   printHelp();
   process.exit(0);
 }
+if (args.version) {
+  console.log(`its-magic v${packageJson.version}`);
+  process.exit(0);
+}
 
 const root = path.resolve(__dirname, "..");
 const isWin = process.platform === "win32";
@@ -68,6 +157,8 @@ if (isWin) {
   ];
   if (args.backup) psArgs.push("-Backup");
   if (args.create) psArgs.push("-Create");
+  if (args.cleanRepo) psArgs.push("-CleanRepo");
+  if (args.yes) psArgs.push("-Yes");
   const res = spawnSync("powershell", psArgs, { stdio: "inherit" });
   process.exit(res.status || 0);
 } else {
@@ -81,6 +172,8 @@ if (isWin) {
   ];
   if (args.backup) shArgs.push("--backup");
   if (args.create) shArgs.push("--create");
+  if (args.cleanRepo) shArgs.push("--clean-repo");
+  if (args.yes) shArgs.push("--yes");
   const res = spawnSync("sh", shArgs, { stdio: "inherit" });
   process.exit(res.status || 0);
 }

package/installer.ps1

@@ -3,7 +3,11 @@ Param(
   [ValidateSet("missing","overwrite","interactive")]
   [string]$Mode,
   [switch]$Backup,
-  [switch]$Create
+  [switch]$Create,
+  [switch]$CleanRepo,
+  [switch]$Yes,
+  [switch]$Help,
+  [switch]$Version
 )
 
 $ErrorActionPreference = "Stop"
@@ -69,7 +73,128 @@ function Prompt-YesNo($Label, $Default = $false) {
   return @("y","yes") -contains $value
 }
 
+function Get-AppVersion($SourceRoot) {
+  try {
+    $pkgPath = Join-Path $SourceRoot "package.json"
+    if (Test-Path $pkgPath -PathType Leaf) {
+      $pkg = Get-Content -Path $pkgPath -Raw | ConvertFrom-Json
+      if ($pkg.version) { return [string]$pkg.version }
+    }
+  } catch {}
+  return "unknown"
+}
+
+function Show-ItsMagicBanner([switch]$IncludeInstallMessage) {
+  $prev = [Console]::OutputEncoding
+  [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+  $b64 = 'ICDilojilojilZfilojilojilojilojilojilojilojilojilZfilojilojilojilojilojilojilojilZcgICAgICDilojilojilojilZcgICDilojilojilojilZcg4paI4paI4paI4paI4paI4pWXICDilojilojilojilojilojilojilZcg4paI4paI4pWXIOKWiOKWiOKWiOKWiOKWiOKWiOKVlwogIOKWiOKWiOKVkeKVmuKVkOKVkOKWiOKWiOKVlOKVkOKVkOKVneKWiOKWiOKVlOKVkOKVkOKVkOKVkOKVnSAgICAgIOKWiOKWiOKWiOKWiOKVlyDilojilojilojilojilZHilojilojilZTilZDilZDilojilojilZfilojilojilZTilZDilZDilZDilZDilZ0g4paI4paI4pWR4paI4paI4pWU4pWQ4pWQ4pWQ4pWQ4pWdCiAg4paI4paI4pWRICAg4paI4paI4pWRICAg4paI4paI4paI4paI4paI4paI4paI4pWX4paI4paI4paI4paI4paI4pWX4paI4paI4pWU4paI4paI4paI4paI4pWU4paI4paI4pWR4paI4paI4paI4paI4paI4paI4paI4pWR4paI4paI4pWRICDilojilojilojilZfilojilojilZHilojilojilZEgICAgIAogIOKWiOKWiOKVkSAgIOKWiOKWiOKVkSAgIOKVmuKVkOKVkOKVkOKVkOKWiOKWiOKVkeKVmuKVkOKVkOKVkOKVkOKVneKWiOKWiOKVkeKVmuKWiOKWiOKVlOKVneKWiOKWiOKVkeKWiOKWiOKVlOKVkOKVkOKWiOKWiOKVkeKWiOKWiOKVkSAgIOKWiOKWiOKVkeKWiOKWiOKVkeKWiOKWiOKVkSAgICAgCiAg4paI4paI4pWRICAg4paI4paI4pWRICAg4paI4paI4paI4paI4paI4paI4paI4pWRICAgICAg4paI4paI4pWRIOKVmuKVkOKVnSDilojilojilZHilojilojilZEgIOKWiOKWiOKVkeKVmuKWiOKWiOKWiOKWiOKWiOKWiOKVlOKVneKWiOKWiOKVkeKVmuKWiOKWiOKWiOKWiOKWiOKWiOKVlwogIOKVmuKVkOKVnSAgIOKVmuKVkOKVnSAgIOKVmuKVkOKVkOKVkOKVkOKVkOKVkOKVnSAgICAgIOKVmuKVkOKVnSAgICAg4pWa4pWQ4pWd4pWa4pWQ4pWdICDilZrilZDilZ0g4pWa4pWQ4pWQ4pWQ4pWQ4pWQ4pWdIOKVmuKVkOKVnSDilZrilZDilZDilZDilZDilZDilZ0='
+  $art = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($b64))
+  $lines = $art -split "`n"
+  $colors = @('Magenta','Magenta','Magenta','Cyan','Cyan','Cyan')
+  Write-Host ""
+  for ($i = 0; $i -lt $lines.Count; $i++) {
+    Write-Host $lines[$i] -ForegroundColor $colors[$i]
+  }
+  Write-Host ""
+  Write-Host "                         AI dev team" -ForegroundColor Yellow
+  if ($IncludeInstallMessage) {
+    Write-Host "                    Installation complete!" -ForegroundColor Green
+  }
+  Write-Host ""
+  [Console]::OutputEncoding = $prev
+}
+
+function Show-ItsMagicHelp($VersionString, $RepoUrl) {
+  Show-ItsMagicBanner
+  Write-Host "its-magic v$VersionString"
+  Write-Host "Repository: $RepoUrl"
+  Write-Host ""
+  Write-Host "Install AI dev team workflow files into any Cursor repository."
+  Write-Host ""
+  Write-Host "Usage:"
+  Write-Host "  its-magic --target <path> [--mode <mode>] [--backup] [--create]"
+  Write-Host "  its-magic --clean-repo [--target <path>] [--yes]"
+  Write-Host "  its-magic --help | --version"
+  Write-Host ""
+  Write-Host "Install options:"
+  Write-Host "  --target <path>   Path to the repository where workflow files are installed."
+  Write-Host "                    If omitted you will be prompted interactively."
+  Write-Host "  --mode <mode>     How to handle files that already exist in the target:"
+  Write-Host "                      missing      Only copy files that do not exist yet (default)."
+  Write-Host "                                   Safe for repos that already have some workflow files."
+  Write-Host "                      overwrite    Replace every file, even if it already exists."
+  Write-Host "                                   Combine with --backup to keep a snapshot first."
+  Write-Host "                      interactive  Ask per file whether to overwrite or skip."
+  Write-Host "  --backup          Before overwriting, save existing files to backups/<timestamp>/."
+  Write-Host "                    Ignored when mode is 'missing' (nothing gets replaced)."
+  Write-Host "  --create          Create the target directory if it does not exist."
+  Write-Host ""
+  Write-Host "Clean options:"
+  Write-Host "  --clean-repo      Remove all its-magic workflow artifacts from the target repo"
+  Write-Host "                    (.cursor, docs/product, docs/engineering, sprints, handoffs,"
+  Write-Host "                    decisions). Your own source code is never touched."
+  Write-Host "  --target <path>   Repo to clean (default: current directory)."
+  Write-Host "  --yes             Skip the confirmation prompt."
+  Write-Host ""
+  Write-Host "Info:"
+  Write-Host "  --help            Show this help and exit."
+  Write-Host "  --version         Print the installed version and exit."
+  Write-Host ""
+  Write-Host "Examples:"
+  Write-Host "  its-magic --target . --mode missing            Safe first-time setup"
+  Write-Host "  its-magic --target . --mode overwrite --backup   Update all files, keep backup"
+  Write-Host "  its-magic --clean-repo --target . --yes        Remove workflow artifacts silently"
+  Write-Host ""
+}
+
 $sourceRoot = Normalize-PathSafe (Split-Path -Parent $MyInvocation.MyCommand.Path)
+$repoUrl = "https://github.com/fl0wm0ti0n/its-magic"
+$appVersion = Get-AppVersion $sourceRoot
+$noArgs = $PSBoundParameters.Count -eq 0
+
+if ($Version) {
+  Write-Host "its-magic v$appVersion"
+  exit 0
+}
+
+if ($Help -or $noArgs) {
+  Show-ItsMagicHelp -VersionString $appVersion -RepoUrl $repoUrl
+  exit 0
+}
+
+if ($CleanRepo) {
+  if (-not $Target) { $Target = "." }
+  $targetRoot = Normalize-PathSafe $Target
+  if (-not (Test-Path $targetRoot -PathType Container)) {
+    Write-Host "Target directory does not exist."
+    exit 1
+  }
+  if (-not $Yes) {
+    $proceed = Prompt-YesNo "Clean its-magic workflow artifacts in $targetRoot?" $false
+    if (-not $proceed) {
+      Write-Host "Aborted."
+      exit 1
+    }
+  }
+  $cleanPaths = @(
+    ".cursor",
+    "docs\product",
+    "docs\engineering",
+    "sprints",
+    "handoffs",
+    "decisions"
+  )
+  foreach ($rel in $cleanPaths) {
+    $fullPath = Join-Path $targetRoot $rel
+    if (Test-Path $fullPath) {
+      Remove-Item -Path $fullPath -Recurse -Force
+      Write-Host "Removed: $rel"
+    }
+  }
+  Write-Host "Clean completed."
+  exit 0
+}
+
 if (-not $Target) {
   $Target = Read-Host "Target repository path"
 }
@@ -165,24 +290,9 @@ foreach ($rel in $files) {
   }
 }
 
-function Show-ItsMagicBanner {
-    $prev = [Console]::OutputEncoding
-    [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
-    $b64 = 'ICDilojilojilZfilojilojilojilojilojilojilojilojilZfilojilojilojilojilojilojilojilZcgICAgICDilojilojilojilZcgICDilojilojilojilZcg4paI4paI4paI4paI4paI4pWXICDilojilojilojilojilojilojilZcg4paI4paI4pWXIOKWiOKWiOKWiOKWiOKWiOKWiOKVlwogIOKWiOKWiOKVkeKVmuKVkOKVkOKWiOKWiOKVlOKVkOKVkOKVneKWiOKWiOKVlOKVkOKVkOKVkOKVkOKVnSAgICAgIOKWiOKWiOKWiOKWiOKVlyDilojilojilojilojilZHilojilojilZTilZDilZDilojilojilZfilojilojilZTilZDilZDilZDilZDilZ0g4paI4paI4pWR4paI4paI4pWU4pWQ4pWQ4pWQ4pWQ4pWdCiAg4paI4paI4pWRICAg4paI4paI4pWRICAg4paI4paI4paI4paI4paI4paI4paI4pWX4paI4paI4paI4paI4paI4pWX4paI4paI4pWU4paI4paI4paI4paI4pWU4paI4paI4pWR4paI4paI4paI4paI4paI4paI4paI4pWR4paI4paI4pWRICDilojilojilojilZfilojilojilZHilojilojilZEgICAgIAogIOKWiOKWiOKVkSAgIOKWiOKWiOKVkSAgIOKVmuKVkOKVkOKVkOKVkOKWiOKWiOKVkeKVmuKVkOKVkOKVkOKVkOKVneKWiOKWiOKVkeKVmuKWiOKWiOKVlOKVneKWiOKWiOKVkeKWiOKWiOKVlOKVkOKVkOKWiOKWiOKVkeKWiOKWiOKVkSAgIOKWiOKWiOKVkeKWiOKWiOKVkeKWiOKWiOKVkSAgICAgCiAg4paI4paI4pWRICAg4paI4paI4pWRICAg4paI4paI4paI4paI4paI4paI4paI4pWRICAgICAg4paI4paI4pWRIOKVmuKVkOKVnSDilojilojilZHilojilojilZEgIOKWiOKWiOKVkeKVmuKWiOKWiOKWiOKWiOKWiOKWiOKVlOKVneKWiOKWiOKVkeKVmuKWiOKWiOKWiOKWiOKWiOKWiOKVlwogIOKVmuKVkOKVnSAgIOKVmuKVkOKVnSAgIOKVmuKVkOKVkOKVkOKVkOKVkOKVkOKVnSAgICAgIOKVmuKVkOKVnSAgICAg4pWa4pWQ4pWd4pWa4pWQ4pWdICDilZrilZDilZ0g4pWa4pWQ4pWQ4pWQ4pWQ4pWQ4pWdIOKVmuKVkOKVnSDilZrilZDilZDilZDilZDilZDilZ0='
-    $art = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($b64))
-    $lines = $art -split "`n"
-    $colors = @('Magenta','Magenta','Magenta','Cyan','Cyan','Cyan')
-    Write-Host ""
-    for ($i = 0; $i -lt $lines.Count; $i++) {
-        Write-Host $lines[$i] -ForegroundColor $colors[$i]
-    }
-    Write-Host ""
-    Write-Host "                         AI dev team" -ForegroundColor Yellow
-    Write-Host "                    Installation complete!" -ForegroundColor Green
-    Write-Host ""
-    [Console]::OutputEncoding = $prev
-}
-
-Show-ItsMagicBanner
+Show-ItsMagicBanner -IncludeInstallMessage
+Write-Host "its-magic v$appVersion"
+Write-Host "Repository: $repoUrl"
+Write-Host ""
 exit 0
 

package/installer.py

@@ -1,14 +1,26 @@
 import argparse
+import json
 import os
 import shutil
 import sys
 from datetime import datetime
 
+REPO_URL = "https://github.com/fl0wm0ti0n/its-magic"
+
 
 def normalize(path):
     return os.path.normpath(os.path.abspath(path))
 
 
+def read_version(source_root):
+    package_path = os.path.join(source_root, "package.json")
+    try:
+        with open(package_path, "r", encoding="utf-8") as f:
+            return json.load(f).get("version", "unknown")
+    except Exception:
+        return "unknown"
+
+
 def list_source_files(source_root, include_paths):
     files = []
     for rel in include_paths:
@@ -63,29 +75,130 @@ def prompt_yes_no(label, default=False):
     return value in ("y", "yes")
 
 
+def show_banner(include_install_message=False):
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+    m = "\033[1;35m"
+    c = "\033[1;36m"
+    y = "\033[1;33m"
+    g = "\033[1;32m"
+    r = "\033[0m"
+    print()
+    print(f"{m}  ██╗████████╗███████╗      ███╗   ███╗ █████╗  ██████╗ ██╗ ██████╗{r}")
+    print(f"{m}  ██║╚══██╔══╝██╔════╝      ████╗ ████║██╔══██╗██╔════╝ ██║██╔════╝{r}")
+    print(f"{m}  ██║   ██║   ███████╗█████╗██╔████╔██║███████║██║  ███╗██║██║     {r}")
+    print(f"{c}  ██║   ██║   ╚════██║╚════╝██║╚██╔╝██║██╔══██║██║   ██║██║██║     {r}")
+    print(f"{c}  ██║   ██║   ███████║      ██║ ╚═╝ ██║██║  ██║╚██████╔╝██║╚██████╗{r}")
+    print(f"{c}  ╚═╝   ╚═╝   ╚══════╝      ╚═╝     ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═╝ ╚═════╝{r}")
+    print()
+    print(f"{y}                         AI dev team{r}")
+    if include_install_message:
+        print(f"{g}                    Installation complete!{r}")
+    print()
+
+
+def show_help(version):
+    show_banner(include_install_message=False)
+    print(f"its-magic v{version}")
+    print(f"Repository: {REPO_URL}")
+    print()
+    print("Install AI dev team workflow files into any Cursor repository.")
+    print()
+    print("Usage:")
+    print("  its-magic --target <path> [--mode <mode>] [--backup] [--create]")
+    print("  its-magic --clean-repo [--target <path>] [--yes]")
+    print("  its-magic --help | --version")
+    print()
+    print("Install options:")
+    print("  --target <path>   Path to the repository where workflow files are installed.")
+    print("                    If omitted you will be prompted interactively.")
+    print("  --mode <mode>     How to handle files that already exist in the target:")
+    print("                      missing      Only copy files that do not exist yet (default).")
+    print("                                   Safe for repos that already have some workflow files.")
+    print("                      overwrite    Replace every file, even if it already exists.")
+    print("                                   Combine with --backup to keep a snapshot first.")
+    print("                      interactive  Ask per file whether to overwrite or skip.")
+    print("  --backup          Before overwriting, save existing files to backups/<timestamp>/.")
+    print("                    Ignored when mode is 'missing' (nothing gets replaced).")
+    print("  --create          Create the target directory if it does not exist.")
+    print()
+    print("Clean options:")
+    print("  --clean-repo      Remove all its-magic workflow artifacts from the target repo")
+    print("                    (.cursor, docs/product, docs/engineering, sprints, handoffs,")
+    print("                    decisions). Your own source code is never touched.")
+    print("  --target <path>   Repo to clean (default: current directory).")
+    print("  --yes             Skip the confirmation prompt.")
+    print()
+    print("Info:")
+    print("  --help, -h        Show this help and exit.")
+    print("  --version, -v     Print the installed version and exit.")
+    print()
+    print("Examples:")
+    print("  its-magic --target . --mode missing            Safe first-time setup")
+    print("  its-magic --target . --mode overwrite --backup   Update all files, keep backup")
+    print("  its-magic --clean-repo --target . --yes        Remove workflow artifacts silently")
+    print()
+
+
+def clean_repo(target_root):
+    clean_paths = [
+        ".cursor",
+        os.path.join("docs", "product"),
+        os.path.join("docs", "engineering"),
+        "sprints",
+        "handoffs",
+        "decisions",
+    ]
+    for rel in clean_paths:
+        full = os.path.join(target_root, rel)
+        if os.path.exists(full):
+            shutil.rmtree(full)
+            print(f"Removed: {rel}")
+    print("Clean completed.")
+
+
 def main():
-    parser = argparse.ArgumentParser(description="Install its-magic into a repo")
-    parser.add_argument("--target", help="Target repository path")
-    parser.add_argument(
-        "--mode",
-        choices=["missing", "overwrite", "interactive"],
-        help="Install mode",
-    )
-    parser.add_argument(
-        "--backup",
-        action="store_true",
-        help="Backup files before overwriting",
-    )
-    parser.add_argument(
-        "--create",
-        action="store_true",
-        help="Create target directory if missing",
+    source_root = normalize(os.path.dirname(__file__))
+    version = read_version(source_root)
+
+    parser = argparse.ArgumentParser(
+        description="Install its-magic into a repo",
+        add_help=False,
     )
+    parser.add_argument("--target", help="Target repository path")
+    parser.add_argument("--mode", choices=["missing", "overwrite", "interactive"], help="Install mode")
+    parser.add_argument("--backup", action="store_true", help="Backup files before overwriting")
+    parser.add_argument("--create", action="store_true", help="Create target directory if missing")
+    parser.add_argument("--clean-repo", action="store_true", help="Remove installed workflow artifacts")
+    parser.add_argument("--yes", action="store_true", help="Skip clean confirmation prompt")
+    parser.add_argument("--help", "-h", action="store_true", help="Show help")
+    parser.add_argument("--version", "-v", action="store_true", help="Show version")
     args = parser.parse_args()
 
-    source_root = normalize(os.path.dirname(__file__))
+    if len(sys.argv) == 1 or args.help:
+        show_help(version)
+        return 0
+
+    if args.version:
+        print(f"its-magic v{version}")
+        return 0
+
     target_root = normalize(args.target) if args.target else None
 
+    if args.clean_repo:
+        if not target_root:
+            target_root = normalize(".")
+        if not os.path.isdir(target_root):
+            print("Target directory does not exist.")
+            return 1
+        if not args.yes and not prompt_yes_no(f"Clean its-magic workflow artifacts in {target_root}?", default=False):
+            print("Aborted.")
+            return 1
+        clean_repo(target_root)
+        return 0
+
     if not target_root:
         target_root = normalize(input("Target repository path: ").strip())
 
@@ -164,30 +277,12 @@ def main():
                     print(f"Backed up: {rel} -> {backup_root}")
                 ensure_parent(dst)
                 shutil.copy2(src, dst)
-            else:
-                continue
-
-    show_banner()
-    return 0
-
 
-def show_banner():
-    M = "\033[1;35m"
-    C = "\033[1;36m"
-    Y = "\033[1;33m"
-    G = "\033[1;32m"
-    R = "\033[0m"
-    print()
-    print(f"{M}  ██╗████████╗███████╗      ███╗   ███╗ █████╗  ██████╗ ██╗ ██████╗{R}")
-    print(f"{M}  ██║╚══██╔══╝██╔════╝      ████╗ ████║██╔══██╗██╔════╝ ██║██╔════╝{R}")
-    print(f"{M}  ██║   ██║   ███████╗█████╗██╔████╔██║███████║██║  ███╗██║██║     {R}")
-    print(f"{C}  ██║   ██║   ╚════██║╚════╝██║╚██╔╝██║██╔══██║██║   ██║██║██║     {R}")
-    print(f"{C}  ██║   ██║   ███████║      ██║ ╚═╝ ██║██║  ██║╚██████╔╝██║╚██████╗{R}")
-    print(f"{C}  ╚═╝   ╚═╝   ╚══════╝      ╚═╝     ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═╝ ╚═════╝{R}")
-    print()
-    print(f"{Y}                         AI dev team{R}")
-    print(f"{G}                    Installation complete!{R}")
+    show_banner(include_install_message=True)
+    print(f"its-magic v{version}")
+    print(f"Repository: {REPO_URL}")
     print()
+    return 0
 
 
 if __name__ == "__main__":

package/installer.sh

@@ -1,6 +1,59 @@
 #!/usr/bin/env sh
 set -e
 
+SOURCE_ROOT=$(cd "$(dirname "$0")" && pwd)
+REPO_URL="https://github.com/fl0wm0ti0n/its-magic"
+APP_VERSION=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$SOURCE_ROOT/package.json" | head -n 1)
+[ -z "$APP_VERSION" ] && APP_VERSION="unknown"
+
+show_banner() {
+  printf "\n"
+  printf "\033[1;35m  ██╗████████╗███████╗      ███╗   ███╗ █████╗  ██████╗ ██╗ ██████╗\033[0m\n"
+  printf "\033[1;35m  ██║╚══██╔══╝██╔════╝      ████╗ ████║██╔══██╗██╔════╝ ██║██╔════╝\033[0m\n"
+  printf "\033[1;35m  ██║   ██║   ███████╗█████╗██╔████╔██║███████║██║  ███╗██║██║     \033[0m\n"
+  printf "\033[1;36m  ██║   ██║   ╚════██║╚════╝██║╚██╔╝██║██╔══██║██║   ██║██║██║     \033[0m\n"
+  printf "\033[1;36m  ██║   ██║   ███████║      ██║ ╚═╝ ██║██║  ██║╚██████╔╝██║╚██████╗\033[0m\n"
+  printf "\033[1;36m  ╚═╝   ╚═╝   ╚══════╝      ╚═╝     ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═╝ ╚═════╝\033[0m\n"
+  printf "\n"
+  printf "\033[1;33m                         AI dev team\033[0m\n"
+  printf "\n"
+}
+
+show_help() {
+  show_banner
+  printf "its-magic v%s\n" "$APP_VERSION"
+  printf "Repository: %s\n\n" "$REPO_URL"
+  printf "Install AI dev team workflow files into any Cursor repository.\n\n"
+  printf "Usage:\n"
+  printf "  its-magic --target <path> [--mode <mode>] [--backup] [--create]\n"
+  printf "  its-magic --clean-repo [--target <path>] [--yes]\n"
+  printf "  its-magic --help | --version\n\n"
+  printf "Install options:\n"
+  printf "  --target <path>   Path to the repository where workflow files are installed.\n"
+  printf "                    If omitted you will be prompted interactively.\n"
+  printf "  --mode <mode>     How to handle files that already exist in the target:\n"
+  printf "                      missing      Only copy files that do not exist yet (default).\n"
+  printf "                                   Safe for repos that already have some workflow files.\n"
+  printf "                      overwrite    Replace every file, even if it already exists.\n"
+  printf "                                   Combine with --backup to keep a snapshot first.\n"
+  printf "                      interactive  Ask per file whether to overwrite or skip.\n"
+  printf "  --backup          Before overwriting, save existing files to backups/<timestamp>/.\n"
+  printf "                    Ignored when mode is 'missing' (nothing gets replaced).\n"
+  printf "  --create          Create the target directory if it does not exist.\n\n"
+  printf "Clean options:\n"
+  printf "  --clean-repo      Remove all its-magic workflow artifacts from the target repo\n"
+  printf "                    (.cursor, docs/product, docs/engineering, sprints, handoffs,\n"
+  printf "                    decisions). Your own source code is never touched.\n"
+  printf "  --target <path>   Repo to clean (default: current directory).\n"
+  printf "  --yes             Skip the confirmation prompt.\n\n"
+  printf "Info:\n"
+  printf "  --help, -h        Show this help and exit.\n"
+  printf "  --version, -v     Print the installed version and exit.\n\n"
+  printf "Examples:\n"
+  printf "  its-magic --target . --mode missing            Safe first-time setup\n"
+  printf "  its-magic --target . --mode overwrite --backup   Update all files, keep backup\n"
+  printf "  its-magic --clean-repo --target . --yes        Remove workflow artifacts silently\n\n"
+}
 
 ensure_parent() {
   dir=$(dirname "$1")
@@ -68,6 +121,14 @@ TARGET=""
 MODE=""
 BACKUP="false"
 CREATE="false"
+CLEAN_REPO="false"
+ASSUME_YES="false"
+SHOW_HELP="false"
+SHOW_VERSION="false"
+
+if [ $# -eq 0 ]; then
+  SHOW_HELP="true"
+fi
 
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -75,11 +136,57 @@ while [ $# -gt 0 ]; do
     --mode) MODE="$2"; shift 2 ;;
     --backup) BACKUP="true"; shift 1 ;;
     --create) CREATE="true"; shift 1 ;;
+    --clean-repo) CLEAN_REPO="true"; shift 1 ;;
+    --yes) ASSUME_YES="true"; shift 1 ;;
+    --help|-h) SHOW_HELP="true"; shift 1 ;;
+    --version|-v) SHOW_VERSION="true"; shift 1 ;;
     *) shift 1 ;;
   esac
 done
 
-SOURCE_ROOT=$(cd "$(dirname "$0")" && pwd)
+if [ "$SHOW_VERSION" = "true" ]; then
+  printf "its-magic v%s\n" "$APP_VERSION"
+  exit 0
+fi
+
+if [ "$SHOW_HELP" = "true" ]; then
+  show_help
+  exit 0
+fi
+
+if [ "$CLEAN_REPO" = "true" ]; then
+  if [ -z "$TARGET" ]; then
+    TARGET="."
+  fi
+  if [ ! -d "$TARGET" ]; then
+    printf "%s\n" "Target directory does not exist."
+    exit 1
+  fi
+  TARGET_ROOT=$(cd "$TARGET" && pwd)
+  if [ "$ASSUME_YES" != "true" ]; then
+    if ! prompt_yes_no "Clean its-magic workflow artifacts in $TARGET_ROOT?" "false"; then
+      printf "%s\n" "Aborted."
+      exit 1
+    fi
+  fi
+  CLEAN_PATHS="
+.cursor
+docs/product
+docs/engineering
+sprints
+handoffs
+decisions
+"
+  for rel in $CLEAN_PATHS; do
+    path="$TARGET_ROOT/$rel"
+    if [ -e "$path" ]; then
+      rm -rf "$path"
+      printf "%s\n" "Removed: $rel"
+    fi
+  done
+  printf "%s\n" "Clean completed."
+  exit 0
+fi
 
 if [ -z "$TARGET" ]; then
   printf "%s" "Target repository path: "
@@ -180,20 +287,9 @@ for rel in $FILES; do
   fi
 done
 
-show_banner() {
-    printf "\n"
-    printf "\033[1;35m  ██╗████████╗███████╗      ███╗   ███╗ █████╗  ██████╗ ██╗ ██████╗\033[0m\n"
-    printf "\033[1;35m  ██║╚══██╔══╝██╔════╝      ████╗ ████║██╔══██╗██╔════╝ ██║██╔════╝\033[0m\n"
-    printf "\033[1;35m  ██║   ██║   ███████╗█████╗██╔████╔██║███████║██║  ███╗██║██║     \033[0m\n"
-    printf "\033[1;36m  ██║   ██║   ╚════██║╚════╝██║╚██╔╝██║██╔══██║██║   ██║██║██║     \033[0m\n"
-    printf "\033[1;36m  ██║   ██║   ███████║      ██║ ╚═╝ ██║██║  ██║╚██████╔╝██║╚██████╗\033[0m\n"
-    printf "\033[1;36m  ╚═╝   ╚═╝   ╚══════╝      ╚═╝     ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═╝ ╚═════╝\033[0m\n"
-    printf "\n"
-    printf "\033[1;33m                         AI dev team\033[0m\n"
-    printf "\033[1;32m                    Installation complete!\033[0m\n"
-    printf "\n"
-}
-
 show_banner
+printf "its-magic v%s\n" "$APP_VERSION"
+printf "Repository: %s\n\n" "$REPO_URL"
+printf "\033[1;32m                    Installation complete!\033[0m\n\n"
 exit 0
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "its-magic",
-  "version": "0.1.2-13",
+  "version": "0.1.2-15",
   "description": "its-magic - AI dev team workflow for Cursor.",
   "license": "MIT",
   "bin": {