coding-friend-cli 1.2.0 → 1.2.1

package/README.md

@@ -75,17 +75,40 @@ npm ls -g coding-friend-cli
 #└── coding-friend-cli@1.1.1 -> ./../../../../../git/coding-friend/cli
 ```
 
+### Running tests
+
+Tests are written with [Vitest](https://vitest.dev/) and live in `src/lib/__tests__/`.
+
+```bash
+cd cli
+
+# Run all tests once
+npm test
+
+# Watch mode (re-runs on file changes)
+npm run test:watch
+```
+
+Current coverage: `lib/json.ts`, `lib/paths.ts`, `lib/exec.ts`.
+
 ## Publish CLI to npm
 
+Publishing is automated via GitHub Actions (`.github/workflows/publish-cli.yml`). Push a tag with the `cli-v*` prefix to trigger it:
+
+```bash
+# Bump version in cli/package.json first, then tag and push
+git tag cli-v1.2.3
+git push origin cli-v1.2.3
+```
+
+The workflow will build, bundle, and publish to npm automatically (with provenance), then create a GitHub Release with the changelog for that version.
+
+**Manual publish (if needed):**
+
 ```bash
-# From the root of coding-friend project
 cd cli
 npm login              # Login if not already
 npm publish            # Build + bundle + publish
-
-# To bump a version
-npm version patch # 1.0.1 -> 1.0.2
-npm version minor # 1.0.1 -> 1.1.0
 ```
 
 `prepublishOnly` runs automatically: builds TypeScript → `dist/` and bundles libs from `lib/`.
@@ -96,4 +119,4 @@ npm version minor # 1.0.1 -> 1.1.0
 
 ## License
 
-MIT
+MIT

package/dist/{chunk-R6ZYK4UX.js → chunk-CSF4FAHL.js}

@@ -103,7 +103,8 @@ function ensureShellCompletion(opts) {
     const existing = extractExistingBlock(content);
     const expectedBlock = newBlock.trim();
     if (existing && existing.trim() === expectedBlock) {
-      if (!opts?.silent) log.dim(`Tab completion already up-to-date in ~/${rcName}`);
+      if (!opts?.silent)
+        log.dim(`Tab completion already up-to-date in ~/${rcName}`);
       return false;
     }
     const updated = replaceBlock(content, newBlock);

package/dist/{chunk-5HZJX47M.js → chunk-Q4DKU5IG.js}

@@ -29,12 +29,10 @@ import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 var __dirname = dirname(fileURLToPath(import.meta.url));
 function getLibPath(name) {
-  const bundled = join(__dirname, "..", "..", "lib", name);
-  if (existsSync(bundled)) return bundled;
-  const sibling = join(__dirname, "..", "..", "..", "lib", name);
-  if (existsSync(sibling)) return sibling;
+  const libDir = join(__dirname, "..", "..", "lib", name);
+  if (existsSync(libDir)) return libDir;
   throw new Error(
-    `Could not find lib/${name}. Ensure it exists in the CLI package or repo.`
+    `Could not find lib/${name}. Ensure it exists in the CLI package.`
   );
 }
 

package/dist/{dev-LZASFXZZ.js → dev-MAAWPWML.js}

@@ -17,7 +17,14 @@ import {
 } from "./chunk-IUTXHCP7.js";
 
 // src/commands/dev.ts
-import { existsSync, unlinkSync, readdirSync, statSync, mkdirSync, copyFileSync } from "fs";
+import {
+  existsSync,
+  unlinkSync,
+  readdirSync,
+  statSync,
+  mkdirSync,
+  copyFileSync
+} from "fs";
 import { resolve, join } from "path";
 import chalk from "chalk";
 var REMOTE_URL = "https://github.com/dinhanhthi/coding-friend.git";
@@ -40,7 +47,9 @@ function isMarketplaceRegistered() {
 }
 function ensureClaude() {
   if (!commandExists("claude")) {
-    log.error("Claude CLI not found. Install it first: https://docs.anthropic.com/en/docs/claude-code");
+    log.error(
+      "Claude CLI not found. Install it first: https://docs.anthropic.com/en/docs/claude-code"
+    );
     return false;
   }
   return true;
@@ -73,18 +82,30 @@ async function devOnCommand(path) {
 `);
   log.info(`Local path: ${chalk.cyan(localPath)}`);
   if (isPluginInstalled()) {
-    if (!runClaude(["plugin", "uninstall", PLUGIN_ID], "Uninstalling remote plugin...")) {
+    if (!runClaude(
+      ["plugin", "uninstall", PLUGIN_ID],
+      "Uninstalling remote plugin..."
+    )) {
       run("claude", ["plugin", "uninstall", PLUGIN_NAME]);
     }
   }
   if (isMarketplaceRegistered()) {
-    runClaude(["plugin", "marketplace", "remove", MARKETPLACE_NAME], "Removing remote marketplace...");
+    runClaude(
+      ["plugin", "marketplace", "remove", MARKETPLACE_NAME],
+      "Removing remote marketplace..."
+    );
   }
-  if (!runClaude(["plugin", "marketplace", "add", localPath], "Adding local marketplace...")) {
+  if (!runClaude(
+    ["plugin", "marketplace", "add", localPath],
+    "Adding local marketplace..."
+  )) {
     log.error("Failed to add local marketplace. Aborting.");
     return;
   }
-  if (!runClaude(["plugin", "install", PLUGIN_ID], "Installing plugin from local source...")) {
+  if (!runClaude(
+    ["plugin", "install", PLUGIN_ID],
+    "Installing plugin from local source..."
+  )) {
     if (!runClaude(["plugin", "install", PLUGIN_NAME], "Retrying install...")) {
       log.error("Failed to install local plugin.");
       return;
@@ -96,7 +117,9 @@ async function devOnCommand(path) {
   };
   writeJson(devStatePath(), devState);
   console.log();
-  log.success(`Dev mode ${chalk.green("ON")} \u2014 using local plugin from ${chalk.cyan(localPath)}`);
+  log.success(
+    `Dev mode ${chalk.green("ON")} \u2014 using local plugin from ${chalk.cyan(localPath)}`
+  );
   log.dim("Restart Claude Code to see changes.");
 }
 async function devOffCommand() {
@@ -106,22 +129,36 @@ async function devOffCommand() {
     return;
   }
   if (!ensureClaude()) return;
-  console.log(`
+  console.log(
+    `
 === ${chalk.yellow("Switching back to remote marketplace")} ===
-`);
+`
+  );
   if (isPluginInstalled()) {
-    if (!runClaude(["plugin", "uninstall", PLUGIN_ID], "Uninstalling local plugin...")) {
+    if (!runClaude(
+      ["plugin", "uninstall", PLUGIN_ID],
+      "Uninstalling local plugin..."
+    )) {
       run("claude", ["plugin", "uninstall", PLUGIN_NAME]);
     }
   }
   if (isMarketplaceRegistered()) {
-    runClaude(["plugin", "marketplace", "remove", MARKETPLACE_NAME], "Removing local marketplace...");
+    runClaude(
+      ["plugin", "marketplace", "remove", MARKETPLACE_NAME],
+      "Removing local marketplace..."
+    );
   }
-  if (!runClaude(["plugin", "marketplace", "add", REMOTE_URL], "Adding remote marketplace...")) {
+  if (!runClaude(
+    ["plugin", "marketplace", "add", REMOTE_URL],
+    "Adding remote marketplace..."
+  )) {
     log.error("Failed to add remote marketplace.");
     return;
   }
-  if (!runClaude(["plugin", "install", PLUGIN_ID], "Installing plugin from remote...")) {
+  if (!runClaude(
+    ["plugin", "install", PLUGIN_ID],
+    "Installing plugin from remote..."
+  )) {
     if (!runClaude(["plugin", "install", PLUGIN_NAME], "Retrying install...")) {
       log.error("Failed to install remote plugin.");
       return;
@@ -136,7 +173,9 @@ async function devOffCommand() {
   log.dim("Restart Claude Code to see changes.");
 }
 function getMarketplaceSource() {
-  const data = readJson(knownMarketplacesPath());
+  const data = readJson(
+    knownMarketplacesPath()
+  );
   if (!data || !(MARKETPLACE_NAME in data)) return null;
   const entry = data[MARKETPLACE_NAME];
   const src = entry.source;
@@ -171,7 +210,9 @@ async function devSyncCommand() {
   const localPath = state.localPath;
   const pluginSrcDir = join(localPath, "plugin");
   if (!existsSync(pluginSrcDir)) {
-    log.error(`No plugin/ directory found at ${localPath}. Make sure you point to the coding-friend repo root.`);
+    log.error(
+      `No plugin/ directory found at ${localPath}. Make sure you point to the coding-friend repo root.`
+    );
     return;
   }
   const cacheBase = pluginCachePath();
@@ -190,14 +231,18 @@ async function devSyncCommand() {
     }
   }
   if (!cacheVersionDir) {
-    log.error("No cached plugin version found. Run `cf dev off && cf dev on` first.");
+    log.error(
+      "No cached plugin version found. Run `cf dev off && cf dev on` first."
+    );
     return;
   }
   const shortDest = cacheVersionDir.replace(process.env.HOME ?? "", "~");
   log.step(`Syncing ${chalk.cyan(pluginSrcDir)} \u2192 ${chalk.dim(shortDest)}`);
   const fileCount = { n: 0 };
   copyDirRecursive(pluginSrcDir, cacheVersionDir, fileCount);
-  log.success(`Synced ${chalk.green(fileCount.n)} files. Restart Claude Code to apply changes.`);
+  log.success(
+    `Synced ${chalk.green(fileCount.n)} files. Restart Claude Code to apply changes.`
+  );
 }
 async function devRestartCommand(path) {
   const state = getDevState();
@@ -232,7 +277,9 @@ async function devStatusCommand() {
   } else {
     log.warn(`Marketplace "${MARKETPLACE_NAME}" not registered.`);
   }
-  log.info(`Plugin installed: ${installed ? chalk.green("yes") : chalk.yellow("no")}`);
+  log.info(
+    `Plugin installed: ${installed ? chalk.green("yes") : chalk.yellow("no")}`
+  );
 }
 export {
   devOffCommand,

package/dist/{host-BK6DYFWF.js → host-2WINWEW7.js}

@@ -1,7 +1,7 @@
 import {
   getLibPath,
   resolveDocsDir
-} from "./chunk-5HZJX47M.js";
+} from "./chunk-Q4DKU5IG.js";
 import "./chunk-HRVSKMNA.js";
 import {
   run,

package/dist/index.js

@@ -10,17 +10,19 @@ var pkg = JSON.parse(
   readFileSync(join(__dirname, "..", "package.json"), "utf-8")
 );
 var program = new Command();
-program.name("cf").description("coding-friend CLI \u2014 host learning docs, setup MCP, init projects").version(pkg.version, "-v, --version");
+program.name("cf").description(
+  "coding-friend CLI \u2014 host learning docs, setup MCP, init projects"
+).version(pkg.version, "-v, --version");
 program.command("init").description("Initialize coding-friend in current project").action(async () => {
-  const { initCommand } = await import("./init-2UKYE2KV.js");
+  const { initCommand } = await import("./init-CTCDQKIQ.js");
   await initCommand();
 });
 program.command("host").description("Build and serve learning docs as a static website").argument("[path]", "path to docs folder").option("-p, --port <port>", "port number", "3333").action(async (path, opts) => {
-  const { hostCommand } = await import("./host-BK6DYFWF.js");
+  const { hostCommand } = await import("./host-2WINWEW7.js");
   await hostCommand(path, opts);
 });
 program.command("mcp").description("Setup MCP server for learning docs").argument("[path]", "path to docs folder").action(async (path) => {
-  const { mcpCommand } = await import("./mcp-CH4SKZSX.js");
+  const { mcpCommand } = await import("./mcp-43HCE2KD.js");
   await mcpCommand(path);
 });
 program.command("statusline").description("Setup coding-friend statusline in Claude Code").action(async () => {
@@ -28,28 +30,43 @@ program.command("statusline").description("Setup coding-friend statusline in Cla
   await statuslineCommand();
 });
 program.command("update").description("Update coding-friend plugin, CLI, and statusline").option("--cli", "Update only the CLI (npm package)").option("--plugin", "Update only the Claude Code plugin").option("--statusline", "Update only the statusline").action(async (opts) => {
-  const { updateCommand } = await import("./update-5A2OP6EY.js");
+  const { updateCommand } = await import("./update-GGCBM7U4.js");
   await updateCommand(opts);
 });
-var dev = program.command("dev").description("Switch between local and remote plugin for development");
+var dev = program.command("dev").description("Development mode commands");
+program.addHelpText(
+  "after",
+  `
+Dev subcommands:
+  dev on [path]       Switch to local plugin source
+  dev off             Switch back to remote marketplace
+  dev status          Show current dev mode
+  dev sync            Copy local source to plugin cache
+  dev restart [path]  Reinstall local dev plugin (off + on)`
+);
 dev.command("on").description("Switch to local plugin source").argument("[path]", "path to local coding-friend repo (default: cwd)").action(async (path) => {
-  const { devOnCommand } = await import("./dev-LZASFXZZ.js");
+  const { devOnCommand } = await import("./dev-MAAWPWML.js");
   await devOnCommand(path);
 });
 dev.command("off").description("Switch back to remote marketplace").action(async () => {
-  const { devOffCommand } = await import("./dev-LZASFXZZ.js");
+  const { devOffCommand } = await import("./dev-MAAWPWML.js");
   await devOffCommand();
 });
 dev.command("status").description("Show current dev mode").action(async () => {
-  const { devStatusCommand } = await import("./dev-LZASFXZZ.js");
+  const { devStatusCommand } = await import("./dev-MAAWPWML.js");
   await devStatusCommand();
 });
-dev.command("sync").description("Copy local source files to plugin cache (no version bump needed)").action(async () => {
-  const { devSyncCommand } = await import("./dev-LZASFXZZ.js");
+dev.command("sync").description(
+  "Copy local source files to plugin cache (no version bump needed)"
+).action(async () => {
+  const { devSyncCommand } = await import("./dev-MAAWPWML.js");
   await devSyncCommand();
 });
-dev.command("restart").description("Reinstall local dev plugin (off + on)").argument("[path]", "path to local coding-friend repo (default: saved path or cwd)").action(async (path) => {
-  const { devRestartCommand } = await import("./dev-LZASFXZZ.js");
+dev.command("restart").description("Reinstall local dev plugin (off + on)").argument(
+  "[path]",
+  "path to local coding-friend repo (default: saved path or cwd)"
+).action(async (path) => {
+  const { devRestartCommand } = await import("./dev-MAAWPWML.js");
   await devRestartCommand(path);
 });
 program.parse();

package/dist/{init-2UKYE2KV.js → init-CTCDQKIQ.js}

@@ -4,7 +4,7 @@ import {
 import {
   ensureShellCompletion,
   hasShellCompletion
-} from "./chunk-R6ZYK4UX.js";
+} from "./chunk-CSF4FAHL.js";
 import {
   run
 } from "./chunk-UFGNO6CW.js";
@@ -183,7 +183,9 @@ async function setupLearnConfig(gitAvailable = true) {
   });
   let categories = DEFAULT_CONFIG.learn.categories;
   if (catChoice === "custom") {
-    console.log('Enter categories (format: "name: description"). Empty line to finish.');
+    console.log(
+      'Enter categories (format: "name: description"). Empty line to finish.'
+    );
     const customCats = [];
     let keepGoing = true;
     while (keepGoing) {
@@ -265,7 +267,11 @@ async function setupClaudePermissions(outputDir, autoCommit) {
   }
   permissions.allow = [...existing, ...missing];
   settings.permissions = permissions;
-  const { readJson: _r, writeJson: _w, ...restImports } = await import("./json-2XS56OJY.js");
+  const {
+    readJson: _r,
+    writeJson: _w,
+    ...restImports
+  } = await import("./json-2XS56OJY.js");
   _w(settingsPath, settings);
   log.success(`Added ${missing.length} permission rules.`);
 }
@@ -287,9 +293,7 @@ function isDefaultConfig(config) {
 }
 async function saveConfig(config) {
   if (isDefaultConfig(config)) {
-    log.dim(
-      "All settings match defaults \u2014 no config file needed."
-    );
+    log.dim("All settings match defaults \u2014 no config file needed.");
     return;
   }
   const target = await select({
@@ -321,10 +325,20 @@ async function initCommand() {
   const hasExternalDir = checkLearnConfig() && isExternalOutputDir(resolvedOutputDir);
   const steps = [
     { name: "docs", label: "Create docs folders", done: checkDocsFolders() },
-    ...gitAvailable ? [{ name: "gitignore", label: "Configure .gitignore", done: checkGitignore() }] : [],
+    ...gitAvailable ? [
+      {
+        name: "gitignore",
+        label: "Configure .gitignore",
+        done: checkGitignore()
+      }
+    ] : [],
     { name: "language", label: "Set docs language", done: checkLanguage() },
     { name: "learn", label: "Configure /cf-learn", done: checkLearnConfig() },
-    { name: "completion", label: "Setup shell tab completion", done: hasShellCompletion() }
+    {
+      name: "completion",
+      label: "Setup shell tab completion",
+      done: hasShellCompletion()
+    }
   ];
   if (hasExternalDir && resolvedOutputDir) {
     steps.push({
@@ -405,10 +419,7 @@ async function initCommand() {
         break;
       case "permissions":
         if (resolvedOutputDir) {
-          await setupClaudePermissions(
-            resolvedOutputDir,
-            learnAutoCommit
-          );
+          await setupClaudePermissions(resolvedOutputDir, learnAutoCommit);
         }
         break;
     }

package/dist/{mcp-CH4SKZSX.js → mcp-43HCE2KD.js}

@@ -1,7 +1,7 @@
 import {
   getLibPath,
   resolveDocsDir
-} from "./chunk-5HZJX47M.js";
+} from "./chunk-Q4DKU5IG.js";
 import "./chunk-HRVSKMNA.js";
 import {
   run

package/dist/postinstall.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   ensureShellCompletion
-} from "./chunk-R6ZYK4UX.js";
+} from "./chunk-CSF4FAHL.js";
 import "./chunk-6DUFTBTO.js";
 
 // src/postinstall.ts

package/dist/{update-5A2OP6EY.js → update-GGCBM7U4.js}

@@ -1,6 +1,6 @@
 import {
   ensureShellCompletion
-} from "./chunk-R6ZYK4UX.js";
+} from "./chunk-CSF4FAHL.js";
 import {
   commandExists,
   run,
@@ -126,10 +126,16 @@ async function updateCommand(opts) {
   const statuslineVersion = getStatuslineVersion();
   const cliVersion = getCliVersion();
   const latestCliVersion = getLatestCliVersion();
-  log.info(`Plugin version: ${currentVersion ? `v${currentVersion}` : chalk.yellow("not found")}`);
-  log.info(`Latest plugin version: ${latestVersion ? chalk.green(`v${latestVersion}`) : chalk.yellow("unknown (cannot reach GitHub)")}`);
+  log.info(
+    `Plugin version: ${currentVersion ? `v${currentVersion}` : chalk.yellow("not found")}`
+  );
+  log.info(
+    `Latest plugin version: ${latestVersion ? chalk.green(`v${latestVersion}`) : chalk.yellow("unknown (cannot reach GitHub)")}`
+  );
   log.info(`CLI version: v${cliVersion}`);
-  log.info(`Latest CLI version: ${latestCliVersion ? chalk.green(`v${latestCliVersion}`) : chalk.yellow("unknown (cannot reach npm)")}`);
+  log.info(
+    `Latest CLI version: ${latestCliVersion ? chalk.green(`v${latestCliVersion}`) : chalk.yellow("unknown (cannot reach npm)")}`
+  );
   log.info(
     `Statusline version: ${statuslineVersion ? chalk.green(`v${statuslineVersion}`) : chalk.yellow("not configured")}`
   );
@@ -140,15 +146,23 @@ async function updateCommand(opts) {
         "Cannot check latest plugin version. Verify manually at https://github.com/dinhanhthi/coding-friend/releases"
       );
     } else if (!currentVersion) {
-      log.warn("Plugin not installed. Run: claude plugin install coding-friend@coding-friend-marketplace");
+      log.warn(
+        "Plugin not installed. Run: claude plugin install coding-friend@coding-friend-marketplace"
+      );
     } else {
       const cmp = semverCompare(currentVersion, latestVersion);
       if (cmp === 0) {
-        log.success(`Plugin already on the latest version (${chalk.green(`v${latestVersion}`)}).`);
+        log.success(
+          `Plugin already on the latest version (${chalk.green(`v${latestVersion}`)}).`
+        );
       } else if (cmp > 0) {
-        log.info(`Plugin is ahead of latest release (local: ${chalk.cyan(`v${currentVersion}`)}, latest: v${latestVersion}). Skipping.`);
+        log.info(
+          `Plugin is ahead of latest release (local: ${chalk.cyan(`v${currentVersion}`)}, latest: v${latestVersion}). Skipping.`
+        );
       } else {
-        log.step(`Plugin update available: ${chalk.yellow(`v${currentVersion}`)} \u2192 ${chalk.green(`v${latestVersion}`)}`);
+        log.step(
+          `Plugin update available: ${chalk.yellow(`v${currentVersion}`)} \u2192 ${chalk.green(`v${latestVersion}`)}`
+        );
         if (!commandExists("claude")) {
           log.error(
             "Claude CLI not found. Install it first, or run: claude plugin update coding-friend@coding-friend-marketplace"
@@ -161,7 +175,9 @@ async function updateCommand(opts) {
             "coding-friend@coding-friend-marketplace"
           ]);
           if (result === null) {
-            log.error("Plugin update failed. Try manually: claude plugin update coding-friend@coding-friend-marketplace");
+            log.error(
+              "Plugin update failed. Try manually: claude plugin update coding-friend@coding-friend-marketplace"
+            );
           } else {
             log.success("Plugin updated!");
             let newVersion = currentVersion;
@@ -188,15 +204,27 @@ async function updateCommand(opts) {
     } else {
       const cmp = semverCompare(cliVersion, latestCliVersion);
       if (cmp === 0) {
-        log.success(`CLI already on the latest version (${chalk.green(`v${latestCliVersion}`)}).`);
+        log.success(
+          `CLI already on the latest version (${chalk.green(`v${latestCliVersion}`)}).`
+        );
       } else if (cmp > 0) {
-        log.info(`CLI is ahead of latest release (local: ${chalk.cyan(`v${cliVersion}`)}, latest: v${latestCliVersion}). Skipping.`);
+        log.info(
+          `CLI is ahead of latest release (local: ${chalk.cyan(`v${cliVersion}`)}, latest: v${latestCliVersion}). Skipping.`
+        );
       } else {
-        log.step(`CLI update available: ${chalk.yellow(`v${cliVersion}`)} \u2192 ${chalk.green(`v${latestCliVersion}`)}`);
+        log.step(
+          `CLI update available: ${chalk.yellow(`v${cliVersion}`)} \u2192 ${chalk.green(`v${latestCliVersion}`)}`
+        );
         log.step("Updating CLI...");
-        const result = run("npm", ["install", "-g", "coding-friend-cli@latest"]);
+        const result = run("npm", [
+          "install",
+          "-g",
+          "coding-friend-cli@latest"
+        ]);
         if (result === null) {
-          log.error("CLI update failed. Try manually: npm install -g coding-friend-cli@latest");
+          log.error(
+            "CLI update failed. Try manually: npm install -g coding-friend-cli@latest"
+          );
         } else {
           log.success(`CLI updated to ${chalk.green(`v${latestCliVersion}`)}`);
         }
@@ -208,7 +236,9 @@ async function updateCommand(opts) {
     if (targetVersion) {
       log.step("Updating statusline...");
       if (updateStatusline(targetVersion)) {
-        log.success(`Statusline updated to ${chalk.green(`v${targetVersion}`)}`);
+        log.success(
+          `Statusline updated to ${chalk.green(`v${targetVersion}`)}`
+        );
       }
     } else {
       log.warn("No cached plugin version found for statusline update.");

package/lib/learn-host/.prettierignore

@@ -1,3 +1,4 @@
 node_modules
 .next
+out
 public/_pagefind

package/lib/learn-host/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog (Learn Host)
 
+## v0.0.2 (2026-03-01)
+
+- Update header styling for consistency with ecosystem redesign
+- Code formatting and style improvements
+
 ## v0.0.1
 
 - Next.js app for hosting learning docs at `localhost:3333`

package/lib/learn-host/README.md

@@ -0,0 +1,114 @@
+# coding-friend-learn-host
+
+Next.js app that renders your `/cf-learn` docs as a browsable website with search, categories, and dark mode.
+
+## Usage (via CLI)
+
+```bash
+cf host                     # serves docs/learn/ on port 3333
+cf host ./my-docs           # serves a custom directory
+cf host -p 4000             # custom port
+```
+
+The CLI handles deps install, build, and serving automatically.
+
+## Local Development
+
+Run the app directly without the CLI — useful when working on the UI itself.
+
+### 1. Install dependencies
+
+```bash
+cd cli/lib/learn-host
+npm install
+```
+
+### 2. Point to a docs directory
+
+The app resolves docs via (in order):
+
+1. `DOCS_DIR` env var
+2. Local `.coding-friend/config.json` → `learn.outputDir`
+3. Global `~/.coding-friend/config.json` → `learn.outputDir`
+4. Default: `docs/learn/` relative to project root
+
+For local dev, set `DOCS_DIR` to any directory with the expected structure:
+
+```
+docs/
+└── learn/
+    ├── category-one/
+    │   ├── my-doc.md
+    │   └── another-doc.md
+    └── category-two/
+        └── some-doc.md
+```
+
+Each `.md` file should have frontmatter:
+
+```md
+---
+title: My Doc Title
+category: category-one
+tags: [typescript, patterns]
+created: 2025-01-01
+updated: 2025-01-15
+---
+
+Content here...
+```
+
+### 3. Run dev server
+
+```bash
+# Point to this repo's own learn docs (if they exist)
+DOCS_DIR=../../../docs/learn npm run dev
+
+# Or point to any other project's docs
+DOCS_DIR=/path/to/your/project/docs/learn npm run dev
+```
+
+App runs at `http://localhost:3333`.
+
+> **Note:** `npm run dev` does not rebuild the Pagefind search index. If you've previously run `npm run build`, search will still work but uses the old index — new or edited docs won't appear in search results until you build again.
+
+### 4. Full build (with search)
+
+```bash
+DOCS_DIR=/path/to/docs npm run build
+npx next start -p 3333
+```
+
+`postbuild` runs `pagefind` to index docs for full-text search.
+
+## Structure
+
+```
+src/
+├── app/
+│   ├── page.tsx                   # Homepage: recent docs, categories, tags
+│   ├── [category]/page.tsx        # Category listing
+│   ├── [category]/[slug]/page.tsx # Individual doc
+│   └── layout.tsx
+├── components/
+│   ├── MarkdownRenderer.tsx       # Renders .md with syntax highlighting
+│   ├── TableOfContents.tsx        # Auto-generated from headings
+│   ├── Sidebar.tsx                # Category navigation
+│   ├── PagefindSearch.tsx         # Full-text search (build-time index)
+│   └── ThemeToggle.tsx
+└── lib/
+    ├── docs.ts                    # getAllDocs, getDocBySlug, etc.
+    └── types.ts
+```
+
+## How It Fits Together
+
+```
+cf host [path]
+  └─ resolves docs dir
+  └─ npm install (one-time)
+  └─ npm run build  (with DOCS_DIR env)
+  └─ npx next start -p 3333  (with DOCS_DIR env)
+```
+
+ISR (Incremental Static Regeneration) is enabled, so new or edited docs appear on the next page refresh without a rebuild.