@readme/cli 0.0.27 → 0.0.29

package/src/commands/import.slug-planner.test.js

@@ -0,0 +1,86 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { ensureUniqueSlugs } from './import.js'
+
+function assignedSlug(categories, page) {
+  return ensureUniqueSlugs(categories).get(page)
+}
+
+test('ensureUniqueSlugs: generic docs terminal paths fall back to introduction', () => {
+  for (const segment of ['doc', 'docs', 'documentation', 'documentations']) {
+    const page = { title: segment, url: `https://example.com/${segment}` }
+    assert.equal(
+      assignedSlug([{ title: 'Documentation', pages: [page] }], page),
+      'introduction',
+    )
+  }
+})
+
+test('ensureUniqueSlugs: terminal generic docs paths use introduction under non-generic categories', () => {
+  const page = { title: 'Docs', url: 'https://example.com/docs' }
+
+  assert.equal(
+    assignedSlug([{ title: 'Guides', pages: [page] }], page),
+    'introduction',
+  )
+})
+
+test('ensureUniqueSlugs: category segment disambiguates introduction collisions', () => {
+  const guidesPage = { title: 'Docs', url: 'https://example.com/docs' }
+  const apiPage = { title: 'Docs', url: 'https://example.com/docs' }
+  const slugs = ensureUniqueSlugs([
+    { title: 'Guides', pages: [guidesPage] },
+    { title: 'API', pages: [apiPage] },
+  ])
+
+  assert.equal(slugs.get(guidesPage), 'guides-introduction')
+  assert.equal(slugs.get(apiPage), 'api-introduction')
+})
+
+test('ensureUniqueSlugs: generic docs category does not prefix an available page slug', () => {
+  const page = { title: 'Getting Started', url: 'https://example.com/docs/getting-started' }
+
+  assert.equal(
+    assignedSlug([{ title: 'Docs', pages: [page] }], page),
+    'getting-started',
+  )
+})
+
+test('ensureUniqueSlugs: generic docs categories use existing numeric suffix fallback for irreducible collisions', () => {
+  const first = { title: 'Getting Started', url: 'https://example.com/docs/getting-started' }
+  const second = { title: 'Getting Started', url: 'https://example.com/documentation/getting-started' }
+  const slugs = ensureUniqueSlugs([
+    { title: 'Docs', pages: [first] },
+    { title: 'Documentation', pages: [second] },
+  ])
+
+  assert.equal(slugs.get(first), 'getting-started')
+  assert.equal(slugs.get(second), 'getting-started-2')
+})
+
+test('ensureUniqueSlugs: generic docs category is assigned before non-generic categories', () => {
+  const docsPage = { title: 'Getting Started', url: 'https://example.com/docs/getting-started' }
+  const aiPage = { title: 'Getting Started', url: 'https://example.com/ai/getting-started' }
+  const slugs = ensureUniqueSlugs([
+    { title: 'AI', pages: [aiPage] },
+    { title: 'Docs', pages: [docsPage] },
+  ])
+
+  assert.equal(slugs.get(docsPage), 'getting-started')
+  assert.equal(slugs.get(aiPage), 'ai-getting-started')
+})
+
+test('ensureUniqueSlugs: non-generic docs paths keep current base slug behavior', () => {
+  const api = { title: 'API', url: 'https://example.com/docs/api' }
+  const gettingStarted = { title: 'Getting Started', url: 'https://example.com/docs/getting-started' }
+  const docsApi = { title: 'Docs API', url: 'https://example.com/docs-api' }
+  const documentationSettings = { title: 'Documentation Settings', url: 'https://example.com/documentation-settings' }
+  const slugs = ensureUniqueSlugs([
+    { title: 'Guides', pages: [api, gettingStarted, docsApi, documentationSettings] },
+  ])
+
+  assert.equal(slugs.get(api), 'api')
+  assert.equal(slugs.get(gettingStarted), 'getting-started')
+  assert.equal(slugs.get(docsApi), 'docs-api')
+  assert.equal(slugs.get(documentationSettings), 'documentation-settings')
+})

package/src/commands/import.test.js

@@ -0,0 +1,136 @@
+import { afterEach, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { __test__ } from './import.js'
+
+const originalFetch = globalThis.fetch
+
+afterEach(() => {
+  globalThis.fetch = originalFetch
+})
+
+function mockLlmsFetch(files) {
+  const seen = []
+  globalThis.fetch = async (url) => {
+    const href = String(url)
+    seen.push(href)
+    if (!Object.hasOwn(files, href)) return new Response('', { status: 404 })
+    return new Response(files[href], {
+      status: 200,
+      headers: { 'content-type': 'text/plain' },
+    })
+  }
+  return seen
+}
+
+function mockRedirectFetch(files) {
+  globalThis.fetch = async (url) => {
+    const entry = files[String(url)]
+    if (!entry) return { ok: false, status: 404, url: String(url), text: async () => '' }
+    return { ok: true, status: 200, url: entry.finalUrl || String(url), text: async () => entry.body || '' }
+  }
+}
+
+function mergedItems(merged) {
+  return merged.parsed.sections.flatMap((section) => section.items.map((item) => ({ text: item.text, url: item.url })))
+}
+
+test('llms discovery and merge resolve nested files, dedupe canonical pages, and preserve distinct page states', async () => {
+  const seen = mockLlmsFetch({
+    'https://example.com/docs/llms.txt': `# Docs\n\n## Index\n- [Guide llms](guide/llms.txt)\n- [API llms](https://example.com/docs/api/llms.txt)\n`,
+    'https://example.com/docs/guide/llms.txt': `# Guide\n\n## Guides\n- [Rendered redirect](/getting-started)\n- [Rendered slash](/getting-started/)\n- [Rendered index](/getting-started/index.html)\n- [Markdown source](/getting-started.md)\n- [Search API](/search?product=api)\n- [Search SDK](/search?product=sdk)\n- [Search API Anchor](/search?product=api#overview)\n- [Hash only](#local)\n- [Mail](mailto:test@example.com)\n- [JS](javascript:alert(1))\n- [Malformed](http://%zz)\n`,
+    'https://example.com/docs/api/llms.txt': `# API\n\n## Reference\n- [Reference](/reference.md)\n- [OpenAPI](/openapi.yaml)\n`,
+  })
+
+  const discovery = await __test__.discoverLlmsTxt(new URL('https://example.com/docs/'))
+  const merged = __test__.mergeValidHits(discovery.hits)
+  const items = mergedItems(merged)
+  const urls = items.map((item) => item.url)
+
+  assert(seen.includes('https://example.com/docs/guide/llms.txt'))
+  assert(seen.includes('https://example.com/docs/api/llms.txt'))
+
+  assert.equal(urls.filter((url) => url.includes('/docs/guide/getting-started')).length, 1)
+  assert(urls.includes('https://example.com/docs/guide/getting-started.md'))
+
+  assert(urls.includes('https://example.com/docs/guide/search?product=api'))
+  assert(urls.includes('https://example.com/docs/guide/search?product=sdk'))
+  assert.equal(urls.filter((url) => url.includes('/docs/guide/search?product=api')).length, 1)
+
+  assert(urls.includes('https://example.com/docs/api/reference.md'))
+  assert(urls.includes('https://example.com/openapi.yaml'))
+
+  assert(!urls.some((url) => url.includes('%zz')))
+  assert(!urls.some((url) => url.startsWith('mailto:') || url.startsWith('javascript:')))
+})
+
+test('llms.txt fetched through a cross-origin redirect resolves links against the final URL', async () => {
+  mockRedirectFetch({
+    'https://docs.example.com/llms.txt': {
+      finalUrl: 'https://example.com/docs/llms.txt',
+      body: `# Docs\n\n## Guides\n- [Sample APIs](/docs/sample-apis.md)\n- [Policies](/policies.md)\n`,
+    },
+  })
+
+  const discovery = await __test__.discoverLlmsTxt(new URL('https://docs.example.com'))
+  const merged = __test__.mergeValidHits(discovery.hits)
+  const urls = mergedItems(merged).map((item) => item.url)
+
+  assert(urls.includes('https://example.com/docs/sample-apis.md'))
+  assert(urls.includes('https://example.com/docs/policies.md'))
+  assert(!urls.some((url) => url.startsWith('https://docs.example.com/')))
+})
+
+test('nested llms.txt with its own redirect resolves links on its final path', async () => {
+  mockRedirectFetch({
+    'https://example.com/llms.txt': {
+      body: `# Root\n\n## Index\n- [Guide llms](/guide/llms.txt)\n`,
+    },
+    'https://example.com/guide/llms.txt': {
+      finalUrl: 'https://example.com/docs/guide/llms.txt',
+      body: `# Guide\n\n## Guides\n- [Intro](intro.md)\n- [Setup](setup.md)\n`,
+    },
+  })
+
+  const discovery = await __test__.discoverLlmsTxt(new URL('https://example.com'))
+  const merged = __test__.mergeValidHits(discovery.hits)
+  const urls = mergedItems(merged).map((item) => item.url)
+
+  assert(urls.includes('https://example.com/docs/guide/intro.md'))
+  assert(urls.includes('https://example.com/docs/guide/setup.md'))
+  assert(!urls.includes('https://example.com/guide/intro.md'))
+  assert(!urls.includes('https://example.com/guide/setup.md'))
+})
+
+test('resolveRedirectedSourceUrl adopts cross-origin path redirects', async () => {
+  mockRedirectFetch({
+    'https://docs.example.com/': { finalUrl: 'https://example.com/docs' },
+  })
+  const final = await __test__.resolveRedirectedSourceUrl(new URL('https://docs.example.com/'))
+  assert.equal(final?.href, 'https://example.com/docs')
+})
+
+test('resolveRedirectedSourceUrl ignores trailing-slash redirects', async () => {
+  mockRedirectFetch({
+    'https://example.com/docs': { finalUrl: 'https://example.com/docs/' },
+  })
+  assert.equal(await __test__.resolveRedirectedSourceUrl(new URL('https://example.com/docs')), null)
+})
+
+test('resolveRedirectedSourceUrl ignores query and hash-only redirects', async () => {
+  mockRedirectFetch({
+    'https://example.com/docs': { finalUrl: 'https://example.com/docs?lang=en#top' },
+  })
+  assert.equal(await __test__.resolveRedirectedSourceUrl(new URL('https://example.com/docs')), null)
+})
+
+test('resolveRedirectedSourceUrl returns null on non-ok responses', async () => {
+  globalThis.fetch = async (url) => ({ ok: false, status: 500, url: String(url), text: async () => '' })
+  assert.equal(await __test__.resolveRedirectedSourceUrl(new URL('https://example.com/')), null)
+})
+
+test('resolveRedirectedSourceUrl returns null when fetch throws', async () => {
+  globalThis.fetch = async () => {
+    throw new Error('network down')
+  }
+  assert.equal(await __test__.resolveRedirectedSourceUrl(new URL('https://example.com/')), null)
+})

package/src/commands/oas-sync.js

@@ -14,12 +14,6 @@ export const description = 'Sync reference pages with OpenAPI specs';
 
 const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace']);
 
-/**
- * Check if this is a ReadMeConfig spec (internal ReadMe pages — skip title/excerpt updates).
- */
-function isReadMeConfig(spec) {
-  return spec.info?.title === 'ReadMeConfig';
-}
 
 /**
  * Find OAS files at the root of reference/ (JSON or YAML).
@@ -168,19 +162,31 @@ function removeFromOrder(orderPath, slug) {
   }
 }
 
-function buildPageContent({ oasFilename, operationId, summary, description }) {
+/**
+ * Spec-derived values (info.title, tags, operationIds) become directory and
+ * file names. Collapse path separators and dot-only names into a single safe
+ * segment so a crafted spec can't write outside reference/.
+ */
+function safeSegment(value, fallback) {
+  const segment = String(value).replace(/[/\\]/g, '-').trim();
+  return !segment || segment === '.' || segment === '..' ? fallback : segment;
+}
+
+function isWithin(baseDir, target) {
+  const rel = path.relative(baseDir, target);
+  return (
+    rel !== '' && rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel)
+  );
+}
+
+function buildPageContent({ oasFilename, operationId }) {
   const frontmatter = {
-    title: summary || operationId,
     api: {
       file: oasFilename,
       operationId,
     },
   };
 
-  if (description) {
-    frontmatter.excerpt = description;
-  }
-
   return matter.stringify('', frontmatter);
 }
 
@@ -189,8 +195,10 @@ function buildPageContent({ oasFilename, operationId, summary, description }) {
  */
 function syncOneOas(refDir, oasFilename, spec) {
   const specOps = extractOperations(spec);
-  const infoTitle = spec.info?.title || path.basename(oasFilename, path.extname(oasFilename));
-  const skipUpdates = isReadMeConfig(spec);
+  const infoTitle = safeSegment(
+    spec.info?.title || path.basename(oasFilename, path.extname(oasFilename)),
+    'api',
+  );
 
   const existingPages = collectExistingPages(refDir).filter(
     (p) => p.data.api.file === oasFilename,
@@ -201,7 +209,7 @@ function syncOneOas(refDir, oasFilename, spec) {
     pagesByOpId.set(page.data.api.operationId, page);
   }
 
-  const changes = { added: [], deleted: [], updated: [] };
+  const changes = { added: [], deleted: [], skipped: [] };
 
   // Deletes: pages referencing operations that no longer exist.
   for (const [opId, page] of pagesByOpId) {
@@ -216,61 +224,32 @@ function syncOneOas(refDir, oasFilename, spec) {
     }
   }
 
-  // Adds + Updates.
+  // Adds: operations with no page yet. Title/excerpt are owned by the OAS spec
+  // at render time, so generated pages carry only the api reference.
   for (const [opId, op] of specOps) {
-    const existing = pagesByOpId.get(opId);
-    const tag = op.tag || 'Other';
-
-    if (!existing) {
-      const pageDir = path.join(refDir, infoTitle, tag);
-      fs.mkdirSync(pageDir, { recursive: true });
-
-      const pagePath = path.join(pageDir, `${opId}.md`);
-      const content = buildPageContent({
-        oasFilename,
-        operationId: opId,
-        summary: op.summary,
-        description: op.description,
-      });
-      fs.writeFileSync(pagePath, content);
-
-      addToOrder(path.join(pageDir, '_order.yaml'), opId);
-      addToOrder(path.join(refDir, infoTitle, '_order.yaml'), tag);
-
-      changes.added.push(path.relative(refDir, pagePath));
-    } else if (!skipUpdates) {
-      const expectedTitle = op.summary || opId;
-      const expectedExcerpt = op.description || null;
-      const currentTitle = existing.data.title;
-      const currentExcerpt = existing.data.excerpt || null;
-
-      const titleChanged = currentTitle !== expectedTitle;
-      const excerptChanged = currentExcerpt !== expectedExcerpt;
-
-      if (titleChanged || excerptChanged) {
-        const updated = { ...existing.data };
-        const updateDetails = [];
+    if (pagesByOpId.has(opId)) continue;
+
+    const tag = safeSegment(op.tag || 'Other', 'Other');
+    const slug = safeSegment(opId, 'operation');
+    const pageDir = path.join(refDir, infoTitle, tag);
+    const pagePath = path.join(pageDir, `${slug}.md`);
+
+    // Never overwrite an existing file: it belongs to a manual page, another
+    // spec, or a different operation whose sanitized name collides with this
+    // one. Skipping (rather than clobbering) keeps repeated syncs stable.
+    if (!isWithin(refDir, pagePath) || fs.existsSync(pagePath)) {
+      changes.skipped.push({ path: path.relative(refDir, pagePath), operationId: opId });
+      continue;
+    }
+    fs.mkdirSync(pageDir, { recursive: true });
 
-        if (titleChanged) {
-          updated.title = expectedTitle;
-          updateDetails.push('title');
-        }
-        if (excerptChanged) {
-          if (expectedExcerpt) {
-            updated.excerpt = expectedExcerpt;
-          } else {
-            delete updated.excerpt;
-          }
-          updateDetails.push('excerpt');
-        }
+    const content = buildPageContent({ oasFilename, operationId: opId });
+    fs.writeFileSync(pagePath, content);
 
-        const body = matter(existing.content).content;
-        const newContent = matter.stringify(body, updated);
-        fs.writeFileSync(existing.filePath, newContent);
+    addToOrder(path.join(pageDir, '_order.yaml'), slug);
+    addToOrder(path.join(refDir, infoTitle, '_order.yaml'), tag);
 
-        changes.updated.push(`${existing.relativePath} (${updateDetails.join(', ')})`);
-      }
-    }
+    changes.added.push(path.relative(refDir, pagePath));
   }
 
   return changes;
@@ -285,7 +264,7 @@ function syncOneOas(refDir, oasFilename, spec) {
  *
  * @param {string | { cwd?: string }} input  Repo root path, or `{ cwd }` object.
  * @returns {null | Array<{ filename: string, spec: object, opCount: number,
- *   changes: { added: string[], deleted: string[], updated: string[] } }>}
+ *   changes: { added: string[], deleted: string[] } }>}
  *   Returns null if there's no reference/ dir or no specs.
  */
 export function syncOas(input) {
@@ -325,11 +304,12 @@ export async function run(_options, _cmd, ctx) {
 
   let totalAdded = 0;
   let totalDeleted = 0;
-  let totalUpdated = 0;
+  let totalSkipped = 0;
 
   for (const { filename, spec, opCount, changes } of results) {
     const title = spec.info?.title || filename;
-    const hasChanges = changes.added.length + changes.deleted.length + changes.updated.length > 0;
+    const hasChanges =
+      changes.added.length + changes.deleted.length + changes.skipped.length > 0;
 
     const dot = hasChanges ? styles.warn('●') : styles.success('●');
     console.log();
@@ -345,20 +325,25 @@ export async function run(_options, _cmd, ctx) {
     for (const file of changes.deleted) {
       console.log(`    ${styles.err('−')} Deleted ${file}`);
     }
-    for (const file of changes.updated) {
-      console.log(`    ${styles.warn('~')} Updated ${file}`);
+    for (const { path: file, operationId } of changes.skipped) {
+      console.log(
+        `    ${styles.warn('!')} Skipped ${file} for "${operationId}" (destination already exists)`,
+      );
     }
 
     totalAdded += changes.added.length;
     totalDeleted += changes.deleted.length;
-    totalUpdated += changes.updated.length;
+    totalSkipped += changes.skipped.length;
   }
 
   console.log();
-  const total = totalAdded + totalDeleted + totalUpdated;
-  if (total === 0) {
+  const total = totalAdded + totalDeleted;
+  const skippedNote = totalSkipped > 0 ? `, ${totalSkipped} skipped` : '';
+  if (total === 0 && totalSkipped === 0) {
     styles.ok('Reference pages are already in sync.');
+  } else if (total === 0) {
+    styles.warning(`No pages synced; ${totalSkipped} skipped (destination already exists).`);
   } else {
-    styles.ok(`Synced: ${totalAdded} added, ${totalDeleted} deleted, ${totalUpdated} updated.`);
+    styles.ok(`Synced: ${totalAdded} added, ${totalDeleted} deleted${skippedNote}.`);
   }
 }

package/src/prompts/index.js

@@ -19,16 +19,33 @@
 
 export const slotOrphansSystemPrompt = [
   'You assign orphan documentation pages to existing categories.',
-  'Output ONLY a valid JSON array of integers — one per orphan page, in order.',
+  'Respond with a JSON object of the form {"assignments": [...]} — one integer per orphan page, in order.',
   'Each integer is the category index (0-based) the orphan belongs in, or -1 if none fit.',
   '',
-  'Example output: [0, 2, 0, 1, -1, 3]',
+  'Example output: {"assignments": [0, 2, 0, 1, -1, 3]}',
   '',
   'Guidance:',
   '- Choose the best semantic fit based on the orphan\'s title and URL path.',
   '- Only use -1 when no existing category is plausible.',
 ].join('\n');
 
+/**
+ * Structured-output schema for slotOrphans. Root must be an object (top-level
+ * arrays aren't allowed), so the index array is wrapped in `assignments`.
+ */
+export const slotOrphansOutputSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['assignments'],
+  properties: {
+    assignments: {
+      type: 'array',
+      items: { type: 'integer' },
+      description: 'One entry per orphan page, in input order: the 0-based category index, or -1 if none fit.',
+    },
+  },
+};
+
 /**
  * @param {object}   input
  * @param {Array<{ title: string, pages?: Array<{ title: string }> }>} input.categories
@@ -54,7 +71,7 @@ export function buildSlotOrphansUserPrompt({ categories, orphans }) {
     `${orphans.length} orphan pages to slot:`,
     ...orphanList,
     '',
-    `Output a JSON array of ${orphans.length} integers, one per orphan in order (category index 0..${categories.length - 1}, or -1 for none).`,
+    `Output {"assignments": [...]} with ${orphans.length} integers, one per orphan in order (category index 0..${categories.length - 1}, or -1 for none).`,
   ].join('\n');
 }
 
@@ -69,12 +86,29 @@ export function slotOrphansPrompt(input) {
 
 export const iconizeNavSystemPrompt = [
   'You assign one FontAwesome Free Solid icon to each documentation category.',
-  'Output ONLY a valid JSON array of icon name strings, one per input category, in order.',
-  'Use the icon name only (no "fa-" prefix, no object wrapper).',
+  'Respond with a JSON object of the form {"icons": [...]} — one icon name string per input category, in order.',
+  'Use the icon name only (no "fa-" prefix).',
   '',
-  'Example output: ["rocket", "book", "code", "gear"]',
+  'Example output: {"icons": ["rocket", "book", "code", "gear"]}',
 ].join('\n');
 
+/**
+ * Structured-output schema for iconizeNav. Root must be an object, so the
+ * icon-name array is wrapped in `icons`.
+ */
+export const iconizeNavOutputSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['icons'],
+  properties: {
+    icons: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'One FontAwesome Free Solid icon name per input category, in order (no "fa-" prefix).',
+    },
+  },
+};
+
 /**
  * @param {object} input
  * @param {Array<{ title: string }>} input.categories
@@ -86,7 +120,7 @@ export function buildIconizeNavUserPrompt({ categories }) {
     '',
     ...categories.map((c, i) => `${i}. ${c.title}`),
     '',
-    'Return a JSON array of FontAwesome icon names, one per category, in order.',
+    'Return {"icons": [...]} with one FontAwesome icon name per category, in order.',
   ].join('\n');
 }
 
@@ -101,13 +135,15 @@ export function iconizeNavPrompt(input) {
 
 export const organizeFromSectionsSystemPrompt = [
   'You assign a FontAwesome Free Solid icon to each documentation section, and lightly polish the section title.',
-  'Output ONLY a valid JSON array — no prose, no markdown, no code fences.',
+  'Respond with a JSON object matching the schema below.',
   '',
   'Schema:',
-  '[',
-  '  { "title": "<lightly polished Title Case, 1-4 words>", "icon": "<fontawesome icon name, no fa- prefix>" },',
-  '  ...',
-  ']',
+  '{',
+  '  "sections": [',
+  '    { "title": "<lightly polished Title Case, 1-4 words>", "icon": "<fontawesome icon name, no fa- prefix>" },',
+  '    ...',
+  '  ]',
+  '}',
   '',
   'Rules:',
   '- Return exactly one entry per input section, in the same order.',
@@ -115,6 +151,31 @@ export const organizeFromSectionsSystemPrompt = [
   '- Pick an icon that semantically fits the section (e.g. rocket for Getting Started, code for API, plug for Integrations).',
 ].join('\n');
 
+/**
+ * Structured-output schema for organizeFromSections. Root must be an object,
+ * so the per-section entries are wrapped in `sections`.
+ */
+export const organizeFromSectionsOutputSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['sections'],
+  properties: {
+    sections: {
+      type: 'array',
+      description: 'Exactly one entry per input section, in the same order.',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['title', 'icon'],
+        properties: {
+          title: { type: 'string', description: 'Lightly polished Title Case section title, 1-4 words.' },
+          icon: { type: 'string', description: 'FontAwesome Free Solid icon name, no "fa-" prefix.' },
+        },
+      },
+    },
+  },
+};
+
 /**
  * @param {object} input
  * @param {string|null|undefined} input.siteTitle
@@ -128,7 +189,7 @@ export function buildOrganizeFromSectionsUserPrompt({ siteTitle, sections }) {
     '',
     ...sections.map((s, i) => `${i}. ${s.title} (${s.items.length} pages)`),
     '',
-    'Output the JSON array now.',
+    'Output the JSON object now.',
   ].join('\n');
 }
 
@@ -166,6 +227,33 @@ export const organizeFromScratchSystemPrompt = [
   '- Keep category titles human-readable, Title Case, 1-4 words.',
 ].join('\n');
 
+/** Structured-output schema for organizeFromScratch. */
+export const organizeFromScratchOutputSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['title', 'categories'],
+  properties: {
+    title: { type: 'string', description: 'Short site or doc title.' },
+    categories: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['title', 'icon', 'pageIds'],
+        properties: {
+          title: { type: 'string', description: 'Title Case category name, 1-4 words.' },
+          icon: { type: 'string', description: 'FontAwesome Free Solid icon name, no "fa-" prefix.' },
+          pageIds: {
+            type: 'array',
+            items: { type: 'integer' },
+            description: 'Integer ids from the input page list. Every input id appears in exactly one category.',
+          },
+        },
+      },
+    },
+  },
+};
+
 /**
  * @param {object} input
  * @param {string|null|undefined} input.siteTitle