nrdocs 0.1.4 → 0.1.6

package/dist/bin.mjs

@@ -498,10 +498,10 @@ async function prompt(question) {
     input: process.stdin,
     output: process.stdout
   });
-  return new Promise((resolve7) => {
+  return new Promise((resolve8) => {
     rl.question(question, (answer) => {
       rl.close();
-      resolve7(answer.trim());
+      resolve8(answer.trim());
     });
   });
 }
@@ -608,17 +608,18 @@ async function prompt2(question, defaultValue) {
     output: process.stdout
   });
   const suffix = defaultValue ? ` (${defaultValue})` : "";
-  return new Promise((resolve7) => {
+  return new Promise((resolve8) => {
     rl.question(`${question}${suffix}: `, (answer) => {
       rl.close();
-      resolve7(answer.trim() || defaultValue || "");
+      resolve8(answer.trim() || defaultValue || "");
     });
   });
 }
-function generateNrdocsYml(title, requestedAccess) {
+function generateNrdocsYml(title, apiUrl, requestedAccess) {
   let yml = `# nrdocs site configuration
 site:
   title: "${title}"
+  api_url: ${apiUrl}
 
 content:
   index: index.md
@@ -670,6 +671,11 @@ jobs:
       - name: Install nrdocs CLI
         run: npm install -g nrdocs
 
+      - name: Diagnose setup
+        run: nrdocs doctor --ci
+        env:
+          NRDOCS_API_URL: ${apiUrl}
+
       - name: Publish docs
         run: nrdocs publish --docs-dir ${docsDir}
         env:
@@ -780,7 +786,7 @@ async function handleInit(args2) {
   fs2.mkdirSync(workflowDir, { recursive: true });
   const createdConfig = !configExists || opts.force;
   if (createdConfig) {
-    fs2.writeFileSync(configFile, generateNrdocsYml(title, opts.requestedAccess));
+    fs2.writeFileSync(configFile, generateNrdocsYml(title, apiUrl, opts.requestedAccess));
   }
   const createdIndex = !fs2.existsSync(indexFile);
   if (createdIndex) {
@@ -803,13 +809,13 @@ async function handleInit(args2) {
   }
   console.log("");
   console.log("Next steps:");
-  console.log("  1. Commit and push to trigger the workflow");
-  console.log("  2. Ask your operator to approve the repo");
+  console.log("  1. Add markdown files under docs/, then run: nrdocs nav generate");
+  console.log("  2. Commit and push to trigger the workflow");
+  console.log("  3. Ask your operator to approve the repo");
 }
 
 // src/commands/publish.ts
-import * as fs6 from "node:fs";
-import * as path7 from "node:path";
+import * as fs7 from "node:fs";
 
 // src/renderer/index.ts
 import * as fs5 from "node:fs";
@@ -6016,45 +6022,80 @@ function extractTitle(markdownContent, filePath) {
 }
 function findMarkdownFiles(dir, relativeTo) {
   const results = [];
+  if (!fs3.existsSync(dir)) return results;
   const entries = fs3.readdirSync(dir, { withFileTypes: true });
   for (const entry of entries) {
     const fullPath = path4.join(dir, entry.name);
     if (entry.isDirectory()) {
       results.push(...findMarkdownFiles(fullPath, relativeTo));
     } else if (entry.isFile() && entry.name.endsWith(".md")) {
-      results.push(path4.relative(relativeTo, fullPath));
+      results.push(path4.relative(relativeTo, fullPath).replace(/\\/g, "/"));
     }
   }
   return results;
 }
-function mdPathToHref(filePath) {
-  const withoutExt = filePath.replace(/\.md$/, "");
-  if (withoutExt === "index") {
-    return "";
-  }
-  return withoutExt.replace(/\\/g, "/") + "/";
+function sortNavPaths(files, indexPath = "index.md") {
+  const normalizedIndex = indexPath.replace(/\\/g, "/");
+  const sorted = [...files].sort((a, b) => a.localeCompare(b, void 0, { numeric: true }));
+  const indexIdx = sorted.indexOf(normalizedIndex);
+  if (indexIdx <= 0) return sorted;
+  const without = sorted.filter((f) => f !== normalizedIndex);
+  return [normalizedIndex, ...without];
 }
-function generateAutoNav(docsDir) {
-  const files = findMarkdownFiles(docsDir, docsDir);
-  files.sort((a, b) => {
-    if (a === "index.md") return -1;
-    if (b === "index.md") return 1;
-    return a.localeCompare(b);
+function mdPathToHref(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  const withoutExt = normalized.replace(/\.md$/, "");
+  if (withoutExt === "index" || withoutExt.endsWith("/index")) {
+    const dir = withoutExt === "index" ? "" : withoutExt.slice(0, -"/index".length);
+    return dir ? `${dir}/` : "";
+  }
+  return `${withoutExt}/`;
+}
+function discoverNavEntries(contentDir, options) {
+  const indexPath = (options?.indexPath ?? "index.md").replace(/\\/g, "/");
+  const files = findMarkdownFiles(contentDir, contentDir);
+  const sorted = sortNavPaths(files, indexPath);
+  return sorted.map((file) => {
+    const fullPath = path4.join(contentDir, file);
+    const content = fs3.readFileSync(fullPath, "utf-8");
+    return {
+      title: extractTitle(content, file),
+      path: file
+    };
   });
+}
+function navConfigToNavItems(entries, contentDir) {
   const items = [];
-  for (const file of files) {
-    const fullPath = path4.join(docsDir, file);
-    const content = fs3.readFileSync(fullPath, "utf-8");
-    const title = extractTitle(content, file);
-    const href = mdPathToHref(file);
-    items.push({
-      title,
-      path: file,
-      href
-    });
+  const walk = (list2) => {
+    for (const entry of list2) {
+      const normalizedPath = entry.path.replace(/\\/g, "/");
+      items.push({
+        title: entry.title,
+        path: normalizedPath,
+        href: mdPathToHref(normalizedPath)
+      });
+      if (entry.children?.length) {
+        walk(entry.children);
+      }
+    }
+  };
+  walk(entries);
+  for (const item of items) {
+    const full = path4.join(contentDir, item.path);
+    if (!fs3.existsSync(full)) {
+      throw new Error(`Nav path not found: ${item.path}`);
+    }
   }
   return items;
 }
+function generateAutoNav(docsDir, indexPath = "index.md") {
+  const entries = discoverNavEntries(docsDir, { indexPath });
+  return entries.map((e) => ({
+    title: e.title,
+    path: e.path,
+    href: mdPathToHref(e.path)
+  }));
+}
 
 // src/renderer/links.ts
 function rewriteLinks(html, basePath, owner, repo) {
@@ -6266,10 +6307,16 @@ function collectFromDir(dir, rootDir, results) {
 }
 
 // src/renderer/index.ts
+function resolveNavItems(resolvedDocsDir, nav, indexPath) {
+  if (nav && nav !== "auto" && Array.isArray(nav)) {
+    return navConfigToNavItems(nav, resolvedDocsDir);
+  }
+  return generateAutoNav(resolvedDocsDir, indexPath);
+}
 async function renderSite(options) {
-  const { docsDir, siteTitle, baseUrl, owner, repo } = options;
+  const { docsDir, siteTitle, baseUrl, owner, repo, nav, indexPath = "index.md" } = options;
   const resolvedDocsDir = path6.resolve(docsDir);
-  const navItems = generateAutoNav(resolvedDocsDir);
+  const navItems = resolveNavItems(resolvedDocsDir, nav, indexPath);
   const siteBase = `/${owner}/${repo}/`;
   const renderedFiles = [];
   for (const navItem of navItems) {
@@ -6375,52 +6422,311 @@ function writeOctal(buf, value, offset, length) {
   writeString(buf, str, offset, length);
 }
 function gzipCompress(data) {
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve8, reject) => {
     zlib.gzip(data, (err, result) => {
       if (err) reject(err);
-      else resolve7(result);
+      else resolve8(result);
     });
   });
 }
 
+// src/errors.ts
+function normalizeApiBaseUrl(url) {
+  let normalized = url.trim().replace(/\/+$/, "");
+  let strippedApiSuffix = false;
+  if (normalized.endsWith("/api")) {
+    normalized = normalized.slice(0, -4);
+    strippedApiSuffix = true;
+  }
+  return { url: normalized, strippedApiSuffix };
+}
+function buildApiUrl(baseUrl, apiPath) {
+  const { url } = normalizeApiBaseUrl(baseUrl);
+  const path11 = apiPath.startsWith("/") ? apiPath : `/${apiPath}`;
+  return `${url}${path11}`;
+}
+function extractFetchError(err) {
+  if (!(err instanceof Error)) {
+    return { message: String(err), kind: "unknown" };
+  }
+  const parts = [];
+  let kind = "network_error";
+  let current = err;
+  for (let depth = 0; depth < 5 && current; depth++) {
+    if (current instanceof Error) {
+      if (current.message && !parts.includes(current.message)) {
+        parts.push(current.message);
+      }
+      const c = current;
+      if (c.code) {
+        const code2 = String(c.code);
+        parts.push(code2);
+        if (code2 === "ENOTFOUND" || code2 === "EAI_AGAIN") kind = "dns_failure";
+        else if (code2 === "ECONNREFUSED" || code2 === "ECONNRESET") kind = "connection_refused";
+        else if (code2 === "CERT_HAS_EXPIRED" || code2 === "UNABLE_TO_VERIFY_LEAF_SIGNATURE") kind = "tls_error";
+        else if (code2 === "UND_ERR_CONNECT_TIMEOUT" || code2 === "ETIMEDOUT") kind = "timeout";
+      }
+      current = c.cause;
+    } else if (typeof current === "object" && current !== null && "code" in current) {
+      parts.push(String(current.code));
+      break;
+    } else {
+      break;
+    }
+  }
+  const cause = parts.length > 1 ? parts.slice(1).join(" \u2192 ") : parts[0];
+  return {
+    message: err.message,
+    cause: cause !== err.message ? cause : void 0,
+    kind
+  };
+}
+function mapPublishExitCode(error) {
+  const code2 = error.code.toUpperCase();
+  if (code2 === "UNAUTHORIZED" || code2 === "OIDC_VERIFICATION_FAILED") return 13;
+  if (code2 === "REPO_DISABLED") return 16;
+  if (code2 === "INVALID_REQUEST" || code2 === "EXTRACTION_FAILED" || code2 === "INVALID_EXTENSION" || code2 === "PATH_TRAVERSAL" || code2 === "REJECTED_EXTENSION") {
+    return 15;
+  }
+  if (code2 === "network_error" || code2 === "timeout" || error.status === 0) return 14;
+  return 14;
+}
+function formatPublishFailure(error, context) {
+  const exitCode = mapPublishExitCode(error);
+  const publishUrl = context.apiBaseUrl ? buildApiUrl(context.apiBaseUrl, "/api/publish") : void 0;
+  const details = [];
+  if (publishUrl) details.push(`URL:     ${publishUrl}`);
+  if (error.status && error.status > 0) details.push(`HTTP:    ${error.status}`);
+  details.push(`Code:    ${error.code}`);
+  if (error.message) details.push(`Message: ${error.message}`);
+  if (error.cause) details.push(`Cause:   ${error.cause}`);
+  if (context.fullName) details.push(`Repo:    ${context.fullName}`);
+  if (context.archiveSizeBytes !== void 0) {
+    details.push(`Size:    ${(context.archiveSizeBytes / 1024).toFixed(1)} KB`);
+  }
+  if (error.responseBody) {
+    const snippet = error.responseBody.slice(0, 120).replace(/\s+/g, " ");
+    details.push(`Body:    ${snippet}${error.responseBody.length > 120 ? "\u2026" : ""}`);
+  }
+  let headline;
+  const fixes = [];
+  if (error.code === "network_error" || error.status === 0) {
+    headline = "Could not reach nrdocs API";
+    fixes.push(
+      "Check api_url in docs/nrdocs.yml and NRDOCS_API_URL in .github/workflows/nrdocs.yml match your deployment."
+    );
+    if (context.apiBaseUrl) {
+      fixes.push(`From a terminal: curl -fsS ${buildApiUrl(context.apiBaseUrl, "/api/status")}`);
+    }
+    fixes.push("Ask your operator to confirm the Worker is deployed (nrdocs deploy).");
+    fixes.push(
+      "If the API host is only reachable on a VPN or private network, GitHub Actions cannot publish to it."
+    );
+  } else if (error.code === "UNAUTHORIZED" || error.code === "OIDC_VERIFICATION_FAILED") {
+    headline = "Publish authentication rejected";
+    fixes.push("Ensure the workflow has permissions.id-token: write.");
+    fixes.push("Re-run the workflow \u2014 OIDC tokens are short-lived.");
+    fixes.push("Confirm this repo is publishing to the correct nrdocs instance URL.");
+  } else if (error.code === "REPO_NOT_ALLOWED") {
+    headline = "Publish rejected \u2014 repo not on allowlist";
+    const owner = context.fullName?.split("/")[0];
+    if (owner) {
+      fixes.push(`Ask the operator: nrdocs rules add '${owner}/*' --access password`);
+    } else {
+      fixes.push("Ask the operator to add an auto-approval rule for this repo.");
+    }
+    fixes.push("Re-run the GitHub Action after the rule exists.");
+  } else if (error.code === "REPO_DISABLED") {
+    headline = "Publish rejected \u2014 repo disabled";
+    fixes.push("Ask the operator to re-enable the repo or approve it again.");
+  } else if (error.code === "timeout") {
+    headline = "Upload timed out";
+    fixes.push("Retry the workflow; if it persists, check Worker limits and network stability.");
+  } else {
+    headline = "Publish failed";
+    fixes.push("Run nrdocs doctor (or nrdocs doctor --ci in GitHub Actions) to diagnose connectivity.");
+    if (context.fullName) {
+      fixes.push(`Check repo status: nrdocs status ${context.fullName}`);
+    }
+  }
+  return { headline, details, fixes, exitCode };
+}
+function printFailure(formatted) {
+  console.error(`
+Error: ${formatted.headline}
+`);
+  for (const line of formatted.details) {
+    console.error(`  ${line}`);
+  }
+  if (formatted.fixes.length > 0) {
+    console.error("\nWhat to try:");
+    formatted.fixes.forEach((fix, i) => {
+      console.error(`  ${i + 1}. ${fix}`);
+    });
+  }
+  console.error("");
+}
+async function probeApiStatus(baseUrl, timeoutMs = 15e3) {
+  const url = buildApiUrl(baseUrl, "/api/status");
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: controller.signal });
+    clearTimeout(timer);
+    if (!res.ok) {
+      return { ok: false, status: res.status, message: `HTTP ${res.status}` };
+    }
+    const contentType = res.headers.get("Content-Type") ?? "";
+    if (!contentType.includes("json")) {
+      const text2 = await res.text();
+      return {
+        ok: false,
+        status: res.status,
+        message: `Non-JSON response (${contentType || "unknown"}): ${text2.slice(0, 80)}`
+      };
+    }
+    const json = await res.json();
+    const version = json.data?.version;
+    return {
+      ok: true,
+      status: res.status,
+      message: version ? `OK (nrdocs ${version})` : "OK",
+      version
+    };
+  } catch (e) {
+    clearTimeout(timer);
+    const extracted = extractFetchError(e);
+    const label = extracted.kind === "timeout" ? "timed out" : extracted.cause ?? extracted.message;
+    return { ok: false, status: 0, message: label };
+  }
+}
+function parseApiUrlFromConfig(content) {
+  const match2 = content.match(/api_url:\s*["']?([^"'\n]+)["']?/);
+  return match2 ? match2[1].trim() : void 0;
+}
+function parseApiUrlFromWorkflow(content) {
+  const match2 = content.match(/NRDOCS_API_URL:\s*(\S+)/);
+  return match2 ? match2[1].trim() : void 0;
+}
+
 // src/api-client.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var PUBLISH_TIMEOUT_MS = 12e4;
 var ApiClient = class {
   baseUrl;
   token;
   constructor(baseUrl, token) {
-    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    const { url, strippedApiSuffix } = normalizeApiBaseUrl(baseUrl);
+    this.baseUrl = url;
+    if (strippedApiSuffix) {
+      console.warn(
+        "Warning: api_url should be the site base (e.g. https://docs.example.com), not \u2026/api \u2014 stripped trailing /api"
+      );
+    }
     this.token = token;
   }
-  headers() {
+  getBaseUrl() {
+    return this.baseUrl;
+  }
+  headers(contentType = "application/json") {
     return {
       Authorization: `Bearer ${this.token}`,
-      "Content-Type": "application/json"
+      "Content-Type": contentType
+    };
+  }
+  async parseJsonResponse(res, url) {
+    const contentType = res.headers?.get?.("Content-Type") ?? "";
+    let text2;
+    try {
+      text2 = await res.text();
+    } catch {
+      return {
+        ok: false,
+        error: {
+          code: "invalid_response",
+          message: "Could not read response body",
+          status: res.status,
+          url
+        }
+      };
+    }
+    if (contentType && !contentType.includes("json")) {
+      return {
+        ok: false,
+        error: {
+          code: "invalid_response",
+          message: `Expected JSON, got ${contentType}`,
+          status: res.status,
+          url,
+          responseBody: text2
+        }
+      };
+    }
+    let json;
+    try {
+      json = JSON.parse(text2);
+    } catch {
+      return {
+        ok: false,
+        error: {
+          code: "invalid_response",
+          message: "Response body is not valid JSON",
+          status: res.status,
+          url,
+          responseBody: text2
+        }
+      };
+    }
+    if (json["ok"] === true) {
+      return { ok: true, data: json["data"] };
+    }
+    const err = json["error"];
+    return {
+      ok: false,
+      error: {
+        code: err?.code ?? "unknown",
+        message: err?.message ?? `HTTP ${res.status}`,
+        status: res.status,
+        url
+      }
     };
   }
-  async request(method, path10, body) {
-    const url = `${this.baseUrl}${path10}`;
+  async request(method, path11, body, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const url = buildApiUrl(this.baseUrl, path11);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     const init = {
       method,
-      headers: this.headers()
+      headers: this.headers(),
+      signal: controller.signal
     };
     if (body !== void 0) {
       init.body = JSON.stringify(body);
     }
     try {
       const res = await fetch(url, init);
-      const json = await res.json();
-      if (json["ok"] === true) {
-        return { ok: true, status: res.status, data: json["data"] };
+      clearTimeout(timer);
+      const parsed = await this.parseJsonResponse(res, url);
+      if (parsed.ok) {
+        return { ok: true, status: res.status, data: parsed.data, url };
       }
-      const err = json["error"];
+      return { ok: false, status: res.status, error: parsed.error, url };
+    } catch (e) {
+      clearTimeout(timer);
+      const extracted = extractFetchError(e);
+      const code2 = extracted.kind === "timeout" ? "timeout" : "network_error";
       return {
         ok: false,
-        status: res.status,
-        error: err ?? { code: "unknown", message: `HTTP ${res.status}` }
+        status: 0,
+        url,
+        error: {
+          code: code2,
+          message: extracted.message,
+          cause: extracted.cause,
+          status: 0,
+          url
+        }
       };
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      return { ok: false, status: 0, error: { code: "network_error", message: msg } };
     }
   }
   async listRepos(filters) {
@@ -6473,31 +6779,145 @@ var ApiClient = class {
   async getOperatorMe() {
     return this.request("GET", "/api/operator/me");
   }
-  async publish(formData) {
-    const url = `${this.baseUrl}/api/publish`;
+  async publish(formData, verbose = false) {
+    const url = buildApiUrl(this.baseUrl, "/api/publish");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PUBLISH_TIMEOUT_MS);
+    if (verbose) {
+      console.log(`  POST ${url}`);
+    }
     try {
       const res = await fetch(url, {
         method: "POST",
         headers: { Authorization: `Bearer ${this.token}` },
-        body: formData
+        body: formData,
+        signal: controller.signal
       });
-      const json = await res.json();
-      if (json["ok"] === true) {
-        return { ok: true, status: res.status, data: json["data"] };
+      clearTimeout(timer);
+      if (verbose && res.status) {
+        console.log(`  HTTP ${res.status}`);
       }
-      const err = json["error"];
+      const parsed = await this.parseJsonResponse(res, url);
+      if (parsed.ok) {
+        return { ok: true, status: res.status, data: parsed.data, url };
+      }
+      return { ok: false, status: res.status, error: parsed.error, url };
+    } catch (e) {
+      clearTimeout(timer);
+      const extracted = extractFetchError(e);
+      const code2 = extracted.kind === "timeout" ? "timeout" : "network_error";
       return {
         ok: false,
-        status: res.status,
-        error: err ?? { code: "unknown", message: `HTTP ${res.status}` }
+        status: 0,
+        url,
+        error: {
+          code: code2,
+          message: extracted.message,
+          cause: extracted.cause,
+          status: 0,
+          url
+        }
       };
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      return { ok: false, status: 0, error: { code: "network_error", message: msg } };
     }
   }
 };
 
+// src/config/docs-config.ts
+import * as fs6 from "node:fs";
+import * as path7 from "node:path";
+import YAML from "yaml";
+function loadDocsConfig(docsDir) {
+  const configPath = path7.resolve(docsDir, "nrdocs.yml");
+  if (!fs6.existsSync(configPath)) {
+    throw new Error(`Config file not found: ${configPath}`);
+  }
+  const raw = fs6.readFileSync(configPath, "utf-8");
+  const config2 = YAML.parse(raw);
+  if (!config2 || typeof config2 !== "object") {
+    throw new Error(`Invalid config: ${configPath}`);
+  }
+  const sourceDir = config2.content?.source_dir ?? ".";
+  const contentDir = path7.resolve(docsDir, sourceDir);
+  return { config: config2, configPath, contentDir };
+}
+function hasExplicitNav(config2) {
+  return Array.isArray(config2.content?.nav);
+}
+function parseNavEntries(nav) {
+  if (!Array.isArray(nav)) {
+    throw new Error('content.nav must be a list or "auto"');
+  }
+  const entries = [];
+  for (const item of nav) {
+    if (!item || typeof item !== "object") {
+      throw new Error("Each nav entry must have title and path");
+    }
+    const rec = item;
+    if (typeof rec["title"] !== "string" || typeof rec["path"] !== "string") {
+      throw new Error("Each nav entry must have title and path strings");
+    }
+    const entry = {
+      title: rec["title"],
+      path: rec["path"].replace(/\\/g, "/")
+    };
+    if (Array.isArray(rec["children"])) {
+      entry.children = parseNavEntries(rec["children"]);
+    }
+    entries.push(entry);
+  }
+  return entries;
+}
+function getExplicitNav(config2) {
+  const nav = config2.content?.nav;
+  if (nav === void 0 || nav === "auto") return null;
+  if (Array.isArray(nav)) return parseNavEntries(nav);
+  throw new Error('content.nav must be "auto" or a list of entries');
+}
+function validateNavPaths(entries, contentDir) {
+  const errors = [];
+  const seen = /* @__PURE__ */ new Set();
+  const walk = (list2) => {
+    for (const e of list2) {
+      const p = e.path.replace(/\\/g, "/");
+      if (seen.has(p)) {
+        errors.push(`Duplicate nav path: ${p}`);
+      }
+      seen.add(p);
+      const full = path7.join(contentDir, p);
+      if (!fs6.existsSync(full)) {
+        errors.push(`Nav path not found: ${p}`);
+      }
+      if (e.children?.length) walk(e.children);
+    }
+  };
+  walk(entries);
+  return { valid: errors.length === 0, errors };
+}
+function writeNavToConfig(configPath, navEntries) {
+  let raw = fs6.readFileSync(configPath, "utf-8");
+  raw = raw.replace(/^# content\.nav generated by: nrdocs nav generate\n/gm, "");
+  const config2 = YAML.parse(raw);
+  if (!config2 || typeof config2 !== "object") {
+    throw new Error(`Invalid config: ${configPath}`);
+  }
+  if (!config2.content) {
+    config2.content = {};
+  }
+  config2.content.nav = navEntries;
+  const doc = new YAML.Document(config2);
+  const header = "# content.nav generated by: nrdocs nav generate\n";
+  const body = doc.toString();
+  fs6.writeFileSync(configPath, header + body, "utf-8");
+}
+function formatNavYaml(navEntries) {
+  const partial = {
+    content: {
+      nav: navEntries
+    }
+  };
+  return YAML.stringify(partial).trimEnd();
+}
+
 // src/commands/publish.ts
 function parsePublishArgs(args2) {
   const opts = {};
@@ -6505,15 +6925,17 @@ function parsePublishArgs(args2) {
     const arg = args2[i];
     if (arg === "--docs-dir" && i + 1 < args2.length) {
       opts.docsDir = args2[++i];
+    } else if (arg === "--verbose" || arg === "-v") {
+      opts.verbose = true;
     }
   }
   return opts;
 }
 function validateConfig2(configPath) {
-  if (!fs6.existsSync(configPath)) {
+  if (!fs7.existsSync(configPath)) {
     return { valid: false, error: `Config file not found: ${configPath}` };
   }
-  const content = fs6.readFileSync(configPath, "utf-8");
+  const content = fs7.readFileSync(configPath, "utf-8");
   if (!content.includes("site:")) {
     return { valid: false, error: 'Config file missing "site:" section' };
   }
@@ -6555,12 +6977,29 @@ async function getOIDCToken() {
 async function handlePublish(args2) {
   const opts = parsePublishArgs(args2);
   const docsDir = opts.docsDir || "docs";
-  const configPath = path7.resolve(docsDir, "nrdocs.yml");
-  const validation = validateConfig2(configPath);
+  let docsConfig;
+  try {
+    docsConfig = loadDocsConfig(docsDir);
+  } catch (e) {
+    console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(10);
+  }
+  const validation = validateConfig2(docsConfig.configPath);
   if (!validation.valid) {
     console.error(`Error: ${validation.error}`);
     process.exit(10);
   }
+  const explicitNav = getExplicitNav(docsConfig.config);
+  if (explicitNav) {
+    const navCheck = validateNavPaths(explicitNav, docsConfig.contentDir);
+    if (!navCheck.valid) {
+      console.error("Error: Invalid content.nav in nrdocs.yml:");
+      for (const err of navCheck.errors) {
+        console.error(`  - ${err}`);
+      }
+      process.exit(10);
+    }
+  }
   const ci = detectCI();
   if (!ci.inCI) {
     console.error("Error: nrdocs publish must run inside GitHub Actions.");
@@ -6585,22 +7024,31 @@ async function handlePublish(args2) {
   const { owner, repo } = repoInfo;
   const ownerLower = owner.toLowerCase();
   const repoLower = repo.toLowerCase();
+  const fullName = `${ownerLower}/${repoLower}`;
   const siteTitle = validation.title || "Documentation";
-  const apiUrl = validation.apiUrl || process.env["NRDOCS_API_URL"] || "";
-  if (!apiUrl) {
+  const rawApiUrl = validation.apiUrl || process.env["NRDOCS_API_URL"] || "";
+  if (!rawApiUrl) {
     console.error("Error: No API URL configured. Set api_url in nrdocs.yml or NRDOCS_API_URL env var.");
     process.exit(10);
   }
-  console.log(`Publishing docs for ${ownerLower}/${repoLower}...`);
+  const { url: apiUrl } = normalizeApiBaseUrl(rawApiUrl);
+  console.log(`Publishing docs for ${fullName}...`);
   console.log(`Docs directory: ${docsDir}`);
   console.log(`Site title: ${siteTitle}`);
+  if (opts.verbose) {
+    console.log(`API base: ${apiUrl}`);
+  }
   console.log("Rendering Markdown...");
+  const indexPath = docsConfig.config.content?.index ?? "index.md";
+  const navOption = explicitNav ?? "auto";
   const site = await renderSite({
-    docsDir,
+    docsDir: docsConfig.contentDir,
     siteTitle,
     baseUrl: apiUrl,
     owner: ownerLower,
-    repo: repoLower
+    repo: repoLower,
+    nav: navOption,
+    indexPath
   });
   console.log(`Rendered ${site.files.length} files.`);
   console.log("Creating archive...");
@@ -6622,106 +7070,346 @@ async function handlePublish(args2) {
     artifact: { format: "tar.gz", size_bytes: archive.length },
     nrdocs: { cli_version: "0.1.1" }
   }));
-  const result = await client.publish(formData);
+  const result = await client.publish(formData, opts.verbose);
   if (result.ok) {
+    const data = result.data;
+    const approval = data?.["approval"];
+    const serving = data?.["serving"];
+    const access = data?.["access"];
     console.log("Published successfully!");
-    console.log(`View at: ${apiUrl}/${ownerLower}/${repoLower}/`);
-  } else {
-    console.error(`Error: Upload failed \u2014 ${result.error?.message || "unknown error"}`);
-    process.exit(14);
+    if (approval?.state) {
+      console.log(`Approval: ${approval.state}`);
+    }
+    if (access?.mode) {
+      console.log(`Access:   ${access.mode}`);
+    }
+    if (serving) {
+      if (serving.visible) {
+        console.log(`Serving:  live (${serving.reason ?? "serving"})`);
+      } else {
+        console.log(`Serving:  not visible (${serving.reason ?? "unknown"})`);
+        if (serving.reason === "awaiting_operator_approval") {
+          console.log("");
+          console.log("An operator must approve this repo before docs are visible.");
+          console.log(`  nrdocs approve ${fullName} --access public`);
+        } else if (serving.reason === "needs_password") {
+          console.log("");
+          console.log("Operator must set a password before password-protected docs are served.");
+          console.log(`  nrdocs password set ${fullName}`);
+        }
+      }
+    }
+    const viewUrl = serving?.url ?? `${apiUrl}/${fullName}/`;
+    console.log(`View at: ${viewUrl}`);
+    return;
   }
+  const apiError = result.error ?? { code: "unknown", message: "unknown error" };
+  const formatted = formatPublishFailure(apiError, {
+    command: "publish",
+    apiBaseUrl: apiUrl,
+    fullName,
+    archiveSizeBytes: archive.length
+  });
+  printFailure(formatted);
+  process.exit(formatted.exitCode);
 }
 
 // src/commands/doctor.ts
-import * as fs7 from "node:fs";
+import * as fs8 from "node:fs";
 import * as path8 from "node:path";
-async function handleDoctor(_args) {
+function parseDoctorArgs(args2) {
+  const opts = {};
+  for (const arg of args2) {
+    if (arg === "--json") opts.json = true;
+    if (arg === "--ci") opts.ci = true;
+  }
+  return opts;
+}
+function countMarkdownFiles(docsDir) {
+  if (!fs8.existsSync(docsDir)) return 0;
+  let count = 0;
+  const walk = (dir) => {
+    for (const entry of fs8.readdirSync(dir, { withFileTypes: true })) {
+      const full = path8.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name.endsWith(".md")) count++;
+    }
+  };
+  walk(docsDir);
+  return count;
+}
+async function handleDoctor(args2) {
+  const opts = parseDoctorArgs(args2);
+  const inCI = opts.ci || process.env["GITHUB_ACTIONS"] === "true";
   const checks = [];
-  const isGitRepo = fs7.existsSync(path8.resolve(".git"));
+  const isGitRepo = fs8.existsSync(path8.resolve(".git"));
   checks.push({
+    section: "Repo setup",
     name: "Git repository",
     status: isGitRepo ? "ok" : "fail",
     message: isGitRepo ? "Found .git directory" : "Not a git repository"
   });
   const configPath = path8.resolve("docs", "nrdocs.yml");
-  const hasConfig = fs7.existsSync(configPath);
+  const hasConfig = fs8.existsSync(configPath);
   checks.push({
+    section: "Repo setup",
     name: "Docs config",
     status: hasConfig ? "ok" : "fail",
     message: hasConfig ? "Found docs/nrdocs.yml" : "Missing docs/nrdocs.yml \u2014 run: nrdocs init"
   });
+  const docsDir = path8.resolve("docs");
+  const mdCount = countMarkdownFiles(docsDir);
+  checks.push({
+    section: "Repo setup",
+    name: "Docs sources",
+    status: mdCount > 0 ? "ok" : "warn",
+    message: mdCount > 0 ? `${mdCount} markdown file(s) in docs/` : "No .md files in docs/ \u2014 publish will produce an empty site"
+  });
   const workflowPath = path8.resolve(".github", "workflows", "nrdocs.yml");
-  const hasWorkflow = fs7.existsSync(workflowPath);
+  const hasWorkflow = fs8.existsSync(workflowPath);
   checks.push({
+    section: "Repo setup",
     name: "GitHub workflow",
     status: hasWorkflow ? "ok" : "warn",
     message: hasWorkflow ? "Found .github/workflows/nrdocs.yml" : "Missing .github/workflows/nrdocs.yml \u2014 run: nrdocs init"
   });
-  let apiUrl;
-  let token;
-  try {
-    const creds = resolveCredentials();
-    apiUrl = creds.api_url;
-    token = creds.operator_token;
+  let configApiUrl;
+  let workflowApiUrl;
+  if (hasConfig) {
+    const content = fs8.readFileSync(configPath, "utf-8");
+    configApiUrl = parseApiUrlFromConfig(content);
     checks.push({
-      name: "API URL",
-      status: "ok",
-      message: `Configured: ${apiUrl}`
+      section: "Publish URL",
+      name: "docs/nrdocs.yml api_url",
+      status: configApiUrl ? "ok" : "warn",
+      message: configApiUrl ?? "Not set \u2014 CI uses NRDOCS_API_URL from workflow env only"
     });
-  } catch {
+  }
+  if (hasWorkflow) {
+    const wfContent = fs8.readFileSync(workflowPath, "utf-8");
+    workflowApiUrl = parseApiUrlFromWorkflow(wfContent);
     checks.push({
-      name: "API URL",
-      status: "warn",
-      message: "Not configured \u2014 run: nrdocs auth login"
+      section: "Publish URL",
+      name: "Workflow NRDOCS_API_URL",
+      status: workflowApiUrl ? "ok" : "fail",
+      message: workflowApiUrl ?? "Missing NRDOCS_API_URL in workflow",
+      fixes: workflowApiUrl ? void 0 : ["Re-run nrdocs init --api-url https://your-docs-url.com"]
     });
   }
-  if (apiUrl && token) {
-    try {
-      const client = new ApiClient(apiUrl, token);
-      const res = await client.getOperatorMe();
-      if (res.ok) {
-        checks.push({
-          name: "API connectivity",
-          status: "ok",
-          message: "Successfully connected to API"
-        });
-      } else {
+  const publishBaseUrl = workflowApiUrl ?? configApiUrl ?? process.env["NRDOCS_API_URL"];
+  if (publishBaseUrl && configApiUrl && workflowApiUrl) {
+    const a = normalizeApiBaseUrl(configApiUrl).url;
+    const b = normalizeApiBaseUrl(workflowApiUrl).url;
+    checks.push({
+      section: "Publish URL",
+      name: "URL consistency",
+      status: a === b ? "ok" : "warn",
+      message: a === b ? "docs/nrdocs.yml and workflow env match" : `Mismatch: yml=${a}, workflow=${b}`,
+      fixes: a === b ? void 0 : ["Use the same base URL in docs/nrdocs.yml and NRDOCS_API_URL in the workflow"]
+    });
+  }
+  if (publishBaseUrl) {
+    const { url } = normalizeApiBaseUrl(publishBaseUrl);
+    const probe = await probeApiStatus(url);
+    checks.push({
+      section: "API reachability",
+      name: "GET /api/status",
+      status: probe.ok ? "ok" : "fail",
+      message: probe.ok ? probe.message : probe.message,
+      fixes: probe.ok ? void 0 : [
+        `Verify the host is reachable: curl -fsS ${url}/api/status`,
+        "Confirm the operator has deployed the Worker (nrdocs deploy).",
+        "GitHub Actions uses this URL for publish \u2014 it must be public on the internet."
+      ]
+    });
+  } else {
+    checks.push({
+      section: "Publish URL",
+      name: "Publish API URL",
+      status: "fail",
+      message: "No publish URL configured",
+      fixes: [
+        "Run nrdocs init --api-url https://your-docs-url.com",
+        "Or set NRDOCS_API_URL in .github/workflows/nrdocs.yml"
+      ]
+    });
+  }
+  if (inCI) {
+    const hasOidcUrl = !!process.env["ACTIONS_ID_TOKEN_REQUEST_URL"];
+    const hasOidcToken = !!process.env["ACTIONS_ID_TOKEN_REQUEST_TOKEN"];
+    checks.push({
+      section: "GitHub Actions",
+      name: "OIDC request URL",
+      status: hasOidcUrl ? "ok" : "fail",
+      message: hasOidcUrl ? "Present" : "Missing ACTIONS_ID_TOKEN_REQUEST_URL",
+      fixes: hasOidcUrl ? void 0 : ["Add permissions.id-token: write to the workflow"]
+    });
+    checks.push({
+      section: "GitHub Actions",
+      name: "OIDC request token",
+      status: hasOidcToken ? "ok" : "fail",
+      message: hasOidcToken ? "Present" : "Missing ACTIONS_ID_TOKEN_REQUEST_TOKEN",
+      fixes: hasOidcToken ? void 0 : ["Add permissions.id-token: write to the workflow"]
+    });
+    const ghRepo = process.env["GITHUB_REPOSITORY"];
+    checks.push({
+      section: "GitHub Actions",
+      name: "GITHUB_REPOSITORY",
+      status: ghRepo ? "ok" : "fail",
+      message: ghRepo ?? "Not set"
+    });
+  }
+  let operatorApiUrl;
+  let operatorToken;
+  try {
+    const creds = resolveCredentials();
+    operatorApiUrl = creds.api_url;
+    operatorToken = creds.operator_token;
+  } catch {
+  }
+  if (operatorApiUrl && operatorToken) {
+    const client = new ApiClient(operatorApiUrl, operatorToken);
+    const res = await client.getOperatorMe();
+    checks.push({
+      section: "Operator auth",
+      name: "Operator token",
+      status: res.ok ? "ok" : "warn",
+      message: res.ok ? "Accepted (GET /api/operator/me)" : `Rejected: ${res.error?.message ?? "unknown"}`
+    });
+    if (publishBaseUrl) {
+      const opBase = normalizeApiBaseUrl(operatorApiUrl).url;
+      const pubBase = normalizeApiBaseUrl(publishBaseUrl).url;
+      if (opBase !== pubBase) {
         checks.push({
-          name: "API connectivity",
+          section: "Operator auth",
+          name: "Operator vs publish URL",
           status: "warn",
-          message: `API returned error: ${res.error?.message ?? "unknown"}`
+          message: `Operator profile uses ${opBase}, publish uses ${pubBase}`,
+          fixes: ["These can differ if intentional; publish uses workflow/config URL, not operator profile"]
         });
       }
-    } catch {
-      checks.push({
-        name: "API connectivity",
-        status: "fail",
-        message: "Could not connect to API"
-      });
     }
+  } else if (!inCI) {
+    checks.push({
+      section: "Operator auth",
+      name: "Operator token",
+      status: "warn",
+      message: "Not configured (optional for repo owners) \u2014 run: nrdocs auth login"
+    });
+  }
+  if (opts.json) {
+    console.log(JSON.stringify({ checks }, null, 2));
+    const publishFailed = checks.some(
+      (c) => (c.section === "API reachability" || c.section === "Publish URL") && c.status === "fail"
+    );
+    if (publishFailed) process.exitCode = 1;
+    return;
   }
   console.log("nrdocs doctor\n");
-  let hasFailure = false;
+  let currentSection = "";
+  let publishPathFailed = false;
+  let repoSetupFailed = false;
   for (const check of checks) {
+    if (check.section !== currentSection) {
+      currentSection = check.section;
+      console.log(`${currentSection}`);
+    }
     const icon = check.status === "ok" ? "\u2713" : check.status === "warn" ? "!" : "\u2717";
-    const prefix = check.status === "ok" ? "  " : check.status === "warn" ? "  " : "  ";
-    console.log(`${prefix}${icon} ${check.name}: ${check.message}`);
-    if (check.status === "fail") hasFailure = true;
+    console.log(`  ${icon} ${check.name}: ${check.message}`);
+    if (check.fixes?.length) {
+      for (const fix of check.fixes) {
+        console.log(`      \u2192 ${fix}`);
+      }
+    }
+    if (check.status === "fail") {
+      if (check.section === "Repo setup") repoSetupFailed = true;
+      if (check.section === "API reachability" || check.section === "Publish URL") {
+        publishPathFailed = true;
+      }
+      if (check.section === "GitHub Actions") publishPathFailed = true;
+    }
   }
   console.log("");
-  if (hasFailure) {
-    console.log("Some checks failed. Fix the issues above and run doctor again.");
+  if (publishPathFailed) {
+    console.log("Summary: Publish path checks FAILED \u2014 fix API reachability/URL before pushing.");
+    process.exitCode = 1;
+  } else if (repoSetupFailed) {
+    console.log("Summary: Repo setup checks failed.");
     process.exitCode = 1;
   } else {
-    console.log("All checks passed!");
+    console.log("Summary: All checks passed for this environment.");
+    if (!operatorToken && !inCI) {
+      console.log("(Operator auth not tested \u2014 optional for repo owners.)");
+    }
+  }
+}
+
+// src/commands/nav.ts
+import * as fs9 from "node:fs";
+import * as path9 from "node:path";
+function parseNavGenerateArgs(args2) {
+  const opts = {};
+  for (let i = 0; i < args2.length; i++) {
+    const arg = args2[i];
+    if (arg === "--docs-dir" && i + 1 < args2.length) {
+      opts.docsDir = args2[++i];
+    } else if (arg === "--force") {
+      opts.force = true;
+    } else if (arg === "--dry-run") {
+      opts.dryRun = true;
+    } else if (arg === "--json") {
+      opts.json = true;
+    }
+  }
+  return opts;
+}
+async function handleNavGenerate(args2) {
+  const opts = parseNavGenerateArgs(args2);
+  const docsDir = path9.resolve(opts.docsDir ?? "docs");
+  const configPath = path9.join(docsDir, "nrdocs.yml");
+  if (!fs9.existsSync(configPath)) {
+    console.error(`Error: Config file not found: ${configPath}`);
+    console.error("Run: nrdocs init");
+    process.exit(10);
+  }
+  let loaded;
+  try {
+    loaded = loadDocsConfig(docsDir);
+  } catch (e) {
+    console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(10);
+  }
+  if (hasExplicitNav(loaded.config) && !opts.force) {
+    console.error("Error: content.nav is already an explicit list in nrdocs.yml.");
+    console.error("Use --force to overwrite, or edit the file manually.");
+    process.exit(2);
+  }
+  const indexPath = loaded.config.content?.index ?? "index.md";
+  const entries = discoverNavEntries(loaded.contentDir, { indexPath });
+  if (entries.length === 0) {
+    console.error(`Error: No markdown files found in ${loaded.contentDir}`);
+    process.exit(10);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify({ nav: entries, files: entries.length }, null, 2));
+    if (opts.dryRun) return;
+  } else if (opts.dryRun) {
+    console.log("# Dry run \u2014 content.nav that would be written:\n");
+    console.log(formatNavYaml(entries));
+    return;
+  }
+  writeNavToConfig(loaded.configPath, entries);
+  if (!opts.json) {
+    console.log(`Generated navigation for ${entries.length} page(s) in ${path9.relative(process.cwd(), configPath)}`);
+    console.log("Edit the file to reorder or rename entries, then run publish.");
   }
 }
 
 // src/commands/deploy.ts
 import * as readline3 from "node:readline";
 import * as crypto from "node:crypto";
-import * as fs8 from "node:fs";
-import * as path9 from "node:path";
+import * as fs10 from "node:fs";
+import * as path10 from "node:path";
 import { execSync } from "node:child_process";
 function parseDeployArgs(args2) {
   const opts = {};
@@ -6745,10 +7433,10 @@ function parseDeployArgs(args2) {
 async function prompt3(question, defaultValue) {
   const rl = readline3.createInterface({ input: process.stdin, output: process.stdout });
   const suffix = defaultValue ? ` [${defaultValue}]` : "";
-  return new Promise((resolve7) => {
+  return new Promise((resolve8) => {
     rl.question(`${question}${suffix}: `, (answer) => {
       rl.close();
-      resolve7(answer.trim() || defaultValue || "");
+      resolve8(answer.trim() || defaultValue || "");
     });
   });
 }
@@ -6790,14 +7478,14 @@ function normalizeUrl2(url) {
 }
 function findWorkerDir() {
   const candidates = [
-    path9.resolve("packages/worker"),
-    path9.resolve("../worker")
+    path10.resolve("packages/worker"),
+    path10.resolve("../worker")
   ];
-  const cliDir = process.argv[1] ? path9.dirname(process.argv[1]) : process.cwd();
-  candidates.push(path9.resolve(cliDir, "../../../worker"));
-  candidates.push(path9.resolve(cliDir, "../../../../packages/worker"));
+  const cliDir = process.argv[1] ? path10.dirname(process.argv[1]) : process.cwd();
+  candidates.push(path10.resolve(cliDir, "../../../worker"));
+  candidates.push(path10.resolve(cliDir, "../../../../packages/worker"));
   for (const candidate of candidates) {
-    if (fs8.existsSync(path9.join(candidate, "src", "index.ts"))) {
+    if (fs10.existsSync(path10.join(candidate, "src", "index.ts"))) {
       return candidate;
     }
   }
@@ -6940,12 +7628,12 @@ bucket_name = "${names.r2}"
 [vars]
 BASE_URL = "${baseUrl}"
 `;
-  const wranglerPath = path9.join(workerDir, "wrangler.toml");
-  fs8.writeFileSync(wranglerPath, wranglerToml);
+  const wranglerPath = path10.join(workerDir, "wrangler.toml");
+  fs10.writeFileSync(wranglerPath, wranglerToml);
   console.log("\u2705 wrangler.toml generated");
   console.log("Applying D1 migrations...");
-  const migrationsDir = path9.join(workerDir, "migrations");
-  if (fs8.existsSync(migrationsDir)) {
+  const migrationsDir = path10.join(workerDir, "migrations");
+  if (fs10.existsSync(migrationsDir)) {
     const migResult = runSilent(`npx wrangler d1 migrations apply ${names.d1} --remote --config "${wranglerPath}"`);
     if (migResult.ok) {
       console.log("\u2705 Migrations applied");
@@ -7249,36 +7937,42 @@ function parsePasswordSetArgs(args2) {
   return opts;
 }
 async function readFromStdin() {
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve8, reject) => {
     let data = "";
     process.stdin.setEncoding("utf-8");
     process.stdin.on("data", (chunk) => {
       data += chunk;
     });
-    process.stdin.on("end", () => resolve7(data.trim()));
+    process.stdin.on("end", () => resolve8(data.trim()));
     process.stdin.on("error", reject);
   });
 }
 async function promptPassword(question) {
-  return new Promise((resolve7) => {
+  return new Promise((resolve8) => {
     const rl = readline4.createInterface({
       input: process.stdin,
-      output: process.stdout
-    });
-    if (process.stdin.isTTY) {
-      process.stdin.setRawMode?.(false);
-    }
-    rl.question(question, (answer) => {
-      rl.close();
-      console.log("");
-      resolve7(answer.trim());
+      output: process.stdout,
+      terminal: true
     });
     const origWrite = process.stdout.write.bind(process.stdout);
-    process.stdout.write = ((chunk) => {
-      if (typeof chunk === "string" && !chunk.includes(question) && chunk !== "\n") {
+    let maskInput = false;
+    process.stdout.write = ((chunk, encodingOrCb, cb) => {
+      if (maskInput && typeof chunk === "string" && chunk !== "\n" && chunk !== "\r\n") {
+        if (typeof encodingOrCb === "function") encodingOrCb();
+        else if (typeof cb === "function") cb();
         return true;
       }
-      return origWrite(chunk);
+      return origWrite(chunk, encodingOrCb, cb);
+    });
+    rl.question(question, (answer) => {
+      maskInput = false;
+      process.stdout.write = origWrite;
+      rl.close();
+      process.stdout.write("\n");
+      resolve8(answer.trim());
+    });
+    setImmediate(() => {
+      maskInput = true;
     });
   });
 }
@@ -7506,7 +8200,8 @@ async function handleStatus(args2) {
     console.error('Error: Repository must be in "owner/repo" format.');
     process.exit(2);
   }
-  const [owner, repo] = parts;
+  const owner = parts[0].toLowerCase();
+  const repo = parts[1].toLowerCase();
   let creds;
   try {
     creds = resolveCredentials();
@@ -7524,8 +8219,9 @@ async function handleStatus(args2) {
     console.log(JSON.stringify(res.data, null, 2));
     return;
   }
-  const data = res.data;
-  console.log(`Repository: ${owner}/${repo}`);
+  const payload = res.data;
+  const data = payload["repo"] ?? payload;
+  console.log(`Repository: ${String(data["full_name"] ?? `${owner}/${repo}`)}`);
   console.log(`State:      ${String(data["approval_state"] ?? "-")}`);
   console.log(`Access:     ${String(data["access_mode"] ?? "-")}`);
   console.log(`Created:    ${String(data["created_at"] ?? "-")}`);
@@ -7663,6 +8359,14 @@ async function runCommand(args2) {
     case "doctor":
       await handleDoctor(rest);
       break;
+    case "nav":
+      if (subCmd === "generate") {
+        await handleNavGenerate(args2.slice(2));
+      } else {
+        console.error("Usage: nrdocs nav generate [--docs-dir docs] [--force] [--dry-run]");
+        process.exitCode = 1;
+      }
+      break;
     case "deploy":
       await handleDeploy(rest);
       break;
@@ -7810,7 +8514,8 @@ Usage:
 Repo-owner commands:
   init        Initialize nrdocs in a GitHub repository
   publish     Build and upload docs artifacts
-  doctor      Diagnose setup and connectivity
+  doctor      Diagnose setup and connectivity (--ci for Actions)
+  nav         Navigation helpers (generate)
 
 Operator commands:
   deploy      Deploy or update nrdocs infrastructure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nrdocs",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "CLI for nrdocs - serverless docs publishing for private GitHub repos",
   "type": "module",
   "bin": {
@@ -25,5 +25,8 @@
     "markdown-it": "^14.1.1",
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
   }
 }