@rootnative/cli 0.0.0-alpha.4 → 0.0.0-alpha.5

package/README.md

@@ -69,8 +69,11 @@ This will:
 2. Detect your package manager (npm, yarn, pnpm, bun)
 3. Detect path aliases from your `tsconfig.json`
 4. Prompt for component and utility output directories
-5. Install `@rootnative/core`
-6. Create an `rootnative.json` config file
+5. Create an `rootnative.json` config file
+6. Offer to add the LLM-docs pointer to your project's `CLAUDE.md`
+7. Offer to install `@rootnative/core`
+
+Steps 6 and 7 are confirmation prompts; `-y` accepts both.
 
 Options:
 
@@ -98,7 +101,7 @@ Add one or more components to your project.
 ```bash
 npx rootnative add button
 npx rootnative add card chip text-field
-npx rootnative add appbar  # auto-adds icon-button + typography dependencies
+npx rootnative add appbar  # auto-adds button + icon-button + typography dependencies
 ```
 
 Options:
@@ -111,7 +114,7 @@ Options:
 
 The `add` command:
 
-1. Resolves the full dependency graph (e.g. `appbar` requires `icon-button` and `typography`)
+1. Resolves the full dependency graph (e.g. `appbar` requires `button`, `icon-button` and `typography`)
 2. Shows a plan of components, utilities, and npm packages to install
 3. Copies component files with import paths rewritten to match your project
 4. Generates a utility barrel file (`rootnative-utils.ts`)
@@ -161,6 +164,8 @@ The `upgrade` command:
 5. Upgrades `@rootnative/core` and installs any new required peer dependencies
 6. Reports optional peer deps that aren't installed (does not auto-install them)
 7. Lists peer deps that are no longer required so you can remove them manually
+8. Moves `registryVersion` in `rootnative.json` forward to the new release tag, so subsequent `add`/`update` calls fetch matching sources
+9. With `-a, --all`, also updates the installed component files
 
 Non-interactive mode for CI/automation:
 
@@ -190,7 +195,8 @@ Checks include:
 - `@rootnative/core` is installed
 - React Native version compatibility
 - Installed component file integrity
-- Peer dependencies (`react-native-safe-area-context`, `@expo/vector-icons`)
+- `@rootnative/inertia` — a hard failure when missing, since every animated component needs it
+- Optional peer dependencies (`react-native-safe-area-context`, `@expo/vector-icons`) — reported as warnings
 
 ## Configuration
 
@@ -204,7 +210,7 @@ Checks include:
     "lib": "@/lib"
   },
   "registryUrl": "https://raw.githubusercontent.com/rootnative/ui",
-  "registryVersion": "main"
+  "registryVersion": "v0.0.0-alpha.4"
 }
 ```
 
@@ -213,7 +219,7 @@ Checks include:
 | `aliases.components` | Where component directories are created |
 | `aliases.lib` | Where utility files are placed |
 | `registryUrl` | Base URL for fetching component source files |
-| `registryVersion` | Git ref to fetch from (branch, tag, or commit) |
+| `registryVersion` | Git ref to fetch from (branch, tag, or commit). `init` pins this to the `v<version>` tag of the latest published release, falling back to `main` only when npm is unreachable or the tag isn't pushed yet. `upgrade` moves the pin forward |
 
 ## Output structure
 
@@ -228,28 +234,41 @@ src/
         types.ts
         styles.ts
         index.ts
+        elevationShadow.ts  # shared internal, flattened per component
+        usePressMorph.ts
+        useStateLayer.ts
       icon-button/          # auto-added (appbar dependency)
         IconButton.tsx
         types.ts
         styles.ts
         index.ts
+        useBooleanProgress.ts
+        usePressMorph.ts
+        useStateLayer.ts
       typography/           # auto-added (appbar dependency)
         Typography.tsx
         types.ts
+        styles.ts
         index.ts
       appbar/
         AppBar.tsx
         types.ts
         styles.ts
         index.ts
+        safe-area.tsx
   lib/
     color.ts
     elevation.ts
-    icon.ts
+    pressable.ts
+    render-icon.tsx
     rtl.ts
     rootnative-utils.ts    # generated barrel
 ```
 
+Shared internal hooks (`useStateLayer`, `usePressMorph`, …) are copied into
+*each* component directory that uses them rather than into a shared folder, so
+each installed component stays self-contained.
+
 ## Available components
 
 | Component | Description |
@@ -271,7 +290,16 @@ src/
 | `text-field` | Text input with animated floating label, 2 variants (filled, outlined) |
 | `layout` | Layout primitives: Box, Row, Column, Grid, and SafeAreaView wrapper |
 | `list` | List container with interactive items and dividers |
+| `divider` | Horizontal or vertical 1dp rule with optional leading/trailing insets and thickness/color overrides. |
+| `loading-indicator` | MD3 Expressive shape-morphing loading spinner (contained + uncontained, determinate + indeterminate) |
 | `portal` | Render children into a host elsewhere in the tree (overlays, dialogs, sheets) |
+| `dialog` | Basic and full-screen modal dialogs with Icon / Title / Content / Actions slots, scrim, and Android back handling. |
+| `snackbar` | Imperative snackbar queue — SnackbarProvider plus useSnackbar() with actions, durations, and safe-area aware placement. |
+| `menu` | Anchored dropdown menu (Menu + Menu.Item) that flips and shifts to stay on screen, with self-managing or controlled visibility. |
+| `tooltip` | Plain and rich tooltips anchored to a control, shown on hover or a long press |
+| `bottom-sheet` | MD3 bottom sheet — modal (scrim) and standard variants, drag handle, velocity-based snap points, drag-to-dismiss. |
+| `tabs` | Primary and secondary tab rows, fixed or scrollable, with a sliding active indicator |
+| `navigation-bar` | MD3 navigation bar — 80dp bottom destination bar with an animated indicator pill |
 | `keyboard-avoiding-wrapper` | Zero-config keyboard-aware wrapper for form layouts |
 
 ## Import rewriting

package/dist/index.mjs

@@ -45,15 +45,96 @@ function resolveAliasPath(alias, cwd) {
 }
 
 // src/lib/detector.ts
+import path3 from "path";
+import fs3 from "fs-extra";
+
+// src/lib/tsconfig-paths.ts
 import path2 from "path";
 import fs2 from "fs-extra";
+function stripJsonComments(raw) {
+  let out = "";
+  let inString = false;
+  let escaped = false;
+  for (let i = 0; i < raw.length; i++) {
+    const char = raw[i];
+    if (inString) {
+      out += char;
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      out += char;
+      continue;
+    }
+    if (char === "/" && raw[i + 1] === "*") {
+      const end = raw.indexOf("*/", i + 2);
+      i = end === -1 ? raw.length : end + 1;
+      continue;
+    }
+    if (char === "/" && raw[i + 1] === "/") {
+      while (i < raw.length && raw[i] !== "\n") i++;
+      out += "\n";
+      continue;
+    }
+    out += char;
+  }
+  return out;
+}
+function parseAliasPrefix(alias) {
+  const match = /^([^./\\][^/\\]*)\//.exec(alias);
+  if (!match) return null;
+  return { prefix: match[1], target: "src" };
+}
+async function ensureTsconfigPaths(cwd, alias) {
+  const parsed = parseAliasPrefix(alias);
+  if (!parsed) return { status: "not-an-alias" };
+  const { prefix, target } = parsed;
+  const tsconfigPath = path2.resolve(cwd, "tsconfig.json");
+  if (!await fs2.pathExists(tsconfigPath)) {
+    return { status: "no-tsconfig" };
+  }
+  try {
+    const raw = await fs2.readFile(tsconfigPath, "utf-8");
+    const tsconfig = JSON.parse(stripJsonComments(raw));
+    const key = `${prefix}/*`;
+    const existing = tsconfig.compilerOptions?.paths;
+    if (existing && key in existing) {
+      return { status: "already-mapped", prefix };
+    }
+    const compilerOptions = tsconfig.compilerOptions ?? {};
+    tsconfig.compilerOptions = {
+      ...compilerOptions,
+      baseUrl: compilerOptions.baseUrl ?? ".",
+      paths: {
+        ...existing,
+        [key]: [`./${target}/*`]
+      }
+    };
+    await fs2.writeJSON(tsconfigPath, tsconfig, { spaces: 2 });
+    return { status: "added", prefix, target };
+  } catch (error) {
+    return {
+      status: "failed",
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+// src/lib/detector.ts
 async function detectProjectType(cwd) {
-  const pkgPath = path2.resolve(cwd, "package.json");
-  const hasPackageJson = await fs2.pathExists(pkgPath);
+  const pkgPath = path3.resolve(cwd, "package.json");
+  const hasPackageJson = await fs3.pathExists(pkgPath);
   if (!hasPackageJson) {
     return "unknown";
   }
-  const pkg = await fs2.readJSON(pkgPath);
+  const pkg = await fs3.readJSON(pkgPath);
   const allDeps = {
     ...pkg.dependencies,
     ...pkg.devDependencies
@@ -75,37 +156,33 @@ async function detectPackageManager(cwd) {
     ["package-lock.json", "npm"]
   ];
   for (const [file, manager] of lockFiles) {
-    if (await fs2.pathExists(path2.resolve(cwd, file))) {
+    if (await fs3.pathExists(path3.resolve(cwd, file))) {
       return manager;
     }
   }
   return "npm";
 }
 async function detectTypeScript(cwd) {
-  return fs2.pathExists(path2.resolve(cwd, "tsconfig.json"));
+  return fs3.pathExists(path3.resolve(cwd, "tsconfig.json"));
 }
 async function detectSrcDir(cwd) {
   const candidates = ["src", "app"];
   for (const dir of candidates) {
-    const dirPath = path2.resolve(cwd, dir);
-    if (await fs2.pathExists(dirPath)) {
+    const dirPath = path3.resolve(cwd, dir);
+    if (await fs3.pathExists(dirPath)) {
       return dir;
     }
   }
   return null;
 }
 async function detectAliases(cwd) {
-  const tsconfigPath = path2.resolve(cwd, "tsconfig.json");
-  if (!await fs2.pathExists(tsconfigPath)) {
+  const tsconfigPath = path3.resolve(cwd, "tsconfig.json");
+  if (!await fs3.pathExists(tsconfigPath)) {
     return null;
   }
   try {
-    const raw = await fs2.readFile(tsconfigPath, "utf-8");
-    const stripped = raw.replace(
-      /\/\*[\s\S]*?\*\/|\/\/.*/g,
-      ""
-    );
-    const tsconfig = JSON.parse(stripped);
+    const raw = await fs3.readFile(tsconfigPath, "utf-8");
+    const tsconfig = JSON.parse(stripJsonComments(raw));
     const paths = tsconfig.compilerOptions?.paths;
     if (!paths) {
       return null;
@@ -147,9 +224,9 @@ function getInstallCommand(pm, packages) {
 }
 
 // src/lib/installer.ts
-import path3 from "path";
+import path4 from "path";
 import { execa } from "execa";
-import fs3 from "fs-extra";
+import fs4 from "fs-extra";
 
 // src/lib/logger.ts
 import chalk from "chalk";
@@ -333,8 +410,8 @@ async function installComponents(options) {
   await generateBarrel(resolution, utilsRegistry, libDir);
   spinner.succeed("Utility files copied");
   for (const { entry } of resolution.components) {
-    const componentDir = path3.join(componentsDir, entry.name);
-    const exists = await fs3.pathExists(componentDir);
+    const componentDir = path4.join(componentsDir, entry.name);
+    const exists = await fs4.pathExists(componentDir);
     if (exists && !force) {
       logger.warn(
         `${entry.name} already exists, skipping (use --force to overwrite)`
@@ -343,17 +420,17 @@ async function installComponents(options) {
     }
     const compSpinner = createSpinner(`Adding ${entry.name}...`);
     compSpinner.start();
-    await fs3.ensureDir(componentDir);
+    await fs4.ensureDir(componentDir);
     for (const filePath of entry.files) {
       const content = await fetchFileContent(config, filePath);
-      const fileName = path3.basename(filePath);
+      const fileName = path4.basename(filePath);
       const transformed = transformImports(content, {
         config,
         componentName: entry.name,
         installedComponents: allComponentNames
       });
-      await fs3.writeFile(
-        path3.join(componentDir, fileName),
+      await fs4.writeFile(
+        path4.join(componentDir, fileName),
         transformed,
         "utf-8"
       );
@@ -379,13 +456,13 @@ async function installComponents(options) {
   }
 }
 async function copyUtilFiles(config, resolution, utilsRegistry, libDir) {
-  await fs3.ensureDir(libDir);
+  await fs4.ensureDir(libDir);
   for (const utilName of resolution.utils) {
     const utilEntry = utilsRegistry[utilName];
     if (!utilEntry) continue;
     const content = await fetchFileContent(config, utilEntry.file);
-    const fileName = path3.basename(utilEntry.file);
-    await fs3.writeFile(path3.join(libDir, fileName), content, "utf-8");
+    const fileName = path4.basename(utilEntry.file);
+    await fs4.writeFile(path4.join(libDir, fileName), content, "utf-8");
   }
 }
 async function generateBarrel(resolution, utilsRegistry, libDir) {
@@ -405,18 +482,18 @@ async function generateBarrel(resolution, utilsRegistry, libDir) {
     utilExports,
     utilTypeExports
   );
-  await fs3.writeFile(
-    path3.join(libDir, "rootnative-utils.ts"),
+  await fs4.writeFile(
+    path4.join(libDir, "rootnative-utils.ts"),
     barrelContent,
     "utf-8"
   );
 }
 function collectDepsToInstall(resolution, cwd) {
   const deps = [];
-  const pkgPath = path3.resolve(cwd, "package.json");
+  const pkgPath = path4.resolve(cwd, "package.json");
   let existingDeps = {};
   try {
-    const pkg = fs3.readJSONSync(pkgPath);
+    const pkg = fs4.readJSONSync(pkgPath);
     existingDeps = {
       ...pkg.dependencies,
       ...pkg.devDependencies
@@ -483,15 +560,17 @@ async function addCommand(componentNames, cwd, options) {
     logger.info("Dry run complete. No files were written.");
     return;
   }
-  const { proceed } = await prompts({
-    type: "confirm",
-    name: "proceed",
-    message: "Proceed with installation?",
-    initial: true
-  });
-  if (!proceed) {
-    logger.info("Cancelled.");
-    return;
+  if (!options.yes) {
+    const { proceed } = await prompts({
+      type: "confirm",
+      name: "proceed",
+      message: "Proceed with installation?",
+      initial: true
+    });
+    if (!proceed) {
+      logger.info("Cancelled.");
+      return;
+    }
   }
   const project = await detectProject(cwd);
   const pm = options.packageManager ?? project.packageManager;
@@ -510,10 +589,10 @@ async function addCommand(componentNames, cwd, options) {
 }
 
 // src/commands/create.ts
-import path4 from "path";
+import path5 from "path";
 import chalk3 from "chalk";
 import { execa as execa2 } from "execa";
-import fs4 from "fs-extra";
+import fs5 from "fs-extra";
 import prompts2 from "prompts";
 var NPM_REGISTRY = "https://registry.npmjs.org";
 var ROOTNATIVE_PACKAGES = ["@rootnative/core", "@rootnative/components"];
@@ -570,7 +649,7 @@ var TEMPLATE_BINARY_FILES = [
   "assets/adaptive-icon.png",
   "assets/favicon.png"
 ];
-var TEMPLATE_OPTIONAL_TEXT_FILES = ["CLAUDE.md"];
+var TEMPLATE_OPTIONAL_TEXT_FILES = ["CLAUDE.md", "README.md"];
 function isValidTemplate(value) {
   return value in TEMPLATE_CONFIGS;
 }
@@ -700,8 +779,8 @@ async function createCommand(name, options = {}) {
     }
     packageManager = value;
   }
-  const targetDir = path4.resolve(process.cwd(), projectName);
-  if (await fs4.pathExists(targetDir)) {
+  const targetDir = path5.resolve(process.cwd(), projectName);
+  if (await fs5.pathExists(targetDir)) {
     if (options.yes) {
       logger.warn(`Directory ${chalk3.bold(projectName)} already exists.`);
       process.exit(1);
@@ -716,7 +795,7 @@ async function createCommand(name, options = {}) {
       logger.info("Create cancelled.");
       return;
     }
-    await fs4.remove(targetDir);
+    await fs5.remove(targetDir);
   }
   const templateConfig = TEMPLATE_CONFIGS[templateName];
   const { baseUrl, pinnedVersion } = await resolveTemplateSource();
@@ -725,7 +804,7 @@ async function createCommand(name, options = {}) {
   spinner.start();
   try {
     for (const dir of templateConfig.dirs) {
-      await fs4.ensureDir(path4.join(targetDir, dir));
+      await fs5.ensureDir(path5.join(targetDir, dir));
     }
     for (const file of templateConfig.textFiles) {
       let content = await fetchText(`${templateBaseUrl}/${file}`);
@@ -750,18 +829,18 @@ async function createCommand(name, options = {}) {
         }
         content = JSON.stringify(appJson, null, 2) + "\n";
       }
-      await fs4.outputFile(path4.join(targetDir, file), content);
+      await fs5.outputFile(path5.join(targetDir, file), content);
     }
     for (const file of TEMPLATE_OPTIONAL_TEXT_FILES) {
       const content = await fetchTextOptional(`${templateBaseUrl}/${file}`);
       if (content !== null) {
-        await fs4.outputFile(path4.join(targetDir, file), content);
+        await fs5.outputFile(path5.join(targetDir, file), content);
       }
     }
     for (const file of TEMPLATE_BINARY_FILES) {
       const buffer = await fetchBinary(`${templateBaseUrl}/${file}`);
       if (buffer) {
-        await fs4.outputFile(path4.join(targetDir, file), buffer);
+        await fs5.outputFile(path5.join(targetDir, file), buffer);
       }
     }
     spinner.succeed("Project created");
@@ -810,28 +889,34 @@ async function createCommand(name, options = {}) {
 }
 
 // src/commands/doctor.ts
-import path5 from "path";
+import path6 from "path";
 import chalk4 from "chalk";
-import fs5 from "fs-extra";
+import fs6 from "fs-extra";
 function logCheck(status, message) {
-  const icon = status === "pass" ? chalk4.green("[pass]") : status === "warn" ? chalk4.yellow("[warn]") : chalk4.red("[fail]");
+  const icon = status === "pass" ? chalk4.green("[pass]") : status === "warn" ? chalk4.yellow("[warn]") : status === "info" ? chalk4.cyan("[info]") : chalk4.red("[fail]");
   console.log(`  ${icon} ${message}`);
 }
+var REQUIRED_BARREL_PEERS = [
+  {
+    name: "react-native-svg",
+    reason: "the @rootnative/components barrel requires it at load time (circular-progress, loading-indicator)"
+  }
+];
 async function doctorCommand(cwd) {
   logger.break();
   console.log(chalk4.bold("RootNative Doctor"));
   logger.break();
   let issues = 0;
-  if (await configExists(cwd)) {
+  const initialized = await configExists(cwd);
+  if (initialized) {
     logCheck("pass", "rootnative.json found");
   } else {
-    logCheck("fail", 'rootnative.json not found. Run "rootnative init" first.');
-    issues++;
-    logger.break();
-    logger.error(`${issues} issue(s) found.`);
-    return;
+    logCheck(
+      "info",
+      'Not initialized for the CLI workflow (no rootnative.json). Run "rootnative init" to copy component source.'
+    );
   }
-  const config = await readConfig(cwd);
+  const config = initialized ? await readConfig(cwd) : null;
   const project = await detectProject(cwd);
   if (project.type !== "unknown") {
     logCheck(
@@ -842,9 +927,9 @@ async function doctorCommand(cwd) {
     logCheck("fail", "Not a React Native or Expo project");
     issues++;
   }
-  const pkgPath = path5.resolve(cwd, "package.json");
-  if (await fs5.pathExists(pkgPath)) {
-    const pkg = await fs5.readJSON(pkgPath);
+  const pkgPath = path6.resolve(cwd, "package.json");
+  if (await fs6.pathExists(pkgPath)) {
+    const pkg = await fs6.readJSON(pkgPath);
     const allDeps = {
       ...pkg.dependencies,
       ...pkg.devDependencies
@@ -857,15 +942,15 @@ async function doctorCommand(cwd) {
       issues++;
     }
   }
-  const corePkgPath = path5.resolve(
+  const corePkgPath = path6.resolve(
     cwd,
     "node_modules",
     "@rootnative",
     "core",
     "package.json"
   );
-  if (await fs5.pathExists(corePkgPath)) {
-    const corePkg = await fs5.readJSON(corePkgPath);
+  if (await fs6.pathExists(corePkgPath)) {
+    const corePkg = await fs6.readJSON(corePkgPath);
     logCheck("pass", `@rootnative/core@${corePkg.version} installed`);
   } else {
     logCheck(
@@ -882,65 +967,67 @@ async function doctorCommand(cwd) {
       "TypeScript not detected. RootNative components use TypeScript."
     );
   }
-  const componentsDir = resolveAliasPath(config.aliases.components, cwd);
-  if (await fs5.pathExists(componentsDir)) {
-    const dirs = await fs5.readdir(componentsDir);
-    const componentDirs = [];
-    for (const dir of dirs) {
-      const fullPath = path5.join(componentsDir, dir);
-      const stat = await fs5.stat(fullPath);
-      if (stat.isDirectory()) {
-        componentDirs.push(dir);
-      }
-    }
-    if (componentDirs.length > 0) {
-      let integrityOk = true;
-      for (const dir of componentDirs) {
-        const indexPath = path5.join(componentsDir, dir, "index.ts");
-        if (!await fs5.pathExists(indexPath)) {
-          logCheck("warn", `Component ${dir} is missing index.ts`);
-          integrityOk = false;
+  if (config) {
+    const componentsDir = resolveAliasPath(config.aliases.components, cwd);
+    if (await fs6.pathExists(componentsDir)) {
+      const dirs = await fs6.readdir(componentsDir);
+      const componentDirs = [];
+      for (const dir of dirs) {
+        const fullPath = path6.join(componentsDir, dir);
+        const stat = await fs6.stat(fullPath);
+        if (stat.isDirectory()) {
+          componentDirs.push(dir);
         }
       }
-      if (integrityOk) {
+      if (componentDirs.length > 0) {
+        let integrityOk = true;
+        for (const dir of componentDirs) {
+          const indexPath = path6.join(componentsDir, dir, "index.ts");
+          if (!await fs6.pathExists(indexPath)) {
+            logCheck("warn", `Component ${dir} is missing index.ts`);
+            integrityOk = false;
+          }
+        }
+        if (integrityOk) {
+          logCheck(
+            "pass",
+            `${componentDirs.length} component(s) installed, all files present`
+          );
+        }
+      } else {
         logCheck(
-          "pass",
-          `${componentDirs.length} component(s) installed, all files present`
+          "warn",
+          'No components installed yet. Run "rootnative add <component>".'
         );
       }
     } else {
       logCheck(
         "warn",
-        'No components installed yet. Run "rootnative add <component>".'
+        `Components directory not found at ${config.aliases.components}`
       );
     }
-  } else {
-    logCheck(
-      "warn",
-      `Components directory not found at ${config.aliases.components}`
-    );
-  }
-  const libDir = resolveAliasPath(config.aliases.lib, cwd);
-  const barrelPath = path5.join(libDir, "rootnative-utils.ts");
-  if (await fs5.pathExists(barrelPath)) {
-    logCheck("pass", "Utility barrel file present");
-  } else {
-    if (await fs5.pathExists(componentsDir)) {
-      const dirs = await fs5.readdir(componentsDir);
-      if (dirs.length > 0) {
-        logCheck("warn", "Utility barrel file (rootnative-utils.ts) missing");
+    const libDir = resolveAliasPath(config.aliases.lib, cwd);
+    const barrelPath = path6.join(libDir, "rootnative-utils.ts");
+    if (await fs6.pathExists(barrelPath)) {
+      logCheck("pass", "Utility barrel file present");
+    } else {
+      if (await fs6.pathExists(componentsDir)) {
+        const dirs = await fs6.readdir(componentsDir);
+        if (dirs.length > 0) {
+          logCheck("warn", "Utility barrel file (rootnative-utils.ts) missing");
+        }
       }
     }
   }
-  const nodeModules = path5.resolve(cwd, "node_modules");
-  const inertiaPkgPath = path5.join(
+  const nodeModules = path6.resolve(cwd, "node_modules");
+  const inertiaPkgPath = path6.join(
     nodeModules,
     "@rootnative",
     "inertia",
     "package.json"
   );
-  if (await fs5.pathExists(inertiaPkgPath)) {
-    const inertiaPkg = await fs5.readJSON(inertiaPkgPath);
+  if (await fs6.pathExists(inertiaPkgPath)) {
+    const inertiaPkg = await fs6.readJSON(inertiaPkgPath);
     logCheck("pass", `@rootnative/inertia@${inertiaPkg.version} installed`);
   } else {
     logCheck(
@@ -949,19 +1036,28 @@ async function doctorCommand(cwd) {
     );
     issues++;
   }
-  const safeAreaInstalled = await fs5.pathExists(
-    path5.join(nodeModules, "react-native-safe-area-context")
+  for (const peer of REQUIRED_BARREL_PEERS) {
+    if (await fs6.pathExists(path6.join(nodeModules, peer.name))) {
+      logCheck("pass", `${peer.name} installed`);
+      continue;
+    }
+    logCheck("fail", `${peer.name} is not installed \u2014 ${peer.reason}.`);
+    console.log(`         Run: ${chalk4.bold(`npx expo install ${peer.name}`)}`);
+    issues++;
+  }
+  const safeAreaInstalled = await fs6.pathExists(
+    path6.join(nodeModules, "react-native-safe-area-context")
   );
   if (safeAreaInstalled) {
     logCheck("pass", "react-native-safe-area-context installed");
   } else {
     logCheck(
       "warn",
-      "react-native-safe-area-context not installed (needed by: appbar, layout)"
+      "react-native-safe-area-context not installed (needed by: appbar, layout, bottom-sheet, navigation-bar, snackbar)"
     );
   }
-  const vectorIconsInstalled = await fs5.pathExists(
-    path5.join(nodeModules, "@expo", "vector-icons")
+  const vectorIconsInstalled = await fs6.pathExists(
+    path6.join(nodeModules, "@expo", "vector-icons")
   );
   if (vectorIconsInstalled) {
     logCheck("pass", "@expo/vector-icons installed");
@@ -974,6 +1070,7 @@ async function doctorCommand(cwd) {
   logger.break();
   if (issues > 0) {
     logger.error(`${issues} issue(s) found.`);
+    process.exitCode = 1;
   } else {
     logger.success("All checks passed!");
   }
@@ -986,8 +1083,8 @@ import { execa as execa3 } from "execa";
 import prompts3 from "prompts";
 
 // src/lib/llm-docs.ts
-import path6 from "path";
-import fs6 from "fs-extra";
+import path7 from "path";
+import fs7 from "fs-extra";
 var CLAUDE_MD = "CLAUDE.md";
 var POINTER_MARKER = "@rootnative/components/llms.txt";
 var LLM_DOCS_POINTER = `## RootNative UI docs for AI agents
@@ -1002,22 +1099,49 @@ This project uses RootNative UI (\`@rootnative/*\`). LLM-optimized docs:
 Prefer the \`node_modules\` copies \u2014 they match the installed version exactly.
 `;
 async function ensureLlmDocsPointer(cwd) {
-  const filePath = path6.join(cwd, CLAUDE_MD);
-  if (!await fs6.pathExists(filePath)) {
-    await fs6.outputFile(filePath, `# CLAUDE.md
+  const filePath = path7.join(cwd, CLAUDE_MD);
+  if (!await fs7.pathExists(filePath)) {
+    await fs7.outputFile(filePath, `# CLAUDE.md
 
 ${LLM_DOCS_POINTER}`);
     return "created";
   }
-  const existing = await fs6.readFile(filePath, "utf8");
+  const existing = await fs7.readFile(filePath, "utf8");
   if (existing.includes(POINTER_MARKER)) {
     return "already-present";
   }
   const separator = existing.endsWith("\n") ? "\n" : "\n\n";
-  await fs6.outputFile(filePath, `${existing}${separator}${LLM_DOCS_POINTER}`);
+  await fs7.outputFile(filePath, `${existing}${separator}${LLM_DOCS_POINTER}`);
   return "appended";
 }
 
+// src/lib/registry-version.ts
+var NPM_REGISTRY2 = "https://registry.npmjs.org";
+async function resolveRegistryVersion() {
+  const fallback = "main";
+  try {
+    const res = await fetch(`${NPM_REGISTRY2}/@rootnative/core`);
+    if (!res.ok) {
+      return { version: fallback, fallback: { reason: "npm-unreachable" } };
+    }
+    const data = await res.json();
+    const version = data["dist-tags"]?.latest;
+    if (!version) {
+      return { version: fallback, fallback: { reason: "no-latest-tag" } };
+    }
+    const ref = `v${version}`;
+    const probe = await fetch(
+      `${DEFAULT_CONFIG.registryUrl}/${ref}/registry/index.json`
+    );
+    if (!probe.ok) {
+      return { version: fallback, fallback: { reason: "tag-missing", version } };
+    }
+    return { version: ref };
+  } catch {
+    return { version: fallback, fallback: { reason: "npm-unreachable" } };
+  }
+}
+
 // src/commands/init.ts
 async function initCommand(cwd, options = {}) {
   logger.break();
@@ -1092,8 +1216,10 @@ async function initCommand(cwd, options = {}) {
     componentsAlias = answers.componentsAlias;
     libAlias = answers.libAlias;
   }
+  const registry = await resolveRegistryVersion();
   const config = {
     ...DEFAULT_CONFIG,
+    registryVersion: registry.version,
     aliases: {
       components: componentsAlias,
       lib: libAlias
@@ -1101,6 +1227,34 @@ async function initCommand(cwd, options = {}) {
   };
   await writeConfig(cwd, config);
   logger.success("Created rootnative.json");
+  if (registry.fallback) {
+    logger.break();
+    if (registry.fallback.reason === "tag-missing") {
+      logger.warn(
+        `Could not pin the registry to v${registry.fallback.version}; using "main".`
+      );
+      logger.warn(
+        "Copied component source may not match your installed packages."
+      );
+    } else {
+      logger.warn('Could not reach npm to pin the registry; using "main".');
+      logger.warn(
+        "Copied component source will come from the development branch."
+      );
+    }
+    logger.break();
+  }
+  const tsconfigPatch = await ensureTsconfigPaths(cwd, componentsAlias);
+  if (tsconfigPatch.status === "added") {
+    logger.success(
+      `Added "${tsconfigPatch.prefix}/*" path alias to tsconfig.json`
+    );
+  } else if (tsconfigPatch.status === "failed") {
+    logger.warn(`Could not update tsconfig.json: ${tsconfigPatch.error}`);
+    logger.info(
+      `Add a "paths" mapping for "${componentsAlias.split("/")[0]}/*" by hand.`
+    );
+  }
   let addLlmDocs = options.yes;
   if (!options.yes) {
     const answer = await prompts3({
@@ -1157,9 +1311,9 @@ async function initCommand(cwd, options = {}) {
 }
 
 // src/commands/list.ts
-import path7 from "path";
+import path8 from "path";
 import chalk6 from "chalk";
-import fs7 from "fs-extra";
+import fs8 from "fs-extra";
 async function listCommand(cwd) {
   logger.break();
   const config = await readConfig(cwd);
@@ -1185,8 +1339,8 @@ async function listCommand(cwd) {
     `  ${chalk6.dim("-".repeat(70))}`
   );
   for (const component of registryIndex.components) {
-    const componentDir = path7.join(componentsDir, component.name);
-    const installed = await fs7.pathExists(componentDir);
+    const componentDir = path8.join(componentsDir, component.name);
+    const installed = await fs8.pathExists(componentDir);
     const status = installed ? chalk6.green("installed") : chalk6.dim("-");
     const nameDisplay = installed ? chalk6.green(component.name) : component.name;
     console.log(
@@ -1206,9 +1360,9 @@ function padEnd(str, length) {
 }
 
 // src/commands/update.ts
-import path8 from "path";
+import path9 from "path";
 import chalk8 from "chalk";
-import fs8 from "fs-extra";
+import fs9 from "fs-extra";
 import prompts4 from "prompts";
 
 // src/lib/diff.ts
@@ -1358,8 +1512,8 @@ async function updateCommand(componentNames, cwd, options) {
     targetNames = componentNames;
     const missing = [];
     for (const name of targetNames) {
-      const dir = path8.join(componentsDir, name);
-      if (!await fs8.pathExists(dir)) {
+      const dir = path9.join(componentsDir, name);
+      if (!await fs9.pathExists(dir)) {
         missing.push(name);
       }
     }
@@ -1382,8 +1536,8 @@ async function updateCommand(componentNames, cwd, options) {
   resolveSpinner.succeed("Registry fetched");
   const componentDiffs = [];
   for (const { entry } of resolution.components) {
-    const componentDir = path8.join(componentsDir, entry.name);
-    if (!await fs8.pathExists(componentDir)) {
+    const componentDir = path9.join(componentsDir, entry.name);
+    if (!await fs9.pathExists(componentDir)) {
       componentDiffs.push({
         name: entry.name,
         diffs: [],
@@ -1393,8 +1547,8 @@ async function updateCommand(componentNames, cwd, options) {
     }
     const diffs = [];
     for (const filePath of entry.files) {
-      const fileName = path8.basename(filePath);
-      const localPath = path8.join(componentDir, fileName);
+      const fileName = path9.basename(filePath);
+      const localPath = path9.join(componentDir, fileName);
       const remoteContent = await fetchFileContent(config, filePath);
       const transformed = transformImports(remoteContent, {
         config,
@@ -1402,8 +1556,8 @@ async function updateCommand(componentNames, cwd, options) {
         installedComponents: allComponentNames
       });
       let localContent = "";
-      if (await fs8.pathExists(localPath)) {
-        localContent = await fs8.readFile(localPath, "utf-8");
+      if (await fs9.pathExists(localPath)) {
+        localContent = await fs9.readFile(localPath, "utf-8");
       }
       diffs.push(computeDiff(localContent, transformed, fileName));
     }
@@ -1414,12 +1568,12 @@ async function updateCommand(componentNames, cwd, options) {
   for (const utilName of resolution.utils) {
     const utilEntry = utilsRegistry[utilName];
     if (!utilEntry) continue;
-    const fileName = path8.basename(utilEntry.file);
-    const localPath = path8.join(libDir, fileName);
+    const fileName = path9.basename(utilEntry.file);
+    const localPath = path9.join(libDir, fileName);
     const remoteContent = await fetchFileContent(config, utilEntry.file);
     let localContent = "";
-    if (await fs8.pathExists(localPath)) {
-      localContent = await fs8.readFile(localPath, "utf-8");
+    if (await fs9.pathExists(localPath)) {
+      localContent = await fs9.readFile(localPath, "utf-8");
     }
     utilDiffs.push(computeDiff(localContent, remoteContent, `lib/${fileName}`));
   }
@@ -1431,10 +1585,10 @@ async function updateCommand(componentNames, cwd, options) {
     }
   }
   const newBarrel = generateUtilsBarrel(resolution.utils, utilExports);
-  const barrelPath = path8.join(libDir, "rootnative-utils.ts");
+  const barrelPath = path9.join(libDir, "rootnative-utils.ts");
   let oldBarrel = "";
-  if (await fs8.pathExists(barrelPath)) {
-    oldBarrel = await fs8.readFile(barrelPath, "utf-8");
+  if (await fs9.pathExists(barrelPath)) {
+    oldBarrel = await fs9.readFile(barrelPath, "utf-8");
   }
   utilDiffs.push(computeDiff(oldBarrel, newBarrel, "lib/rootnative-utils.ts"));
   const changedComponents = componentDiffs.filter((c) => c.hasChanges);
@@ -1497,8 +1651,8 @@ async function updateCommand(componentNames, cwd, options) {
   const applySpinner = createSpinner("Applying updates...");
   applySpinner.start();
   for (const comp of changedComponents) {
-    const componentDir = path8.join(componentsDir, comp.name);
-    await fs8.ensureDir(componentDir);
+    const componentDir = path9.join(componentsDir, comp.name);
+    await fs9.ensureDir(componentDir);
     if (comp.diffs.length === 0) {
       const entry = resolution.components.find(
         (c) => c.entry.name === comp.name
@@ -1506,14 +1660,14 @@ async function updateCommand(componentNames, cwd, options) {
       if (!entry) continue;
       for (const filePath of entry.entry.files) {
         const content = await fetchFileContent(config, filePath);
-        const fileName = path8.basename(filePath);
+        const fileName = path9.basename(filePath);
         const transformed = transformImports(content, {
           config,
           componentName: comp.name,
           installedComponents: allComponentNames
         });
-        await fs8.writeFile(
-          path8.join(componentDir, fileName),
+        await fs9.writeFile(
+          path9.join(componentDir, fileName),
           transformed,
           "utf-8"
         );
@@ -1523,23 +1677,23 @@ async function updateCommand(componentNames, cwd, options) {
     for (const diff of comp.diffs) {
       if (!diff.hasChanges) continue;
       const newContent = diff.lines.filter((l) => l.type !== "remove").map((l) => l.content).join("\n");
-      await fs8.writeFile(
-        path8.join(componentDir, diff.fileName),
+      await fs9.writeFile(
+        path9.join(componentDir, diff.fileName),
         newContent,
         "utf-8"
       );
     }
   }
-  await fs8.ensureDir(libDir);
+  await fs9.ensureDir(libDir);
   for (const diff of changedUtils) {
     if (!diff.hasChanges) continue;
     const newContent = diff.lines.filter((l) => l.type !== "remove").map((l) => l.content).join("\n");
-    const filePath = path8.join(
+    const filePath = path9.join(
       libDir,
       // diff.fileName is like "lib/color.ts" — strip the "lib/" prefix
       diff.fileName.replace(/^lib\//, "")
     );
-    await fs8.writeFile(filePath, newContent, "utf-8");
+    await fs9.writeFile(filePath, newContent, "utf-8");
   }
   applySpinner.succeed("Updates applied");
   logger.break();
@@ -1549,17 +1703,17 @@ async function updateCommand(componentNames, cwd, options) {
   logger.break();
 }
 async function getInstalledComponents(componentsDir) {
-  if (!await fs8.pathExists(componentsDir)) {
+  if (!await fs9.pathExists(componentsDir)) {
     return [];
   }
-  const entries = await fs8.readdir(componentsDir);
+  const entries = await fs9.readdir(componentsDir);
   const components = [];
   for (const entry of entries) {
-    const fullPath = path8.join(componentsDir, entry);
-    const stat = await fs8.stat(fullPath);
+    const fullPath = path9.join(componentsDir, entry);
+    const stat = await fs9.stat(fullPath);
     if (stat.isDirectory()) {
-      const indexPath = path8.join(fullPath, "index.ts");
-      if (await fs8.pathExists(indexPath)) {
+      const indexPath = path9.join(fullPath, "index.ts");
+      if (await fs9.pathExists(indexPath)) {
         components.push(entry);
       }
     }
@@ -1568,10 +1722,10 @@ async function getInstalledComponents(componentsDir) {
 }
 
 // src/commands/upgrade.ts
-import path9 from "path";
+import path10 from "path";
 import chalk9 from "chalk";
 import { execa as execa4 } from "execa";
-import fs9 from "fs-extra";
+import fs10 from "fs-extra";
 import prompts5 from "prompts";
 async function fetchLatestFromNpm(packageName) {
   const url = `https://registry.npmjs.org/${packageName}/latest`;
@@ -1584,16 +1738,16 @@ async function fetchLatestFromNpm(packageName) {
   return response.json();
 }
 function getInstalledPackageInfo(cwd, packageName) {
-  const pkgPath = path9.resolve(
+  const pkgPath = path10.resolve(
     cwd,
     "node_modules",
     ...packageName.split("/"),
     "package.json"
   );
-  if (!fs9.pathExistsSync(pkgPath)) {
+  if (!fs10.pathExistsSync(pkgPath)) {
     return null;
   }
-  const pkg = fs9.readJSONSync(pkgPath);
+  const pkg = fs10.readJSONSync(pkgPath);
   return {
     version: pkg.version,
     peerDependencies: pkg.peerDependencies,
@@ -1624,9 +1778,9 @@ function diffPeerDeps(current, latest) {
   return { added, changed, removed };
 }
 function getProjectDeps(cwd) {
-  const pkgPath = path9.resolve(cwd, "package.json");
+  const pkgPath = path10.resolve(cwd, "package.json");
   try {
-    const pkg = fs9.readJSONSync(pkgPath);
+    const pkg = fs10.readJSONSync(pkgPath);
     return {
       ...pkg.dependencies,
       ...pkg.devDependencies
@@ -1638,6 +1792,19 @@ function getProjectDeps(cwd) {
 function hasDiffChanges(diff) {
   return Object.keys(diff.added).length > 0 || Object.keys(diff.changed).length > 0 || diff.removed.length > 0;
 }
+async function repinRegistryVersion(cwd) {
+  const config = await readConfig(cwd);
+  const next = await resolveRegistryVersion();
+  if (next.fallback && config.registryVersion !== "main") {
+    logger.warn(
+      `Kept the registry pinned to ${chalk9.bold(config.registryVersion)} \u2014 could not resolve a newer release tag.`
+    );
+    return;
+  }
+  if (config.registryVersion === next.version) return;
+  await writeConfig(cwd, { ...config, registryVersion: next.version });
+  logger.success(`Registry pinned to ${chalk9.bold(next.version)}`);
+}
 async function upgradeCommand(cwd, options = {}) {
   logger.break();
   await readConfig(cwd);
@@ -1666,6 +1833,7 @@ async function upgradeCommand(cwd, options = {}) {
       `Already on the latest version ${chalk9.bold(`v${installed.version}`)}`
     );
     logger.break();
+    await repinRegistryVersion(cwd);
     if (options.all) {
       logger.info("Updating installed components...");
       await updateCommand([], cwd, { all: true, dryRun: false });
@@ -1783,6 +1951,7 @@ async function upgradeCommand(cwd, options = {}) {
       logger.info(`  ${pkg}`);
     }
   }
+  await repinRegistryVersion(cwd);
   logger.break();
   if (options.all) {
     logger.info("Updating installed components...");
@@ -1834,7 +2003,7 @@ program.command("init").description("Initialize your project for RootNative UI")
     handleError(error);
   }
 });
-program.command("add").description("Add components to your project").argument("<components...>", "Component names to add").option("-f, --force", "Overwrite existing components", false).option(
+program.command("add").description("Add components to your project").argument("<components...>", "Component names to add").option("-y, --yes", "Skip prompts and use defaults", false).option("-f, --force", "Overwrite existing components", false).option(
   "-d, --dry-run",
   "Show what would be installed without making changes",
   false
@@ -1849,6 +2018,7 @@ program.command("add").description("Add components to your project").argument("<
     await addCommand(components, process.cwd(), {
       force: options.force,
       dryRun: options.dryRun,
+      yes: options.yes,
       packageManager: options.packageManager
     });
   } catch (error) {

package/llms.txt

@@ -1,6 +1,6 @@
 # @rootnative/cli — CLI for RootNative UI
 
-> Version: 0.0.0-alpha.4
+> Version: 0.0.0-alpha.5
 > Binary: `rootnative`
 > Requirements: Node >=18
 
@@ -47,10 +47,12 @@ Creates `rootnative.json`:
   "$schema": "https://rootnative.github.io/ui/schema.json",
   "aliases": { "components": "@/components/ui", "lib": "@/lib" },
   "registryUrl": "https://raw.githubusercontent.com/rootnative/ui",
-  "registryVersion": "main"
+  "registryVersion": "v0.0.0-alpha.5"
 }
 ```
 
+`init` pins `registryVersion` to the `v<version>` git tag of the latest published release, so a project keeps fetching the same component sources until you run `rootnative upgrade` (which moves the pin forward). It falls back to `main` only when npm is unreachable or the tag has not been pushed yet.
+
 #### `rootnative add <components...>`
 
 Add components to your project. Resolves dependency graph, copies files with rewritten imports, installs npm deps.
@@ -58,7 +60,7 @@ Add components to your project. Resolves dependency graph, copies files with rew
 ```bash
 npx rootnative add button
 npx rootnative add card chip text-field
-npx rootnative add appbar      # auto-adds icon-button + typography
+npx rootnative add appbar      # auto-adds button + icon-button + typography
 ```
 
 Options:
@@ -85,6 +87,7 @@ npx rootnative upgrade -y      # Non-interactive — skip confirmation
 
 Options:
 - `-y, --yes` — Skip confirmation prompt
+- `-a, --all` — Also update the installed component files, not just the package
 - `--package-manager <pm>` — Package manager to use (`npm`, `yarn`, `pnpm`, `bun`)
 
 What it does:
@@ -95,6 +98,8 @@ What it does:
 5. Upgrades `@rootnative/core` and installs any new required peer dependencies in one step
 6. Reports optional peer deps that aren't installed (does not auto-install optional deps)
 7. Lists peer deps that are no longer required so you can remove them manually
+8. Moves `registryVersion` forward to the new release tag, so later `add`/`update` calls fetch matching sources
+9. With `-a, --all`, also updates the installed component files
 
 #### `rootnative list`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootnative/cli",
-  "version": "0.0.0-alpha.4",
+  "version": "0.0.0-alpha.5",
   "description": "CLI for adding RootNative UI components to your React Native project",
   "private": false,
   "bin": {