@lucasvu/scope-ui 0.1.1 → 0.1.2

package/AI_SETUP.md

@@ -298,7 +298,7 @@ File generate ra se la source of truth cho palette, surface, radius va shadow cu
 
 Neu can them mot bundled package theme layer de co shell tone dung san, import no o app entry. Neu theme layer do la attribute-scoped, set them `data-client-theme` bang `applyDocumentClientTheme`.
 
-`AGENTS.md` se co them shell brief + screen brief dang YAML de agent dien cac gia tri nhu `workspaceLabel`, `pageTabs`, `searchPlaceholder`, `routeUrl`, `sidebarItems`, `pageTitle`, `filters`, `fields`, `tableColumns` truoc khi bat dau viet JSX.
+`AGENTS.md` se duoc generate theo format agent-definition YAML, co `activation-instructions`, `agent`, `persona`, `commands`, `dependencies`, va `brief_templates`. Agent se dien cac gia tri nhu `workspaceLabel`, `pageTabs`, `searchPlaceholder`, `routeUrl`, `sidebarItems`, `pageTitle`, `filters`, `fields`, `tableColumns` truoc khi bat dau viet JSX. Neu tool cua ban discover agent theo file rieng, co the truyen `--agents-file agents/dev.md` hoac mot path tuong tu.
 
 `src/layout-presets/workspace-admin-v1.ts` khong can import vao runtime. Day la layout contract cho agent/codegen doc de giu dark sidebar, gradient topbar, intro card, tab row, va toolbar card nhat quan giua cac man.
 

package/README.md

@@ -61,7 +61,7 @@ npx scope-ui-init --list-themes
 
 Lưu ý: các lệnh này chỉ chạy được sau khi project đã cài `@lucasvu/scope-ui`. Nếu chưa cài package, `npx` sẽ đi tìm một package riêng tên `scope-ui-init` trên npm và báo `E404`.
 
-Lệnh này sẽ tạo `AGENTS.md`, `src/styles/ui-theme.css`, và `src/layout-presets/workspace-admin-v1.ts` trong repo hiện tại theo preset đã chọn. `AGENTS.md` giờ có thêm playbook step-by-step để agent hỏi đủ input, đọc layout preset, rồi dựng màn hình đúng layout/component/theme chung. Nếu không truyền `--theme`, preset mặc định là `ocean`. Dùng `--force` nếu muốn overwrite file đã tồn tại.
+Lệnh này sẽ tạo `AGENTS.md`, `src/styles/ui-theme.css`, và `src/layout-presets/workspace-admin-v1.ts` trong repo hiện tại theo preset đã chọn. `AGENTS.md` giờ được generate theo format agent-definition YAML có `activation-instructions`, `agent`, `persona`, `commands`, `dependencies`, `brief_templates`, và rule lock theme/layout. Nếu muốn output thẳng vào path agent-discovery của tooling, dùng `--agents-file`, ví dụ `npx scope-ui-init --theme sunset --agents-file agents/dev.md`. Nếu không truyền `--theme`, preset mặc định là `ocean`. Dùng `--force` nếu muốn overwrite file đã tồn tại.
 
 5. Dùng component:
 
@@ -180,10 +180,11 @@ Nếu muốn AI render UI đúng và ổn định theo thư viện này, đừng
 - Cài package trước khi bootstrap: `npm install @lucasvu/scope-ui`
 - Chạy `npx scope-ui-init --list-themes` để xem preset được duyệt
 - Chạy `npx scope-ui-init --theme <preset>` ở project consumer sau khi đã cài `@lucasvu/scope-ui` để tạo `AGENTS.md`, `src/styles/ui-theme.css`, và `src/layout-presets/workspace-admin-v1.ts`
+- Nếu tooling của bạn đọc agent theo file riêng, dùng `--agents-file agents/dev.md` hoặc path tương đương để generate luôn agent markdown đúng chỗ
 - Khoá project vào một preset thay vì tự bịa palette mới cho từng page
-- Để agent đọc luôn playbook trong `AGENTS.md` và `src/layout-presets/workspace-admin-v1.ts` để đi đúng thứ tự: hỏi input, khóa shell, chọn component, dựng layout, rồi mới tinh chỉnh token
+- Để agent đọc luôn agent-definition trong `AGENTS.md` hoặc file bạn truyền qua `--agents-file`, cùng với `src/layout-presets/workspace-admin-v1.ts`, để đi đúng thứ tự: hỏi input, khóa shell, chọn component, dựng layout, rồi mới tinh chỉnh token
 - Buộc agent điền shell + screen brief trước khi code: `workspaceLabel`, `pageTabs`, `searchPlaceholder`, `routeUrl`, `sidebarItems`, `activeSidebarItemId`, `pageTitle`, `actions`, `filters`, `fields`, `tableColumns`
-- `AGENTS.md` mới sẽ có sẵn block brief dạng YAML để agent hoặc dev điền trực tiếp trước khi code
+- `AGENTS.md` mới sẽ có sẵn block `commands`, `dependencies`, và `brief_templates` dạng YAML để agent hoặc dev điền trực tiếp trước khi code
 - Chỉ dùng các component canonical ở root package; tránh `MainFe` nếu không phải legacy screen
 - Cho agent đọc `uiAiManifest` để biết component nào dùng cho intent nào, props quan trọng là gì, và khi nào không nên dùng
 - Cho agent đọc `uiScreenBlueprint`, `uiThemeContract` và `uiThemePresets` để biết screen recipe, preset và token nào được phép override

package/bin/scope-ui-init.mjs

@@ -333,6 +333,9 @@ Usage:
   npx scope-ui-init --theme sunset
     Fast path when you already know the preset you want.
 
+  npx scope-ui-init --theme sunset --agents-file agents/dev.md
+    Optional: write the generated agent definition straight into a tool-specific agent path.
+
   npx scope-ui-init --list-themes
     Optional: inspect approved presets before choosing one.
 
@@ -341,7 +344,7 @@ Usage:
 
 Options:
   --force        overwrite existing files
-  --agents-file  target path for the generated AGENTS.md file
+  --agents-file  target path for the generated agent markdown file
   --theme-file   target path for the generated theme override file
   --layout-file  target path for the generated layout preset file
   --theme        theme preset id (${Object.keys(THEME_PRESETS).join(', ')})
@@ -383,223 +386,283 @@ function renderTokenBlock(tokens) {
     .join('\n')
 }
 
-function renderMarkdownList(items) {
-  return items.map((item) => `- ${item}`).join('\n')
+function quoteYaml(value) {
+  return JSON.stringify(value)
 }
 
-function createAgentsTemplate({ themeFile, layoutFile, themePreset, layoutPreset }) {
-  return `# Agent Rules
-
-This repo uses \`${PACKAGE_NAME}\` as the default UI library.
-Use \`${PACKAGE_NAME}\` for React components and \`${PACKAGE_NAME}/core\` for framework-agnostic theme/runtime contracts.
-This repo is locked to the \`${themePreset.label}\` theme preset (\`${themePreset.id}\`).
-This repo uses the \`${layoutPreset.label}\` shell preset (\`${layoutPreset.id}\`) as the shared layout baseline.
-
-Primary references:
-- \`node_modules/${PACKAGE_NAME}/README.md\`
-- \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\`
-- \`uiScreenBlueprint\`, \`uiAiManifest\`, and \`uiThemeLayerAssets\` from \`${PACKAGE_NAME}/core\`
-- \`${themeFile}\`
-- \`${layoutFile}\`
-
-Theme preset summary:
-- ${themePreset.description}
-- Recommended for: ${themePreset.recommendedFor.join(', ')}
-
-Layout preset summary:
-${renderMarkdownList(layoutPreset.shellRecipe)}
-
-## Workspace Base
-
-For Vite + micro frontend repos, keep this structure stable:
-
-- \`${PACKAGE_NAME}\` owns the React component surface
-- \`${PACKAGE_NAME}/core\` owns theme contracts, bundled theme layers, color-mode runtime, and framework-agnostic contracts
-- \`apps/shell\` owns the shared app shell, top-level routing, remote mounts, and theme imports
-- \`apps/*-mfe\` owns page-level business screens and feature routes
-
-If the repo still has a \`packages/shared\` folder, keep it for business utils or internal loaders, not for the primary theme runtime.
-
-Recommended folders:
-
-- shell: \`src/app\`, \`src/layouts\`, \`src/routes\`, \`src/remotes\`, \`src/styles/ui-theme.css\`
-- remote: \`src/features\`, \`src/pages\`, \`src/routes\`, \`src/services\`, \`src/styles/index.css\`
-
-Theme layers:
-
-1. Import \`${PACKAGE_NAME}/styles.css\` first.
-2. If the repo wants a bundled shell/theme layer, import one from \`${PACKAGE_NAME}/themes/*\` next.
-3. Import \`${themeFile}\` after the bundled theme layer.
-4. Keep app-specific overrides thin and token-based.
-
-If the bundled theme layer is client-theme-scoped, set \`data-client-theme\` with \`applyDocumentClientTheme(...)\`.
-
-## Required Flow
-
-When asked to build or edit a screen, follow these steps in order:
-
-1. Read \`${themeFile}\`, \`${layoutFile}\`, \`node_modules/${PACKAGE_NAME}/README.md\`, \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\`, and the exported \`uiScreenBlueprint\` contract before generating UI.
-2. If the task touches app bootstrap, shell setup, or micro frontend structure, scaffold the repo around the workspace base above before writing page JSX.
-3. Fill the shell brief and screen brief first. If a required field is missing, stop and ask for that exact value before writing JSX. Only leave TODO placeholders when the user explicitly asks for an incomplete scaffold.
-4. Verify the app entry imports \`${PACKAGE_NAME}/styles.css\` first, then any bundled theme layer from \`${PACKAGE_NAME}/themes/*\`, then \`${themeFile}\`.
-5. Treat \`${layoutFile}\` as the source of truth for the app shell. Keep the dark sidebar, gradient topbar, intro card, and card-based body structure aligned with that preset unless the user explicitly asks for a different shell.
-6. Keep the shell in the host app. Do not let a remote rebuild its own global shell unless the task explicitly asks for a standalone shell.
-7. Identify the page kind (\`list | form | detail | dashboard\`), then map each block to canonical components from \`uiAiManifest\` before writing JSX.
-8. Build the shell in this exact order: \`Sidebar\` -> workspace topbar -> intro card (\`Breadcrumb\` + \`PageTitle\`) -> optional segmented tabs -> toolbar card -> page body cards/grids.
-9. For list pages, build the toolbar card first and then the \`DataTable\`. For form pages, keep the same shell and swap the body into section cards and a bottom action row. For detail pages, keep the shell and render summary/detail cards plus related tables. For dashboard pages, keep the shell and render stat cards plus supporting cards/tables.
-10. If \`${layoutFile}\` says a slot is optional, omit it cleanly when the brief does not request it. Do not invent tabs, workspace labels, filters, or toolbar actions.
-11. Keep all colors, radius, surface, and shadow decisions inside \`${themeFile}\`. If the preset is insufficient, update tokens there instead of styling one page ad hoc.
-12. Before finishing, run the output checklist in this file.
-
-## Ask For Missing Input
-
-If any of these are missing, ask the user directly before writing JSX:
-
-${renderMarkdownList(layoutPreset.askBeforeCoding)}
-
-## Shell Brief
-
-Complete this shell brief before writing JSX:
-
-\`\`\`yaml
-layoutPreset: ${layoutPreset.id}
-workspaceLabel:
-timezoneLabel:
-userBadgeLabel:
-pageTabs:
-  - value:
-    label:
-activePageTab:
-searchPlaceholder:
-toolbarNote:
-\`\`\`
-
-## Screen Brief
+function renderYamlList(items, indent = 2) {
+  const prefix = ' '.repeat(indent)
+  return items.map((item) => `${prefix}- ${quoteYaml(item)}`).join('\n')
+}
 
-Complete this screen brief before writing JSX:
+function createAgentsTemplate({ themeFile, layoutFile, themePreset, layoutPreset }) {
+  const importOrder = [
+    `${PACKAGE_NAME}/styles.css`,
+    `${PACKAGE_NAME}/themes/*`,
+    themeFile,
+  ]
+  const activationInstructions = [
+    'ONLY load dependency files when user selects them for execution via command or request of a task',
+    'The agent.customization field ALWAYS takes precedence over any conflicting instructions',
+    'When listing commands or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute',
+    'STAY IN CHARACTER!',
+    `Read \`${themeFile}\`, \`${layoutFile}\`, \`node_modules/${PACKAGE_NAME}/README.md\`, and \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\` before generating UI`,
+    `Lock all UI work to the \`${themePreset.label}\` theme preset (\`${themePreset.id}\`) and the \`${layoutPreset.label}\` shell preset (\`${layoutPreset.id}\`) unless the user explicitly asks to change them`,
+    `Keep stylesheet import order as \`${PACKAGE_NAME}/styles.css\` -> optional \`${PACKAGE_NAME}/themes/*\` -> \`${themeFile}\``,
+    'If a bundled theme layer is client-theme-scoped, use `applyDocumentClientTheme(...)` after importing it',
+  ]
+  const corePrinciples = [
+    `CRITICAL: \`${themeFile}\` is the only source of truth for palette, radius, surface, and shadow decisions for this project`,
+    `CRITICAL: \`${layoutFile}\` is the source of truth for the shared shell and page frame`,
+    'CRITICAL: Follow the build-screen command when the user asks to implement or update a screen',
+    `CRITICAL: Use root exports from \`${PACKAGE_NAME}\` and avoid \`MainFe\` unless the task explicitly targets legacy screens`,
+    'CRITICAL: Keep the host app responsible for sidebar, topbar, remote mount, theme mode, and bundled theme layer activation',
+    'CRITICAL: Ask for missing required brief values before writing JSX unless the user explicitly asks for a scaffold with TODOs',
+    'Numbered Options - Always use numbered lists when presenting choices to the user',
+  ]
+  const runtimeContracts = [
+    `${PACKAGE_NAME}/core -> uiAiManifest`,
+    `${PACKAGE_NAME}/core -> uiScreenBlueprint`,
+    `${PACKAGE_NAME}/core -> uiThemeContract`,
+    `${PACKAGE_NAME}/core -> uiThemeLayerAssets`,
+    `${PACKAGE_NAME}/core -> uiThemePresets`,
+  ]
+  const pageKinds = ['list', 'form', 'detail', 'dashboard']
+  const pageFrameRecipes = {
+    list: [
+      'dark Sidebar',
+      'workspace topbar',
+      'intro card',
+      'optional segmented tabs',
+      'toolbar Card',
+      'DataTable Card',
+    ],
+    form: [
+      'dark Sidebar',
+      'workspace topbar',
+      'intro card',
+      'optional segmented tabs',
+      'top actions',
+      'sectioned form Card blocks',
+      'bottom action row',
+    ],
+    detail: [
+      'dark Sidebar',
+      'workspace topbar',
+      'intro card',
+      'optional segmented tabs',
+      'status/actions',
+      'summary metadata Card',
+      'detail Card blocks',
+      'related DataTable',
+    ],
+    dashboard: [
+      'dark Sidebar',
+      'workspace topbar',
+      'intro card',
+      'optional segmented tabs',
+      'toolbar Card',
+      'Stat row',
+      'insight Card blocks and DataTable',
+    ],
+  }
+  const hardRules = [
+    `import \`${PACKAGE_NAME}/styles.css\` once at the app entry`,
+    `import a bundled theme layer from \`${PACKAGE_NAME}/themes/*\` after the package stylesheet when the repo chooses one`,
+    'import the project theme override file after the bundled theme layer',
+    'use `applyDocumentClientTheme` when the chosen bundled theme layer is client-theme-scoped',
+    `use root exports from \`${PACKAGE_NAME}\` for React components`,
+    `use \`${PACKAGE_NAME}/core\` for theme/runtime utilities in non-React or mixed-framework setup`,
+    `use \`${themeFile}\` as the only source of truth for colors, radius, surfaces, and shadows`,
+    `use \`${layoutFile}\` as the source of truth for the shell layout and shared page frame`,
+    'keep the host shell responsible for sidebar, topbar, remote mount, and theme mode',
+    'keep remotes focused on feature routes and page business content',
+    'read `uiAiManifest` before choosing components',
+    'read `uiThemeLayerAssets` before choosing a bundled theme layer',
+    'read `uiThemeContract` before changing colors, surfaces, borders, radius, or shadows',
+    'keep UI token-driven and theme-driven',
+  ]
+  const doNotRules = [
+    'import from `MainFe` unless the task explicitly targets a legacy screen',
+    `invent a second palette or one-off brand colors outside \`${themeFile}\``,
+    'replace the shared dark-sidebar + gradient-topbar shell with a flat blank layout unless the user explicitly requests it',
+    'restyle individual pages if the preset tokens can solve it globally',
+    'create duplicate Button/Input/Select wrappers unless a project-specific behavior is required',
+    'let each remote define a different shell or a different palette',
+  ]
+  const componentChoices = [
+    'Input for short text',
+    'Textarea for multiline text',
+    'Select for small fixed options',
+    'SearchableSelect for larger local option sets',
+    'Combobox for type-and-pick',
+    'AsyncCombobox for remote search',
+    'MultiSelect for multi-pick',
+    'Field only for custom controls or grouped content',
+    'DataTable for tabular records',
+  ]
+  const outputCheck = [
+    'The shell brief and screen brief are complete',
+    'Any missing required input was explicitly asked for before coding',
+    `The shell matches \`${layoutPreset.id}\` with a dark sidebar, gradient topbar, intro card, and card-based body structure`,
+    'The chosen components match the page kind and the brief',
+    'No `MainFe` imports were used',
+    'No hardcoded brand colors were added in page components',
+    `Theme decisions live in \`${themeFile}\`, not in ad hoc JSX styling`,
+    'The app entry import order is package stylesheet -> bundled theme layer if present -> project theme override',
+    'The shell still lives in the host app and remotes only own business screens',
+    'Spacing, card structure, and actions are consistent with the shared preset',
+    'The layout shell stayed stable even if the page body changed',
+  ]
+
+  return `# dev
+
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 \`\`\`yaml
-pageKind: list | form | detail | dashboard
-routeUrl:
-sidebarItems:
-  - id:
-    title:
-    href:
-    icon:
-activeSidebarItemId:
-breadcrumbs:
-  - label:
-    href:
-    current:
-pageTitle:
-pageSubtitle:
-primaryAction:
-  label:
-  href:
-secondaryActions:
-  - label:
-    href:
-summaryStats:
-  - label:
-    value:
-    delta:
-    trend:
-filters:
-  - type:
-    label:
-    key:
-tableColumns:
-  - key:
-    title:
-    type:
-rowActions:
-  - label:
-    key:
-formSections:
-  - title:
-    fields: []
-fields:
-  - name:
-    type:
-    label:
-    required:
-    helperText:
-detailSections:
-  - title:
-    type:
-emptyState:
-  title:
-  description:
-  actionLabel:
-permissions: []
+activation-instructions:
+${renderYamlList(activationInstructions, 2)}
+agent:
+  name: James
+  id: dev
+  title: Theme-Locked Full Stack Developer
+  icon: 💻
+  whenToUse: ${quoteYaml(`Use for UI implementation, shell alignment, theme-safe refactors, and development best practices with ${PACKAGE_NAME}`)}
+  customization:
+    package_name: ${quoteYaml(PACKAGE_NAME)}
+    package_core: ${quoteYaml(`${PACKAGE_NAME}/core`)}
+    theme_preset_id: ${quoteYaml(themePreset.id)}
+    theme_preset_label: ${quoteYaml(themePreset.label)}
+    theme_preset_description: ${quoteYaml(themePreset.description)}
+    theme_file: ${quoteYaml(themeFile)}
+    layout_preset_id: ${quoteYaml(layoutPreset.id)}
+    layout_preset_label: ${quoteYaml(layoutPreset.label)}
+    layout_preset_description: ${quoteYaml(layoutPreset.description)}
+    layout_file: ${quoteYaml(layoutFile)}
+    import_order:
+${renderYamlList(importOrder, 6)}
+    recommended_for:
+${renderYamlList(themePreset.recommendedFor, 6)}
+    shell_recipe:
+${renderYamlList(layoutPreset.shellRecipe, 6)}
+persona:
+  role: ${quoteYaml('Expert Senior UI Engineer & Implementation Specialist')}
+  style: ${quoteYaml('Extremely concise, pragmatic, detail-oriented, solution-focused')}
+  identity: ${quoteYaml(`Expert who implements screens by locking to the selected theme preset, the shared shell contract, and canonical ${PACKAGE_NAME} components`)}
+  focus: ${quoteYaml('Executing UI tasks with precision, keeping shell and theme stable, and avoiding ad hoc palette drift')}
+core_principles:
+${renderYamlList(corePrinciples, 2)}
+commands:
+  - help: ${quoteYaml('Show numbered list of available commands, selected theme preset, and shared layout preset')}
+  - build-screen:
+      - order-of-execution: ${quoteYaml('Read theme and layout source -> fill shell brief + screen brief -> verify stylesheet import order -> map blocks to canonical components -> implement shell/body -> run tests/validations -> summarize changes')}
+      - required-inputs:
+${renderYamlList(layoutPreset.requiredFields, 10)}
+      - ask-before-coding:
+${renderYamlList(layoutPreset.askBeforeCoding, 10)}
+      - page-kinds:
+${renderYamlList(pageKinds, 10)}
+      - shell-lock:
+${renderYamlList(layoutPreset.shellRecipe, 10)}
+      - blocking: ${quoteYaml('HALT for: Missing required brief values | conflicting theme instructions | unknown bundled theme activation | failing regression | requests to mix multiple palettes')}
+      - ready-for-review: ${quoteYaml('Shell matches the shared preset + Theme stays token-driven + Canonical components are used + Validations pass')}
+      - completion: ${quoteYaml('Shell brief complete -> Screen brief complete -> Import order correct -> No MainFe drift -> Tests/validations pass -> Summarize changes')}
+  - review-theme: ${quoteYaml('Audit or update theme usage without inventing a second palette')}
+  - run-tests: ${quoteYaml('Execute the package build and any relevant validations for the touched files')}
+  - explain: ${quoteYaml('Teach me what and why you did whatever you just did in detail so I can learn')}
+  - exit: ${quoteYaml('Say goodbye as the Developer, and then abandon inhabiting this persona')}
+dependencies:
+  docs:
+${renderYamlList(['README.md', 'AI_SETUP.md'], 4)}
+  project-files:
+${renderYamlList([themeFile, layoutFile], 4)}
+  runtime-contracts:
+${renderYamlList(runtimeContracts, 4)}
+brief_templates:
+  shell:
+    layoutPreset: ${quoteYaml(layoutPreset.id)}
+    workspaceLabel:
+    timezoneLabel:
+    userBadgeLabel:
+    pageTabs:
+      - value:
+        label:
+    activePageTab:
+    searchPlaceholder:
+    toolbarNote:
+  screen:
+    pageKind: ${quoteYaml('list | form | detail | dashboard')}
+    routeUrl:
+    sidebarItems:
+      - id:
+        title:
+        href:
+        icon:
+    activeSidebarItemId:
+    breadcrumbs:
+      - label:
+        href:
+        current:
+    pageTitle:
+    pageSubtitle:
+    primaryAction:
+      label:
+      href:
+    secondaryActions:
+      - label:
+        href:
+    summaryStats:
+      - label:
+        value:
+        delta:
+        trend:
+    filters:
+      - type:
+        label:
+        key:
+    tableColumns:
+      - key:
+        title:
+        type:
+    rowActions:
+      - label:
+        key:
+    formSections:
+      - title:
+        fields: []
+    fields:
+      - name:
+        type:
+        label:
+        required:
+        helperText:
+    detailSections:
+      - title:
+        type:
+    emptyState:
+      title:
+      description:
+      actionLabel:
+    permissions: []
+page_frame_recipes:
+  list:
+${renderYamlList(pageFrameRecipes.list, 4)}
+  form:
+${renderYamlList(pageFrameRecipes.form, 4)}
+  detail:
+${renderYamlList(pageFrameRecipes.detail, 4)}
+  dashboard:
+${renderYamlList(pageFrameRecipes.dashboard, 4)}
+implementation_rules:
+  hard-rules:
+${renderYamlList(hardRules, 4)}
+  do-not:
+${renderYamlList(doNotRules, 4)}
+  component-choice:
+${renderYamlList(componentChoices, 4)}
+output_check:
+${renderYamlList(outputCheck, 2)}
 \`\`\`
-
-## Shell Lock
-
-Keep the layout aligned with \`${layoutPreset.id}\`:
-
-${renderMarkdownList(layoutPreset.shellRecipe)}
-
-## Page Frame Recipes
-
-- \`list\`: dark \`Sidebar\` -> workspace topbar -> intro card -> optional segmented tabs -> toolbar \`Card\` -> \`DataTable\` \`Card\`
-- \`form\`: dark \`Sidebar\` -> workspace topbar -> intro card -> optional segmented tabs -> top actions -> sectioned form \`Card\` blocks -> bottom action row
-- \`detail\`: dark \`Sidebar\` -> workspace topbar -> intro card -> optional segmented tabs -> status/actions -> summary metadata \`Card\` -> detail \`Card\` blocks -> related \`DataTable\`
-- \`dashboard\`: dark \`Sidebar\` -> workspace topbar -> intro card -> optional segmented tabs -> toolbar \`Card\` -> \`Stat\` row -> insight \`Card\` blocks and \`DataTable\`
-
-## Hard Rules
-
-- import \`${PACKAGE_NAME}/styles.css\` once at the app entry
-- import a bundled theme layer from \`${PACKAGE_NAME}/themes/*\` after the package stylesheet when the repo chooses one
-- import the project theme override file after the bundled theme layer
-- use \`applyDocumentClientTheme\` when the chosen bundled theme layer is client-theme-scoped
-- use root exports from \`${PACKAGE_NAME}\` for React components
-- use \`${PACKAGE_NAME}/core\` for theme/runtime utilities in non-React or mixed-framework setup
-- use \`${themeFile}\` as the only source of truth for colors, radius, surfaces, and shadows
-- use \`${layoutFile}\` as the source of truth for the shell layout and shared page frame
-- keep layouts and component choices aligned with the shared preset-driven UI used across projects
-- keep the host shell responsible for sidebar, topbar, remote mount, and theme mode
-- keep remotes focused on feature routes and page business content
-- read \`uiAiManifest\` before choosing components
-- read \`uiThemeLayerAssets\` before choosing a bundled theme layer
-- read \`uiThemeContract\` before changing colors, surfaces, borders, radius, or shadows
-- keep UI token-driven and theme-driven
-
-Do not:
-- import from \`MainFe\` unless the task explicitly targets a legacy screen
-- invent a second palette or one-off brand colors outside \`${themeFile}\`
-- replace the shared dark-sidebar + gradient-topbar shell with a flat blank layout unless the user explicitly requests it
-- restyle individual pages if the preset tokens can solve it globally
-- create duplicate Button/Input/Select wrappers unless a project-specific behavior is required
-- let each remote define a different shell or a different palette
-
-## Component Choice
-
-- \`Input\` for short text
-- \`Textarea\` for multiline text
-- \`Select\` for small fixed options
-- \`SearchableSelect\` for larger local option sets
-- \`Combobox\` for type-and-pick
-- \`AsyncCombobox\` for remote search
-- \`MultiSelect\` for multi-pick
-- \`Field\` only for custom controls or grouped content
-- \`DataTable\` for tabular records
-
-## Output Check
-
-Before finishing, confirm all of these are true:
-
-- The shell brief and screen brief are complete.
-- Any missing required input was explicitly asked for before coding.
-- The shell matches \`${layoutPreset.id}\` with a dark sidebar, gradient topbar, intro card, and card-based body structure.
-- The chosen components match the page kind and the brief.
-- No \`MainFe\` imports were used.
-- No hardcoded brand colors were added in page components.
-- Theme decisions live in \`${themeFile}\`, not in ad hoc JSX styling.
-- The app entry import order is package stylesheet -> bundled theme layer if present -> project theme override.
-- The shell still lives in the host app and remotes only own business screens.
-- Spacing, card structure, and actions are consistent with the shared preset.
-- The layout shell stayed stable even if the page body changed.
 `
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucasvu/scope-ui",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",