@atlashub/smartstack-cli 4.81.0 → 5.0.0

package/templates/skills/development/frontend/layout/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: scaffold-layout
+description: Scaffold the app-level layout shell (PageTemplate + AppShell) reading nav from /api/navigation/menu, honoring per-app branding via @customised marker.
+group: D
+phase: devFrontend
+kind: main
+section_label: 'SCAFFOLD-LAYOUT (PageTemplate + AppShell + nav rendering for the generated client app)'
+allowed-tools: [Read, Write, Edit, Glob, Grep]
+---
+
+# scaffold-layout — App-level layout shell scaffolder
+
+## Context
+
+You are scaffolding the **layout shell** of a SmartStack-generated React app. Two files anchor every page:
+
+- `src/components/ui/PageTemplate.tsx` — the wrapper every page mounts inside (`<PageTemplate title=…>`). Carries the breadcrumb, page title and content slot. Path matches what `scaffold-component` imports (`@/components/ui/PageTemplate`); a wrong path here triggers the silent-spinner subagent ad-lib that drops props.
+- `src/components/AppShell.tsx` — the top-level shell mounted at the root: header, sidebar (nav rendering from `/api/navigation/menu`), main content outlet.
+
+These files exist locally (not only in `@atlashub/smartstack` npm) so per-app branding can override them: logo placement, header slots, custom user menu. The npm package provides primitives (Sidebar, Header) and contracts (NavMenuResponse type); the local file is the customisation surface.
+
+Without these files, the BA dev pipeline (`audit-dev-frontend` rule DEV-UI-005) fails: pages reference `<PageTemplate>` but the import resolves to nothing.
+
+## Invocation
+
+```
+npx tsx skills/development/frontend/layout/cli/scaffold-layout/index.ts \
+  --spec '{"projectPath":"<abs>","appCode":"<app>"}'
+```
+
+`--spec` JSON:
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `projectPath` | string | yes | Absolute path to the web root (holds `src/`). |
+| `appCode` | string | yes | Used in the AppShell branding header. |
+| `force` | boolean | no | Overwrite even when content matches. Default false. |
+
+## What it produces
+
+- `src/components/ui/PageTemplate.tsx` — page wrapper. Renders `title`, `subtitle`, `icon`, `actions`, `className`, `contentClassName` and `children` (every prop the page templates pass).
+- `src/components/AppShell.tsx` — root shell with sidebar/header/main outlet.
+- `src/components/Sidebar.tsx` — nav rendering (separate file so apps can swap it).
+
+## Idempotency contract
+
+Same as scaffold-theme: `/* @customised */` (or `// @customised`) marker at the top of any file = preserve. Otherwise overwrite when content drifts. AUTO-GENERATED header included.
+
+## When NOT to use
+
+- Adding new sidebar items → those come from the BA navigation tables → `scaffold-core-seed` populates `/api/navigation/menu` → AppShell renders them automatically. Do not edit Sidebar.tsx by hand.
+- Per-page layout (split-pane, tabs) → those are page-level concerns; don't touch the shell.

package/templates/skills/development/frontend/layout/cli/scaffold-layout/__tests__/generate.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from 'vitest'
+import { generate } from '../generate.js'
+
+describe('scaffold-layout / generate', () => {
+  const spec = { projectPath: '/web', appCode: 'TestV2', force: false }
+
+  it('writes PageTemplate at src/components/ui/PageTemplate.tsx (not the legacy src/components path)', () => {
+    const files = generate(spec)
+    const pt = files.find((f) => f.path.endsWith('PageTemplate.tsx'))
+    expect(pt).toBeDefined()
+    expect(pt!.path).toBe('src/components/ui/PageTemplate.tsx')
+    // Negative: ensure the legacy non-ui path is gone — the path mismatch
+    // (scaffold-layout writes here, scaffold-component imports from /ui/)
+    // is the silent-spinner #1 root cause.
+    expect(files.some((f) => f.path === 'src/components/PageTemplate.tsx')).toBe(false)
+  })
+
+  it('declares all six props in PageTemplateProps', () => {
+    const files = generate(spec)
+    const pt = files.find((f) => f.path.endsWith('PageTemplate.tsx'))!
+    // Each prop name must appear in the interface
+    for (const prop of ['title', 'subtitle', 'icon', 'actions', 'children', 'className', 'contentClassName']) {
+      expect(pt.content).toMatch(new RegExp(`\\b${prop}\\??:`))
+    }
+  })
+
+  it('destructures and renders subtitle / icon / actions / className / contentClassName', () => {
+    const files = generate(spec)
+    const pt = files.find((f) => f.path.endsWith('PageTemplate.tsx'))!
+    // Destructured in the component signature (multiline OK)
+    expect(pt.content).toMatch(/title,[\s\S]*subtitle,[\s\S]*icon,[\s\S]*actions,[\s\S]*children,[\s\S]*className,[\s\S]*contentClassName/)
+    // Each prop is rendered somewhere in JSX
+    expect(pt.content).toMatch(/\{subtitle\s*&&/)
+    expect(pt.content).toMatch(/\{icon\s*&&/)
+    expect(pt.content).toMatch(/\{actions\s*&&/)
+    expect(pt.content).toMatch(/className\s*\?\?\s*''/)
+    expect(pt.content).toMatch(/contentClassName\s*\?\?\s*''/)
+  })
+
+  it('still emits AppShell + Sidebar at src/components/', () => {
+    const files = generate(spec)
+    expect(files.some((f) => f.path === 'src/components/AppShell.tsx')).toBe(true)
+    expect(files.some((f) => f.path === 'src/components/Sidebar.tsx')).toBe(true)
+  })
+
+  it('Fix #6 — emits no `: JSX.Element` return annotations (TS infers from JSX)', () => {
+    // Under `verbatimModuleSyntax: true`, `JSX` is not a global and would
+    // need `import type { JSX } from 'react'`. Cleanest is to omit the
+    // annotation — TS infers correctly from the JSX return.
+    const files = generate(spec)
+    for (const file of files.filter(f => f.path.endsWith('.tsx'))) {
+      expect(file.content, file.path).not.toMatch(/\):\s*JSX\.Element\s*\{/)
+    }
+  })
+
+  it('Fix #6 — emits `import type { ReactNode }` (not `import { ReactNode }`)', () => {
+    // Under verbatimModuleSyntax: true, value imports of types fail
+    // compilation with `'ReactNode' is a type and must be imported using a
+    // type-only import`. Force type-only imports everywhere ReactNode shows up.
+    const files = generate(spec)
+    for (const file of files.filter(f => f.path.endsWith('.tsx'))) {
+      // Negative: a bare value import of ReactNode must not appear.
+      expect(file.content, file.path).not.toMatch(/import\s*\{\s*ReactNode\b[^}]*\}\s*from\s*'react'/)
+    }
+  })
+})

package/templates/skills/development/frontend/layout/cli/scaffold-layout/generate.ts

@@ -0,0 +1,175 @@
+/**
+ * scaffold-layout/generate.ts — Build PageTemplate.tsx + AppShell.tsx + Sidebar.tsx.
+ *
+ * Pure function — no I/O.
+ */
+import type { GeneratedFile, ScaffoldLayoutInput } from './types.js';
+
+const HEADER = `/* AUTO-GENERATED — re-run scaffold-layout to refresh. Add @customised at the top to opt out. */`;
+
+function pageTemplate(): string {
+  return `${HEADER}
+import { useEffect, type ReactNode, Fragment } from 'react';
+import { Link } from 'react-router-dom';
+import { ChevronRight } from 'lucide-react';
+
+export interface BreadcrumbItem {
+  readonly label: string;
+  readonly href?: string;
+}
+
+export interface PageTemplateProps {
+  title: string;
+  subtitle?: string | null;
+  icon?: ReactNode;
+  actions?: ReactNode;
+  breadcrumbs?: BreadcrumbItem[];
+  children: ReactNode;
+  className?: string;
+  contentClassName?: string;
+}
+
+export function PageTemplate({
+  title,
+  subtitle,
+  icon,
+  actions,
+  breadcrumbs,
+  children,
+  className,
+  contentClassName,
+}: PageTemplateProps) {
+  useEffect(() => {
+    const prev = document.title;
+    document.title = title;
+    return () => {
+      document.title = prev;
+    };
+  }, [title]);
+
+  return (
+    <div className={\`flex flex-col gap-6 p-6 \${className ?? ''}\`}>
+      {breadcrumbs && breadcrumbs.length > 0 && (
+        <nav aria-label="Breadcrumb" className="flex items-center gap-1.5 text-sm">
+          {breadcrumbs.map((item, i) => (
+            <Fragment key={i}>
+              {i > 0 && <ChevronRight className="w-3.5 h-3.5 text-[var(--text-muted)]" />}
+              {item.href && i < breadcrumbs.length - 1 ? (
+                <Link to={item.href} className="text-[var(--text-muted)] hover:text-[var(--color-accent-600)] transition-colors">
+                  {item.label}
+                </Link>
+              ) : (
+                <span className={i === breadcrumbs.length - 1 ? 'font-medium text-[var(--text-primary)]' : 'text-[var(--text-muted)]'}>
+                  {item.label}
+                </span>
+              )}
+            </Fragment>
+          ))}
+        </nav>
+      )}
+      <header className="flex items-center justify-between">
+        <div className="flex items-center gap-3">
+          {icon && <span className="text-[var(--color-accent-500)]">{icon}</span>}
+          <div>
+            <h1 className="text-2xl font-bold text-[var(--text-primary)]">{title}</h1>
+            {subtitle && <p className="text-sm text-[var(--text-muted)]">{subtitle}</p>}
+          </div>
+        </div>
+        {actions && <div className="flex items-center gap-2">{actions}</div>}
+      </header>
+      <main className={contentClassName ?? ''}>{children}</main>
+    </div>
+  );
+}
+`;
+}
+
+function appShell(spec: ScaffoldLayoutInput): string {
+  const brand = spec.appCode.charAt(0).toUpperCase() + spec.appCode.slice(1);
+  return `${HEADER}
+import type { ReactNode } from 'react';
+import { Sidebar } from './Sidebar';
+
+export interface AppShellProps {
+  children: ReactNode;
+}
+
+export function AppShell({ children }: AppShellProps) {
+  return (
+    <div className="flex flex-col h-screen bg-[var(--bg-app)]">
+      <header className="flex items-center justify-between h-14 px-4 border-b border-[var(--border-color)] bg-[var(--bg-card)]">
+        <div className="text-lg font-semibold text-[var(--text-primary)]">${brand}</div>
+        <div className="flex items-center gap-2">{/* user menu, theme toggle, etc. */}</div>
+      </header>
+      <div className="flex flex-1 overflow-hidden">
+        <aside className="w-64 border-r border-[var(--border-color)] bg-[var(--bg-card)] overflow-y-auto">
+          <Sidebar />
+        </aside>
+        <main className="flex-1 overflow-y-auto">{children}</main>
+      </div>
+    </div>
+  );
+}
+`;
+}
+
+function sidebar(): string {
+  return `${HEADER}
+import { useEffect, useState } from 'react';
+import { Link } from 'react-router-dom';
+import { api } from '@atlashub/smartstack';
+
+interface NavEntry {
+  componentKey: string;
+  label: string;
+  href: string;
+  children?: NavEntry[];
+}
+
+export function Sidebar() {
+  const [entries, setEntries] = useState<NavEntry[]>([]);
+
+  useEffect(() => {
+    api.get<NavEntry[]>('/api/navigation/menu')
+      .then((r) => setEntries(Array.isArray(r) ? r : []))
+      .catch(() => setEntries([]));
+  }, []);
+
+  return (
+    <nav className="flex flex-col gap-1 p-3">
+      {entries.map((e) => (
+        <NavItem key={e.componentKey} entry={e} />
+      ))}
+    </nav>
+  );
+}
+
+function NavItem({ entry }: { entry: NavEntry }) {
+  return (
+    <div className="flex flex-col">
+      <Link
+        to={entry.href}
+        className="px-3 py-2 rounded-[var(--radius-button)] text-sm text-[var(--text-primary)] hover:bg-[var(--bg-hover)] transition-colors"
+      >
+        {entry.label}
+      </Link>
+      {entry.children && entry.children.length > 0 && (
+        <div className="ml-4 flex flex-col gap-0.5">
+          {entry.children.map((c) => (
+            <NavItem key={c.componentKey} entry={c} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+`;
+}
+
+export function generate(spec: ScaffoldLayoutInput): GeneratedFile[] {
+  return [
+    { path: 'src/components/ui/PageTemplate.tsx', content: pageTemplate() },
+    { path: 'src/components/AppShell.tsx', content: appShell(spec) },
+    { path: 'src/components/Sidebar.tsx', content: sidebar() },
+  ];
+}

package/templates/skills/development/frontend/layout/cli/scaffold-layout/index.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * cli:scaffold-layout — Scaffold app-level layout shell.
+ *
+ * Idempotent: skips writes if existing file content matches; honors
+ * `/* @customised *\/` (or `// @customised`) marker at the top of the file.
+ */
+import { parseArgs } from 'node:util';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { validate } from './validate.js';
+import { generate } from './generate.js';
+import { generateEnvelope, failGenerate, printEnvelope } from '../../../../../lib/output.js';
+
+const COMMAND = 'scaffold-layout';
+
+function isCustomised(source: string): boolean {
+  const head = source.trimStart().slice(0, 100);
+  return head.startsWith('/* @customised') || head.startsWith('// @customised');
+}
+
+function main(): 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.spec) {
+    printEnvelope(failGenerate(COMMAND, validation.errors));
+    process.exit(1);
+  }
+
+  const spec = validation.spec;
+  const files = generate(spec);
+
+  if (values.dry_run) {
+    printEnvelope(generateEnvelope(COMMAND, {
+      data: { dryRun: true, files: files.map((f) => f.path) },
+      warnings: validation.warnings,
+    }));
+    process.exit(0);
+  }
+
+  const filesCreated: string[] = [];
+  const filesModified: string[] = [];
+  const skipped: string[] = [];
+
+  for (const file of files) {
+    const abs = resolve(join(spec.projectPath, file.path));
+    if (existsSync(abs)) {
+      const existing = readFileSync(abs, 'utf-8');
+      if (isCustomised(existing)) {
+        skipped.push(file.path);
+        continue;
+      }
+      if (!spec.force && existing === file.content) continue;
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, file.content, 'utf-8');
+      filesModified.push(abs);
+    } else {
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, file.content, 'utf-8');
+      filesCreated.push(abs);
+    }
+  }
+
+  const nextSteps: string[] = [];
+  if (skipped.length > 0) {
+    nextSteps.push(`Skipped ${skipped.length} customised file(s): ${skipped.join(', ')}. Remove the @customised marker to allow overwrites.`);
+  }
+  if (filesCreated.length === 0 && filesModified.length === 0 && skipped.length === 0) {
+    nextSteps.push('Layout already up-to-date — no changes needed.');
+  }
+  if (filesCreated.length > 0) {
+    nextSteps.push('Wrap your routes in <AppShell> at src/main.tsx (or App.tsx) to mount the new shell.');
+  }
+
+  printEnvelope(generateEnvelope(COMMAND, {
+    data: { fileCount: filesCreated.length + filesModified.length, skipped: skipped.length },
+    filesCreated,
+    filesModified,
+    warnings: validation.warnings,
+    nextSteps,
+  }));
+}
+
+main();

package/templates/skills/development/frontend/layout/cli/scaffold-layout/types.ts

@@ -0,0 +1,17 @@
+/**
+ * scaffold-layout/types.ts — Input contract + generated file shape.
+ */
+import { z } from 'zod';
+
+export const ScaffoldLayoutInputSchema = z.object({
+  projectPath: z.string().min(1),
+  appCode: z.string().min(1),
+  force: z.boolean().default(false),
+});
+
+export type ScaffoldLayoutInput = z.infer<typeof ScaffoldLayoutInputSchema>;
+
+export interface GeneratedFile {
+  path: string;
+  content: string;
+}

package/templates/skills/development/frontend/layout/cli/scaffold-layout/validate.ts

@@ -0,0 +1,37 @@
+/**
+ * scaffold-layout/validate.ts — Args validation.
+ */
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { ScaffoldLayoutInputSchema, type ScaffoldLayoutInput } from './types.js';
+
+export interface ValidationResult {
+  valid: boolean;
+  spec: ScaffoldLayoutInput | null;
+  errors: string[];
+  warnings: string[];
+}
+
+export function validate(raw: unknown): ValidationResult {
+  const parsed = ScaffoldLayoutInputSchema.safeParse(raw);
+  if (!parsed.success) {
+    return {
+      valid: false,
+      spec: null,
+      errors: parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`),
+      warnings: [],
+    };
+  }
+  const spec = parsed.data;
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  const abs = path.resolve(spec.projectPath);
+  if (!existsSync(abs)) errors.push(`projectPath does not exist: ${abs}`);
+  else if (!statSync(abs).isDirectory()) errors.push(`projectPath is not a directory: ${abs}`);
+  else if (!existsSync(path.join(abs, 'src'))) {
+    warnings.push(`projectPath has no "src" folder yet — it will be created.`);
+  }
+
+  return { valid: errors.length === 0, spec, errors, warnings };
+}

package/templates/skills/development/frontend/routes/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: frontend-routes
+description: >
+  Generates PageRegistry registrations for SmartStack's DB-driven routing
+  (DynamicRouter). Validates componentKey format before emission and fails
+  loud on bad specs rather than producing silent-spinner registries.
+phase: development/frontend
+cli: cli/scaffold-routes
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# Frontend Routes — PageRegistry + DynamicRouter
+
+Generates route registrations for SmartStack's database-driven routing system.
+The CLI emits **one file per module** (`src/extensions/{module}Registry.ts`)
+that calls `PageRegistry.register()` for each page.
+
+## Output pattern
+
+```ts
+// src/extensions/hrmRegistry.ts
+import React from 'react';
+import { PageRegistry, lazyWithRetry } from '@atlashub/smartstack';
+
+const EmployeeListPage = lazyWithRetry(() =>
+  import('@/pages/myapp/hrm/employees/EmployeeListPage').then((m) => {
+    const mod = m as { default?: React.ComponentType; EmployeeListPage?: React.ComponentType };
+    const resolved = mod.EmployeeListPage ?? mod.default;
+    if (!resolved) {
+      throw new Error("Page 'EmployeeListPage' at @/pages/myapp/hrm/employees/EmployeeListPage has no default or named export matching its file name.");
+    }
+    return { default: resolved };
+  })
+);
+
+PageRegistry.register('myapp.hrm.employees', EmployeeListPage);
+// ... detail, create, edit
+```
+
+`lazyWithRetry` (re-exported from `@atlashub/smartstack` since v3.51+) wraps
+`React.lazy` with exponential-backoff retry on transient `ChunkLoadError`s
+(HMR rebundle window, CDN flap, post-deploy stale cache). Without retry, a
+transient `Failed to fetch dynamically imported module` surfaces immediately
+as a `RouteErrorBoundary` screen on the user's first navigation after a
+deploy. With retry, the next attempt picks up the fresh chunk.
+
+The wrapper also tolerates both `export default` and `export const {PageName}`
+forms. If neither exists, it throws at resolution time with a developer-readable
+message — preventing the classic silent-spinner failure.
+
+## ⚠ BLOCKING — componentKey validation
+
+The CLI validates every emitted `componentKey` against SmartStack's contract
+BEFORE writing files. On failure, the CLI throws — no partial registry is emitted.
+
+Rules (enforced by `validateComponentKey` in `types.ts`):
+- 2 to 4 dot-separated segments: `{app}.{module}`, `{app}.{module}.{section}`, or `{app}.{module}.{section}.{view}`
+- Each segment matches `/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/` (kebab-case, starts with letter)
+- Final segment may be one of the 24 implicit suffixes (detail, edit, create, new, duplicate, settings, configure, permissions, members, history, logs, analytics, preview, versions, comments, attachments, audit, export, notifications, schedule, workflow, summary, test, runs, import)
+
+Rejected examples:
+- `Hrm.Employees.List` (not kebab-case)
+- `hrm.employees` (only 2 segments when app is required)
+- `myapp.hrm..employees` (empty segment)
+- `hrm.employees.list.page.details` (5 segments)
+
+## ⚠ BLOCKING — Wiring in main.tsx
+
+Every generated `{module}Registry.ts` MUST be imported in `src/main.tsx` BEFORE
+`createRoot(...).render(...)`:
+
+```tsx
+import './extensions/hrmRegistry';
+import './extensions/catalogueRegistry';
+// ... one per module
+
+createRoot(...).render(<App />);
+```
+
+Missing this import = the `PageRegistry.register()` calls never run = `DynamicRouter`
+finds nothing = blank screen for every route in that module.
+
+The `frontend/structure` SKILL's `main.tsx` template lists the expected shape.
+
+## ⚠ BLOCKING — Key Rules
+
+1. **DB-driven routes**: routes come from `GET /api/navigation/menu`, NEVER hardcoded in the React tree.
+2. **PageRegistry**: central registry mapping `componentKey` → lazy-loaded component.
+3. **Implicit suffixes**: `.detail` → `/:id`, `.edit` → `/:id/edit`, `.create` → `/create`. Handled by `DynamicRouter` — do NOT add `<Route path="/:id">` manually.
+4. **ProtectedRoute**: applied globally by `DynamicRouter` — no per-route wrapping needed.
+5. **Lazy loading**: ALL pages via `lazyWithRetry()` (re-exported from `@atlashub/smartstack`) — never bare `React.lazy()` (no retry on chunk-load races) and never static imports of page components.
+6. **No hardcoded navigation**: `<Link to={getPath('myapp.hrm.employees')}>` via SDK helper, or relative `<Link to="../employees/123">`.
+7. **componentKey MUST match the seed ComponentKey**: backend seed + frontend registry are two halves of the same contract. Diff = silent spinner.
+8. **Permission matching via `hasRouteAccess(permKey, routePath)`** — never bypass with `hasFullAccess`, never compare strings raw. Rules: `*` matches everything (super-admin only), `app.*` matches any `app.module.action`, `app.module.read` implies access to `app.module` (read is the baseline access action), otherwise exact match.
+
+## Menu API contract (DB → DTO → DynamicRouter)
+
+`GET /api/navigation/menu` returns a **4-level hierarchy of DTOs** that the frontend's `useRouteConfig` flattens into routes:
+
+```
+ApplicationMenuDto  →  ModuleMenuDto  →  SectionMenuDto  →  ResourceMenuDto
+       │                    │                  │                  │
+       ├─ ComponentKey      ├─ ComponentKey    ├─ ComponentKey    ├─ ComponentKey
+       ├─ PermissionPath    ├─ PermissionPath  ├─ PermissionPath  └─ PermissionPath
+       ├─ IsOpen ⚠          ├─ RequiredFeature
+       └─ RequiredFeature
+```
+
+- `ComponentKey` + `PermissionPath` exist at **every** level (computed at runtime from hierarchical code paths).
+- **`IsOpen` exists ONLY on `ApplicationMenuDto`** — domain property persisted on `core.nav_Applications`. When `true`, bypasses permission + feature checks at the Application level (e.g. `myspace.*` is always accessible to authenticated users). The seeding skill MUST set `IsOpen` on the Application, never on lower levels.
+- **`RequiredFeature` exists on `ApplicationMenuDto` and `ModuleMenuDto`** (2 levels, sourced from `LicenseFeatureMapping`) — gates by license edition.
+- `OUTLET_SECTIONS` config (in `DynamicRouter`) declares sections that render their sub-pages via React Router `<Outlet>` (tab UIs like `Settings`, `AppSettings`). Components resolve from `PageRegistry` — never hardcode the Outlet tree.
+
+## After generation — MANDATORY
+
+```
+@.claude/skills/development/audit/SKILL.md
+Audit the route registrations I just generated. Check lazy-loading,
+componentKey format, main.tsx wiring, no hardcoded <Route path=>.
+```
+
+## Invocation
+
+```bash
+npx tsx skills/development/frontend/routes/cli/scaffold-routes/index.ts \
+  --spec '{"module":"hrm","appCode":"myapp","entities":[{"name":"Employee","section":"employees","views":["list","detail","create"]}],"projectPath":"/path"}'
+```
+
+## Output files
+
+- `src/extensions/{module}Registry.ts` — one file per module, contains all `PageRegistry.register(...)` calls.
+- `src/extensions/{module}Routes.ts` — single source of truth for URL paths in
+  the module. Generated alongside the registry from the same spec, so URL
+  paths and componentKeys can never drift. Generated pages MUST consume it
+  (`import { routes } from '@/extensions/${module}Routes'`) instead of
+  hardcoding URLs in `navigate()` calls.
+
+  ```ts
+  // Example: src/extensions/budgetsRoutes.ts
+  export const routes = {
+    budgets: {
+      list:   () => '/budgets/budgets',
+      detail: (id: string) => `/budgets/budgets/${id}`,
+      edit:   (id: string) => `/budgets/budgets/${id}/edit`,
+      create: () => '/budgets/budgets/create',
+    },
+  } as const;
+  ```
+
+  URL conventions match `DynamicRouter`'s `IMPLICIT_SUFFIXES` table : `.create`
+  → `/create` (NOT `/new`), `.detail` → `/:id`, `.edit` → `/:id/edit`. Audit
+  DEV-UI-013 catches any page that bypasses the helper with a hardcoded URL.