@shanyucoder/flowgrid 0.1.5 → 0.1.8

package/engines/docs/lib/render-bundle-markdown.mjs

@@ -3,6 +3,9 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import { parse } from 'yaml'
 import { renderSpecMarkdown } from './render-spec-markdown.mjs'
+import { renderDataModelMarkdown } from './render-data-model-markdown.mjs'
+import { renderApiSummaryMarkdown } from './render-api-summary-markdown.mjs'
+import { resolveBackendSpecForBundle } from '../../spec/lib/audit-db-tables.mjs'
 
 /**
  * Flatten bundle → spec shape (tests / fallback). Prefer ir/spec.yaml for site MD.
@@ -67,6 +70,22 @@ export function irGeneratedMarkdownPath(bundleFile) {
   return path.join(dir, 'ir', 'generated', 'spec.md')
 }
 
+/** Reviewer-facing DB tables — `…/<leaf>/ir/generated/data-model.md` */
+export function irGeneratedDataModelPath(bundleFile) {
+  const dir = path.dirname(path.resolve(bundleFile))
+  return path.join(dir, 'ir', 'generated', 'data-model.md')
+}
+
+/** API summary for readers — `…/<leaf>/ir/generated/api.md` */
+export function irGeneratedApiPath(bundleFile) {
+  const dir = path.dirname(path.resolve(bundleFile))
+  return path.join(dir, 'ir', 'generated', 'api.md')
+}
+
+export function designIrPathForBundle(bundleFile) {
+  return path.join(path.dirname(path.resolve(bundleFile)), 'ir', 'design.yaml')
+}
+
 export function irSpecPathForBundle(bundleFile) {
   return path.join(path.dirname(path.resolve(bundleFile)), 'ir', 'spec.yaml')
 }
@@ -77,13 +96,69 @@ export function irSpecPathForBundle(bundleFile) {
 export async function writeBundleMarkdownFile(bundleFile, context = {}) {
   const specFile = irSpecPathForBundle(bundleFile)
   if (!existsSync(specFile)) return null
-  return writeIrSpecMarkdownFile(specFile, irGeneratedMarkdownPath(bundleFile), context)
+  const specOut = await writeIrSpecMarkdownFile(specFile, irGeneratedMarkdownPath(bundleFile), context)
+  await writeDataModelMarkdownFile(bundleFile)
+  await writeApiMarkdownFile(bundleFile)
+  return specOut
+}
+
+export async function writeApiMarkdownFile(bundleFile) {
+  const resolved = path.resolve(bundleFile)
+  const backendPath = resolveBackendSpecForBundle(resolved, null)
+  if (!backendPath || !existsSync(backendPath)) return null
+  const backendSpec = parse(await readFile(backendPath, 'utf8')) ?? {}
+  const specFile = irSpecPathForBundle(bundleFile)
+  const spec = existsSync(specFile) ? parse(await readFile(specFile, 'utf8')) ?? {} : {}
+  const pageId = spec['page-id'] ?? spec.id
+  const markdown = renderApiSummaryMarkdown(backendSpec, {
+    pageId,
+    title: spec.title ?? backendSpec.feature?.title,
+    backendRelPath: path.relative(path.dirname(resolved), backendPath).split(path.sep).join('/'),
+  })
+  const out = irGeneratedApiPath(bundleFile)
+  await mkdir(path.dirname(out), { recursive: true })
+  await writeFile(out, markdown, 'utf8')
+  return out
+}
+
+export async function writeDataModelMarkdownFile(bundleFile) {
+  const designFile = designIrPathForBundle(bundleFile)
+  if (!existsSync(designFile)) return null
+  const design = parse(await readFile(designFile, 'utf8')) ?? {}
+  const specFile = irSpecPathForBundle(bundleFile)
+  const spec = existsSync(specFile) ? parse(await readFile(specFile, 'utf8')) ?? {} : {}
+  const markdown = renderDataModelMarkdown({
+    pageId: spec.id ?? design.id,
+    title: spec.title ?? design.title,
+    design,
+    spec,
+  })
+  const out = irGeneratedDataModelPath(bundleFile)
+  await mkdir(path.dirname(out), { recursive: true })
+  await writeFile(out, markdown, 'utf8')
+  return out
+}
+
+export function mergeDesignIntoSpecForRender(spec, design) {
+  if (!design || typeof design !== 'object') return spec
+  const out = { ...spec }
+  if (design.ui?.list) {
+    out.ui = { ...(out.ui ?? {}), list: { ...(out.ui?.list ?? {}), ...design.ui.list } }
+  }
+  if (design.sections && !out.sections) out.sections = design.sections
+  if (design.actions && !out.actions) out.actions = design.actions
+  if (design.stateMatrix && !out.stateMatrix) out.stateMatrix = design.stateMatrix
+  if (design.nav && !out.nav) out.nav = design.nav
+  return out
 }
 
 export async function writeIrSpecMarkdownFile(specFile, mdOut, context = {}) {
   const spec = parse(await readFile(specFile, 'utf8')) ?? {}
+  const designFile = path.join(path.dirname(specFile), 'design.yaml')
+  const design = existsSync(designFile) ? parse(await readFile(designFile, 'utf8')) ?? {} : {}
+  const specShape = mergeDesignIntoSpecForRender(spec, design)
   const projectRoot = context.projectRoot ?? process.cwd()
-  const markdown = renderIrSpecMarkdown(spec, {
+  const markdown = renderIrSpecMarkdown(specShape, {
     testcases: [],
     output: { specFile: path.basename(mdOut), testcasesDir: 'testcases' },
     devAppBaseUrl: context.devAppBaseUrl ?? '',

package/engines/docs/lib/render-data-model-markdown.mjs

@@ -0,0 +1,171 @@
+import { renderTable } from './markdown-table.mjs'
+import { collectDesignDbBindings } from '../../spec/lib/audit-db-tables.mjs'
+
+function roleLabel(role) {
+  const map = {
+    read: 'Chỉ đọc',
+    write: 'Chỉ ghi',
+    'read-write': 'Đọc & ghi',
+    join: 'Join / lookup',
+    aggregate: 'Tổng hợp (read)',
+  }
+  return map[role] || role || '—'
+}
+
+function groupBindingsByTable(bindings) {
+  const byTable = new Map()
+  for (const b of bindings) {
+    if (!b.schema || !b.field) continue
+    if (!byTable.has(b.schema)) byTable.set(b.schema, [])
+    byTable.get(b.schema).push(b)
+  }
+  return byTable
+}
+
+function tableOverviewRows(design, tableNames) {
+  const meta = design.dataModel?.tables
+  const byName = new Map()
+  if (Array.isArray(meta)) {
+    for (const t of meta) {
+      if (t?.schema) byName.set(String(t.schema), t)
+    }
+  }
+  return tableNames.map((schema) => {
+    const m = byName.get(schema) ?? {}
+    return [
+      `\`${schema}\``,
+      roleLabel(m.roleOnScreen),
+      m.summary || m.purpose || '—',
+      m.erdEntity ? `\`${m.erdEntity}\`` : '—',
+    ]
+  })
+}
+
+/**
+ * Human-readable DB view for reviewers (multi-table safe). SSOT remains bundle / ir/design.yaml + 01.
+ * @param {{
+ *   pageId?: string,
+ *   title?: string,
+ *   design?: Record<string, unknown>,
+ *   spec?: Record<string, unknown>,
+ * }} input
+ */
+export function renderDataModelMarkdown(input = {}) {
+  const design = input.design ?? {}
+  const spec = input.spec ?? {}
+  const pageId = input.pageId ?? design.id ?? '—'
+  const title = input.title ?? design.title ?? pageId
+  const bundleShape = { design, spec: { entities: design.entities ?? spec.entities, ui: design.ui ?? spec.ui } }
+  const { bindings, tables } = collectDesignDbBindings(bundleShape)
+  const fullBindings = bindings.filter((b) => b.schema && b.field)
+  const byTable = groupBindingsByTable(fullBindings)
+  const tableNames = tables.length ? tables : [...byTable.keys()]
+
+  const parts = [
+    `# Data model — ${title}`,
+    '',
+    `> **Page ID:** \`${pageId}\` · Đọc cùng [spec.md](./spec.md) trên VitePress (sidebar **Data model**). SSOT ghi: bundle + \`ir/design.yaml\` · BE: \`api/*/01-backend-spec.yaml\`.`,
+    '',
+  ]
+
+  if (design.dataModel?.erdRef || design.dataModel?.notes) {
+    parts.push('## Ghi chú & ERD', '')
+    if (design.dataModel.erdRef) {
+      parts.push(`- **ERD (Phase 0):** ${design.dataModel.erdRef}`)
+    }
+    if (design.dataModel.notes) {
+      parts.push('', String(design.dataModel.notes), '')
+    }
+    parts.push('')
+  }
+
+  const entities = design.entities ?? spec.entities
+  if (Array.isArray(entities) && entities.length) {
+    parts.push('## Entity trên màn (spec.entities)', '')
+    for (const e of entities) {
+      if (typeof e === 'string') {
+        parts.push(`- **${e}**`)
+        continue
+      }
+      const name = e.name ?? e.table ?? 'Entity'
+      parts.push(`- **${name}**${e.description ? ` — ${e.description}` : ''}`)
+      if (e.relatesTo) parts.push(`  - Quan hệ: ${e.relatesTo}`)
+    }
+    parts.push('')
+  }
+
+  if (Array.isArray(design.relationships) && design.relationships.length) {
+    parts.push('## Quan hệ (relationships)', '')
+    for (const r of design.relationships) {
+      parts.push(`- ${typeof r === 'string' ? r : formatRecord(r)}`)
+    }
+    parts.push('')
+  }
+
+  if (tableNames.length) {
+    parts.push('## Tổng quan bảng (multi-table)', '')
+    parts.push(
+      renderTable(
+        ['Bảng (schema)', 'Vai trò trên màn', 'Mô tả review', 'Entity ER (nếu có)'],
+        tableOverviewRows(design, tableNames),
+      ),
+      '',
+    )
+  }
+
+  if (!fullBindings.length) {
+    parts.push(
+      '_Chưa có `design.sections[].db` / list column `db` — bổ sung trên bundle rồi chạy `flowgrid split`._',
+      '',
+    )
+    return parts.join('\n')
+  }
+
+  for (const schema of tableNames) {
+    const rows = (byTable.get(schema) ?? []).map((b) => {
+      const enumStr =
+        b.enumMapping && typeof b.enumMapping === 'object'
+          ? Object.entries(b.enumMapping)
+              .map(([k, v]) => `\`${k}\` → ${v}`)
+              .join('<br>')
+          : '—'
+      return [
+        b.label || '—',
+        b.bindField ? `\`${b.bindField}\`` : '—',
+        `\`${b.field}\``,
+        b.required ? 'Có' : 'Không',
+        b.path?.includes('list') ? 'List' : 'Form / section',
+        enumStr,
+      ]
+    })
+    if (!rows.length) continue
+    parts.push(`## Bảng \`${schema}\``, '')
+    parts.push(
+      renderTable(
+        ['Nhãn UI', 'bind.field (API/payload)', 'Cột DB', 'Bắt buộc?', 'Nguồn UI', 'enumMapping'],
+        rows,
+      ),
+      '',
+    )
+  }
+
+  parts.push(
+    '## Backend codegen',
+    '',
+    '- Map `db.schema` ↔ `01-backend-spec.yaml` → `modules[].entities[].table` (hoặc `name`).',
+    '- Map `db.field` ↔ `entities[].fields[].name`; quan hệ ORM theo ERD + `entity-relationship.md` extract.',
+    '- `bind.field` ↔ request/response DTO trên endpoint (`executionContract.apiRef`).',
+    '',
+  )
+
+  return `${parts.join('\n').trim()}\n`
+}
+
+function formatRecord(obj) {
+  if (obj == null) return ''
+  if (typeof obj !== 'object') return String(obj)
+  return Object.entries(obj)
+    .filter(([, v]) => v != null && v !== '')
+    .map(([k, v]) => `${k}: ${v}`)
+    .join('; ')
+}

package/engines/docs/lib/render-design-tables.mjs

@@ -120,6 +120,95 @@ export function collectFormFields(nodes = []) {
 /**
  * Bảng Từ Điển Dữ Liệu & Quy Tắc Kiểm Tra Hợp Lệ (Data Dictionary Table 6 cột)
  */
+/**
+ * Bảng cột danh sách (list / admin-crud) — từ spec.ui.list, không chỉ form sections.
+ * @param {{ columns?: unknown[], filters?: unknown[], pagination?: unknown }} listUi
+ */
+/**
+ * @param {{ filters?: unknown[], pagination?: unknown }} listUi
+ */
+export function renderListFiltersTable(listUi = {}) {
+  const filters = listUi?.filters
+  if (!Array.isArray(filters) || !filters.length) return ''
+
+  const rows = filters.map((f) => {
+    if (!f || typeof f !== 'object') return null
+    return [
+      f.label || f.name || '—',
+      f.name != null ? `\`${f.name}\`` : '—',
+      f.type || '—',
+      f.widget || '—',
+      f.meaning || '—',
+      f.purpose || '—',
+      f.placeholder || '—',
+    ]
+  }).filter(Boolean)
+
+  if (!rows.length) return ''
+
+  return renderTable(
+    ['Nhãn', 'Tên filter', 'Kiểu', 'Widget', 'Ý nghĩa', 'Mục đích', 'Placeholder'],
+    rows,
+  )
+}
+
+export function renderListPaginationBlock(listUi = {}) {
+  const p = listUi?.pagination
+  if (!p || typeof p !== 'object') return ''
+  const bits = []
+  if (p.enabled === false) return '_Phân trang: tắt trên màn này._\n'
+  if (p.pageSize != null) bits.push(`Kích thước trang mặc định: **${p.pageSize}**`)
+  if (p.pageSizeOptions?.length) {
+    bits.push(`Tùy chọn: ${p.pageSizeOptions.map((n) => `\`${n}\``).join(', ')}`)
+  }
+  if (p.showTotal != null) bits.push(`Hiển thị tổng số bản ghi: ${p.showTotal ? 'Có' : 'Không'}`)
+  if (p.infiniteScroll) bits.push('Chế độ: infinite scroll')
+  if (!bits.length) {
+    return '_Phân trang: bật (chi tiết kỹ thuật trên bundle / design actions)._ \n'
+  }
+  return bits.map((b) => `- ${b}`).join('\n') + '\n'
+}
+
+export function renderListColumnsTable(listUi = {}) {
+  const columns = listUi?.columns
+  if (!Array.isArray(columns) || !columns.length) return ''
+
+  const rows = columns.map((col) => {
+    if (!col || typeof col !== 'object') return null
+    const db = col.db
+    let dbCell = '—'
+    if (db && typeof db === 'object') {
+      if (db.schema && db.field) dbCell = `\`${db.schema}.${db.field}\``
+      else if (db.schema) dbCell = `\`${db.schema}\` (thiếu field)`
+      else if (db.field) dbCell = `\`${db.field}\` (thiếu schema)`
+    }
+    return [
+      col.title || col.label || '—',
+      col.key != null ? `\`${col.key}\`` : '—',
+      col.meaning || '—',
+      col.purpose || '—',
+      [col.widget, col.render].filter(Boolean).join(' / ') || '—',
+      col.sortable ? 'Có' : 'Không',
+      dbCell,
+    ]
+  }).filter(Boolean)
+
+  if (!rows.length) return ''
+
+  return renderTable(
+    [
+      'Nhãn cột',
+      'Key',
+      'Ý nghĩa nghiệp vụ',
+      'Mục đích UI',
+      'Widget / render',
+      'Sort',
+      'DB (schema.field)',
+    ],
+    rows,
+  )
+}
+
 export function renderValidationDictionaryTable(sections = []) {
   const fields = collectFormFields(sections)
   if (!fields.length) return ''
@@ -685,11 +774,4 @@ function formatApi(action) {
   if (action.api) return String(action.api)
   if (Array.isArray(action.apiRefs)) return action.apiRefs.join(', ')
   return ''
-}
-
-export {
-  renderValidationDictionaryTable,
-  renderStateMatrixTable,
-  renderActionFlowsDetailed,
-  renderCustomWidgetSpecs
 }

package/engines/docs/lib/render-template.mjs

@@ -10,6 +10,9 @@ import {
   renderBehaviorTable,
   renderActionsTable,
   renderValidationDictionaryTable,
+  renderListColumnsTable,
+  renderListFiltersTable,
+  renderListPaginationBlock,
   renderStateMatrixTable,
   renderActionFlowsDetailed,
   renderCustomWidgetSpecs
@@ -66,6 +69,9 @@ export function renderWithTemplate(spec, context) {
     renderBehaviorTable,
     renderActionsTable,
     renderValidationDictionaryTable,
+    renderListColumnsTable,
+    renderListFiltersTable,
+    renderListPaginationBlock,
     renderStateMatrixTable,
     renderActionFlowsDetailed,
     renderCustomWidgetSpecs

package/engines/docs/render-docs.mjs

@@ -8,7 +8,9 @@ import { renderSpecMarkdown } from './lib/render-spec-markdown.mjs'
 import {
   irGeneratedMarkdownPath,
   irSpecPathForBundle,
-  writeIrSpecMarkdownFile
+  writeIrSpecMarkdownFile,
+  writeDataModelMarkdownFile,
+  writeApiMarkdownFile,
 } from './lib/render-bundle-markdown.mjs'
 
 const projectRoot = process.cwd()
@@ -34,7 +36,7 @@ const legacyRoot = cliFlag('legacy-root') ? path.resolve(cliFlag('legacy-root'))
 
 const devAppBaseUrl = resolveDevAppBaseUrl(projectRoot)
 
-import { renderFeatureBackendSpec, listBackendSpecFiles } from '../../scripts/backend-api/render-backend-spec.mjs'
+import { renderFeatureBackendSpec, listBackendSpecFiles } from '../openapi/render-backend-spec.mjs'
 import { writeQaList } from './lib/render-qa-list.mjs'
 
 async function main() {
@@ -63,6 +65,8 @@ async function main() {
     try {
       const mdOut = irGeneratedMarkdownPath(bundleFile)
       await writeIrSpecMarkdownFile(specIr, mdOut, { projectRoot, devAppBaseUrl })
+      await writeDataModelMarkdownFile(bundleFile)
+      await writeApiMarkdownFile(bundleFile)
     } catch (error) {
       failed++
       console.error(`docs:render: FAIL ${path.relative(projectRoot, specIr)}: ${error.message ?? error}`)

package/engines/docs/vitepress/config.ts

@@ -3,7 +3,7 @@ import { defineConfig } from 'vitepress'
 import fs from 'node:fs'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
-import { buildSurfacesSidebarItems, SKIP_NAV_DIRS, markdownNavText } from './surfaces-nav.mjs'
+import { buildSurfacesSidebarItems, SKIP_NAV_DIRS, markdownNavText, leafGeneratedNavNodes } from './surfaces-nav.mjs'
 
 import { fileURLToPath } from 'node:url'
 
@@ -89,12 +89,12 @@ function mdTitleFromFile(filePath: string, fallback: string) {
 }
 
 function attachGeneratedDocs(dirPath: string, urlPrefix: string, items: any[]) {
-  const spec = path.join(dirPath, 'ir', 'generated', 'spec.md')
-  if (fs.existsSync(spec)) {
-    items.push({
-      text: mdTitleFromFile(spec, 'spec'),
-      link: `${urlPrefix}ir/generated/spec`,
-    })
+  const toLink = (abs: string) => {
+    const rel = path.relative(dirPath, abs).split(path.sep).join('/').replace(/\.md$/, '')
+    return `${urlPrefix}${rel}`
+  }
+  for (const node of leafGeneratedNavNodes(dirPath, toLink)) {
+    items.push({ text: node.text, link: node.link })
   }
 }
 

package/engines/docs/vitepress/surfaces-nav.mjs

@@ -83,6 +83,38 @@ export function isFunctionLeaf(dir) {
   return existsSync(path.join(dir, 'ir', 'spec.yaml'))
 }
 
+/**
+ * VitePress nav entries for ir/generated under a function leaf.
+ * @param {string} leafDir
+ * @param {(absPath: string) => string} toHref
+ */
+export function leafGeneratedNavNodes(leafDir, toHref) {
+  const pageId = pageIdFromLeaf(leafDir)
+  const specMd = path.join(leafDir, 'ir', 'generated', 'spec.md')
+  const dmMd = path.join(leafDir, 'ir', 'generated', 'data-model.md')
+  const apiMd = path.join(leafDir, 'ir', 'generated', 'api.md')
+  const nodes = []
+  if (existsSync(specMd)) {
+    nodes.push({
+      text: `Spec · ${pageId}`,
+      link: toHref(specMd),
+    })
+  }
+  if (existsSync(dmMd)) {
+    nodes.push({
+      text: 'Data model',
+      link: toHref(dmMd),
+    })
+  }
+  if (existsSync(apiMd)) {
+    nodes.push({
+      text: 'API summary',
+      link: toHref(apiMd),
+    })
+  }
+  return nodes
+}
+
 export function pageIdFromLeaf(dir) {
   const specFile = path.join(dir, 'ir', 'spec.yaml')
   if (existsSync(specFile)) {
@@ -119,18 +151,16 @@ export function walkSurfacesNav(dir, toHref) {
     if (SKIP_NAV_DIRS.has(ent.name)) continue
     const full = path.join(dir, ent.name)
     if (isNumericSeq(ent.name) && isFunctionLeaf(full)) {
-      const pageId = pageIdFromLeaf(full)
-      const specMd = path.join(full, 'ir', 'generated', 'spec.md')
-      
-      // Bỏ qua nếu chưa chạy split (chưa có spec.md)
-      if (!existsSync(specMd)) continue
-      
-      const href = toHref(specMd)
-      children.push({
-        text: `${ent.name} + ${pageId}`,
-        href,
-        link: href,
-      })
+      const leafNodes = leafGeneratedNavNodes(full, toHref)
+      if (!leafNodes.length) continue
+      if (leafNodes.length === 1) {
+        children.push(leafNodes[0])
+      } else {
+        children.push({
+          text: `${ent.name} · ${pageIdFromLeaf(full)}`,
+          items: leafNodes,
+        })
+      }
       continue
     }
     const nested = walkSurfacesNav(full, toHref)
@@ -163,8 +193,9 @@ export function buildSurfacesSidebarItems(surfacesDir, urlPrefix) {
 function toVitepressItem(node) {
   const item = { text: node.text }
   if (node.link) item.link = node.link
-  if (node.items?.length) {
-    item.items = node.items.map(toVitepressItem)
+  const nested = node.items || node.children
+  if (nested?.length) {
+    item.items = nested.map(toVitepressItem)
     item.collapsed = true
   }
   return item

package/engines/openapi/check-backend-spec.mjs

@@ -44,7 +44,7 @@ export async function checkBackendSpecFiles(options, cwd = process.cwd()) {
   return files
 }
 
-function parseArgs(argv) {
+export function parseApiCheckArgs(argv) {
   const options = { spec: null }
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]
@@ -55,7 +55,7 @@ function parseArgs(argv) {
 }
 
 async function main() {
-  await checkBackendSpecFiles(parseArgs(process.argv.slice(2)), process.cwd())
+  await checkBackendSpecFiles(parseApiCheckArgs(process.argv.slice(2)), process.cwd())
 }
 
 if (path.resolve(process.argv[1] ?? '') === fileURLToPath(import.meta.url)) {

package/engines/openapi/lib/markdown-table.mjs

@@ -0,0 +1,8 @@
+export {
+  MD_NONE,
+  escapeMarkdownHeading,
+  escapeCell,
+  renderTable,
+  objectRows,
+  formatCellValue,
+} from '../../docs/lib/markdown-table.mjs'

package/engines/openapi/lib/render-backend-spec-markdown.mjs

@@ -0,0 +1,78 @@
+import { stringify } from 'yaml'
+import { renderTable, escapeMarkdownHeading, MD_NONE } from './markdown-table.mjs'
+
+/**
+ * @param {Record<string, unknown>} spec
+ * @param {{ specFile?: string, slug?: string }} context
+ */
+export function renderBackendSpecMarkdown(spec, context = {}) {
+  const feature = spec.feature ?? {}
+  const title = feature.title ?? context.slug ?? 'Backend API'
+  const lines = [
+    `# ${escapeMarkdownHeading(title)}`,
+    '',
+    `- **Source:** \`${context.specFile ?? '01-backend-spec.yaml'}\``,
+    `- **Status:** ${feature.status ?? 'draft'}`,
+    '',
+  ]
+
+  if (feature.source) {
+    lines.push('## Traceability', '', '```yaml', stringify(feature.source).trim(), '```', '')
+  }
+
+  const endpoints = spec.api?.endpoints ?? []
+  if (endpoints.length) {
+    lines.push('## Endpoints', '')
+    lines.push(
+      renderTable(
+        ['id', 'method', 'path', 'action', 'purpose'],
+        endpoints.map((ep) => [
+          ep.id ?? '',
+          ep.method ?? '',
+          ep.path ?? '',
+          ep.action ?? '',
+          ep.purpose ?? '',
+        ]),
+      ),
+    )
+    lines.push('')
+  } else {
+    lines.push('## Endpoints', '', MD_NONE, '')
+  }
+
+  if (spec.decisions?.length) {
+    lines.push('## Decisions', '')
+    for (const d of spec.decisions) {
+      lines.push(`- **${d.id ?? 'DEC'}:** ${d.summary ?? ''}`)
+    }
+    lines.push('')
+  }
+
+  if (spec.changeLog?.length) {
+    lines.push('## Change log', '')
+    for (const c of spec.changeLog) {
+      lines.push(`- **${c.id ?? 'CHG'}:** ${c.summary ?? ''}`)
+    }
+    lines.push('')
+  }
+
+  return lines.join('\n').endsWith('\n') ? lines.join('\n') : `${lines.join('\n')}\n`
+}
+
+/**
+ * @param {Record<string, unknown>} spec
+ * @param {{ specFile?: string, slug?: string }} context
+ */
+export function renderCommonSpecMarkdown(spec, context = {}) {
+  const title = spec.title ?? context.slug ?? 'Common API'
+  return [
+    `# ${escapeMarkdownHeading(title)}`,
+    '',
+    `- **Source:** \`${context.specFile ?? 'common.yaml'}\``,
+    '',
+    '```yaml',
+    stringify(spec).trim(),
+    '```',
+    '',
+  ].join('\n')
+}