@feeef.dev/cli 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feeef.dev/cli",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Feeef developer CLI — templates, auth, and cloud tools",
   "type": "module",
   "bin": {
@@ -51,7 +51,7 @@
     "commander": "^12.1.0",
     "dotenv": "^16.4.7",
     "esbuild": "^0.25.0",
-    "feeef": "^0.12.1",
+    "feeef": "^0.12.2",
     "picocolors": "^1.1.1",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"

package/scaffolds/blank/.cursor/rules/feeef-theme.mdc

@@ -13,22 +13,24 @@ Before editing theme source, read:
 
 ## Non-negotiables
 
+- **Flat TSX for leaf customs** — `pages|shared|library/.../<name>.tsx` with `export const meta` + `function App()`.
+- Folder form (`<name>/<name>.tsx` + `slots/`) **only** when slots/children are required.
+- Never author new customs as `component.json` + `component.jsx`.
+- Never invent deep nested shell trees when a flat sibling stack + `$ref` works.
 - `code`, `propsSchema`, `slotsSchema`, `slots`, `slotsLayout` are **top-level** — never under `props`.
-- Custom components expose `function App() {}`. Author `.jsx`/`.tsx`; build bundles imports (see `docs/16-AUTHORING-TS-IMPORTS.md`).
 - Prefer `React.useState` / `React.useEffect` in custom code.
-- Styles: `hsl(var(--primary))` etc. — not raw decoration ints.
+- Styles: `hsl(var(--primary))` etc. — not raw decoration ints (`docs/12-DARK-LIGHT-THEME.md`).
 - Navigation: `Link` / `RouterNav` / `useRouter`.
-- Repeated UI → `shared/components/<id>/` + `$ref` (`docs/07-SHARED-COMPONENTS.md`).
-- Order / COD → `docs/08-ORDER-FORM.md` (draft, geo, `POST /api/orders/create`, anti-abuse).
-- Checkout / thanks / product → `docs/11-PAGES-CHECKOUT-THANKS-PRODUCT.md` (single `main` + slots).
-- Dark / light → `docs/12-DARK-LIGHT-THEME.md`.
+- Repeated UI → `shared/components/<id>.tsx` + `$ref` (`docs/07-SHARED-COMPONENTS.md`).
+- Order / COD → `docs/08-ORDER-FORM.md`.
+- Checkout / thanks / product → `docs/11-PAGES-CHECKOUT-THANKS-PRODUCT.md`.
 - Multilang → `docs/13-TEMPLATE-I18N.md`.
 - Product lists → `docs/14-FILTERATOR.md`.
-- Never `useEffect([cartCtx])` that resets shipping `state` to null — bootstrap once; preserve address.
 
 ## After edits
 
 ```bash
 npm run build   # or npm run check
+npm run typecheck
 npm run dev     # hard-refresh browser
 ```

package/scaffolds/blank/.cursor/rules/theme-source.mdc

@@ -8,25 +8,32 @@ alwaysApply: false
 
 You are editing **theme source**, not a hand-maintained `dist/data.json`.
 
-## Structure
+## Structure (required)
 
-- Prefer page-level: `pages/<page>/components/hero.tsx` — builds to published `sections.main`
-- Legacy: `pages/<page>/sections/<id>/components/` still works (do not mix with flat `components/` on the same page)
-- Leaf file: `export const meta` (+ `propsSchema`) + `function App() { … }`
-- Folder layout (`hero/component.tsx` + `slots/` / `children/`) only when nesting or colocated helpers are needed
+- **Flat TSX is mandatory for leaf customs:** `pages/<page>/components/<name>.tsx`
+- Same for shared/library leaves: `shared/components/<id>.tsx`, `library/components/<id>.tsx`
+- Leaf file = `export const meta` (+ `propsSchema`) + `function App() { … }`
 - Type props: `type Props = FeeefLivePropsOf<typeof propsSchema>` then `const p = props as Props`
-- `satisfies FeeefComponentMeta<typeof propsSchema>` keeps `meta.props` aligned with the schema
-- Prefer **slots** + `slotsLayout` for chrome instead of extra section keys (`header` / `footer`)
+- `satisfies FeeefComponentMeta<typeof propsSchema>` keeps `meta.props` aligned
+- **Folder only** when you need `slots/` / `children/` / colocated modules (`<name>/<name>.tsx`)
+- `$ref` placements are leaf `.json` stubs (not duplicated JSX)
+- Prefer a **flat sibling stack** on the page; use a shell folder only when slots are necessary
+- Built-ins (`cart_order_form`, `product_body`, …) are leaf `.json` with `"type": "…"`
+
+## Forbidden
+
+1. `component.json` + `component.jsx` pairs for new customs
+2. Both `hero.tsx` and `hero/` for the same id
+3. Mixing `pages/<page>/components/` and `pages/<page>/sections/` on one page
+4. Inventing deep nested `*-shell/slots/**` trees when flat siblings + `$ref` work
+5. Putting JSX inside `.json` meta / `$ref` files
+6. Duplicating header/footer JSX — use `shared/components/<id>.tsx` + `$ref`
 
 ## Rules
 
-1. Do not put JSX inside `.json` meta files.
-2. Custom components: flat `<name>.tsx` with `export const meta` + `function App()` (legacy folder ok).
-3. Set `"order"` so sibling order is deterministic.
-4. Slot folder names must match `slotsSchema` keys.
-5. After edits: `npm run build` (or rely on `npm run dev` watch).
-6. Read `docs/03-CUSTOM-COMPONENTS.md` before writing JSX.
-7. Read `docs/05-ANTI-PATTERNS.md` before inventing patterns.
-8. If UI exists on another page, use `shared/components/<id>.tsx` — do not duplicate.
-9. Do not mix `pages/<page>/components/` and `pages/<page>/sections/` on the same page.
-10. Prefer `feeef template add page|component` / `remove` over hand-creating trees (keeps manifest + starter meta in sync).
+1. Set `"order"` so sibling order is deterministic.
+2. Slot folder names must match `slotsSchema` keys.
+3. After edits: `npm run build` (or rely on `npm run dev` watch).
+4. Read `docs/03-CUSTOM-COMPONENTS.md` before writing JSX.
+5. Read `docs/05-ANTI-PATTERNS.md` before inventing patterns.
+6. Prefer `feeef template add page|component` / `remove` over hand-creating trees.

package/scaffolds/blank/.cursor/skills/feeef-theme/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: feeef-theme
 description: >-
-  Author Feeef theme packages (pages/shared/library, custom react-live components,
+  Author Feeef theme packages (pages/shared/library, flat TSX custom components,
   TemplateData build, order forms, i18n, filterator, dark/light). Use when editing
-  this theme's component.json, component.jsx/tsx, locales, or publishing with feeef.
+  this theme's *.tsx, locales, or publishing with feeef.
 ---
 
 # Feeef Theme Skill
@@ -13,30 +13,42 @@ description: >-
 1. `AGENTS.md`
 2. `docs/00-INDEX.md`
 3. Task-specific doc from the cheat-sheet
-4. Skim `docs/05-ANTI-PATTERNS.md` before writing JSON/JSX
+4. Skim `docs/05-ANTI-PATTERNS.md` before writing JSON/TSX
+
+## Authoring contract (required)
+
+- **Flat TSX leaves:** `pages/<page>/components/<name>.tsx`
+- `export const meta` (+ `propsSchema`) + `function App()`
+- `type Props = FeeefLivePropsOf<typeof propsSchema>`; `const p = props as Props`
+- `satisfies FeeefComponentMeta<typeof propsSchema>`
+- **Folder only** for `slots/` / `children/` / colocated helpers
+- Shared leaves: `shared/components/<id>.tsx` + placement `{ "$ref": "shared.<id>" }` as `.json`
+- Prefer flat sibling stacks; do **not** invent nested `*-shell/slots/**` when siblings work
+- Scaffold with `feeef template add page|component` — do not invent trees by hand
 
 ## Workflows
 
 ### Edit a component
 
-1. Open the folder under `pages/…/components/` or `shared/components/`
-2. Edit `component.json` + `component.jsx` / `.tsx`
+1. Open the flat `.tsx` (or `…/<name>.tsx` if it has slots)
+2. Edit `meta` + `App` — no parallel `component.json` for customs
 3. `npm run build` && hard-refresh `npm run dev`
 
 ### Shared chrome
 
-1. Canonical folder: `shared/components/<id>/`
+1. Canonical leaf: `shared/components/<id>.tsx`
 2. Placements: `{ "$ref": "shared.<id>", "instanceId": "…", "props": { } }`
 3. See `docs/07-SHARED-COMPONENTS.md`
 
 ### Order / COD
 
 1. Read `docs/08-ORDER-FORM.md` first
-2. `POST /api/orders/create` only; draft + pending; geo rules; anti-abuse
+2. Prefer native `product_order_form` / `cart_order_form` `.json` leaves
+3. Custom forms: `POST /api/orders/create` only; draft + pending; geo; anti-abuse
 
 ### Special pages
 
-`docs/11-PAGES-CHECKOUT-THANKS-PRODUCT.md` — single `main` + slots.
+`docs/11-PAGES-CHECKOUT-THANKS-PRODUCT.md` — `main` via flat `components/`; slots when needed.
 
 ### Lists / PLP
 
@@ -50,7 +62,7 @@ description: >-
 
 - Top-level custom fields — never under `props`
 - `function App()` in published `code`
-- CSS vars for brand colors
+- CSS vars for brand colors (`hsl(var(--…))`)
 - Stable `instanceId`
 - Repeated UI → `shared/` + `$ref`
 - Orders → create API + draft/pending contract

package/scaffolds/blank/.cursor/skills/feeef-theme/reference.md

@@ -6,65 +6,70 @@
 |---|---|
 | `build` | source → `dist/data.json` |
 | `check` | validate |
-| `dev` | preview |
+| `typecheck` | `tsc --noEmit` |
+| `test` | smoke custom `App`s |
+| `dev` | remote draft preview |
 | `publish` | upload (+ optional `--apply`) |
 
-## Custom component JSON
+## Flat TSX leaf (required)
 
-```json
-{
-  "order": 0,
-  "type": "custom",
-  "instanceId": "custom_example",
-  "title": "Example",
-  "propsSchema": {
-    "heading": { "type": "string" }
-  },
-  "props": { "heading": "Hello" },
-  "slotsSchema": {},
-  "slots": {}
-}
-```
+```tsx
+const propsSchema = {
+  heading: { type: "string", name: "Heading" },
+} as const;
 
-## JSX skeleton
+export const meta = {
+  type: "custom",
+  title: "Hero",
+  order: 0,
+  propsSchema,
+  props: { heading: "" },
+} as const satisfies FeeefComponentMeta<typeof propsSchema>;
+
+type Props = FeeefLivePropsOf<typeof propsSchema>;
 
-```jsx
 function App() {
-  const storeCtx = useStore();
-  const store = storeCtx?.store;
+  const p = props as Props;
   return (
     <section style={{ color: "hsl(var(--foreground))" }}>
-      <h1>{props.heading}</h1>
-      {props.slots?.body}
+      <h1>{p.heading || t("home.heroHeading")}</h1>
     </section>
   );
 }
 ```
 
+Paths:
+
+- `pages/<page>/components/<name>.tsx`
+- `shared/components/<id>.tsx`
+- `library/components/<id>.tsx`
+
+Folder (`<name>/<name>.tsx` + `slots/`) **only** when nesting is required.
+
 ## Shared placement
 
 ```json
 {
   "order": 0,
-  "$ref": "shared.footer",
-  "instanceId": "contact_footer_1",
+  "$ref": "shared.header",
+  "instanceId": "home_header",
   "props": {}
 }
 ```
 
 ## Order form (quick)
 
-- `POST /api/orders/create` only
-- Draft when phone digits === country length; pending reuses draft `id`
-- See `docs/08-ORDER-FORM.md`
+- Prefer native `cart_order_form` / `product_order_form` `.json`
+- Custom: `POST /api/orders/create` only — `docs/08-ORDER-FORM.md`
 
 ## Pages
 
 | Page | Path | Rule |
 |---|---|---|
-| product | `/products/:id` | `main` only — layout in slots |
-| checkout | `/checkout` | `main` only |
-| thank_you | `/thanks` | `main` only |
+| home / products / contact | flat `components/` stack | `$ref` chrome as siblings |
+| product | `/products/:id` | shell folder + slots if needed |
+| checkout | `/checkout` | `cart_order_form` leaf |
+| thank_you | `/thanks` | body + chrome |
 
 ## Colors / i18n / lists
 

package/scaffolds/blank/AGENTS.md

@@ -8,9 +8,10 @@ editor, the storefront preview, and published stores. Follow this file exactly.
 1. **One JSON contract** — `TemplateData` (built into `dist/data.json`) is what Feeef stores and renders. `dist/schema.json` is the editor schema.
 2. **Source vs dist** — edit `schema.ts`, `pages/`, `shared/`, `library/`, `locales/`, `props.json`; run `npm run build`. Do not hand-edit large `dist/*` as the source of truth.
 3. **Template schema is yours** — `schema.ts` (`satisfies FeeefThemeSchema`) controls pages/layouts/root `propsSchema`. Build merges Lithium built-ins into `dist/schema.json` for publish.
-4. **`type: "custom"` is react-live** — published `code` is a **string** evaluated in a sandbox. It must expose top-level `function App() { … }`. Author with a flat file like `hero.tsx`: `export const meta` (include `propsSchema`) + `App`. Type props via `FeeefLivePropsOf<typeof propsSchema>`. Local/`npm` imports are **bundled at build time** (see `docs/16-AUTHORING-TS-IMPORTS.md`). Use a folder (`hero/component.tsx`) only when you need `slots/` / `children/` or colocated modules.
+4. **`type: "custom"` is react-live** — published `code` is a **string** evaluated in a sandbox. It must expose top-level `function App() { … }`. **Author flat TSX:** `pages/<page>/components/<name>.tsx` with `export const meta` (include `propsSchema`) + `App`. Type props via `FeeefLivePropsOf<typeof propsSchema>` and `satisfies FeeefComponentMeta<typeof propsSchema>`. Local/`npm` imports are **bundled at build time** (see `docs/16-AUTHORING-TS-IMPORTS.md`). Use a folder (`<name>/<name>.tsx`) **only** when you need `slots/` / `children/` or colocated modules. **Do not** author new customs as `component.json` + `component.jsx`.
 5. **`code` / `propsSchema` / `slotsSchema` / `slots` / `slotsLayout` are TOP-LEVEL** on the component object — never nest them under `props`.
 6. **Planes stay separate** — schema (editable fields) ≠ merchant content (`props`) ≠ renderer.
+7. **Prefer flat sibling stacks** — `header.json` (`$ref`) + `hero.tsx` + `footer.json` under `pages/<page>/components/`. Do **not** invent deep nested `*-shell/slots/**` trees when siblings work.
 
 ## Before you change anything
 
@@ -36,7 +37,9 @@ editor, the storefront preview, and published stores. Follow this file exactly.
 | Keep `instanceId` stable when editing existing components | Selection + React keys |
 | `children` only for `grid` / `flex` / `container` | Other types use `slots` |
 | Empty section **keys** optional; published JSON still has `sections` object | Flat disk → `sections.main`; legacy multi-section keys still work |
-| UI on 2+ pages → `shared/components/` + `$ref` | No duplicated chrome JSX |
+| UI on 2+ pages → `shared/components/<id>.tsx` + `$ref` | No duplicated chrome JSX |
+| Flat TSX leaves for customs — no `component.json`+`jsx` pairs | Meta in `export const meta` |
+| No hand-built nested shell trees when flat stack works | Siblings under `components/` |
 | Custom order forms → `docs/08-ORDER-FORM.md` | Draft, geo, create API, anti-abuse |
 | Never re-bootstrap shipping on every `cartCtx` change | Wipes state/city |
 | Add to cart = `addCurrentItemToCart` (or `cart.add`) | Not `updateCurrentItem({})` theater |
@@ -60,7 +63,7 @@ dist/data.json               # TemplateData
 dist/schema.json             # merged editor schema (not hand-edited)
 ```
 
-Prefer a single `main` stack + component **slots** for chrome. Do not mix flat `components/` and `sections/` on one page.
+Prefer a **flat sibling stack** under `pages/<page>/components/` (builds to `sections.main`). Use a shell folder + slots only when nesting is required (typical for product/checkout). Do not mix flat `components/` and `sections/` on one page.
 
 ## Local commands
 
@@ -85,7 +88,7 @@ npm run publish -- --apply
 
 **Preview:** `npm run dev` pushes `metadata.templatePreview` and opens `?preview=…`. Customers keep live `templateData`. Exit via banner or `/?preview=0`. Go live only with `publish --apply`.
 
-**AI / agents:** use `feeef template add page|component` (and `remove`) instead of inventing folder trees by hand. New pages are flat `components/` → published `sections.main`. Do not mix flat `components/` with `sections/` on the same page.
+**AI / agents:** use `feeef template add page|component` (and `remove`) instead of inventing folder trees by hand. New pages are flat `components/*.tsx` → published `sections.main`. Shared chrome = flat `shared/components/<id>.tsx` + `$ref` `.json` placements. Do **not** mix flat `components/` with `sections/` on the same page. Do **not** invent deep `*-shell/slots/**` nests when a flat stack works.
 
 Editor: `tsconfig.json` + `types/feeef-live-scope.d.ts` + `types/feeef-template-schema.d.ts` explain react-live globals and `FeeefThemeSchema` (template schema type) to VS Code / Cursor.
 

package/scaffolds/blank/README.md

@@ -8,7 +8,7 @@ npm install -g @feeef.dev/cli
 
 **AI / Cursor:** read [`AGENTS.md`](./AGENTS.md) and [`docs/00-INDEX.md`](./docs/00-INDEX.md) first. Rules and skills live under [`.cursor/`](./.cursor/).
 
-Author components under `pages/<page>/components/<name>.tsx` (`export const meta` + `function App()`). Build maps them to published `sections.main`. Legacy `sections/<id>/` still works. Local `import`s are bundled at `npm run build` into react-live `code` (`react` stays provided by the storefront).
+Author components under `pages/<page>/components/<name>.tsx` (`export const meta` + `function App()`). **Flat TSX is required for leaf customs.** Build maps them to published `sections.main`. Use a folder only for `slots/` / `children/`. Shared chrome: `shared/components/<id>.tsx` + `$ref` `.json` placements. Local `import`s are bundled at `npm run build` into react-live `code` (`react` stays provided by the storefront).
 
 Editor: `tsconfig.json` + `types/feeef-live-scope.d.ts` teach VS Code / Cursor about live-scope globals (`props`, `t`, `useStore`, …). Run `npm install` once after init.
 

package/scaffolds/blank/docs/03-CUSTOM-COMPONENTS.md

@@ -2,12 +2,11 @@
 
 > Theme package copy — paths assume this theme folder is the project root.
 
-Full API: `docs/03-CUSTOM-COMPONENTS.md`.  
-Architecture: `docs/03-CUSTOM-COMPONENTS.md`.
+Full API and authoring contract for `type: "custom"` components.
 
 ## What a custom component is
 
-A `TemplateDataComponent` with:
+A `TemplateDataComponent` with top-level:
 
 ```json
 {
@@ -23,29 +22,68 @@ A `TemplateDataComponent` with:
 }
 ```
 
-`code` is executed by `CustomLive` (`components/system/custom-live.tsx`) via **react-live**. Authoring may use `component.tsx` and local/npm `import`s — the **theme build** (esbuild) emits a single `code` string. There is still **no browser bundler** at runtime: `react` / `react-dom` stay in the live scope (do not import them expecting a separate React copy).
+`code` is executed by `CustomLive` via **react-live**. You author **TypeScript/TSX on disk**; `npm run build` (template-kit) emits the `code` string. There is **no browser bundler** at runtime: `react` / `react-dom` stay in the live scope.
 
-## Required code shape
+## Required authoring shape (flat TSX)
+
+**Prefer a single flat file** under the page (or shared/library):
+
+```
+pages/home/components/hero.tsx
+shared/components/header.tsx
+library/components/promo-banner.tsx
+```
+
+```tsx
+const propsSchema = {
+  heading: { type: "string", name: "Heading" },
+} as const;
+
+export const meta = {
+  type: "custom",
+  title: "Hero",
+  order: 0,
+  propsSchema,
+  props: { heading: "" },
+} as const satisfies FeeefComponentMeta<typeof propsSchema>;
+
+type Props = FeeefLivePropsOf<typeof propsSchema>;
 
-```jsx
 function App() {
-  const storeCtx = useStore();
-  // …
-  return <div>…</div>;
+  const p = props as Props;
+  return <h1>{p.heading || t("home.heroHeading")}</h1>;
 }
 ```
 
-- Entry must be **`function App()`** (warning if missing; may not render).
+Rules:
+
+- Entry must be **`function App()`** (published `code` must expose it).
 - Prefer **`React.useState` / `React.useEffect` / …** — merchant preview may not inject bare hooks.
-- No `import` / `export` / `require`.
+- **Do not** author a parallel `component.json` for customs — meta lives in `export const meta`.
+- **Do not** put `import` / `export` / `require` in the *published* live string (build strips / bundles). Authoring **may** use local/`npm` imports — see [16-AUTHORING-TS-IMPORTS.md](./16-AUTHORING-TS-IMPORTS.md).
+- Type props with `FeeefLivePropsOf<typeof propsSchema>`; cast `const p = props as Props`.
+
+### When to use a folder
 
-## Injected scope (no imports needed)
+Use a folder **only** when you need `slots/`, `children/`, or colocated modules:
+
+```
+pages/product/components/product-shell/
+  product-shell.tsx          # export const meta + App (includes slotsSchema)
+  slots/header/header.json   # $ref or leaf
+  slots/body/gallery.tsx
+  slots/form/order.json      # built-in type
+```
+
+Never create both `hero.tsx` and `hero/` for the same id.
+
+## Injected scope (no imports needed at runtime)
 
 | Symbol | Use |
 |---|---|
 | `React` | Hooks, Fragment |
-| `props` | Instance props |
-| `props.slots` | Pre-rendered slot children (`props.slots?.sections`) |
+| `props` | Instance props — cast with `FeeefLivePropsOf` |
+| `props.slots` | Pre-rendered slot children |
 | `SlotContextBridge` | Provide context to slot children |
 | `useSlotContext(key)` | Read parent slot context |
 | `useStore()` | `{ store }` or null — **null-check** |
@@ -54,12 +92,12 @@ function App() {
 | `useFeeef` | SDK instance or null |
 | `useTheme()` | next-themes |
 | `useTemplate()` | read-only template state |
-| `t(key, params?)` | Theme locales (`data.i18n`) — see [13-TEMPLATE-I18N.md](./13-TEMPLATE-I18N.md) |
+| `t(key, params?)` | Theme locales — [13-TEMPLATE-I18N.md](./13-TEMPLATE-I18N.md) |
 | `useFeeefT()` / `useFeeefLocale()` | Theme i18n hooks |
 | `useRouter` / `usePathname` / `useSearchParams` | next/navigation |
-| `Link` | next/link — prefer over `<a>` |
+| `Link` | next/link — prefer over `<a>` for in-app nav |
 | `RouterNav` | clickable block with stopPropagation for nested cards |
-| `SlotsLayout` | Renders `props.slotsLayout` (sm/md/lg row/column trees) with `props.slots` — prefer over hardcoding slot order |
+| `SlotsLayout` | Renders `props.slotsLayout` with `props.slots` |
 | `dartColorToCssColor` | convert Flutter color ints from **props** |
 
 For product markdown details use registry **`product_body`** (reads `product.body`), not CustomLive HTML injection.
@@ -70,27 +108,19 @@ For product markdown details use registry **`product_body`** (reads `product.bod
 - Corners: `var(--corners-card)`, `var(--corners-buttons-large)`, …
 - **Do not** assign `store.decoration.primary` directly (Flutter AARRGGBB int).
 - Prefer store fields for chrome: `store.logoUrl`, `store.name`, `store.contacts`, …
-- **Dark / light:** ride native tokens (`:root` / `.dark`). Do not invent a parallel palette. Full contract: [12-DARK-LIGHT-THEME.md](./12-DARK-LIGHT-THEME.md).
-- Toggle: `const { resolvedTheme, setTheme } = useTheme();`
+- **Dark / light:** ride native tokens (`:root` / `.dark`) — [12-DARK-LIGHT-THEME.md](./12-DARK-LIGHT-THEME.md).
 
 ## Slots in JSX
 
-Parent:
-
-```jsx
-<SlotContextBridge value={{ shell: { isOpen, setIsOpen } }}>
-  {props.slots?.sections}
-</SlotContextBridge>
+```tsx
+{props.slots?.header}
+<main>{props.slots?.body}</main>
 {props.slots?.footer}
 ```
 
-Child (in slot):
-
-```jsx
-const shell = useSlotContext("shell");
-```
+Or prefer `<SlotsLayout />` when `slotsLayout` is set.
 
-**Never** use slot context for navigation (`routerNav` stubs). Use `Link` / `RouterNav` / `useRouter()`.
+**Never** use slot context for navigation. Use `Link` / `RouterNav` / `useRouter()`.
 
 ## Product media
 
@@ -99,18 +129,17 @@ const shell = useSlotContext("shell");
 
 ## Cart
 
-```jsx
+```tsx
 const cartCtx = useFeeefCart();
 if (!cartCtx) return null;
 cartCtx.cart.add({ product, quantity: 1, variantPath: "Color/Red" });
 ```
 
-## Kit authoring
-
-In `…/my-comp/`:
+## Kit authoring checklist
 
-- `component.json` — meta (no `code` string when using jsx file)
-- `component.jsx` — the `function App()` source → compiled into `code`
-- `slots/<slotId>/<child>/` — nested components
+1. Prefer `feeef template add component <page> <name>` → flat `<name>.tsx`
+2. Put chrome reused on 2+ pages in `shared/components/<id>.tsx` + `$ref` placements ([07](./07-SHARED-COMPONENTS.md))
+3. Built-ins (order forms, `product_body`) stay as leaf `.json` with `type: "…"`
+4. `npm run build` then `npm run dev`
 
-See [04-WORKFLOW.md](./04-WORKFLOW.md).
+See [04-WORKFLOW.md](./04-WORKFLOW.md) / [04-WORKFLOW.md](./04-WORKFLOW.md).

package/scaffolds/blank/docs/04-WORKFLOW.md

@@ -63,7 +63,7 @@ pages/<page>/components/            # preferred (→ published sections.main)
   <name>.tsx                        # leaf: export const meta + App
   <name>.json                       # leaf built-in / no code
   <name>/                           # only when slots/ or children/ needed
-    component.tsx
+    <name>.tsx
     slots/… | children/…
 pages/<page>/sections/<section>/components/   # legacy multi-section (still supported)
 shared/components/<id>.tsx
@@ -98,9 +98,9 @@ Types: `types/feeef-template-schema.d.ts`. Fallback: `schema.json` (same shape).
 
 ## Custom components
 
-- Prefer page-level `components/hero.tsx` — `export const meta` + `function App() { … }`
-- Use a folder only when you need `slots/` or `children/` (or colocated helpers)
-- Chrome / layout: use **slots** + `slotsLayout` on a shell component (not extra section keys)
+- **Required:** page-level `components/hero.tsx` — `export const meta` + `function App() { … }`
+- Use a folder **only** when you need `slots/` or `children/` (or colocated helpers)
+- Prefer flat sibling stacks (`header.json` `$ref` + section `.tsx` + `footer.json`); shell folders only when slots are necessary
 - Type-safe props from schema:
 
 ```tsx
@@ -124,6 +124,7 @@ function App() {
 
 - Build strips `meta` and bundles into react-live `code` (see [16-AUTHORING-TS-IMPORTS.md](./16-AUTHORING-TS-IMPORTS.md))
 - `react` stays provided by the storefront — do not bundle a second React
+- **Do not** author new customs as `component.json` + `component.jsx`
 
 ## Do not
 
@@ -132,3 +133,5 @@ function App() {
 - Call `ff.orders.send` from custom checkout (use `POST /api/orders/create` — [08](./08-ORDER-FORM.md))
 - Expect `npm run dev` to update what customers see (it does not)
 - Clone the Lithium storefront just to preview (remote draft is the default)
+- Invent deep nested `*-shell/slots/**` trees when a flat `components/` stack works
+- Create both `name.tsx` and `name/` for the same id

package/scaffolds/blank/docs/05-ANTI-PATTERNS.md

@@ -35,7 +35,7 @@ High-signal mistakes AIs and humans make in this system.
 | `<a href="/p/x">` for in-app nav | `<Link href="/p/x">` or `RouterNav` |
 | `useSlotContext('x').routerNav.push` | Real `useRouter` / `Link` / `RouterNav` |
 | Assuming `useStore()` non-null | Always null-check |
-| TypeScript / JSX types in published `code` | Author `component.tsx`; build strips types into `code` |
+| TypeScript / JSX types in published `code` | Author `<name>.tsx` (or `<name>/<name>.tsx` with slots); build strips types into `code` |
 | Assuming raw `import` works inside react-live without build | Use theme `npm run build` — imports are bundled into `code` |
 | Bundling a second `react` into `code` | Mark react as external (build does this); use live scope |
 
@@ -46,12 +46,13 @@ High-signal mistakes AIs and humans make in this system.
 | Hand-edit `dist/data.json` as primary workflow | Edit `pages/` / `shared/`, then `npm run build` |
 | Use Node APIs inside component source | Use `utils/get-template.ts` |
 | Arbitrary filesystem preview paths | Only `feeef template dev` / CLI override |
-| Treating `npm run dev` as “go live” | Draft only — use `publish --apply` for customers |
-| Cloning Lithium storefront just to preview | Default is remote draft (`?preview=`) |
 | Expect Shopify reference dumps to render | They are not Feeef themes |
-| Skip `npm run check` after edits | Rebuild and refresh draft preview |
+| Skip `npm run check` after edits | Rebuild and hard-refresh preview |
 | Commit `dist/` as source | Source is the folder tree |
-| Duplicate the same footer/navbar JSX on every page | Promote to `shared/components/<id>/` + `$ref` |
+| Duplicate the same footer/navbar JSX on every page | Promote to `shared/components/<id>.tsx` + `$ref` |
+| Author customs as `component.json` + `component.jsx` | Flat `<name>.tsx` with `export const meta` + `App` |
+| Hand-build nested `*-shell/slots/**` when a flat stack works | Flat `pages/<page>/components/*` siblings + `$ref` |
+| Both `hero.tsx` and `hero/` for the same id | Keep **one** entry (folder only if slots/children needed) |
 | Copy dawn-order-form as “complete” checkout | Follow `docs/08-ORDER-FORM.md` + native `order-form.tsx` |
 | `ff.orders.send` from custom JSX | `fetch("/api/orders/create")` |
 | Free-text wilaya/city without cascade/indices | Legacy 1-based indices or new state codes + city names |
@@ -66,7 +67,7 @@ High-signal mistakes AIs and humans make in this system.
 
 ## Registry / built-ins
 
-Prefer built-in types when they fit; otherwise `type: "custom"` with `component.jsx` / `.tsx`.
+Prefer built-in types when they fit; otherwise `type: "custom"` with flat `.tsx` (`export const meta` + `App`).
 
 ## AI generation