@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/documentation/cli/extract-doc/index.ts

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * cli:extract-doc — read-only extraction for the /documentation skill.
+ *
+ * Emits an ExecuteEnvelope on stdout and writes NO files. Claude reads the
+ * `report` to author a faithful doc page, then calls scaffold-doc (i18n +
+ * wiring) and ui-polish (theme tokens).
+ *
+ * Usage:
+ *   npx tsx skills/documentation/cli/extract-doc/index.ts \
+ *     --spec '{"type":"user","target":"users","application":"administration","projectPath":"/abs/path"}'
+ */
+import { parseArgs } from 'node:util'
+import { validate } from './validate.js'
+import { extract } from './extract.js'
+import { executeEnvelope, failExecute, printEnvelope } from '../../../lib/output.js'
+import type { ExtractDocInput, ExtractReport } from './types.js'
+
+const COMMAND = 'extract-doc'
+
+async function main(): Promise<void> {
+  const { values } = parseArgs({ options: { spec: { type: 'string' } }, strict: true })
+  if (!values.spec) {
+    printEnvelope(failExecute(COMMAND, ['--spec is required']))
+    process.exit(1)
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(values.spec)
+  } catch {
+    printEnvelope(failExecute(COMMAND, ['Invalid JSON in --spec']))
+    process.exit(1)
+  }
+  const validation = validate(raw)
+  if (!validation.valid) {
+    printEnvelope(failExecute(COMMAND, validation.errors))
+    process.exit(1)
+  }
+  const warnings = [...validation.warnings]
+  try {
+    const report = await extract(raw as ExtractDocInput, warnings)
+    printEnvelope(executeEnvelope<ExtractReport>(COMMAND, { report, warnings, nextSteps: buildNextSteps(report) }))
+  } catch (err) {
+    printEnvelope(failExecute(COMMAND, [err instanceof Error ? err.message : String(err)]))
+    process.exit(1)
+  }
+}
+
+function buildNextSteps(report: ExtractReport): string[] {
+  const steps: string[] = []
+
+  // Corrective gate (two mirror checks): surface forbidden "sales" framing to
+  // strip AND a missing mandatory "objective" to add. The step-03 gate re-runs
+  // this same scan and blocks until the doc is both clean and complete.
+  const forbidden = report.existingDoc.forbiddenSections
+  if (forbidden.length > 0) {
+    const locations = forbidden.map((f) => `${f.file}:${f.line} (${f.token})`).join(', ')
+    steps.push(
+      `EXISTING doc contains forbidden problème/solution / Bénéfices / Avant-Après sections at ${locations} — ` +
+        `REMOVE them while regenerating. Do NOT re-author the benefits/beforeAfter/problem/solution keys ` +
+        `(the doc leads with a factual "objective", not a sales pitch). The step-03 gate re-runs this scan and blocks until clean.`,
+    )
+  }
+  const missing = report.existingDoc.missingRequired
+  if (missing.includes('objective')) {
+    steps.push(
+      `EXISTING doc has NO "Objectif" section — the mandatory Section 1 (a short factual description of what the ` +
+        `module does, written as an objective). ADD it FIRST as its own section: author the i18n keys ` +
+        `"sections.objective" + "objective" (user) or "overview.objective" (DocRenderer) and render t('objective'). ` +
+        `The header subtitle is NOT a substitute. The step-03 gate re-runs this scan and blocks until present.`,
+    )
+  }
+  if (missing.includes('summary')) {
+    steps.push(
+      `EXISTING user doc has NO header accent tagline — the one-line accent summary between the title and the ` +
+        `subtitle. ADD the i18n key "summary" and render it as <p class="text-xl text-[var(--color-accent-600)] ` +
+        `font-medium">{t('summary')}</p>, then the stats line (N {t('header.businessRules')} · N {t('header.apiEndpoints')} · …, ` +
+        `count as plain sibling text, NOT pills). The step-03 gate blocks until present.`,
+    )
+  }
+
+  if (report.type === 'user') {
+    steps.push(
+      report.resolved.pageTsxPath
+        ? `Read ${report.resolved.pageTsxPath} and reproduce it faithfully as annotated Mock UI (do NOT invent a generic table/KPI layout).`
+        : 'No real page found under src/pages — author the Mock UI from the live app or the pagespec.',
+    )
+    if (report.charts.length > 0) {
+      steps.push(
+        `Match each chart TYPE: ${report.charts
+          .map((c) => `${c.component} → ${c.mockUiPattern}`)
+          .join(' | ')}`,
+      )
+    }
+  }
+  steps.push(
+    'Then call scaffold-doc to write the i18n files (4 langs) + wire routes/manifest/config, and run ui-polish to enforce theme tokens.',
+  )
+  return steps
+}
+
+void main()

package/templates/skills/documentation/cli/extract-doc/types.ts

@@ -0,0 +1,133 @@
+/**
+ * cli:extract-doc — types.ts
+ *
+ * Read-only extraction for the /documentation skill. Produces a JSON report
+ * (NO file writes) that Claude consumes to author a faithful doc page:
+ *   - the real page TSX path (so Claude can read & reproduce it),
+ *   - chart type per imported chart (recharts → Mock UI pattern),
+ *   - API endpoints, business rules, entity properties,
+ *   - a suggested i18n namespace + base routes for the wiring step.
+ *
+ * Extraction is richest for `user` (reads page + controller + entity + tests).
+ * For developer/testing the report is intentionally thin — those docs are
+ * authored from external/tool knowledge, not from project code.
+ */
+import { z } from 'zod'
+
+export const ExtractDocInputSchema = z.object({
+  type: z.enum(['user', 'developer', 'database', 'testing']),
+  /** Module / tool / schema name, lowercase (e.g. "users", "sla", "support"). */
+  target: z.string().min(1),
+  /** Parent application for `user` docs (e.g. "administration"). */
+  application: z.string().min(1).optional(),
+  /** Explicit page TSX (relative to projectPath) to document — overrides auto-detection. */
+  pagePath: z.string().min(1).optional(),
+  /** Absolute path to the SmartStack project root being documented. */
+  projectPath: z.string().min(1),
+})
+
+export type ExtractDocInput = z.infer<typeof ExtractDocInputSchema>
+
+export interface ChartInfo {
+  /** Imported chart component name (e.g. "WeeklyUsageChart"). */
+  component: string
+  /** Raw import specifier (e.g. "@/components/dashboard/WeeklyUsageChart"). */
+  importPath: string
+  /** Resolved source file (relative to project root) or null if unresolved. */
+  sourceFile: string | null
+  /** Detected recharts primitive (BarChart | PieChart | LineChart | …). */
+  rechartsType: string | null
+  /** `layout=` prop value when present (drives vertical vs horizontal bars). */
+  layout: string | null
+  /** Human guidance for the faithful Mock UI pattern to generate. */
+  mockUiPattern: string
+}
+
+export interface ApiEndpoint {
+  method: string
+  path: string
+  handler: string
+  permission: string
+}
+
+export interface BusinessRule {
+  id: string
+  name: string
+  category: string
+  statement: string
+}
+
+export interface EntityProperty {
+  name: string
+  type: string
+  nullable: boolean
+}
+
+/**
+ * A forbidden "sales" framing detected in an EXISTING doc artifact
+ * (problème/solution, Bénéfices, Avant/Après). Documentation leads with a
+ * factual `objective` — never a value-proposition pitch (SKILL.md rule #12).
+ */
+export interface ForbiddenSection {
+  /** File the token was found in (relative to project root). */
+  file: string
+  /** 1-based line number. */
+  line: number
+  /** The offending token (problem | solution | benefits | beforeAfter | a literal section title). */
+  token: string
+  /** Trimmed source line (truncated) for the report. */
+  snippet: string
+}
+
+/** Scan of the EXISTING doc page / doc-data / i18n for structural compliance. */
+export interface ExistingDocReport {
+  /** Whether any existing doc artifact was located for this module. */
+  found: boolean
+  /** Located artifacts (index.tsx / doc-data.ts / docs-<kebab>.json), relative to project root. */
+  files: string[]
+  /** Forbidden sections still present — non-empty means the doc must be corrected. */
+  forbiddenSections: ForbiddenSection[]
+  /**
+   * Mandatory elements ABSENT from an existing doc (the mirror of
+   * `forbiddenSections`). May contain:
+   *   - `'objective'` — the factual Section 1 that replaced problème/solution
+   *     (all doc types; SKILL.md rule #12).
+   *   - `'summary'` — the header accent tagline (`user` type only; the one-line
+   *     accent summary between title and subtitle).
+   * Empty when the doc is compliant, or when none was found yet (nothing to
+   * require before the doc is authored).
+   */
+  missingRequired: string[]
+}
+
+export interface ExtractReport {
+  type: string
+  target: string
+  application: string | null
+  /** Suggested i18n namespace, e.g. "docsAdministrationUsers". */
+  namespace: string
+  resolved: {
+    projectRoot: string
+    webRoot: string | null
+    apiDir: string | null
+    domainDir: string | null
+    /** Real page TSX (relative to project root) Claude must read & reproduce. */
+    pageTsxPath: string | null
+    pageCandidatesTried: string[]
+  }
+  navRoute: string | null
+  /** Best-effort frontend routes for wiring (DocPanelContext keys / manifest). */
+  suggestedRoutes: string[]
+  charts: ChartInfo[]
+  apiEndpoints: ApiEndpoint[]
+  businessRules: BusinessRule[]
+  entity: { name: string; file: string | null; properties: EntityProperty[] } | null
+  /** Forbidden-section scan of the EXISTING doc (drives the step-03 corrective gate). */
+  existingDoc: ExistingDocReport
+}
+
+export interface ValidationResult {
+  valid: boolean
+  errors: string[]
+  warnings: string[]
+}

package/templates/skills/documentation/cli/extract-doc/validate.ts

@@ -0,0 +1,35 @@
+/**
+ * cli:extract-doc — validate.ts
+ *
+ * Structural Zod validation + a non-blocking sanity check that the project
+ * path exists. Never blocks on missing layers (Domain/Api/web): extraction
+ * degrades gracefully and reports what it could not find as warnings, so a
+ * partially-scaffolded project still yields a useful report.
+ */
+import { existsSync } from 'node:fs'
+import { ExtractDocInputSchema, type ValidationResult } from './types.js'
+
+export function validate(raw: unknown): ValidationResult {
+  const result = ExtractDocInputSchema.safeParse(raw)
+  if (!result.success) {
+    return {
+      valid: false,
+      errors: result.error.issues.map((i) => `[${i.path.join('.')}] ${i.message}`),
+      warnings: [],
+    }
+  }
+  if (!existsSync(result.data.projectPath)) {
+    return {
+      valid: false,
+      errors: [`projectPath does not exist: ${result.data.projectPath}`],
+      warnings: [],
+    }
+  }
+  const warnings: string[] = []
+  if (result.data.type === 'user' && !result.data.application) {
+    warnings.push(
+      'No `application` provided for a user-type doc — the namespace/route suggestions will omit the app prefix.',
+    )
+  }
+  return { valid: true, errors: [], warnings }
+}

package/templates/skills/documentation/cli/scaffold-doc/generate.ts

@@ -0,0 +1,198 @@
+/**
+ * cli:scaffold-doc — generate.ts
+ *
+ * Deterministic file ops (i18n locale JSON + docs-manifest.json upsert, both
+ * idempotent) and computation of the wiring plan for the in-place TSX edits.
+ * Locates the wiring target files by glob so it adapts to client projects that
+ * differ from the reference app; when a target is missing it still returns the
+ * instruction (file=null) so nothing is silently skipped.
+ */
+import path from 'node:path'
+import { findSmartStackStructure } from '../../../lib/detector.js'
+import { findFiles, readJson, writeJson, fileExists } from '../../../lib/fs.js'
+import { toKebabCase } from '../../../lib/string-utils.js'
+import { LANGS, type ScaffoldDocInput, type WiringInstruction } from './types.js'
+
+export interface GenerateResult {
+  filesCreated: string[]
+  filesModified: string[]
+  warnings: string[]
+  wiring: WiringInstruction[]
+  nextSteps: string[]
+}
+
+export async function generate(spec: ScaffoldDocInput): Promise<GenerateResult> {
+  const res: GenerateResult = { filesCreated: [], filesModified: [], warnings: [], wiring: [], nextSteps: [] }
+  const structure = await findSmartStackStructure(spec.projectPath)
+  const web = structure.web
+  if (!web) {
+    res.warnings.push('Web project not found under projectPath — cannot write i18n / manifest or locate wiring targets.')
+    return res
+  }
+
+  const kebab = toKebabCase(spec.namespace) // docsAdministrationUsers → docs-administration-users
+  const routeFull = `/docs/business/${spec.routePath}`
+
+  // ── 1. i18n locale files (FLAT shape, canonical central location) ────────
+  if (spec.i18n) {
+    for (const lang of LANGS) {
+      const content = spec.i18n[lang]
+      if (!content) continue
+      // user-type docs are FLAT (resolved via t('title')); DocRenderer types
+      // (developer/database/testing, resolved via t('<namespace>.path')) nest the
+      // content under the namespace key. Author flat content — the CLI wraps it.
+      const payload = spec.type === 'user' ? content : { [spec.namespace]: content }
+      const abs = path.join(web, 'src', 'i18n', 'locales', lang, `${kebab}.json`)
+      const existed = await fileExists(abs)
+      if (!spec.dryRun) await writeJson(abs, payload)
+      ;(existed ? res.filesModified : res.filesCreated).push(relTo(spec.projectPath, abs))
+    }
+  }
+
+  // ── 2. docs-manifest.json upsert (idempotent by id) ──────────────────────
+  const manifestAbs = path.join(web, 'src', 'pages', 'docs', 'docs-manifest.json')
+  if (await fileExists(manifestAbs)) {
+    const manifest = await readJson<{ modules?: ManifestEntry[]; lastUpdated?: string; [k: string]: unknown }>(
+      manifestAbs,
+    )
+    if (!Array.isArray(manifest.modules)) manifest.modules = []
+    const now = new Date().toISOString()
+    const languages = spec.i18n ? Object.keys(spec.i18n) : [...LANGS]
+    const dataFile = `${spec.pageImportPath.replace(/^@\/pages\/docs\//, '')}/index.tsx`
+    const existingIdx = manifest.modules.findIndex((m) => m.id === spec.manifest.id)
+    const entry: ManifestEntry = {
+      id: spec.manifest.id,
+      type: spec.type,
+      application: spec.application ?? '',
+      module: spec.target,
+      name: spec.manifest.name,
+      description: spec.manifest.description,
+      path: routeFull,
+      dataFile,
+      i18nNamespace: spec.namespace,
+      version: spec.manifest.version,
+      createdAt: existingIdx >= 0 ? (manifest.modules[existingIdx].createdAt ?? now) : now,
+      updatedAt: now,
+      languages,
+      deferredLanguages: spec.manifest.deferredLanguages,
+    }
+    if (existingIdx >= 0) manifest.modules[existingIdx] = entry
+    else manifest.modules.push(entry)
+    manifest.lastUpdated = now
+    if (!spec.dryRun) await writeJson(manifestAbs, manifest)
+    res.filesModified.push(relTo(spec.projectPath, manifestAbs))
+  } else {
+    res.warnings.push(
+      `docs-manifest.json not found at ${relTo(spec.projectPath, manifestAbs)} — manifest upsert skipped.`,
+    )
+  }
+
+  // ── 3. Wiring plan (TSX in-place edits Claude applies with Edit) ─────────
+  res.wiring = await computeWiring(spec, web, kebab, routeFull)
+
+  res.nextSteps = [
+    spec.i18n
+      ? 'i18n files written. Author the doc page body per templates.md (faithful Mock UI for user type).'
+      : 'Author the doc page body + the 4 i18n locale JSON files (FLAT) per templates.md.',
+    `Apply the ${res.wiring.length} wiring instruction(s) in report.data.wiring with Edit — each has an idempotencyMarker; skip if already present in the file.`,
+    'Run /ui-components (ui-polish CLI) on the generated page to guarantee zero hardcoded colors.',
+  ]
+  return res
+}
+
+interface ManifestEntry {
+  id: string
+  type: string
+  application: string
+  module: string
+  name: string
+  description: string
+  path: string
+  dataFile: string
+  i18nNamespace: string
+  version: string
+  createdAt?: string
+  updatedAt?: string
+  languages: string[]
+  deferredLanguages: string[]
+}
+
+async function computeWiring(
+  spec: ScaffoldDocInput,
+  web: string,
+  kebab: string,
+  routeFull: string,
+): Promise<WiringInstruction[]> {
+  const wiring: WiringInstruction[] = []
+
+  // (a) i18n config.ts — register the namespace (4 insertion points).
+  const configAbs = (await findFirst(web, '**/i18n/config.ts')) ?? (await findFirst(web, '**/i18n/config.tsx'))
+  wiring.push({
+    file: configAbs ? relTo(spec.projectPath, configAbs) : null,
+    action: `Register i18n namespace "${spec.namespace}" — FOUR insertion points in config.ts.`,
+    anchor: `ns: [`,
+    insert:
+      `1) destructured var: add \`${spec.namespace}\` to the \`const [ … ] = await Promise.all([\` list.\n` +
+      `2) import() call (same order): \`import(\`./locales/\${lang}/${kebab}.json\`).catch(() => ({ default: {} })),\`\n` +
+      `3) return object: \`${spec.namespace}: ${spec.namespace}.default || {},\`\n` +
+      `4) ns array: add the string \`'${spec.namespace}'\` inside \`ns: [ … ]\`.`,
+    idempotencyMarker: `'${spec.namespace}'`,
+  })
+
+  // (b) DocRoutes.tsx — lazy import + child route under /docs/business.
+  const routerAbs =
+    (await findFirst(web, '**/DocRoutes.tsx')) ?? (await findFirst(web, '**/DynamicRouter.tsx'))
+  wiring.push({
+    file: routerAbs ? relTo(spec.projectPath, routerAbs) : null,
+    action: 'Add the lazy import + child route for the doc page (route group "/docs/business").',
+    anchor: `path="/docs/business"`,
+    insert:
+      `// near the other lazy doc imports:\n` +
+      `const ${spec.componentName} = lazy(() => import('${spec.pageImportPath}'));\n` +
+      `// inside the <Route path="/docs/business" element={<DocsLayout/>}> group, as a child:\n` +
+      `<Route path="${spec.routePath}" element={<Suspense fallback={<PageLoader />}><${spec.componentName} /></Suspense>} />`,
+    idempotencyMarker: spec.componentName,
+  })
+
+  // (c) DocPanelContext.tsx — docMapping (+ optional appDocMapping default).
+  const panelAbs = await findFirst(web, '**/DocPanelContext.tsx')
+  const keys = spec.docMappings.length > 0 ? spec.docMappings : [spec.routePath]
+  const mappingLines = keys.map((k) => `  '${k}': '${routeFull}',`).join('\n')
+  wiring.push({
+    file: panelAbs ? relTo(spec.projectPath, panelAbs) : null,
+    action: 'Add the contextual-panel route mappings (and the app default if requested).',
+    anchor: `const docMapping`,
+    insert:
+      `// inside docMapping:\n${mappingLines}` +
+      (spec.appDocDefault && spec.application
+        ? `\n// inside appDocMapping:\n  '${spec.application}': '${routeFull}',`
+        : ''),
+    idempotencyMarker: `'${keys[0]}':`,
+  })
+
+  // (d) UserIndexPage.tsx — module entry (user type only).
+  if (spec.type === 'user') {
+    const indexAbs = await findFirst(web, '**/UserIndexPage.tsx')
+    const camel = spec.target.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase())
+    wiring.push({
+      file: indexAbs ? relTo(spec.projectPath, indexAbs) : null,
+      action: `Add the module entry under the "${spec.application ?? '?'}" application's modules[].`,
+      anchor: `modules: [`,
+      insert:
+        `{ name: t('user.modules.${camel}.name'), icon: FileText, href: '${routeFull}', description: t('user.modules.${camel}.description') },\n` +
+        `// also add user.modules.${camel}.name/.description to the docs i18n (UserIndexPage namespace), and pick a real lucide icon instead of FileText.`,
+      idempotencyMarker: `'${routeFull}'`,
+    })
+  }
+
+  return wiring
+}
+
+async function findFirst(cwd: string, pattern: string): Promise<string | null> {
+  const files = await findFiles(pattern, { cwd })
+  return files.length > 0 ? files[0] : null
+}
+
+function relTo(root: string, abs: string): string {
+  return path.relative(root, abs).replace(/\\/g, '/')
+}

package/templates/skills/documentation/cli/scaffold-doc/index.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * cli:scaffold-doc — write the deterministic doc artifacts + emit a wiring plan.
+ *
+ * Writes (idempotently): the 4 i18n locale JSON files (FLAT) and the
+ * docs-manifest.json entry. Computes a precise wiring plan (report.data.wiring)
+ * for the in-place TSX edits (i18n config.ts, DocRoutes.tsx, DocPanelContext.tsx,
+ * UserIndexPage.tsx) that Claude applies with Edit. Does NOT author the doc page
+ * body or i18n content — those stay LLM-authored per templates.md.
+ *
+ * Usage:
+ *   npx tsx skills/documentation/cli/scaffold-doc/index.ts --spec '<JSON>' [--dry_run]
+ */
+import { parseArgs } from 'node:util'
+import { validate } from './validate.js'
+import { generate } from './generate.js'
+import { generateEnvelope, failGenerate, printEnvelope } from '../../../lib/output.js'
+
+const COMMAND = 'scaffold-doc'
+
+async function main(): Promise<void> {
+  const { values } = parseArgs({
+    options: { spec: { type: 'string' }, dry_run: { type: 'boolean', default: false } },
+    strict: true,
+  })
+  if (!values.spec) {
+    printEnvelope(failGenerate(COMMAND, ['--spec is required']))
+    process.exit(1)
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(values.spec)
+  } catch {
+    printEnvelope(failGenerate(COMMAND, ['Invalid JSON in --spec']))
+    process.exit(1)
+  }
+  const validation = validate(raw)
+  if (!validation.valid || !validation.value) {
+    printEnvelope(failGenerate(COMMAND, validation.errors))
+    process.exit(1)
+  }
+  const spec = validation.value
+  if (values.dry_run) spec.dryRun = true
+  try {
+    const result = await generate(spec)
+    printEnvelope(
+      generateEnvelope(COMMAND, {
+        data: { dryRun: spec.dryRun, namespace: spec.namespace, wiring: result.wiring },
+        filesCreated: result.filesCreated,
+        filesModified: result.filesModified,
+        warnings: [...validation.warnings, ...result.warnings],
+        nextSteps: result.nextSteps,
+      }),
+    )
+  } catch (err) {
+    printEnvelope(failGenerate(COMMAND, [err instanceof Error ? err.message : String(err)]))
+    process.exit(1)
+  }
+}
+
+void main()

package/templates/skills/documentation/cli/scaffold-doc/types.ts

@@ -0,0 +1,72 @@
+/**
+ * cli:scaffold-doc — types.ts
+ *
+ * The deterministic side of doc generation. It does the file operations that
+ * are stable + error-prone for an LLM to do by hand:
+ *   - write the 4 i18n locale JSON files at the canonical path + shape (FLAT),
+ *   - idempotently upsert the `docs-manifest.json` entry (pure JSON),
+ *   - compute a precise WIRING PLAN (file + anchor + snippet + idempotency
+ *     marker) for the in-place TSX edits (i18n config.ts, DocRoutes.tsx,
+ *     DocPanelContext.tsx, UserIndexPage.tsx).
+ *
+ * The TSX edits themselves are returned as instructions (not auto-applied):
+ * those files vary across client projects, so Claude applies them with Edit,
+ * adapting to the real file — robust where a hardcoded regex would corrupt code.
+ * The doc page body + i18n CONTENT stay authored by Claude (templates.md).
+ */
+import { z } from 'zod'
+
+export const LANGS = ['fr', 'en', 'de', 'it'] as const
+
+export const ScaffoldDocInputSchema = z.object({
+  type: z.enum(['user', 'developer', 'database', 'testing']),
+  /** Module / tool / schema name, lowercase (e.g. "users"). */
+  target: z.string().min(1),
+  /** Parent application (e.g. "administration"). */
+  application: z.string().min(1).optional(),
+  /** i18n namespace, camelCase (e.g. "docsAdministrationUsers"). From extract-doc. */
+  namespace: z.string().min(1),
+  /** Route under /docs/business, no leading slash (e.g. "administration/users"). */
+  routePath: z.string().min(1),
+  /** Lazy component name for the route (e.g. "UsersDocPage"). */
+  componentName: z.string().min(1),
+  /** Page import specifier (e.g. "@/pages/docs/business/platform/administration/users"). */
+  pageImportPath: z.string().min(1),
+  /** Per-language i18n content (FLAT objects). FR is the source. Optional — Claude may write these itself. */
+  i18n: z.record(z.enum(LANGS), z.record(z.string(), z.unknown())).optional(),
+  manifest: z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    description: z.string().default(''),
+    version: z.string().default('1.0.0'),
+    deferredLanguages: z.array(z.string()).default([]),
+  }),
+  /** Pathname keys for DocPanelContext docMapping (e.g. ["administration/users","administration/users/list"]). */
+  docMappings: z.array(z.string()).default([]),
+  /** When true, also set appDocMapping[application] to this doc (the app's default doc). */
+  appDocDefault: z.boolean().default(false),
+  projectPath: z.string().min(1),
+  dryRun: z.boolean().default(false),
+})
+
+export type ScaffoldDocInput = z.infer<typeof ScaffoldDocInputSchema>
+
+export interface WiringInstruction {
+  /** Target file, relative to project root. Null if the file could not be located. */
+  file: string | null
+  /** Human description of the edit. */
+  action: string
+  /** A unique string already in the file, near where the insert goes. */
+  anchor: string
+  /** The text Claude should insert (usually right after the anchor / inside the anchored block). */
+  insert: string
+  /** If this string is already in the file, the wiring is done — skip (idempotency). */
+  idempotencyMarker: string
+}
+
+export interface ValidationResult {
+  valid: boolean
+  errors: string[]
+  warnings: string[]
+  value?: ScaffoldDocInput
+}

package/templates/skills/documentation/cli/scaffold-doc/validate.ts

@@ -0,0 +1,33 @@
+/**
+ * cli:scaffold-doc — validate.ts
+ * Zod validation (returns the parsed value WITH defaults applied) + non-blocking
+ * sanity checks. Never blocks on app-shape differences — generate degrades to
+ * warnings + wiring instructions.
+ */
+import { existsSync } from 'node:fs'
+import { ScaffoldDocInputSchema, type ValidationResult } from './types.js'
+
+export function validate(raw: unknown): ValidationResult {
+  const parsed = ScaffoldDocInputSchema.safeParse(raw)
+  if (!parsed.success) {
+    return {
+      valid: false,
+      errors: parsed.error.issues.map((i) => `[${i.path.join('.')}] ${i.message}`),
+      warnings: [],
+    }
+  }
+  const d = parsed.data
+  if (!existsSync(d.projectPath)) {
+    return { valid: false, errors: [`projectPath does not exist: ${d.projectPath}`], warnings: [] }
+  }
+  const warnings: string[] = []
+  if (!d.i18n) {
+    warnings.push('No i18n payload — author the 4 locale JSON files separately (templates.md).')
+  } else if (!d.i18n.fr) {
+    warnings.push('i18n payload has no `fr` (source language) — the FR file will not be written.')
+  }
+  if (d.type === 'user' && !d.application) {
+    warnings.push('user-type doc without `application` — the UserIndexPage wiring instruction will be generic.')
+  }
+  return { valid: true, errors: [], warnings, value: d }
+}