updose 0.2.0 → 0.3.0

package/README.md

@@ -31,6 +31,7 @@ npx updose <command>
     - [`skills.json` Reference](#skillsjson-reference)
     - [Example: Single-Target Boilerplate (Claude)](#example-single-target-boilerplate-claude)
     - [Example: Multi-Target Boilerplate](#example-multi-target-boilerplate)
+    - [Monorepo Support](#monorepo-support)
   - [Publishing](#publishing)
   - [License](#license)
 
@@ -43,6 +44,8 @@ npx updose search react
 # Install a boilerplate from a GitHub repository
 npx updose add owner/repo-name
 
+# Install from a subdirectory within a monorepo
+npx updose add owner/repo-name/nextjs
 ```
 
 ## Commands
@@ -51,21 +54,29 @@ npx updose add owner/repo-name
 
 Install a boilerplate from a GitHub repository into your project.
 
+The `<repo>` argument accepts two formats:
+
+- **`owner/repo`** — installs from the repository root (standard boilerplate)
+- **`owner/repo/dir`** — installs from a subdirectory within the repository (monorepo boilerplate). The `dir` can be nested (e.g., `owner/repo/templates/v2`).
+
 ```bash
-npx updose add owner/repo-name
-npx updose add owner/repo-name -y         # Skip all prompts (install all targets, append main docs, overwrite others)
-npx updose add owner/repo-name --dry-run  # Preview what would be installed without writing any files
+npx updose add owner/repo-name                  # Install from repository root
+npx updose add owner/repo-name/nextjs            # Install from "nextjs" subdirectory
+npx updose add owner/repo-name/templates/v2      # Install from nested subdirectory
+npx updose add owner/repo-name -y                # Skip all prompts
+npx updose add owner/repo-name/nextjs --dry-run  # Preview monorepo install
 ```
 
 **What happens when you run `add`:**
 
-1. Fetches the boilerplate's `updose.json` manifest from the GitHub repository
-2. If the boilerplate supports multiple targets (e.g., both Claude and Gemini), prompts you to choose which targets to install. With `-y`, all targets are installed automatically.
-3. Downloads the file tree from the repository and filters files for the selected target(s)
-4. Installs each file into your project. If a file already exists, the prompt depends on the file type:
+1. Parses the `<repo>` argument to determine the repository (`owner/repo`) and optional subdirectory
+2. Fetches the boilerplate's `updose.json` manifest from the repository root or the specified subdirectory
+3. If the boilerplate supports multiple targets (e.g., both Claude and Gemini), prompts you to choose which targets to install. With `-y`, all targets are installed automatically.
+4. Downloads the file tree from the repository and filters files for the selected target(s). When a subdirectory is specified, only files under that subdirectory are considered.
+5. Installs each file into your project. If a file already exists, the prompt depends on the file type:
    - **Main docs** (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`): **Append** / **Overwrite** / **Skip**
    - **Other files** (rules, commands, agents, etc.): **Overwrite** / **Skip**
-5. If a `skills.json` file exists in the boilerplate, installs each declared skill via [skills.sh](https://skills.sh/). Skills are installed for the selected targets (`-a`), copied into the project (`--copy`), and auto-confirmed (`-y`)
+6. If a `skills.json` file exists in the boilerplate (or its subdirectory), installs each declared skill via [skills.sh](https://skills.sh/). Skills are installed for the selected targets (`-a`), copied into the project (`--copy`), and auto-confirmed (`-y`)
 
 | Option      | Description                                                                                           |
 |--------     |-------------                                                                                          |
@@ -138,6 +149,17 @@ mkdir my-boilerplate && cd my-boilerplate
 npx updose init
 ```
 
+To scaffold inside a subdirectory (for monorepo setups), use the `--dir` option:
+
+```bash
+npx updose init --dir nextjs          # Creates boilerplate in the "nextjs" subdirectory
+npx updose init --dir templates/v2    # Nested subdirectory is also supported
+```
+
+| Option         | Description                                                                                                                |
+|--------        |-------------                                                                                                               |
+| `--dir <dir>`  | Create the boilerplate inside the specified subdirectory instead of the repository root. The directory is created if it doesn't exist. |
+
 **What happens when you run `init`:**
 
 1. Prompts you for boilerplate configuration (see below)
@@ -145,11 +167,13 @@ npx updose init
 3. If a file already exists, asks whether to **Overwrite** or **Skip**
 4. Shows next steps for publishing
 
+When `--dir` is used, all generated files are placed inside the specified subdirectory instead of the repository root.
+
 **Interactive prompts:**
 
 | Prompt          | Description                             | Default                                                                                                       |
 |--------         |-------------                            |---------                                                                                                      |
-| **Name**        | Boilerplate name                        | Current directory name                                                                                        |
+| **Name**        | Boilerplate name                        | Without `--dir`: current directory name (e.g., `my-boilerplate`). With `--dir`: `<repo>/<dir>` (e.g., `my-boilerplate/nextjs`) |
 | **Description** | Short description (optional)            | —                                                                                                             |
 | **Author**      | GitHub username                         | Auto-detected from `git config github.user` or `gh api user`. If neither is available, you enter it manually. |
 | **Targets**     | Which AI tools to support (multiselect) | All selected (`claude`, `codex`, `gemini`)                                                                    |
@@ -172,7 +196,7 @@ Plus target-specific directories based on your selection:
 | Codex   | `codex/AGENTS.md`                                                       |
 | Gemini  | `gemini/GEMINI.md`, `gemini/skills/`                                    |
 
-**Example — scaffolding with all targets selected:**
+**Example — scaffolding with all targets selected (no `--dir`):**
 
 ```
 my-boilerplate/
@@ -191,27 +215,57 @@ my-boilerplate/
     └── skills/
 ```
 
+**Example — scaffolding with `--dir nextjs`:**
+
+```
+my-monorepo/
+├── nextjs/                  ← created by --dir
+│   ├── updose.json
+│   ├── skills.json
+│   ├── README.md
+│   ├── claude/
+│   │   ├── CLAUDE.md
+│   │   ├── rules/
+│   │   ├── agents/
+│   │   └── skills/
+│   ├── codex/
+│   │   └── AGENTS.md
+│   └── gemini/
+│       ├── GEMINI.md
+│       └── skills/
+├── remix/                   ← another boilerplate in the same repo
+│   └── ...
+└── README.md                ← repo-level README (not managed by updose)
+```
+
 After scaffolding, follow the next steps printed by the command:
 
 1. Edit your boilerplate files in each target directory
 2. Push to GitHub
-3. Publish with `npx updose publish`
-4. Others can install with `npx updose add <author>/<name>`
+3. Publish with `npx updose publish` (or `npx updose publish --dir nextjs` for monorepo)
+4. Others can install with `npx updose add <author>/<name>` (or `npx updose add <author>/<repo>/nextjs` for monorepo)
 
 ### `updose publish`
 
 Publish your boilerplate to the marketplace so others can find and install it.
 
 ```bash
-npx updose publish
+npx updose publish                   # Publish from repository root
+npx updose publish --dir nextjs      # Publish from a subdirectory (monorepo)
 ```
 
+| Option         | Description                                                                                                           |
+|--------        |-------------                                                                                                          |
+| `--dir <dir>`  | Read `updose.json` from the specified subdirectory instead of the repository root. Use this when publishing a monorepo boilerplate. |
+
 **What happens when you run `publish`:**
 
-1. Reads and parses `updose.json` from the current directory. If the file is missing, shows an error and suggests running `updose init` first.
+1. Reads and parses `updose.json` from the current directory (or the subdirectory specified by `--dir`). If the file is missing, shows an error and suggests running `updose init` first.
 2. Validates the manifest structure (name, author, version, targets are required)
 3. Detects the GitHub repository by running `git remote get-url origin`. Supports both HTTPS (`https://github.com/owner/repo.git`) and SSH (`git@github.com:owner/repo.git`) formats.
-4. Validates that `author` and `name` in `updose.json` match the repository owner and name (case-insensitive). If they don't match, shows an error and exits.
+4. Validates that `author` and `name` in `updose.json` match the expected name:
+   - Without `--dir`: `name` must match the repository name (e.g., `react-starter`)
+   - With `--dir`: `name` must match `<repo>/<dir>` (e.g., `my-monorepo/nextjs`)
 5. Authenticates via GitHub — if no valid token exists, automatically runs the `login` flow (see below)
 6. Verifies the repository actually exists on GitHub. If the repo has not been pushed yet, shows an error and exits.
 7. Displays a publication summary for review:
@@ -225,13 +279,27 @@ Publishing:
   Tags:        react, typescript, web
 ```
 
+When `--dir` is used, the summary also includes a `Directory` field:
+
+```
+Publishing:
+  Name:        my-monorepo/nextjs
+  Version:     1.0.0
+  Repository:  example-user/my-monorepo
+  Directory:   nextjs
+  Targets:     claude
+  Tags:        react, nextjs
+```
+
 8. Asks for confirmation: **"Publish to registry?"** (defaults to yes). If declined, displays "Publish cancelled." and exits.
 9. Registers the boilerplate in the marketplace registry
-10. On success, displays: `Users can now install with: npx updose add owner/repo`
+10. On success, displays the install command:
+    - Without `--dir`: `Users can now install with: npx updose add owner/repo`
+    - With `--dir`: `Users can now install with: npx updose add owner/repo/dir`
 
 **Prerequisites:**
 
-- A valid `updose.json` in the current directory (run `updose init` to create one)
+- A valid `updose.json` in the current directory or specified subdirectory (run `updose init` to create one)
 - A GitHub remote (`origin`) configured and pushed to GitHub
 - GitHub authentication (handled automatically if not already logged in)
 
@@ -388,7 +456,7 @@ The manifest file that describes your boilerplate.
 
 | Field         | Required  | Description                                                             |
 |-------        |---------- |-------------                                                            |
-| `name`        | Yes       | The boilerplate name. Must match the GitHub repository name.            |
+| `name`        | Yes       | The boilerplate name. Must match the GitHub repository name (e.g., `react-starter`). For monorepo boilerplates, must be `<repo>/<dir>` (e.g., `my-starters/nextjs`). |
 | `author`      | Yes       | Author name. Must match the GitHub repository owner.                    |
 | `version`     | Yes       | Version string following [semver](https://semver.org/) (e.g., `1.0.0`). |
 | `targets`     | Yes       | Array of supported targets: `"claude"`, `"codex"`, and/or `"gemini"`.   |
@@ -497,16 +565,104 @@ boilerplate-multi-target/
 
 When a user installs a multi-target boilerplate, they are prompted to choose which targets to install. With `-y`, all targets are installed automatically.
 
+### Monorepo Support
+
+A single GitHub repository can contain multiple boilerplates, each in its own subdirectory. This is useful when you want to publish several related boilerplates (e.g., framework-specific starters) from one repo.
+
+**How it works:**
+
+- Each subdirectory is an independent boilerplate with its own `updose.json`, `skills.json`, and target directories
+- The `name` field in `updose.json` must be `<repo>/<dir>` (e.g., `my-starters/nextjs`)
+- Users install with `npx updose add owner/repo/dir` instead of `npx updose add owner/repo`
+
+**Monorepo directory structure:**
+
+```
+my-starters/                         ← GitHub repository root
+├── README.md                        ← repo-level README (not managed by updose)
+├── nextjs/                          ← boilerplate for Next.js
+│   ├── updose.json                  ← name: "my-starters/nextjs"
+│   ├── skills.json
+│   ├── claude/
+│   │   ├── CLAUDE.md
+│   │   └── rules/
+│   │       └── nextjs-conventions.md
+│   └── gemini/
+│       └── GEMINI.md
+├── remix/                           ← boilerplate for Remix
+│   ├── updose.json                  ← name: "my-starters/remix"
+│   ├── skills.json
+│   └── claude/
+│       ├── CLAUDE.md
+│       └── rules/
+│           └── remix-conventions.md
+└── sveltekit/                       ← boilerplate for SvelteKit
+    ├── updose.json                  ← name: "my-starters/sveltekit"
+    ├── skills.json
+    └── claude/
+        └── CLAUDE.md
+```
+
+**`updose.json` for a monorepo boilerplate (`nextjs/updose.json`):**
+
+```json
+{
+  "name": "my-starters/nextjs",
+  "author": "example-user",
+  "version": "1.0.0",
+  "description": "Next.js boilerplate for Claude and Gemini",
+  "targets": ["claude", "gemini"],
+  "tags": ["nextjs", "react", "web"]
+}
+```
+
+> Note: The `name` field uses the format `<repo>/<dir>` (e.g., `my-starters/nextjs`), not just the directory name.
+
+**Workflow for creating a monorepo boilerplate:**
+
+```bash
+# 1. Scaffold each boilerplate in its own subdirectory
+npx updose init --dir nextjs
+npx updose init --dir remix
+npx updose init --dir sveltekit
+
+# 2. Edit each boilerplate's files
+# (edit nextjs/claude/CLAUDE.md, remix/claude/CLAUDE.md, etc.)
+
+# 3. Push to GitHub
+git add . && git commit -m "Add boilerplates" && git push
+
+# 4. Publish each boilerplate separately
+npx updose publish --dir nextjs
+npx updose publish --dir remix
+npx updose publish --dir sveltekit
+```
+
+**Users install each boilerplate independently:**
+
+```bash
+npx updose add example-user/my-starters/nextjs
+npx updose add example-user/my-starters/remix
+```
+
 ## Publishing
 
 To share your boilerplate with others through the marketplace:
 
-1. Scaffold with `npx updose init`
+1. Scaffold with `npx updose init` (or `npx updose init --dir <dir>` for monorepo)
 2. Add your content (rules, commands, agents, skills, etc.)
 3. Push to a GitHub repository
-4. Run `npx updose publish`
+4. Run `npx updose publish` (or `npx updose publish --dir <dir>` for monorepo)
+
+After publishing, anyone can install your boilerplate:
 
-After publishing, anyone can install your boilerplate with `npx updose add your-username/my-boilerplate`.
+```bash
+# Standard boilerplate
+npx updose add your-username/my-boilerplate
+
+# Monorepo boilerplate
+npx updose add your-username/my-monorepo/nextjs
+```
 
 ## License
 

package/dist/index.cjs

@@ -51,18 +51,18 @@ async function searchBoilerplates(query, filters) {
   }
   return await res.json();
 }
-async function recordDownload(repo) {
+async function recordDownload(repo, dir) {
   await fetch(`${API_BASE_URL}/download`, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       "User-Agent": USER_AGENT
     },
-    body: JSON.stringify({ repo }),
+    body: JSON.stringify({ repo, dir: dir ?? null }),
     signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
   });
 }
-async function registerBoilerplate(repo, manifest, githubToken) {
+async function registerBoilerplate(repo, manifest, githubToken, dir) {
   const res = await fetch(`${API_BASE_URL}/register`, {
     method: "POST",
     headers: {
@@ -70,7 +70,7 @@ async function registerBoilerplate(repo, manifest, githubToken) {
       Authorization: `Bearer ${githubToken}`,
       "User-Agent": USER_AGENT
     },
-    body: JSON.stringify({ repo, manifest }),
+    body: JSON.stringify({ repo, manifest, dir: dir ?? null }),
     signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
   });
   if (!res.ok) {
@@ -308,6 +308,18 @@ function optionalStringArray(obj, key) {
 // src/core/github.ts
 var GITHUB_RAW = "https://raw.githubusercontent.com";
 var FETCH_TIMEOUT_MS2 = 3e4;
+function parseRepoInput(input) {
+  const parts = input.split("/");
+  if (parts.length < 2 || !parts[0] || !parts[1]) {
+    throw new Error(
+      `Invalid repository format: "${input}". Expected "owner/repo" or "owner/repo/dir".`
+    );
+  }
+  const repo = `${parts[0]}/${parts[1]}`;
+  const raw = parts.length > 2 ? parts.slice(2).join("/").replace(/\/+$/, "") : void 0;
+  const dir = raw || void 0;
+  return { repo, dir };
+}
 function parseRepo(repo) {
   const parts = repo.split("/");
   if (parts.length !== 2 || !parts[0] || !parts[1]) {
@@ -387,11 +399,12 @@ async function fetchFile(repo, path) {
   }
   return res.text();
 }
-async function fetchManifest(repo) {
-  const content = await fetchFile(repo, MANIFEST_FILENAME);
+async function fetchManifest(repo, dir) {
+  const path = dir ? `${dir}/${MANIFEST_FILENAME}` : MANIFEST_FILENAME;
+  const content = await fetchFile(repo, path);
   if (content === null) {
     throw new Error(
-      `No ${MANIFEST_FILENAME} found in ${repo}. Is this an updose boilerplate?`
+      `No ${MANIFEST_FILENAME} found in ${dir ? `${repo}/${dir}` : repo}. Is this an updose boilerplate?`
     );
   }
   let raw;
@@ -429,8 +442,9 @@ async function fetchRepoTree(repo) {
   }
   return data.tree.filter((entry) => entry.type === "blob");
 }
-async function fetchSkillsJson(repo) {
-  return fetchFile(repo, SKILLS_FILENAME);
+async function fetchSkillsJson(repo, dir) {
+  const path = dir ? `${dir}/${SKILLS_FILENAME}` : SKILLS_FILENAME;
+  return fetchFile(repo, path);
 }
 
 // src/core/installer.ts
@@ -613,15 +627,16 @@ async function settledPool(tasks, limit) {
   );
   return results;
 }
-async function addCommand(repo, options) {
+async function addCommand(repoInput, options) {
   try {
+    const { repo, dir } = parseRepoInput(repoInput);
     const cwd = process.cwd();
     const skipPrompts = options.yes ?? false;
     const dryRun = options.dryRun ?? false;
     const manifestSpinner = createSpinner("Fetching updose.json...").start();
     let manifest;
     try {
-      manifest = await fetchManifest(repo);
+      manifest = await fetchManifest(repo, dir);
       manifestSpinner.success(
         `Found ${manifest.name} by ${manifest.author} (v${manifest.version})`
       );
@@ -654,7 +669,7 @@ async function addCommand(repo, options) {
     const filesByTarget = /* @__PURE__ */ new Map();
     for (const target of selectedTargets) {
       const sourceDir = getSourceDir(target);
-      const prefix = `${sourceDir}/`;
+      const prefix = dir ? `${dir}/${sourceDir}/` : `${sourceDir}/`;
       const files = tree.filter((entry) => {
         if (!entry.path.startsWith(prefix)) return false;
         const relativePath = entry.path.slice(prefix.length);
@@ -687,7 +702,7 @@ async function addCommand(repo, options) {
           dryRunCount++;
         }
       }
-      const skillsContent2 = await fetchSkillsJson(repo);
+      const skillsContent2 = await fetchSkillsJson(repo, dir);
       if (skillsContent2 !== null) {
         try {
           const skillsManifest = parseSkills(
@@ -746,7 +761,7 @@ async function addCommand(repo, options) {
       }
     }
     let skillsInstalled = 0;
-    const skillsContent = await fetchSkillsJson(repo);
+    const skillsContent = await fetchSkillsJson(repo, dir);
     if (skillsContent === null) {
       info("No skills.json found \u2014 skipping skills installation.");
     } else {
@@ -794,7 +809,7 @@ async function addCommand(repo, options) {
     const summary = skillsInstalled > 0 ? `${installed} file(s) + ${skillsInstalled} skill(s)` : `${installed} file(s)`;
     success(`Done! ${summary} installed, ${skipped} skipped.`);
     if (installed + skillsInstalled > 0) {
-      await recordDownload(repo).catch(() => {
+      await recordDownload(repo, dir).catch(() => {
       });
     }
   } catch (err) {
@@ -807,6 +822,7 @@ async function addCommand(repo, options) {
 
 // src/commands/init.ts
 var import_node_child_process2 = require("child_process");
+var import_promises2 = require("fs/promises");
 var import_node_path4 = require("path");
 var import_prompts4 = __toESM(require("prompts"), 1);
 var DEFAULT_VERSION = "0.1.0";
@@ -912,10 +928,16 @@ function buildFileList(name, description, author, targets) {
   }
   return files;
 }
-async function initCommand() {
+async function initCommand(options) {
   try {
     const cwd = process.cwd();
-    const defaultName = (0, import_node_path4.basename)(cwd);
+    const dir = options.dir;
+    const baseDir = dir ? (0, import_node_path4.join)(cwd, dir) : cwd;
+    if (dir) {
+      await (0, import_promises2.mkdir)(baseDir, { recursive: true });
+    }
+    const repoName = (0, import_node_path4.basename)(cwd);
+    const defaultName = dir ? `${repoName}/${dir}` : repoName;
     const gitUser = getGitHubUsername();
     info("Scaffolding a new updose boilerplate...\n");
     let cancelled = false;
@@ -972,7 +994,7 @@ async function initCommand() {
     let created = 0;
     let skipped = 0;
     for (const file of files) {
-      const destPath = (0, import_node_path4.join)(cwd, file.path);
+      const destPath = (0, import_node_path4.join)(baseDir, file.path);
       const exists = await fileExists(destPath);
       if (exists) {
         const { action } = await (0, import_prompts4.default)({
@@ -998,14 +1020,21 @@ async function initCommand() {
     success(`Boilerplate scaffolded! (${created} created, ${skipped} skipped)`);
     console.log();
     info("Next steps:");
-    console.log(
-      `  1. Edit your boilerplate files in ${targets.map((t) => `${t}/`).join(", ")}`
-    );
+    const editDirs = targets.map((t) => dir ? `${dir}/${t}/` : `${t}/`);
+    console.log(`  1. Edit your boilerplate files in ${editDirs.join(", ")}`);
     console.log("  2. Push to GitHub");
-    console.log("  3. Publish with: npx updose publish");
     console.log(
-      `  4. Others can install with: npx updose add ${author}/${name}`
+      `  3. Publish with: npx updose publish${dir ? ` --dir ${dir}` : ""}`
     );
+    if (dir) {
+      console.log(
+        `  4. Others can install with: npx updose add ${author}/${repoName}/${dir}`
+      );
+    } else {
+      console.log(
+        `  4. Others can install with: npx updose add ${author}/${name}`
+      );
+    }
   } catch (err) {
     error(
       err instanceof Error ? err.message : "An unexpected error occurred during init."
@@ -1015,7 +1044,7 @@ async function initCommand() {
 }
 
 // src/auth/github-oauth.ts
-var import_promises2 = require("fs/promises");
+var import_promises3 = require("fs/promises");
 var import_node_os = require("os");
 var import_node_path5 = require("path");
 var import_chalk2 = __toESM(require("chalk"), 1);
@@ -1032,7 +1061,7 @@ var AUTH_FILE_MODE = 384;
 var MAX_POLL_INTERVAL_SEC = 60;
 async function getStoredToken() {
   try {
-    const content = await (0, import_promises2.readFile)(AUTH_FILE, "utf-8");
+    const content = await (0, import_promises3.readFile)(AUTH_FILE, "utf-8");
     const data = JSON.parse(content);
     return data.github_token ?? null;
   } catch {
@@ -1041,7 +1070,7 @@ async function getStoredToken() {
 }
 async function getStoredAuth() {
   try {
-    const content = await (0, import_promises2.readFile)(AUTH_FILE, "utf-8");
+    const content = await (0, import_promises3.readFile)(AUTH_FILE, "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
@@ -1097,8 +1126,8 @@ async function login() {
     throw new Error("GitHub authorization failed");
   }
   const username = await fetchUsername(token);
-  await (0, import_promises2.mkdir)(AUTH_DIR, { recursive: true });
-  await (0, import_promises2.writeFile)(
+  await (0, import_promises3.mkdir)(AUTH_DIR, { recursive: true });
+  await (0, import_promises3.writeFile)(
     AUTH_FILE,
     JSON.stringify(
       { github_token: token, github_username: username },
@@ -1183,7 +1212,7 @@ function sleep(ms) {
 }
 async function logout() {
   try {
-    await (0, import_promises2.unlink)(AUTH_FILE);
+    await (0, import_promises3.unlink)(AUTH_FILE);
     return true;
   } catch {
     return false;
@@ -1218,20 +1247,32 @@ async function logoutCommand() {
 
 // src/commands/publish.ts
 var import_node_child_process3 = require("child_process");
-var import_promises3 = require("fs/promises");
+var import_node_fs = require("fs");
+var import_promises4 = require("fs/promises");
 var import_node_path6 = require("path");
 var import_chalk3 = __toESM(require("chalk"), 1);
 var FETCH_TIMEOUT_MS3 = 1e4;
-async function publishCommand() {
+async function publishCommand(options) {
   const cwd = process.cwd();
+  const dir = options.dir;
+  const manifestDir = dir ? (0, import_node_path6.join)(cwd, dir) : cwd;
+  if (dir && !(0, import_node_fs.existsSync)(manifestDir)) {
+    error(`Directory "${dir}" does not exist.`);
+    process.exitCode = 1;
+    return;
+  }
   let raw;
   try {
-    const content = await (0, import_promises3.readFile)((0, import_node_path6.join)(cwd, MANIFEST_FILENAME), "utf-8");
+    const content = await (0, import_promises4.readFile)(
+      (0, import_node_path6.join)(manifestDir, MANIFEST_FILENAME),
+      "utf-8"
+    );
     raw = JSON.parse(content);
   } catch (err) {
     if (err.code === "ENOENT") {
+      const location = dir ? `"${dir}"` : "current directory";
       error(
-        `No ${MANIFEST_FILENAME} found in current directory. Run \`updose init\` first.`
+        `No ${MANIFEST_FILENAME} found in ${location}. Run \`updose init\` first.`
       );
     } else {
       error(
@@ -1265,9 +1306,10 @@ async function publishCommand() {
     process.exitCode = 1;
     return;
   }
-  if (manifest.name.toLowerCase() !== repoName.toLowerCase()) {
+  const expectedName = dir ? `${repoName}/${dir}` : repoName;
+  if (manifest.name.toLowerCase() !== expectedName.toLowerCase()) {
     error(
-      `Manifest name "${manifest.name}" does not match repository name "${repoName}".`
+      `Manifest name "${manifest.name}" does not match expected name "${expectedName}".`
     );
     process.exitCode = 1;
     return;
@@ -1317,6 +1359,9 @@ Make sure you have pushed your code to GitHub.`
   console.log(`  Name:        ${manifest.name}`);
   console.log(`  Version:     ${manifest.version}`);
   console.log(`  Repository:  ${repo}`);
+  if (dir) {
+    console.log(`  Directory:   ${dir}`);
+  }
   console.log(`  Targets:     ${manifest.targets.join(", ")}`);
   if (manifest.tags?.length) {
     console.log(`  Tags:        ${manifest.tags.join(", ")}`);
@@ -1338,11 +1383,15 @@ Make sure you have pushed your code to GitHub.`
         targets: manifest.targets,
         tags: manifest.tags
       },
-      token
+      token,
+      dir
     );
     spinner.success("Published successfully!");
     console.log();
-    info(`Users can now install with: ${import_chalk3.default.cyan(`npx updose add ${repo}`)}`);
+    const installPath = dir ? `${repo}/${dir}` : repo;
+    info(
+      `Users can now install with: ${import_chalk3.default.cyan(`npx updose add ${installPath}`)}`
+    );
   } catch (err) {
     spinner.fail("Publication failed");
     error(err.message);
@@ -1421,17 +1470,18 @@ function formatResult(bp) {
   if (bp.tags.length > 0) {
     console.log(`    ${bp.tags.map((t) => import_chalk4.default.dim(`#${t}`)).join(" ")}`);
   }
-  console.log(`    ${import_chalk4.default.dim(bp.repo)}`);
+  const repoPath = bp.dir ? `${bp.repo}/${bp.dir}` : bp.repo;
+  console.log(`    ${import_chalk4.default.dim(repoPath)}`);
   console.log();
 }
 
 // src/index.ts
 var program = new import_commander.Command();
-program.name("updose").description("AI coding tool boilerplate marketplace").version("0.2.0");
+program.name("updose").description("AI coding tool boilerplate marketplace").version("0.3.0");
 program.command("add <repo>").description("Install a boilerplate").option("-y, --yes", "Skip all prompts and use defaults").option("--dry-run", "Preview install without writing files").action(addCommand);
 program.command("search [query]").description("Search for boilerplates").option("--target <target>", "Filter by target (claude, codex, gemini)").option("--tag <tag>", "Filter by tag").option("--author <author>", "Filter by author").action(searchCommand);
-program.command("init").description("Scaffold a new boilerplate repository").action(initCommand);
-program.command("publish").description("Publish your boilerplate to the registry").action(publishCommand);
+program.command("init").description("Scaffold a new boilerplate repository").option("--dir <dir>", "Create boilerplate in a subdirectory").action(initCommand);
+program.command("publish").description("Publish your boilerplate to the registry").option("--dir <dir>", "Publish from a subdirectory").action(publishCommand);
 program.command("login").description("Log in to GitHub").action(loginCommand);
 program.command("logout").description("Log out from GitHub").action(logoutCommand);
 program.parse();

package/dist/index.js

@@ -29,18 +29,18 @@ async function searchBoilerplates(query, filters) {
   }
   return await res.json();
 }
-async function recordDownload(repo) {
+async function recordDownload(repo, dir) {
   await fetch(`${API_BASE_URL}/download`, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       "User-Agent": USER_AGENT
     },
-    body: JSON.stringify({ repo }),
+    body: JSON.stringify({ repo, dir: dir ?? null }),
     signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
   });
 }
-async function registerBoilerplate(repo, manifest, githubToken) {
+async function registerBoilerplate(repo, manifest, githubToken, dir) {
   const res = await fetch(`${API_BASE_URL}/register`, {
     method: "POST",
     headers: {
@@ -48,7 +48,7 @@ async function registerBoilerplate(repo, manifest, githubToken) {
       Authorization: `Bearer ${githubToken}`,
       "User-Agent": USER_AGENT
     },
-    body: JSON.stringify({ repo, manifest }),
+    body: JSON.stringify({ repo, manifest, dir: dir ?? null }),
     signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
   });
   if (!res.ok) {
@@ -286,6 +286,18 @@ function optionalStringArray(obj, key) {
 // src/core/github.ts
 var GITHUB_RAW = "https://raw.githubusercontent.com";
 var FETCH_TIMEOUT_MS2 = 3e4;
+function parseRepoInput(input) {
+  const parts = input.split("/");
+  if (parts.length < 2 || !parts[0] || !parts[1]) {
+    throw new Error(
+      `Invalid repository format: "${input}". Expected "owner/repo" or "owner/repo/dir".`
+    );
+  }
+  const repo = `${parts[0]}/${parts[1]}`;
+  const raw = parts.length > 2 ? parts.slice(2).join("/").replace(/\/+$/, "") : void 0;
+  const dir = raw || void 0;
+  return { repo, dir };
+}
 function parseRepo(repo) {
   const parts = repo.split("/");
   if (parts.length !== 2 || !parts[0] || !parts[1]) {
@@ -365,11 +377,12 @@ async function fetchFile(repo, path) {
   }
   return res.text();
 }
-async function fetchManifest(repo) {
-  const content = await fetchFile(repo, MANIFEST_FILENAME);
+async function fetchManifest(repo, dir) {
+  const path = dir ? `${dir}/${MANIFEST_FILENAME}` : MANIFEST_FILENAME;
+  const content = await fetchFile(repo, path);
   if (content === null) {
     throw new Error(
-      `No ${MANIFEST_FILENAME} found in ${repo}. Is this an updose boilerplate?`
+      `No ${MANIFEST_FILENAME} found in ${dir ? `${repo}/${dir}` : repo}. Is this an updose boilerplate?`
     );
   }
   let raw;
@@ -407,8 +420,9 @@ async function fetchRepoTree(repo) {
   }
   return data.tree.filter((entry) => entry.type === "blob");
 }
-async function fetchSkillsJson(repo) {
-  return fetchFile(repo, SKILLS_FILENAME);
+async function fetchSkillsJson(repo, dir) {
+  const path = dir ? `${dir}/${SKILLS_FILENAME}` : SKILLS_FILENAME;
+  return fetchFile(repo, path);
 }
 
 // src/core/installer.ts
@@ -591,15 +605,16 @@ async function settledPool(tasks, limit) {
   );
   return results;
 }
-async function addCommand(repo, options) {
+async function addCommand(repoInput, options) {
   try {
+    const { repo, dir } = parseRepoInput(repoInput);
     const cwd = process.cwd();
     const skipPrompts = options.yes ?? false;
     const dryRun = options.dryRun ?? false;
     const manifestSpinner = createSpinner("Fetching updose.json...").start();
     let manifest;
     try {
-      manifest = await fetchManifest(repo);
+      manifest = await fetchManifest(repo, dir);
       manifestSpinner.success(
         `Found ${manifest.name} by ${manifest.author} (v${manifest.version})`
       );
@@ -632,7 +647,7 @@ async function addCommand(repo, options) {
     const filesByTarget = /* @__PURE__ */ new Map();
     for (const target of selectedTargets) {
       const sourceDir = getSourceDir(target);
-      const prefix = `${sourceDir}/`;
+      const prefix = dir ? `${dir}/${sourceDir}/` : `${sourceDir}/`;
       const files = tree.filter((entry) => {
         if (!entry.path.startsWith(prefix)) return false;
         const relativePath = entry.path.slice(prefix.length);
@@ -665,7 +680,7 @@ async function addCommand(repo, options) {
           dryRunCount++;
         }
       }
-      const skillsContent2 = await fetchSkillsJson(repo);
+      const skillsContent2 = await fetchSkillsJson(repo, dir);
       if (skillsContent2 !== null) {
         try {
           const skillsManifest = parseSkills(
@@ -724,7 +739,7 @@ async function addCommand(repo, options) {
       }
     }
     let skillsInstalled = 0;
-    const skillsContent = await fetchSkillsJson(repo);
+    const skillsContent = await fetchSkillsJson(repo, dir);
     if (skillsContent === null) {
       info("No skills.json found \u2014 skipping skills installation.");
     } else {
@@ -772,7 +787,7 @@ async function addCommand(repo, options) {
     const summary = skillsInstalled > 0 ? `${installed} file(s) + ${skillsInstalled} skill(s)` : `${installed} file(s)`;
     success(`Done! ${summary} installed, ${skipped} skipped.`);
     if (installed + skillsInstalled > 0) {
-      await recordDownload(repo).catch(() => {
+      await recordDownload(repo, dir).catch(() => {
       });
     }
   } catch (err) {
@@ -785,6 +800,7 @@ async function addCommand(repo, options) {
 
 // src/commands/init.ts
 import { execSync } from "child_process";
+import { mkdir as mkdir2 } from "fs/promises";
 import { basename, join as join2 } from "path";
 import prompts2 from "prompts";
 var DEFAULT_VERSION = "0.1.0";
@@ -890,10 +906,16 @@ function buildFileList(name, description, author, targets) {
   }
   return files;
 }
-async function initCommand() {
+async function initCommand(options) {
   try {
     const cwd = process.cwd();
-    const defaultName = basename(cwd);
+    const dir = options.dir;
+    const baseDir = dir ? join2(cwd, dir) : cwd;
+    if (dir) {
+      await mkdir2(baseDir, { recursive: true });
+    }
+    const repoName = basename(cwd);
+    const defaultName = dir ? `${repoName}/${dir}` : repoName;
     const gitUser = getGitHubUsername();
     info("Scaffolding a new updose boilerplate...\n");
     let cancelled = false;
@@ -950,7 +972,7 @@ async function initCommand() {
     let created = 0;
     let skipped = 0;
     for (const file of files) {
-      const destPath = join2(cwd, file.path);
+      const destPath = join2(baseDir, file.path);
       const exists = await fileExists(destPath);
       if (exists) {
         const { action } = await prompts2({
@@ -976,14 +998,21 @@ async function initCommand() {
     success(`Boilerplate scaffolded! (${created} created, ${skipped} skipped)`);
     console.log();
     info("Next steps:");
-    console.log(
-      `  1. Edit your boilerplate files in ${targets.map((t) => `${t}/`).join(", ")}`
-    );
+    const editDirs = targets.map((t) => dir ? `${dir}/${t}/` : `${t}/`);
+    console.log(`  1. Edit your boilerplate files in ${editDirs.join(", ")}`);
     console.log("  2. Push to GitHub");
-    console.log("  3. Publish with: npx updose publish");
     console.log(
-      `  4. Others can install with: npx updose add ${author}/${name}`
+      `  3. Publish with: npx updose publish${dir ? ` --dir ${dir}` : ""}`
     );
+    if (dir) {
+      console.log(
+        `  4. Others can install with: npx updose add ${author}/${repoName}/${dir}`
+      );
+    } else {
+      console.log(
+        `  4. Others can install with: npx updose add ${author}/${name}`
+      );
+    }
   } catch (err) {
     error(
       err instanceof Error ? err.message : "An unexpected error occurred during init."
@@ -993,7 +1022,7 @@ async function initCommand() {
 }
 
 // src/auth/github-oauth.ts
-import { mkdir as mkdir2, readFile as readFile2, unlink, writeFile as writeFile2 } from "fs/promises";
+import { mkdir as mkdir3, readFile as readFile2, unlink, writeFile as writeFile2 } from "fs/promises";
 import { homedir } from "os";
 import { join as join3 } from "path";
 import chalk2 from "chalk";
@@ -1075,7 +1104,7 @@ async function login() {
     throw new Error("GitHub authorization failed");
   }
   const username = await fetchUsername(token);
-  await mkdir2(AUTH_DIR, { recursive: true });
+  await mkdir3(AUTH_DIR, { recursive: true });
   await writeFile2(
     AUTH_FILE,
     JSON.stringify(
@@ -1196,20 +1225,32 @@ async function logoutCommand() {
 
 // src/commands/publish.ts
 import { execSync as execSync2 } from "child_process";
+import { existsSync } from "fs";
 import { readFile as readFile3 } from "fs/promises";
 import { join as join4 } from "path";
 import chalk3 from "chalk";
 var FETCH_TIMEOUT_MS3 = 1e4;
-async function publishCommand() {
+async function publishCommand(options) {
   const cwd = process.cwd();
+  const dir = options.dir;
+  const manifestDir = dir ? join4(cwd, dir) : cwd;
+  if (dir && !existsSync(manifestDir)) {
+    error(`Directory "${dir}" does not exist.`);
+    process.exitCode = 1;
+    return;
+  }
   let raw;
   try {
-    const content = await readFile3(join4(cwd, MANIFEST_FILENAME), "utf-8");
+    const content = await readFile3(
+      join4(manifestDir, MANIFEST_FILENAME),
+      "utf-8"
+    );
     raw = JSON.parse(content);
   } catch (err) {
     if (err.code === "ENOENT") {
+      const location = dir ? `"${dir}"` : "current directory";
       error(
-        `No ${MANIFEST_FILENAME} found in current directory. Run \`updose init\` first.`
+        `No ${MANIFEST_FILENAME} found in ${location}. Run \`updose init\` first.`
       );
     } else {
       error(
@@ -1243,9 +1284,10 @@ async function publishCommand() {
     process.exitCode = 1;
     return;
   }
-  if (manifest.name.toLowerCase() !== repoName.toLowerCase()) {
+  const expectedName = dir ? `${repoName}/${dir}` : repoName;
+  if (manifest.name.toLowerCase() !== expectedName.toLowerCase()) {
     error(
-      `Manifest name "${manifest.name}" does not match repository name "${repoName}".`
+      `Manifest name "${manifest.name}" does not match expected name "${expectedName}".`
     );
     process.exitCode = 1;
     return;
@@ -1295,6 +1337,9 @@ Make sure you have pushed your code to GitHub.`
   console.log(`  Name:        ${manifest.name}`);
   console.log(`  Version:     ${manifest.version}`);
   console.log(`  Repository:  ${repo}`);
+  if (dir) {
+    console.log(`  Directory:   ${dir}`);
+  }
   console.log(`  Targets:     ${manifest.targets.join(", ")}`);
   if (manifest.tags?.length) {
     console.log(`  Tags:        ${manifest.tags.join(", ")}`);
@@ -1316,11 +1361,15 @@ Make sure you have pushed your code to GitHub.`
         targets: manifest.targets,
         tags: manifest.tags
       },
-      token
+      token,
+      dir
     );
     spinner.success("Published successfully!");
     console.log();
-    info(`Users can now install with: ${chalk3.cyan(`npx updose add ${repo}`)}`);
+    const installPath = dir ? `${repo}/${dir}` : repo;
+    info(
+      `Users can now install with: ${chalk3.cyan(`npx updose add ${installPath}`)}`
+    );
   } catch (err) {
     spinner.fail("Publication failed");
     error(err.message);
@@ -1399,17 +1448,18 @@ function formatResult(bp) {
   if (bp.tags.length > 0) {
     console.log(`    ${bp.tags.map((t) => chalk4.dim(`#${t}`)).join(" ")}`);
   }
-  console.log(`    ${chalk4.dim(bp.repo)}`);
+  const repoPath = bp.dir ? `${bp.repo}/${bp.dir}` : bp.repo;
+  console.log(`    ${chalk4.dim(repoPath)}`);
   console.log();
 }
 
 // src/index.ts
 var program = new Command();
-program.name("updose").description("AI coding tool boilerplate marketplace").version("0.2.0");
+program.name("updose").description("AI coding tool boilerplate marketplace").version("0.3.0");
 program.command("add <repo>").description("Install a boilerplate").option("-y, --yes", "Skip all prompts and use defaults").option("--dry-run", "Preview install without writing files").action(addCommand);
 program.command("search [query]").description("Search for boilerplates").option("--target <target>", "Filter by target (claude, codex, gemini)").option("--tag <tag>", "Filter by tag").option("--author <author>", "Filter by author").action(searchCommand);
-program.command("init").description("Scaffold a new boilerplate repository").action(initCommand);
-program.command("publish").description("Publish your boilerplate to the registry").action(publishCommand);
+program.command("init").description("Scaffold a new boilerplate repository").option("--dir <dir>", "Create boilerplate in a subdirectory").action(initCommand);
+program.command("publish").description("Publish your boilerplate to the registry").option("--dir <dir>", "Publish from a subdirectory").action(publishCommand);
 program.command("login").description("Log in to GitHub").action(loginCommand);
 program.command("logout").description("Log out from GitHub").action(logoutCommand);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "updose",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "AI coding tool boilerplate marketplace",
   "main": "dist/index.cjs",