---
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.
