@feeef.dev/cli 0.2.0

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

@@ -0,0 +1,32 @@
+---
+description: Rules when editing theme component source (tsx / json / slots).
+globs: pages/**/*,shared/**/*,library/**/*
+alwaysApply: false
+---
+
+# Theme source folders
+
+You are editing **theme source**, not a hand-maintained `dist/data.json`.
+
+## Structure
+
+- 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
+- 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`)
+
+## 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).

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

@@ -0,0 +1,15 @@
+---
+name: feeef-filterator
+description: >-
+  Feeef filterator + products/categories list APIs for PLPs, related products,
+  and search grids in theme custom components. Canonical: docs/14-FILTERATOR.md.
+---
+
+# Feeef Filterator
+
+Read **`docs/14-FILTERATOR.md`** before changing product/category fetch logic.
+
+- Always pass `store_id`
+- Prefer server `in_stock` / `price_min` / `filterator` over client-only filtering
+- Related products = same category / random / sold — no dedicated related API
+- `media` values are URL strings; link to `/products/…`

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

@@ -0,0 +1,56 @@
+---
+name: feeef-theme
+description: >-
+  Author Feeef theme packages (pages/shared/library, custom react-live 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.
+---
+
+# Feeef Theme Skill
+
+## First action
+
+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
+
+## Workflows
+
+### Edit a component
+
+1. Open the folder under `pages/…/components/` or `shared/components/`
+2. Edit `component.json` + `component.jsx` / `.tsx`
+3. `npm run build` && hard-refresh `npm run dev`
+
+### Shared chrome
+
+1. Canonical folder: `shared/components/<id>/`
+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
+
+### Special pages
+
+`docs/11-PAGES-CHECKOUT-THANKS-PRODUCT.md` — single `main` + slots.
+
+### Lists / PLP
+
+`docs/14-FILTERATOR.md` + skill `feeef-filterator`.
+
+### TS / imports
+
+`docs/16-AUTHORING-TS-IMPORTS.md` — build bundles into react-live `code`.
+
+## Invariants
+
+- Top-level custom fields — never under `props`
+- `function App()` in published `code`
+- CSS vars for brand colors
+- Stable `instanceId`
+- Repeated UI → `shared/` + `$ref`
+- Orders → create API + draft/pending contract

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

@@ -0,0 +1,73 @@
+# Feeef Theme — Quick Reference
+
+## Commands (theme root)
+
+| npm script | Effect |
+|---|---|
+| `build` | source → `dist/data.json` |
+| `check` | validate |
+| `dev` | preview |
+| `publish` | upload (+ optional `--apply`) |
+
+## Custom component JSON
+
+```json
+{
+  "order": 0,
+  "type": "custom",
+  "instanceId": "custom_example",
+  "title": "Example",
+  "propsSchema": {
+    "heading": { "type": "string" }
+  },
+  "props": { "heading": "Hello" },
+  "slotsSchema": {},
+  "slots": {}
+}
+```
+
+## JSX skeleton
+
+```jsx
+function App() {
+  const storeCtx = useStore();
+  const store = storeCtx?.store;
+  return (
+    <section style={{ color: "hsl(var(--foreground))" }}>
+      <h1>{props.heading}</h1>
+      {props.slots?.body}
+    </section>
+  );
+}
+```
+
+## Shared placement
+
+```json
+{
+  "order": 0,
+  "$ref": "shared.footer",
+  "instanceId": "contact_footer_1",
+  "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`
+
+## Pages
+
+| Page | Path | Rule |
+|---|---|---|
+| product | `/products/:id` | `main` only — layout in slots |
+| checkout | `/checkout` | `main` only |
+| thank_you | `/thanks` | `main` only |
+
+## Colors / i18n / lists
+
+- Colors: `hsl(var(--primary))` — `docs/12-DARK-LIGHT-THEME.md`
+- Copy: `t('key')` + `locales/*.json` — `docs/13-TEMPLATE-I18N.md`
+- Products: filterator / list params — `docs/14-FILTERATOR.md`

package/scaffolds/blank/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["dbaeumer.vscode-eslint"]
+}

package/scaffolds/blank/.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "typescript.enablePromptUseWorkspaceTsdk": true,
+  "typescript.tsserver.maxTsServerMemory": 3072,
+  "files.associations": {
+    "**/components/**/*.tsx": "typescriptreact",
+    "**/components/**/*.jsx": "javascriptreact",
+    "**/component.tsx": "typescriptreact",
+    "**/component.jsx": "javascriptreact"
+  },
+  "editor.defaultFormatter": null,
+  "js/ts.implicitProjectConfig.checkJs": false
+}

package/scaffolds/blank/AGENTS.md

@@ -0,0 +1,104 @@
+# AGENTS — Feeef Theme (READ BEFORE EDITING)
+
+You are editing a **Feeef theme package** (this folder). Mistakes break the merchant
+editor, the storefront preview, and published stores. Follow this file exactly.
+
+## Mandatory mental model
+
+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. **Theme 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.
+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.
+
+## Before you change anything
+
+1. Read [`docs/00-INDEX.md`](./docs/00-INDEX.md) and the doc for your task.
+2. Custom JSX/TSX → [`docs/03-CUSTOM-COMPONENTS.md`](./docs/03-CUSTOM-COMPONENTS.md) + skim [`docs/05-ANTI-PATTERNS.md`](./docs/05-ANTI-PATTERNS.md).
+3. Order / COD / checkout forms → [`docs/08-ORDER-FORM.md`](./docs/08-ORDER-FORM.md) **first**.
+4. Folder layout / CLI → [`docs/04-WORKFLOW.md`](./docs/04-WORKFLOW.md).
+5. Shared chrome → [`docs/07-SHARED-COMPONENTS.md`](./docs/07-SHARED-COMPONENTS.md).
+6. Checkout / thanks / product pages → [`docs/11-PAGES-CHECKOUT-THANKS-PRODUCT.md`](./docs/11-PAGES-CHECKOUT-THANKS-PRODUCT.md).
+7. Dark/light → [`docs/12-DARK-LIGHT-THEME.md`](./docs/12-DARK-LIGHT-THEME.md).
+8. Multilang → [`docs/13-TEMPLATE-I18N.md`](./docs/13-TEMPLATE-I18N.md).
+9. Product grids / filters → [`docs/14-FILTERATOR.md`](./docs/14-FILTERATOR.md).
+10. After edits: `npm run build` (or `npm run check`), then hard-refresh `npm run dev`.
+
+## Hard rules (never violate)
+
+| Rule | Why |
+|---|---|
+| Do not put `code` / `propsSchema` / `slots*` inside `props` | Breaks editor + renderer |
+| Prefer `React.useState` (not bare `useState`) in custom code | Merchant editor scope |
+| Prefer `hsl(var(--primary))` over decoration color ints | Dark/light CSS tokens |
+| Use `Link` / `RouterNav` / `useRouter()` for in-app nav | Slot-context routers are stubs |
+| 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 |
+| 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 |
+| Submit orders via `POST /api/orders/create` | Not browser `ff.orders.send` |
+| Do not invent unknown registry `type` strings | Prefer `custom` or built-ins |
+| Do not bypass order anti-abuse checks | Honeypot, dwell, in-flight lock |
+
+## Theme layout
+
+```
+schema.ts                    # theme-owned schema overlay
+props.json                   # default root props
+pages/<page>/components/     # preferred — builds to sections.main
+  <name>.tsx
+pages/<page>/sections/<id>/… # legacy multi-section (compat)
+shared/components/<id>.tsx
+library/components/<id>.tsx
+locales/{en,ar,…}.json
+feeef.template.json
+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.
+
+## Local commands
+
+```bash
+feeef signin
+feeef use                 # bind a store
+npm install               # once — React/TS types for the editor
+
+# Scaffold (prefer these over hand-creating folders)
+feeef template add page <pageId>                    # pages/<id>/components/
+feeef template add component <pageId> <name>        # starter <name>.tsx
+feeef template remove page <pageId> --yes
+feeef template remove component <pageId> <name> --yes
+
+npm run build             # → dist/data.json
+npm run check
+npm run typecheck         # optional IDE/tsc
+npm run dev               # preview
+npm run 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.
+
+Editor: `tsconfig.json` + `types/feeef-live-scope.d.ts` + `types/feeef-template-schema.d.ts` explain react-live globals and `FeeefThemeSchema` to VS Code / Cursor.
+
+## Companion docs
+
+| Doc | When |
+|---|---|
+| [`docs/03-CUSTOM-COMPONENTS.md`](./docs/03-CUSTOM-COMPONENTS.md) | JSX sandbox + scope |
+| [`docs/04-WORKFLOW.md`](./docs/04-WORKFLOW.md) | Build / preview / publish |
+| [`docs/05-ANTI-PATTERNS.md`](./docs/05-ANTI-PATTERNS.md) | Common AI mistakes |
+| [`docs/07-SHARED-COMPONENTS.md`](./docs/07-SHARED-COMPONENTS.md) | `$ref` / shared |
+| [`docs/08-ORDER-FORM.md`](./docs/08-ORDER-FORM.md) | COD / checkout contract |
+| [`docs/09-THEME-PORTING.md`](./docs/09-THEME-PORTING.md) | Full-theme craft lessons |
+| [`docs/10-SCHEMA-LIBRARY.md`](./docs/10-SCHEMA-LIBRARY.md) | Theme library catalog |
+| [`docs/11-PAGES-CHECKOUT-THANKS-PRODUCT.md`](./docs/11-PAGES-CHECKOUT-THANKS-PRODUCT.md) | Special pages |
+| [`docs/12-DARK-LIGHT-THEME.md`](./docs/12-DARK-LIGHT-THEME.md) | Theme mode + tokens |
+| [`docs/13-TEMPLATE-I18N.md`](./docs/13-TEMPLATE-I18N.md) | `locales` + `t()` |
+| [`docs/14-FILTERATOR.md`](./docs/14-FILTERATOR.md) | Product/category lists |
+| [`docs/16-AUTHORING-TS-IMPORTS.md`](./docs/16-AUTHORING-TS-IMPORTS.md) | TSX + npm imports |

package/scaffolds/blank/README.md

@@ -0,0 +1,21 @@
+# Feeef theme
+
+This folder is a **Node.js package** (see `package.json`). Scripts wrap the global `feeef` CLI — install it once (`npm link` from the Feeef `cli/` package, or `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).
+
+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.
+
+```bash
+feeef signin
+feeef use                 # or: feeef use <store-id-or-slug>
+
+npm run build             # → dist/data.json
+npm run check
+npm run dev               # → http://{slug}.localhost.feeef.org:3456
+npm run publish -- --apply
+```
+
+See `feeef template --help`.

package/scaffolds/blank/docs/00-INDEX.md

@@ -0,0 +1,33 @@
+# Theme docs — index
+
+Read [`../AGENTS.md`](../AGENTS.md) first. Jump by task below.
+
+| # | Doc | Contents |
+|---|---|---|
+| 00 | This file | Navigation |
+| 03 | [CUSTOM-COMPONENTS](./03-CUSTOM-COMPONENTS.md) | react-live, scope API, slots |
+| 04 | [WORKFLOW](./04-WORKFLOW.md) | Build, preview, publish from this package |
+| 05 | [ANTI-PATTERNS](./05-ANTI-PATTERNS.md) | What not to do (high signal) |
+| 07 | [SHARED-COMPONENTS](./07-SHARED-COMPONENTS.md) | `shared/` + `$ref` |
+| 08 | [ORDER-FORM](./08-ORDER-FORM.md) | COD / checkout contract |
+| 09 | [THEME-PORTING](./09-THEME-PORTING.md) | Craft / cart / search / PLP lessons |
+| 10 | [SCHEMA-LIBRARY](./10-SCHEMA-LIBRARY.md) | Drag-drop theme library |
+| 11 | [PAGES](./11-PAGES-CHECKOUT-THANKS-PRODUCT.md) | checkout / thanks / product |
+| 12 | [DARK-LIGHT](./12-DARK-LIGHT-THEME.md) | Dark / light / system |
+| 13 | [I18N](./13-TEMPLATE-I18N.md) | `locales/*.json` + `t()` |
+| 14 | [FILTERATOR](./14-FILTERATOR.md) | Product / category lists |
+| 16 | [TS-IMPORTS](./16-AUTHORING-TS-IMPORTS.md) | TypeScript + npm imports |
+
+## Task cheat-sheet
+
+| Task | Read |
+|---|---|
+| Edit custom JSX/TSX | 03, 05, 16 |
+| Shared header/footer | **07** |
+| Order / COD form | **08** |
+| Checkout / thanks / PDP | **11** |
+| Dark / light | **12** |
+| Translations | **13** |
+| Product grids / filters | **14** |
+| Port / polish a full theme | **09** |
+| Build / preview / publish | **04** |

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

@@ -0,0 +1,116 @@
+# Custom Components (react-live)
+
+> 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`.
+
+## What a custom component is
+
+A `TemplateDataComponent` with:
+
+```json
+{
+  "type": "custom",
+  "instanceId": "…",
+  "title": "…",
+  "code": "function App() { … }",
+  "propsSchema": { … },
+  "props": { … },
+  "slotsSchema": { … },
+  "slots": { … },
+  "slotsLayout": { … }
+}
+```
+
+`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).
+
+## Required code shape
+
+```jsx
+function App() {
+  const storeCtx = useStore();
+  // …
+  return <div>…</div>;
+}
+```
+
+- Entry must be **`function App()`** (warning if missing; may not render).
+- Prefer **`React.useState` / `React.useEffect` / …** — merchant preview may not inject bare hooks.
+- No `import` / `export` / `require`.
+
+## Injected scope (no imports needed)
+
+| Symbol | Use |
+|---|---|
+| `React` | Hooks, Fragment |
+| `props` | Instance props |
+| `props.slots` | Pre-rendered slot children (`props.slots?.sections`) |
+| `SlotContextBridge` | Provide context to slot children |
+| `useSlotContext(key)` | Read parent slot context |
+| `useStore()` | `{ store }` or null — **null-check** |
+| `useFeeefCart()` | `{ cart, count, store }` or null |
+| `useCurrentProduct()` | `{ product }` — product pages |
+| `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) |
+| `useFeeefT()` / `useFeeefLocale()` | Theme i18n hooks |
+| `useRouter` / `usePathname` / `useSearchParams` | next/navigation |
+| `Link` | next/link — prefer over `<a>` |
+| `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 |
+| `dartColorToCssColor` | convert Flutter color ints from **props** |
+
+For product markdown details use registry **`product_body`** (reads `product.body`), not CustomLive HTML injection.
+
+## Styling rules
+
+- Brand colors: `hsl(var(--primary))`, `hsl(var(--primary-foreground))`, `hsl(var(--background))`, …
+- 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();`
+
+## Slots in JSX
+
+Parent:
+
+```jsx
+<SlotContextBridge value={{ shell: { isOpen, setIsOpen } }}>
+  {props.slots?.sections}
+</SlotContextBridge>
+{props.slots?.footer}
+```
+
+Child (in slot):
+
+```jsx
+const shell = useSlotContext("shell");
+```
+
+**Never** use slot context for navigation (`routerNav` stubs). Use `Link` / `RouterNav` / `useRouter()`.
+
+## Product media
+
+- `product.photoUrl` — cover image string.
+- `product.media` — **`string[]` of URLs**, not `{ url }[]`.
+
+## Cart
+
+```jsx
+const cartCtx = useFeeefCart();
+if (!cartCtx) return null;
+cartCtx.cart.add({ product, quantity: 1, variantPath: "Color/Red" });
+```
+
+## Kit authoring
+
+In `…/my-comp/`:
+
+- `component.json` — meta (no `code` string when using jsx file)
+- `component.jsx` — the `function App()` source → compiled into `code`
+- `slots/<slotId>/<child>/` — nested components
+
+See [04-WORKFLOW.md](./04-WORKFLOW.md).

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

@@ -0,0 +1,129 @@
+# Theme workflow (this package)
+
+This folder is a **Node.js theme package**. Scripts wrap the Feeef CLI (`feeef`).
+
+## Setup (once)
+
+```bash
+# Install Feeef CLI globally (or npm link from the Feeef cli package)
+feeef signin
+feeef use                 # pick one of your stores
+```
+
+## Everyday loop
+
+1. Add pages/components with the CLI (or edit under `pages/`, `shared/`, `library/`, `locales/`).
+2. `npm run build` → writes `dist/data.json` (+ locales).
+3. `npm run dev` → pushes a **draft** preview to your store and opens `https://{slug}.…/?preview=…` (live theme unchanged).
+4. Ship: `npm run publish -- --apply` (or `feeef template publish --apply`).
+
+| Script / command | Effect |
+|---|---|
+| `feeef template add page <id>` | Create `pages/<id>/` + update `feeef.template.json` |
+| `feeef template add component <page> <name>` | Starter `<name>.tsx` (meta + App) |
+| `feeef template remove page <id>` | Delete page folder + manifest entry |
+| `feeef template remove component <page> <name>` | Delete component file/folder |
+| `npm run build` | Compile source → `dist/` |
+| `npm run check` | Validate without relying on a dirty dist |
+| `npm run dev` | Watch/build + remote draft preview (never overwrites live) |
+| `npm run publish` | Upload template + locales (+ optional install) |
+
+Exit draft preview in the browser via the banner (**Exit preview**) or `/?preview=0`.
+
+### Scaffold examples
+
+```bash
+feeef template add page products
+feeef template add component products grid --title "Product grid"
+feeef template remove component products grid --yes
+feeef template remove page products --yes
+```
+
+Legacy themes that already use `sections/`: `add component` writes under `sections/main/components/` (or pass `--section header`).
+
+## Source layout
+
+```
+feeef.template.json
+schema.ts                           # theme-owned schema overlay (typed)
+props.json                          # default root props (data)
+pages/<page>/page.json
+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
+    slots/… | children/…
+pages/<page>/sections/<section>/components/   # legacy multi-section (still supported)
+shared/components/<id>.tsx
+library/components/<id>.tsx
+locales/en.json
+```
+
+Do **not** mix `pages/<page>/components/` and `pages/<page>/sections/` on the same page.
+
+### Theme schema (`schema.ts`)
+
+Controls what the merchant editor sees for **this** theme (pages, layouts, root `propsSchema`). Build merges it with Lithium built-ins → `dist/schema.json` (publish uploads that as `StoreTemplate.schema`).
+
+```ts
+export const schema = {
+  name: "my-theme",
+  version: "0.1.0",
+  schema: "1.0",
+  propsSchema: { theme: { type: "object", /* … */ } },
+  pages: {
+    home: {
+      name: "Home",
+      path: "/",
+      sections: { main: {} },
+      layout: { sm: [{ type: "column", children: ["main"] }] },
+    },
+  },
+} as const satisfies FeeefThemeSchema;
+```
+
+Types: `types/feeef-template-schema.d.ts`. Fallback: `schema.json` (same shape).
+
+## Custom components
+locales/en.json
+feeef.template.json
+```
+
+Do **not** mix `pages/<page>/components/` and `pages/<page>/sections/` on the same page.
+
+## 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)
+- Type-safe props from schema:
+
+```tsx
+const propsSchema = { heading: { type: "string" } } 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>;
+
+function App() {
+  const p = props as Props; // p.heading: string
+  return <h1>{p.heading}</h1>;
+}
+```
+
+- 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
+
+- Commit hand-tweaked `dist/data.json` as the only source of truth
+- Put `code` / schemas under `props`
+- Call `ff.orders.send` from custom checkout (use `POST /api/orders/create` — [08](./08-ORDER-FORM.md))
+- Set production env overrides meant for local preview only