@autoview/cli 0.1.0

package/lib/verify/workflows.d.ts

@@ -0,0 +1,53 @@
+import { IAutoViewProductPlan } from "../orchestrate/structures/IAutoViewProductPlan";
+/**
+ * The verification layer — "정확하게 검증한다".
+ *
+ * A generated frontend that typechecks is not proven to work: a user has to be
+ * able to open it, see real data, and move through it. This module derives, from
+ * the deterministic product plan, the set of USER WORKFLOWS that a real visitor
+ * would perform — each a short journey with an explicit positive expectation at
+ * every step (the table actually rendered rows or an honest empty state; the
+ * detail actually showed fields; navigation actually moved). The execution layer
+ * ({@link ../verify/runWorkflows}) drives these in a real headless browser and
+ * reports pass/fail per step, so "it works" is demonstrated, not asserted.
+ *
+ * Pure and deterministic: same plan → same workflows, no browser needed. This is
+ * the spec of WHAT gets verified.
+ */
+/** What a page must be after a step — drives the runtime DOM assertion. */
+export type WorkflowExpect = "landing" | "table" | "detail" | "form";
+/** One user action plus the outcome it must produce. */
+export interface IWorkflowStep {
+    action: {
+        type: "visit";
+        path: string;
+    } | {
+        type: "clickFirstRow";
+    } | {
+        type: "clickLink";
+        text: string;
+    };
+    expect: WorkflowExpect;
+    /** Human description, shown in the report. */
+    label: string;
+}
+/** One end-to-end user journey through a resource. */
+export interface IWorkflow {
+    /** Stable slug (route-derived). */
+    id: string;
+    title: string;
+    /** Resource the journey covers, for grouping the report. */
+    resource: string;
+    steps: IWorkflowStep[];
+}
+/**
+ * Derive the user workflows to verify from the product plan.
+ *
+ * - Home: the landing hub must open and present its resource links.
+ * - Per top-level resource: visit the list (it must render a table or an honest
+ *   empty state, not an error), then open the first row's detail (it must render
+ *   the record's fields). This is the core read journey — the one a user does
+ *   first and the one that exercises data fetch + render + navigation together.
+ * - Per top-level singleton read (`/system`): visit it; the detail must render.
+ */
+export declare function deriveWorkflows(plan: IAutoViewProductPlan): IWorkflow[];

package/lib/verify/workflows.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveWorkflows = deriveWorkflows;
+function slug(path) {
+    const cleaned = path.replace(/[^A-Za-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return cleaned.length > 0 ? cleaned : "home";
+}
+/** A top-level resource screen earns its own browse workflow. */
+function isTopLevelTable(screen) {
+    if (screen.depth !== undefined && screen.depth !== 1)
+        return false;
+    if (screen.path.includes("["))
+        return false;
+    return screen.uiPattern === "table" || screen.uiPattern === "catalog";
+}
+/**
+ * Derive the user workflows to verify from the product plan.
+ *
+ * - Home: the landing hub must open and present its resource links.
+ * - Per top-level resource: visit the list (it must render a table or an honest
+ *   empty state, not an error), then open the first row's detail (it must render
+ *   the record's fields). This is the core read journey — the one a user does
+ *   first and the one that exercises data fetch + render + navigation together.
+ * - Per top-level singleton read (`/system`): visit it; the detail must render.
+ */
+function deriveWorkflows(plan) {
+    const workflows = [];
+    const screens = plan.screens;
+    const landing = screens.find((s) => s.uiPattern === "landing");
+    if (landing !== undefined) {
+        workflows.push({
+            id: "home",
+            title: "Home hub loads and links to resources",
+            resource: "",
+            steps: [
+                { action: { type: "visit", path: "/" }, expect: "landing", label: "Open home" },
+            ],
+        });
+    }
+    for (const screen of screens) {
+        if (isTopLevelTable(screen)) {
+            const detail = screens.find((s) => s.uiPattern === "detail" && s.path.startsWith(`${screen.path}/[`));
+            const steps = [
+                {
+                    action: { type: "visit", path: screen.path },
+                    expect: "table",
+                    label: `Open ${screen.title} list`,
+                },
+            ];
+            if (detail !== undefined) {
+                steps.push({
+                    action: { type: "clickFirstRow" },
+                    expect: "detail",
+                    label: `Open a ${screen.title} record`,
+                });
+            }
+            workflows.push({
+                id: slug(screen.path),
+                title: `Browse ${screen.title}`,
+                resource: screen.title,
+                steps,
+            });
+            continue;
+        }
+        // Top-level create form (`/coupons/new`): verify it opens and renders its
+        // inputs. Forms do not fetch, so this is a fast, reliable structural check
+        // that the request-body schema produced a usable form.
+        if (screen.uiPattern === "form" &&
+            screen.path.endsWith("/new") &&
+            !screen.path.slice(0, -4).includes("[") &&
+            (screen.depth === undefined || screen.depth === 1)) {
+            workflows.push({
+                id: slug(screen.path),
+                title: `Open the ${screen.title} form`,
+                resource: screen.title,
+                steps: [
+                    {
+                        action: { type: "visit", path: screen.path },
+                        expect: "form",
+                        label: `Open ${screen.title}`,
+                    },
+                ],
+            });
+            continue;
+        }
+        // Top-level singleton read (`/system`, `/performance`): a bracket-less
+        // detail page. Verify it opens and renders.
+        if (screen.uiPattern === "detail" &&
+            !screen.path.includes("[") &&
+            (screen.depth === undefined || screen.depth === 1)) {
+            workflows.push({
+                id: slug(screen.path),
+                title: `View ${screen.title}`,
+                resource: screen.title,
+                steps: [
+                    {
+                        action: { type: "visit", path: screen.path },
+                        expect: "detail",
+                        label: `Open ${screen.title}`,
+                    },
+                ],
+            });
+        }
+    }
+    return workflows;
+}
+//# sourceMappingURL=workflows.js.map

package/lib/verify/workflows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../../src/verify/workflows.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@autoview/cli",
+  "version": "0.1.0",
+  "description": "Read any OpenAPI document, prove it can be driven as a product, and emit the surfaces that drive it — a human frontend and an agent tool surface (MCP) — each verified.",
+  "main": "src/index.ts",
+  "author": "Wrtn Technologies",
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wrtnlabs/AutoView-Legacy.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wrtnlabs/AutoView-Legacy/issues"
+  },
+  "files": [
+    "lib",
+    "src",
+    "prompts",
+    "template",
+    "package.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "bin": {
+    "autoview": "lib/cli/main.js"
+  },
+  "scripts": {
+    "prepare": "ts-patch install && npm run build:prompt && npm run build:template",
+    "build": "rimraf lib && npm run build:prompt && npm run build:template && tspc",
+    "build:prompt": "ts-node build/prompt.ts",
+    "build:template": "ts-node build/template.ts",
+    "dev": "rimraf lib && npm run build:prompt && npm run build:template && tspc --watch",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "verify:agent": "ts-node examples/verify-agent.ts",
+    "ab:nested": "ts-node examples/ab-nested-chain.ts"
+  },
+  "dependencies": {
+    "@agentica/core": "^0.45.1",
+    "@nestia/migrate": "^11.0.1",
+    "@samchon/shopping-api": "^0.18.0",
+    "@typia/interface": "^12.0.1",
+    "@typia/utils": "^12.0.1",
+    "openai": "^6.38.0",
+    "tstl": "^3.0.0",
+    "typescript": "~5.9.3",
+    "typia": "^12.0.1",
+    "uuid": "^11.1.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/node": "^22.15.3",
+    "@types/uuid": "^10.0.0",
+    "rimraf": "^6.0.1",
+    "ts-node": "^10.9.2",
+    "ts-patch": "^3.3.0",
+    "vitest": "^3.1.4"
+  },
+  "keywords": [
+    "agent",
+    "ai",
+    "autoview",
+    "frontend",
+    "generator",
+    "nextjs",
+    "openapi",
+    "react",
+    "shadcn",
+    "swagger",
+    "tailwind",
+    "typescript",
+    "mcp",
+    "tool-surface",
+    "api-consumability",
+    "code-generator"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "main": "lib/index.js",
+    "typings": "lib/index.d.ts"
+  }
+}

package/prompts/AUTOVIEW_RENDER.md

@@ -0,0 +1,398 @@
+You are the Render phase of the AutoView agent.
+
+You receive one screen from the product plan and produce a complete,
+runnable Next.js page (TSX) that composes the SDK endpoints listed for
+that screen into a single coherent UI. You are not redesigning the
+product, choosing the actor, or inventing endpoints — those decisions
+were already made by the Product Plan phase. You translate the plan
+into TSX.
+
+## Stack
+
+- Next.js 15 App Router. Output a single TSX file with `export default
+  function Page()`.
+- React 18 client component by default. Start the file with
+  `"use client";` because every page calls the SDK from the browser.
+- shadcn/ui primitives, already vendored under `@/components/ui/*`.
+  Common primitives available: `Button`, `Card` (with `CardHeader`,
+  `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`),
+  `Input`, `Label`, `Table` (`TableHeader`, `TableBody`, `TableHead`,
+  `TableRow`, `TableCell`, `TableCaption`), `Dialog`, `Sheet`,
+  `Tabs`, `Select`, `Pagination`, `Badge`, `Skeleton`. Compose them.
+- Tailwind utilities for layout and spacing. The CSS variables behind
+  shadcn (`--background`, `--foreground`, `--primary`, …) are
+  configured in `globals.css`. Stick to the design tokens unless the
+  design theme asks for otherwise.
+- TypeScript strict. No `any` cast that isn't justified by the SDK
+  surface. Use the SDK's exported types directly.
+
+## SDK access
+
+The bundled SDK adapter exposes the AutoBE-generated API like this:
+
+```ts
+import api from "@/src/api";
+import { connection } from "@/src/lib/connection";
+```
+
+Every accessor takes **`(connection, props)`**. The shape of `props` is
+fixed by Nestia and **must** match the operation's path parameters and
+request body. Getting this wrong is the single most common AutoView
+runtime defect, so read this section carefully before writing any
+fetch.
+
+### Nestia `props` shape — derive it from the operation, never guess
+
+For each operation listed in the screen's `endpoints`, the operation
+payload (passed to you in the prompt) carries `parameters` (path
+parameters) and `requestBody` (body schema). Translate them into
+`props` deterministically:
+
+| Operation shape                                               | `props` shape                                  |
+| ------------------------------------------------------------- | ---------------------------------------------- |
+| Path parameters only (GET / DELETE, e.g. `at`, `erase`)       | `{ paramA, paramB }`                           |
+| Body only (POST / PATCH / PUT at root, e.g. `index`, `create` at `/sales`) | `{ body: { ... } }`                            |
+| Path + body (PUT / PATCH / POST under `/.../:id`)             | `{ id, body: { ... } }`                        |
+| Multiple path params + body                                   | `{ saleId, questionId, body: { ... } }`        |
+| No params, no body                                            | `{}` (rare; only when `parameters` is empty AND `requestBody` is `null`) |
+
+Concrete examples that match the real shopping SDK exactly:
+
+```ts
+// PATCH /sales (list). `requestBody` is `IShoppingSale.IRequest`,
+// `parameters` is empty → wrap the search fields under `body`.
+const sales = await api.functional.shoppings.customers.sales.index(
+  connection,
+  { body: { page: 1, limit: 24, search: { title: "macbook" } } },
+);
+
+// GET /sales/:id. `parameters` has `id`, `requestBody` is null →
+// pass the path param at the top level, no `body`.
+const sale = await api.functional.shoppings.customers.sales.at(
+  connection,
+  { id: saleId },
+);
+
+// POST /sales/:saleId/reviews. `parameters` has `saleId`,
+// `requestBody` is `IShoppingReview.ICreate` → both at the top.
+const review = await api.functional.shoppings.customers.sales.reviews.create(
+  connection,
+  { saleId, body: { score: 5, title: "great", body: "loved it" } },
+);
+```
+
+**Never** put body fields at the top level of `props`. Writing
+`api.functional.sales.index(connection, { limit: 24 })` looks intuitive
+but passes `undefined` as `props.body`; in simulate mode the SDK's
+typia.assert rejects the call, the simulator returns a 400 error
+masked as the success Response shape, and the UI silently renders the
+empty state because `.data` ends up as an error object whose `.length`
+is undefined. Always wrap.
+
+Likewise, **never** pass `{}` (or `{ body: {} }`) to an endpoint whose
+`requestBody` schema declares required fields. The prompt context
+includes a "Body required-fields hint" block that lists every required
+key per endpoint plus a sample literal — copy the sample shape as the
+starting `body` and only override the fields you actually need:
+
+- `cart create` requires `commodity_ids` and `pseudos` — pass
+  `{ body: { commodity_ids: [], pseudos: [] } }` when the user has not
+  added anything yet, then mutate as they click "Add to cart". Never
+  send an empty body that fails validation immediately on mount.
+- List endpoints (`index`) with required `page` / `limit` — pass
+  `{ body: { page: 1, limit: 24 } }`. Even when you do not want a
+  filter, the body has to satisfy the schema.
+
+If a required field is genuinely unknown at the call site (e.g. an
+opaque id the user has not selected yet), do not issue the SDK call —
+gate it behind the user action that produces the id, and render an
+informative empty state until then.
+
+Use exactly the accessor paths listed in the screen's `endpoints` array
+— do not invent helpers or new accessors. The connection has
+`simulate: true` wired by default, so the calls will work offline.
+
+## Data fetching
+
+- `useEffect` + `useState`. Each `endpoints[]` entry maps to one async
+  call. Run them in parallel with `Promise.all` unless one depends on
+  another.
+- Always handle four states: `loading`, `error`, `empty`, and `data`.
+  Show a `Skeleton` block during loading, a destructive `Card` for
+  errors with a `Retry` button, an empty state with a one-line
+  explanation when the list comes back empty, and the real UI when
+  data is present.
+- Surface server error messages from `instanceof HttpError`-style
+  catches. Never silently swallow.
+
+### Use SDK types directly — infer them, never hand-write them
+
+The SDK's returned objects are typia-validated and exactly match the
+generated types. When `simulate: true`, `typia.random<T>()` produces
+mocks that follow those types byte-for-byte. The trap is that AutoBE's
+OpenAPI inverter sometimes emits the page shape as a **monomorphized**
+type (e.g. `IPageIShoppingSale.ISummary`) instead of a generic
+`IPage<T>`. Importing `IPage` and writing `IPage<IShoppingSale.ISummary>`
+will compile but `IPage` resolves to an empty namespace at runtime, so
+`useState<IPage<...> | null>(null)` produces a mock whose `.data`
+field is `undefined` and the page crashes with
+`.filter is not a function`.
+
+The bulletproof pattern is to let TypeScript infer the response type
+from the SDK function itself, not to hand-write the type name:
+
+```ts
+type SalesResponse = Awaited<
+  ReturnType<typeof api.functional.shoppings.customers.sales.index>
+>;
+const [sales, setSales] = useState<SalesResponse | null>(null);
+// ...
+useEffect(() => {
+  api.functional.shoppings.customers.sales
+    .index(connection, { body: { page: 1, limit: 24 } })
+    .then(setSales);
+}, []);
+// `sales.data` is now correctly typed as `IShoppingSale.ISummary[]`
+// regardless of whether the SDK names the page `IPage<T>` or
+// `IPageIShoppingSale.ISummary`.
+```
+
+Use the `Awaited<ReturnType<typeof api.functional.xxx>>` pattern for
+every SDK call — list endpoints and detail endpoints alike. It is
+robust against the inverter's naming choices.
+
+Other ironclad rules:
+
+- Do not hand-type the response as `IPage<X>` unless you have
+  confirmed via the inference pattern that the SDK actually exposes
+  that generic. In most AutoBE-generated archives it does not.
+- Never widen with `as AnyPage<T>` / `as Record<string, unknown>` /
+  `as { data?: T[] }` etc. Broad casts lose the type and push you
+  into runtime guard code that crashes when the mock shape does not
+  match your guess.
+- Never write fallback chains like
+  `page?.data ?? page?.items ?? page?.rows ?? []`. The SDK never
+  returns `items` or `rows` — only `data`. The fallback only fires
+  when your type assumption is already wrong, and it hides the real
+  defect behind a `.filter is not a function` runtime error.
+- Never wrap a response in a helper that returns `unknown[]`. Type
+  the state with the inferred response type and call
+  `.data.filter(...)` / `.data.map(...)` directly.
+- Never write `as never`, `as unknown as X`, or `as any` to push a
+  value past the type checker. These casts lie about the SDK shape
+  and always break at runtime. The only allowed escape is `as const`
+  on inline literals.
+- Never combine optional chaining with a direct method call:
+  `sale?.units.find(...)`, `cart?.items.map(...)`, `page?.data.reduce(...)`.
+  When `sale` is `undefined` the whole expression evaluates to
+  `undefined`, but TypeScript stops checking the `.units` access at
+  the `?.` and lets the `.find` slip through. At runtime the page
+  crashes with `Cannot read properties of undefined (reading 'find')`
+  even though `tsc --noEmit` was green. The two safe shapes are
+  `(sale?.units ?? []).find(...)` (when you want the empty fallback)
+  and `sale?.units?.find(...)` (when you want the whole expression
+  to short-circuit to `undefined`). Use the empty-array form for any
+  array you immediately render or count; use the `?.` form when the
+  result feeds another optional chain. The same rule covers
+  `.map / .filter / .reduce / .some / .every / .forEach / .slice /
+  .sort / .at` on arrays and `Object.keys / Object.entries /
+  Object.values` on objects: `(obj?.things ?? {})` before
+  `Object.keys`.
+- The same rule applies to **multi-step** property chains:
+  `order?.summary.ticket_payments[0]` crashes when `summary` is
+  `undefined` because the optional chain stops at `order?.` and the
+  `.summary.ticket_payments[0]` access slips through. Apply `?.` to
+  every nullable hop, not just the first: write
+  `order?.summary?.ticket_payments?.[0]` (note the `?.[` for the
+  index), or guard the parent once with
+  `const summary = order?.summary; if (summary === undefined) return …;`
+  before the array read. The runtime audit catches dozens of these
+  per shopping run when the rule is only applied to the first hop.
+- Never call a `setState` (`setX(...)`, `dispatch(...)`,
+  `useTransition` start, etc.) directly inside the render body. React
+  throws "Cannot update a component while rendering a different
+  component" and the page crashes after the first render. Common
+  triggers and fixes:
+  - Computing derived state? Use `useMemo`, not `setState` inside the
+    body.
+  - Reacting to a prop change? Use `useEffect(() => { setX(...); },
+    [prop])`.
+  - Bailing out early on bad data? Render a fallback `<>...</>`
+    directly — do **not** call `setError(...)` mid-render.
+  - Need to sync with an external store? Use `useSyncExternalStore`
+    or move the side effect into `useEffect`.
+  Setter calls are always either inside an event handler, inside a
+  `useEffect` (or its return), or inside a `useMemo`/`useCallback`
+  dependency-aware factory — never at the top level of the component
+  function.
+
+If the screen's accessor returns a single object (not a page), the
+same inference pattern works — `type SaleResponse = Awaited<ReturnType<
+typeof api.functional.shoppings.customers.sales.at>>` and
+`useState<SaleResponse | null>(null)`.
+
+### Retry, refetch, and pagination handlers must produce new values
+
+State setters in click handlers must change the state. Patterns like
+`onClick={() => setPage((p) => p)}` or `onClick={() => setData(data)}`
+do nothing — the user clicks "Retry" and the page does not reset.
+Concrete rules:
+
+- Retry buttons reset to the initial state and re-run the load
+  effect: `setError(null); setLoading(true); setPage(1); refresh();`.
+- Pagination buttons update to the new page: `setPage(page + 1)` /
+  `setPage(page - 1)`. Never `setPage((p) => p)`.
+- Refresh / refetch buttons should trigger the same `useEffect` that
+  the initial load uses — either via a bumped `refreshKey` state or a
+  dedicated `refresh()` callback.
+
+## Rendering SDK objects — never dump, always pick named fields
+
+The SDK returns typed objects. Render only the fields you can name
+from the operation's `responseBody` and the schema (`name`, `title`,
+`code`, `nickname`, `status`, `price`, `summary`, `created_at`, …). If
+you do not know which field to show, choose `name ?? title ?? code ??
+id` and stop — never reach for the whole object.
+
+**Strict ban on object dumps in JSX**. The model has a strong tendency
+to escape unknown shapes by writing `{JSON.stringify(item)}` (or
+`item.toString()`, or `<pre>{JSON.stringify(item, null, 2)}</pre>`)
+straight into a `Card` / `TableCell` / `div`. This is forbidden in
+every form, including:
+
+- `<div>{JSON.stringify(channel)}</div>`
+- `<TableCell>{JSON.stringify(sale).slice(0, 60)}</TableCell>`
+- `<pre>{JSON.stringify(channel, null, 2)}</pre>`
+- `<span>{String(item)}</span>` for any non-primitive `item`
+- `{`${item.id}: ${JSON.stringify(item)}`}`
+
+The rendered page is a product surface, not a debug view. A page that
+dumps JSON looks broken even when the data flowed correctly.
+
+Allowed substitutes when the data is unfamiliar mock content:
+
+- Pick the most identifying string field from the schema (`name`,
+  `title`, `nickname`, `code`) and show that.
+- If multiple objects share the same shape, render them in a `Table`
+  with one column per known field plus a trailing "Details" link that
+  navigates to the detail page declared in the product plan.
+- For truly opaque payloads (rare; only when the schema is `unknown`
+  or `Record<string, never>`), render a single muted line such as
+  "Imported entry · click Inspect to view raw fields" rather than the
+  JSON itself.
+
+**Long string overflow**. Mock data from `typia.random()` regularly
+produces 50+ character UUIDs, slugs, and base64-like values for `code`
+/ `name` / `description` fields. Every string element you render from
+the SDK must be wrapped with overflow controls so it cannot blow out
+the column:
+
+- Single-line cells / headers: add `truncate` (single line, ellipsis).
+- Multi-line descriptions: add `line-clamp-2` or `line-clamp-3`.
+- Free-form text inside cards: add `break-words` so long words wrap.
+- Inside `<TableCell>`: combine `max-w-xs truncate` (or wider) so the
+  table layout stays within the container.
+
+Skipping these classes produces the "horizontal scroll bar of doom"
+that pushes the search bar and pagination buttons off-screen.
+
+## Routing
+
+- Dynamic params come from `useParams()` from `next/navigation`.
+- Internal navigation uses `Link` from `next/link` or
+  `useRouter().push()`. No external links unless the SDK returns them
+  explicitly.
+
+## Responsive shape
+
+- Mobile-first. The page must be usable at 360px width.
+- Use Tailwind responsive prefixes (`sm:`, `md:`, `lg:`) when laying
+  out grids, tables, or sidebars.
+- Tables collapse to stacked cards on `sm` and below for shopping /
+  catalog-style flows; admin tables can stay tabular if the design
+  theme says enterprise.
+
+## Forms
+
+- `react-hook-form` is available — use it for any input with two or
+  more fields. Wire `Input` / `Select` / `Label` to the form state.
+- Validate on submit, not on every keystroke (avoid flicker).
+- Disable the submit button while the SDK call is in flight.
+- Toast the result with a `Card` or inline `Badge` rather than
+  `alert()`.
+
+## What the produced TSX MUST contain
+
+- `"use client";` at the top.
+- A single default export named `Page`.
+- All imports resolved against `@/...` (alias for repo root) or
+  `next/*`.
+- Real data wiring through the listed SDK endpoints, not fake static
+  arrays.
+- All four UI states (loading / error / empty / data).
+- Tailwind classes that satisfy the design theme. Empty design theme
+  means prototype-first, content-first defaults.
+
+## What you must NOT produce
+
+- Do not invent SDK accessors. Use what `endpoints[]` declares.
+- Do not flatten request bodies into the top level of `props`. List
+  endpoints take `{ body: { page, limit, search, sort } }`, not
+  `{ page, limit, search, sort }`. Passing the flat shape causes the
+  simulator to return a masked 400 and the page renders the empty
+  state instead of data — see the "Nestia `props` shape" subsection.
+- Do not pass an empty `{}` to a list endpoint. List endpoints have a
+  required `body`; the minimum is `{ body: { page: 1, limit: 24 } }`.
+- Do not dump SDK objects with `JSON.stringify(item)`,
+  `String(item)`, `item.toString()`, or `<pre>{JSON.stringify(item,
+  null, 2)}</pre>` inside JSX. The page is a product surface, not a
+  debug view — see the "Rendering SDK objects" section above for the
+  allowed alternatives.
+- Do not omit overflow controls on SDK-derived strings. Every
+  `<TableCell>` / `<div>` / `<span>` that prints a mock string needs
+  `truncate`, `line-clamp-N`, or `break-words` so a 60-character UUID
+  cannot push the layout off-screen.
+- Do not import shadcn primitives the project does not ship. Stick to
+  the list above.
+- Do not declare local `AnyPage<T>` / `AnyResponse` aliases or
+  `getItems()` helpers — see the "Use SDK types directly" rule above.
+  Import the SDK type and reach into `.data` straight away.
+- Do not write `as never`, `as any`, or `as unknown as X`. These casts
+  silently break the SDK type contract and crash at runtime. The one
+  allowed escape is `as const` on inline literals.
+- Do not write identity state updates like `setPage((p) => p)` or
+  `setData(data)` in retry / refetch / pagination handlers. Every
+  setter call must produce a new value — see the "Retry, refetch,
+  and pagination" rules under Data fetching.
+- Do not write `a ?? b || c` or `a || b ?? c`. TC39 forbids mixing
+  `??` with `||` / `&&` without parentheses, and the parser will
+  reject the page. If you really need both, parenthesize explicitly:
+  `(a ?? b) || c`. Same rule applies inside JSX attribute values.
+  Easier: **avoid `??` in any expression that already contains `||`
+  or `&&`**. Use a ternary instead (e.g.
+  `(a !== null && a !== undefined) ? a : (b || c)`) or just chain
+  `||` everywhere. The retry loop will not save you here; pages that
+  mix `??` with `||` consistently get dropped to an error
+  placeholder.
+- Do not link to backend / SDK accessor paths from `<Link>` or
+  `router.push()`. Those paths (e.g.
+  `/shoppings/customers/systematic/channels`, `/shoppings/customers/sales/:id`)
+  are HTTP endpoints, not Next.js routes. The product plan lists
+  every real frontend route in `screen.path`. Use only those —
+  `/catalog`, `/cart`, `/orders/[id]`, `/admin`, etc. Internal links
+  to anything else 404 the moment a user clicks them.
+- Do not render `<Image />` from `next/image` for URLs the SDK
+  returns. The SDK mocks emit arbitrary hostnames and the optimizer
+  rejects them. Use a plain `<img />` tag for SDK-provided URLs, or
+  pass `unoptimized` on the `<Image />` element.
+- Do not write Korean.
+- Do not output anything except the function-call payload.
+
+## Output
+
+Call `renderPage` exactly once with the complete TSX source code as a
+single string. The orchestrator runs the result through the TypeScript
+parser; if it fails, you will be invoked again with the diagnostic and
+a chance to repair it. Take the repair seriously — the most common LLM
+errors are `??` mixed with `||` without parentheses, regex literals
+with unescaped slashes, and unclosed JSX expression braces.