@astryxdesign/cli 0.3.0-canary.d1b7d82 → 0.3.0-canary.dccdabe

package/assets/templates/pages/shell-top-nav/page.tsx

@@ -158,7 +158,7 @@ export default function ShellTopNav() {
                   <MegaFeatured
                     title="The Autumn Edit"
                     description="Layering staples in warm, earthy tones."
-                    image="https://lookaside.facebook.com/assets/astryx/texture-beige-horizontal-1.png"
+                    image="/template-assets/texture-beige-horizontal-1.png"
                     imageAlt="Autumn collection lookbook"
                     linkLabel="Shop the edit"
                     linkHref="#autumn-edit"
@@ -172,7 +172,7 @@ export default function ShellTopNav() {
                   <MegaFeatured
                     title="Meet Studio Mara"
                     description="Modern tailoring, made to last."
-                    image="https://lookaside.facebook.com/assets/astryx/texture-beige-horizontal-2.png"
+                    image="/template-assets/texture-beige-horizontal-2.png"
                     imageAlt="Studio Mara lookbook"
                     linkLabel="Discover the label"
                     linkHref="#studio-mara"

package/assets/templates/pages/side-gallery/page.tsx

@@ -25,39 +25,39 @@ const imageClip = {
 
 const IMAGES = [
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-lifestyle-vertical-3.png',
+    src: '/template-assets/colorful-lifestyle-vertical-3.png',
     alt: 'Colorful lifestyle scene',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-lifestyle-horizontal-1.png',
+    src: '/template-assets/colorful-lifestyle-horizontal-1.png',
     alt: 'Colorful lifestyle horizontal',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-lifestyle-vertical-1.png',
+    src: '/template-assets/colorful-lifestyle-vertical-1.png',
     alt: 'Colorful lifestyle vertical',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-home-vertical-2.png',
+    src: '/template-assets/colorful-home-vertical-2.png',
     alt: 'Colorful home interior',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-home-vertical-3.png',
+    src: '/template-assets/colorful-home-vertical-3.png',
     alt: 'Colorful home scene',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-home-vertical-1.png',
+    src: '/template-assets/colorful-home-vertical-1.png',
     alt: 'Colorful home vertical',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-lifestyle-horizontal-2.png',
+    src: '/template-assets/colorful-lifestyle-horizontal-2.png',
     alt: 'Colorful lifestyle wide',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-lifestyle-vertical-2.png',
+    src: '/template-assets/colorful-lifestyle-vertical-2.png',
     alt: 'Colorful lifestyle detail',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-lifestyle-vertical-4.png',
+    src: '/template-assets/colorful-lifestyle-vertical-4.png',
     alt: 'Colorful lifestyle portrait',
   },
 ];

package/assets/templates/pages/table-page-chart/page.tsx

@@ -46,37 +46,37 @@ const PRODUCTS = [
   {
     name: 'Ceremonial Matcha Latte',
     category: 'Matcha' as ProductCategory,
-    image: 'https://lookaside.facebook.com/assets/astryx/matcha-product-1.png',
+    image: '/template-assets/matcha-product-1.png',
     price: 6,
   },
   {
     name: 'Oat Milk Cappuccino',
     category: 'Coffee' as ProductCategory,
-    image: 'https://lookaside.facebook.com/assets/astryx/matcha-product-2.png',
+    image: '/template-assets/matcha-product-2.png',
     price: 5,
   },
   {
     name: 'Jasmine Green Tea',
     category: 'Tea' as ProductCategory,
-    image: 'https://lookaside.facebook.com/assets/astryx/matcha-product-3.png',
+    image: '/template-assets/matcha-product-3.png',
     price: 4,
   },
   {
     name: 'Mango Matcha Smoothie',
     category: 'Smoothie' as ProductCategory,
-    image: 'https://lookaside.facebook.com/assets/astryx/matcha-product-4.png',
+    image: '/template-assets/matcha-product-4.png',
     price: 8,
   },
   {
     name: 'Hojicha Latte',
     category: 'Specialty' as ProductCategory,
-    image: 'https://lookaside.facebook.com/assets/astryx/matcha-product-5.png',
+    image: '/template-assets/matcha-product-5.png',
     price: 7,
   },
   {
     name: 'Iced Yuzu Matcha',
     category: 'Matcha' as ProductCategory,
-    image: 'https://lookaside.facebook.com/assets/astryx/matcha-product-6.png',
+    image: '/template-assets/matcha-product-6.png',
     price: 7,
   },
 ];

package/assets/templates/pages/theme-showcase/page.tsx

@@ -283,13 +283,13 @@ const DEFAULT_PRODUCTS: ProductSpec[] = [
 // Neutral product photos, served from the shared astryx asset CDN so the
 // scaffolded template renders real imagery without needing local public assets.
 const DEFAULT_IMAGES: Record<string, string> = {
-  watch: 'https://lookaside.facebook.com/assets/astryx/Neutral-Watch.png',
+  watch: '/template-assets/Neutral-Watch.png',
   headphones:
-    'https://lookaside.facebook.com/assets/astryx/Neutral-Headphones.png',
-  backpack: 'https://lookaside.facebook.com/assets/astryx/Neutral-Backpack.png',
-  wallet: 'https://lookaside.facebook.com/assets/astryx/Neutral-Wallet.png',
-  tumbler: 'https://lookaside.facebook.com/assets/astryx/Neutral-Tumbler.png',
-  throw_: 'https://lookaside.facebook.com/assets/astryx/Neutral-Blanket.png',
+    '/template-assets/Neutral-Headphones.png',
+  backpack: '/template-assets/Neutral-Backpack.png',
+  wallet: '/template-assets/Neutral-Wallet.png',
+  tumbler: '/template-assets/Neutral-Tumbler.png',
+  throw_: '/template-assets/Neutral-Blanket.png',
 };
 
 export interface ThemeShowcaseProps {

package/authoring/codemod/codemod.doc.mjs

@@ -42,7 +42,7 @@ export const doc = {
       name: 'fileExtensions',
       type: 'string[]',
       description:
-        'File extensions this codemod applies to. Code codemods only — a ' +
+        'File extensions this codemod applies to. Code codemods only; a ' +
         'config codemod always targets astryx.config.*.',
       example: "['.tsx', '.ts']",
     },
@@ -140,7 +140,7 @@ export const doc = {
       type: 'prose',
       text:
         "The config-codemod variant (type: 'config') carries the same fields " +
-        'as a code codemod except fileExtensions — it always targets the ' +
+        'as a code codemod except fileExtensions: it always targets the ' +
         'astryx.config.* file rather than a set of source files.',
     },
     {

package/authoring/config/config.doc.mjs

@@ -46,7 +46,7 @@ export const doc = {
     {
       name: 'experimental',
       type: '{ xle?: { components?: Record<string, XleComponent> } }',
-      description: 'Unstable features — may change without a breaking bump.',
+      description: 'Unstable features; may change without a breaking bump.',
       fields: [
         {
           name: 'experimental.xle.components',

package/authoring/doctypes/base/type.ts

@@ -270,6 +270,12 @@ export interface ComponentThemingDerivedVar {
   /** Named expansion strategy instead of specific vars.
    *  `'container'` — expands padding to 7 container layout tokens. */
   expand?: 'container';
+  /** Emit only the internal `vars`, dropping the source property from the
+   *  generated rule. Use when the class-carrying element must not receive the
+   *  standard property itself — the value reaches a child through the var
+   *  (e.g. TextArea's flush wrapper drives the inner textarea's inline
+   *  padding). Without this, the property is emitted alongside the var. */
+  replaces?: boolean;
 }
 
 /**

package/authoring/doctypes/command/command.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   displayName: 'CommandDoc',
   namespace: 'authoring',
   description:
-    'The doc-type for a CLI command — the terminal binding of an operation. A command ' +
+    'The doc-type for a CLI command: the terminal binding of an operation. A command ' +
     'is not its own behavior; it is a FunctionDoc exposed on the CLI, referenced via `fn`, ' +
     'carrying only CLI-surface facts (args, flags, subcommands, examples, exit codes). ' +
     'A `defineCommand` converter turns it into Commander config + `--help`.',
@@ -231,7 +231,7 @@ export const doc = {
   notes: [
     {
       type: 'prose',
-      text: 'A command carries only CLI-surface facts. Behavior, parameters, returns, and thrown errors live in the FunctionDoc it points at via `fn` — the function does not know it has a CLI.',
+      text: 'A command carries only CLI-surface facts. Behavior, parameters, returns, and thrown errors live in the FunctionDoc it points at via `fn`; the function does not know it has a CLI.',
     },
     {
       type: 'prose',

package/authoring/doctypes/component/component.doc.mjs

@@ -50,7 +50,7 @@ export const doc = {
       name: 'hiddenComponents',
       type: 'string[]',
       description:
-        'Sub-component names to hide from human-facing UI (CLI listings, docs catalogs). They stay public and importable — agents and tooling can still discover them via source.',
+        'Sub-component names to hide from human-facing UI (CLI listings, docs catalogs). They stay public and importable; agents and tooling can still discover them via source.',
     },
     {
       name: 'hidden',
@@ -104,7 +104,7 @@ export const doc = {
           name: 'theming.derived',
           type: 'ComponentThemingDerivedVar[]',
           description:
-            'Maps standard CSS properties to internal vars for theme-pipeline expansion. Ordered by priority — earlier entries emit first.',
+            'Maps standard CSS properties to internal vars for theme-pipeline expansion. Ordered by priority: earlier entries emit first.',
         },
       ],
     },
@@ -170,7 +170,7 @@ export const doc = {
       name: 'description',
       type: 'string',
       description:
-        "SubComponentDoc variant (required there): one-sentence description of the sub-component's role within the parent composition. Single/Multi docs have no top-level description — they derive their summary from `usage`.",
+        "SubComponentDoc variant (required there): one-sentence description of the sub-component's role within the parent composition. Single/Multi docs have no top-level description; they derive their summary from `usage`.",
     },
   ],
   examples: [
@@ -187,7 +187,7 @@ export const docs = {
       'A Switch toggles a single setting on or off. Use it for instant, binary preferences that apply immediately without a submit step.',
     bestPractices: [
       {guidance: true, description: 'Apply the change immediately when toggled.'},
-      {guidance: false, description: 'Use a Switch for actions that need confirmation — prefer a Checkbox in a form.'},
+      {guidance: false, description: 'Use a Switch for actions that need confirmation; prefer a Checkbox in a form.'},
     ],
   },
   props: [
@@ -226,9 +226,9 @@ export const docs = {
       type: 'list',
       style: 'unordered',
       items: [
-        'SingleComponentDoc — one primary component; put props directly on the doc via `props`. Use for Switch, Badge, Spinner, TextInput.',
-        'MultiComponentDoc — a directory exporting several components/hooks; list them in `components` (inline ComponentEntry or name-only ComponentRef). Use for Table, Dialog, TabList.',
-        'SubComponentDoc — a single sub-component in its own {Name}.doc.mjs inside the parent directory; set `subComponentOf` to the parent name. It inherits family fields and may omit `usage`.',
+        'SingleComponentDoc: one primary component; put props directly on the doc via `props`. Use for Switch, Badge, Spinner, TextInput.',
+        'MultiComponentDoc: a directory exporting several components/hooks; list them in `components` (inline ComponentEntry or name-only ComponentRef). Use for Table, Dialog, TabList.',
+        'SubComponentDoc: a single sub-component in its own {Name}.doc.mjs inside the parent directory; set `subComponentOf` to the parent name. It inherits family fields and may omit `usage`.',
       ],
     },
     {

package/authoring/doctypes/enum/enum.doc.mjs

@@ -14,7 +14,7 @@ export const doc = {
   displayName: 'EnumDoc',
   namespace: 'authoring',
   description:
-    'The doc-type for a closed vocabulary — a fixed set of literal values such as ' +
+    'The doc-type for a closed vocabulary: a fixed set of literal values such as ' +
     'error codes or response-type discriminants. Colocated as a `.doc.mjs` next to ' +
     'the source of truth it documents.',
   appliesTo: '<enum>.doc.mjs',
@@ -59,7 +59,7 @@ export const doc = {
     {
       name: 'members',
       type: 'EnumMemberDoc[]',
-      description: 'The enumerated members — one entry per literal value.',
+      description: 'The enumerated members: one entry per literal value.',
       required: true,
       fields: [
         {

package/authoring/doctypes/function/function.doc.mjs

@@ -41,7 +41,7 @@ export const doc = {
       name: 'kind',
       type: "'hook' | 'api'",
       description:
-        'Which flavor — drives docsite sectioning; inferred from importPath if omitted.',
+        'Which flavor; drives docsite sectioning; inferred from importPath if omitted.',
     },
     {
       name: 'summary',
@@ -127,7 +127,7 @@ export const doc = {
         {
           name: 'returns[].name',
           type: 'string',
-          description: 'Field name (hooks) — omit for API envelope entries.',
+          description: 'Field name (hooks); omit for API envelope entries.',
         },
         {
           name: 'returns[].type',
@@ -191,7 +191,7 @@ export const doc = {
       name: 'usage',
       type: 'UsageDoc',
       description:
-        'Usage documentation (hooks) — description, best practices, anatomy. Same shape as HookDoc.usage.',
+        'Usage documentation (hooks): description, best practices, anatomy. Same shape as HookDoc.usage.',
     },
     {
       name: 'command',

package/authoring/doctypes/hook/hook.doc.mjs

@@ -43,7 +43,7 @@ export const doc = {
       name: 'group',
       type: 'string',
       description:
-        'Optional group for sidebar/docs organization — same as ComponentDoc.group.',
+        'Optional group for sidebar/docs organization; same as ComponentDoc.group.',
     },
     {
       name: 'keywords',
@@ -117,7 +117,7 @@ export const doc = {
     {
       name: 'usage',
       type: 'UsageDoc',
-      description: 'Usage documentation — description and best practices.',
+      description: 'Usage documentation: description and best practices.',
       required: true,
       fields: [
         {
@@ -190,7 +190,7 @@ export const docs = {
   notes: [
     {
       type: 'prose',
-      text: "A hook's discriminant is `type: 'function'` — HookDoc and FunctionDoc share the generalized function kind. HookDoc is the hook-flavored view: named `returns` fields and a required `usage` block.",
+      text: "A hook's discriminant is `type: 'function'`: HookDoc and FunctionDoc share the generalized function kind. HookDoc is the hook-flavored view: named `returns` fields and a required `usage` block.",
     },
     {
       type: 'prose',

package/authoring/doctypes/reference/reference.doc.mjs

@@ -14,7 +14,7 @@ export const doc = {
   displayName: 'ReferenceDoc',
   namespace: 'authoring',
   description:
-    'The doc-type for a reference/topic doc — tokens, principles, theming, patterns, ' +
+    'The doc-type for a reference/topic doc: tokens, principles, theming, patterns, ' +
     'accessibility, migration guides. Unlike ComponentDoc it is not tied to a component: ' +
     'drop a `.doc.mjs` in the docs directory and it shows up in `astryx docs`. Content is ' +
     'built from ordered sections of mixed content blocks.',
@@ -120,7 +120,7 @@ export const docs = {
   notes: [
     {
       type: 'prose',
-      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock — a discriminated union. New block types can be added without breaking existing docs. The same union is reused by the `notes` field on SchemaDoc and CommandDoc.',
+      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, a discriminated union. New block types can be added without breaking existing docs. The same union is reused by the `notes` field on SchemaDoc and CommandDoc.',
     },
     {
       type: 'code',
@@ -140,7 +140,7 @@ export const docs = {
     },
     {
       type: 'prose',
-      text: "A section may set `previewType` to render a visual preview column for token tables — one of 'swatch' | 'shadow-box' | 'radius-box' | 'spacing-bar' | 'size-bar' | 'border-line' | 'duration-bar' | 'easing-curve' | 'font-sample'.",
+      text: "A section may set `previewType` to render a visual preview column for token tables: one of 'swatch' | 'shadow-box' | 'radius-box' | 'spacing-bar' | 'size-bar' | 'border-line' | 'duration-bar' | 'easing-curve' | 'font-sample'.",
     },
   ],
 };

package/authoring/doctypes/schema/schema.doc.mjs

@@ -190,7 +190,7 @@ export const doc = {
       type: 'list',
       style: 'dont',
       items: [
-        'Set `required: false` for optional fields — omit `required` entirely instead.',
+        'Set `required: false` for optional fields; omit `required` entirely instead.',
       ],
     },
   ],

package/authoring/doctypes/template/template.doc.mjs

@@ -150,13 +150,13 @@ export const doc = {
       type: 'list',
       style: 'unordered',
       items: [
-        "PageTemplateDoc (type: 'page') — a full page template; `name` doubles as its display value.",
-        "BlockTemplateDoc (type: 'block') — an example of a component; requires `exampleFor` and `aspectRatio`.",
+        "PageTemplateDoc (type: 'page'): a full page template; `name` doubles as its display value.",
+        "BlockTemplateDoc (type: 'block'): an example of a component; requires `exampleFor` and `aspectRatio`.",
       ],
     },
     {
       type: 'prose',
-      text: "`category` uses the shared TemplateCategory taxonomy: 'Group - Variant' strings (e.g. 'Table - Bulk Actions'). Not every value maps to an existing template — unused values are reserved so authors get autocomplete for the full taxonomy.",
+      text: "`category` uses the shared TemplateCategory taxonomy: 'Group - Variant' strings (e.g. 'Table - Bulk Actions'). Not every value maps to an existing template; unused values are reserved so authors get autocomplete for the full taxonomy.",
     },
   ],
 };

package/clients/cli/commands/build.doc.mjs

@@ -17,7 +17,7 @@ export const doc = {
     'Build a page: composition kit for an idea, or the workflow playbook (no args)',
   description:
     'The assemble-a-page entry point. With no query it returns the how-to-build-a-page ' +
-    'playbook; with a query it groups the unified search hits into a composition kit — ' +
+    'playbook; with a query it groups the unified search hits into a composition kit: ' +
     'the closest templates, drop-in blocks, and idea-specific components and hooks.',
   fn: 'build',
   args: [{name: 'query', param: 'query', required: false}],

package/clients/cli/commands/component.doc.mjs

@@ -69,7 +69,7 @@ export const doc = {
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'unknown component, category, or package — or @astryxdesign/core cannot be resolved',
+      when: 'unknown component, category, or package, or @astryxdesign/core cannot be resolved',
     },
   ],
   related: ['search', 'hook', 'docs', 'template', 'swizzle'],

package/clients/cli/commands/doctor.doc.mjs

@@ -15,8 +15,8 @@ export const doc = {
   namespace: 'cli',
   summary: 'Diagnose your XDS setup and report problems with fixes',
   description:
-    'Runs read-only diagnostics — Node version, @astryxdesign/core install and version ' +
-    'alignment, installed themes, config validity, agent docs, and the package manager — ' +
+    'Runs read-only diagnostics: Node version, @astryxdesign/core install and version ' +
+    'alignment, installed themes, config validity, agent docs, and the package manager, ' +
     'and reports pass/warn/fail with an actionable fix for each problem. Safe as a CI gate.',
   fn: 'doctor',
   examples: [

package/clients/cli/commands/layout-expand.doc.mjs

@@ -17,7 +17,7 @@ export const doc = {
   summary: 'Expand a layout expression into validated XDS TSX',
   description:
     'Parses and validates a compressed XLE/XLO expression, then expands it into ' +
-    'ready-to-use XDS TSX — routing children into slots, scaffolding typed useState for ' +
+    'ready-to-use XDS TSX, routing children into slots, scaffolding typed useState for ' +
     'interactive controls, and splicing referenced blocks. Writes to a path, or returns the code.',
   fn: 'layoutExpand',
   args: [

package/clients/cli/commands/layout.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   summary: 'Generate XDS layouts from compressed expressions (XLE/XLO)',
   description:
     'The layout command group. Running astryx layout with no subcommand prints the ' +
-    'subcommand list; the work happens in the subcommands — expand an expression into ' +
+    'subcommand list; the work happens in the subcommands: expand an expression into ' +
     'TSX (expand), validate one (check), or print the grammar cheatsheet (grammar).',
   subcommands: ['expand', 'check', 'grammar'],
   examples: [

package/clients/cli/commands/manifest.doc.mjs

@@ -3,7 +3,7 @@
 /**
  * @file CommandDoc for `astryx manifest`. A CLI-only capability manifest with no
  * wrapped API function (so no `fn`); it emits the full command surface — args,
- * flags, subcommands, and JSON response types — as a single typed envelope.
+ * flags, subcommands, and JSON response types, as a single typed envelope.
  * @position packages/cli/clients/cli/commands — command documentation
  */
 
@@ -15,8 +15,8 @@ export const doc = {
   namespace: 'cli',
   summary: 'Print the full CLI capability manifest (use with --json).',
   description:
-    'Emits the complete CLI surface — every command with its arguments, options, ' +
-    'subcommands, and JSON response types — as a single typed envelope for agents and ' +
+    'Emits the complete CLI surface: every command with its arguments, options, ' +
+    'subcommands, and JSON response types, as a single typed envelope for agents and ' +
     'tooling to introspect. Intended to be run with --json.',
   examples: [
     {label: 'Full manifest', cli: 'astryx manifest --json'},

package/clients/cli/commands/search.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   namespace: 'cli',
   summary: 'Search components, hooks, docs, and templates in one ranked list',
   description:
-    'Terminal front-end to search() — prints one ranked, greppable list across ' +
+    'Terminal front-end to search(): prints one ranked, greppable list across ' +
     'every content domain, each row carrying a follow-up command to act on it.',
   fn: 'search',
   args: [{name: 'query', param: 'query', required: true}],

package/clients/cli/commands/theme-add.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   namespace: 'cli',
   summary: 'Scaffold a theme into your project as editable source',
   description:
-    "Copies a bundled theme's source into your project so you own it — no theme package " +
+    "Copies a bundled theme's source into your project so you own it, no theme package " +
     'needed. Writes are staged then renamed, rolling back on failure. Running it with no ' +
     'slug, or with --list, lists the bundled themes instead.',
   fn: 'themeAdd',

package/clients/cli/commands/theme-build.doc.mjs

@@ -17,7 +17,7 @@ export const doc = {
   summary: 'Compile a defineTheme file to CSS + JS',
   description:
     'Compiles a file that calls defineTheme() into a scoped CSS file, a JS module, and ' +
-    'type declarations — the exact CSS the <Theme> runtime emits. With --check it writes ' +
+    'type declarations: the exact CSS the <Theme> runtime emits. With --check it writes ' +
     'nothing and instead reports whether the committed outputs have drifted from source.',
   fn: 'themeBuild',
   args: [{name: 'file', param: 'file', required: true}],

package/clients/cli/commands/theme-list.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   namespace: 'cli',
   summary: 'List themes available to add',
   description:
-    'Lists the themes bundled with this CLI build — the ones theme add can scaffold — ' +
+    'Lists the themes bundled with this CLI build (the ones theme add can scaffold), ' +
     'each with its slug, display name, description, and maintained flag.',
   fn: 'themeList',
   examples: [{label: 'List bundled themes', cli: 'astryx theme list --json'}],

package/clients/cli/commands/theme.doc.mjs

@@ -13,10 +13,10 @@ export const doc = {
   name: 'theme',
   displayName: 'astryx theme',
   namespace: 'cli',
-  summary: 'Theme tools — build, export, and manage themes',
+  summary: 'Theme tools: build, export, and manage themes',
   description:
     'The theme command group. Running astryx theme with no subcommand prints the ' +
-    'subcommand list; the work happens in the subcommands — compile a theme (build), ' +
+    'subcommand list; the work happens in the subcommands: compile a theme (build), ' +
     'scaffold one into your project (add), or list the bundled themes (list).',
   subcommands: ['build', 'add', 'list'],
   examples: [

package/clients/cli/commands/validate-integration.doc.mjs

@@ -16,8 +16,8 @@ export const doc = {
   namespace: 'cli',
   summary: 'Validate an Astryx integration package (manifest + contributions)',
   description:
-    'Validates ONE integration at a time — the local package rooted at cwd, or an ' +
-    'installed package resolved by name — schema-checking its manifest, verifying each ' +
+    'Validates ONE integration at a time: the local package rooted at cwd, or an ' +
+    'installed package resolved by name, schema-checking its manifest, verifying each ' +
     'declared contribution root, and reporting every finding. Safe as a CI gate.',
   fn: 'validateIntegration',
   args: [{name: 'package', param: 'pkg', required: false}],

package/foundation/agent-docs/agent-docs.mjs

@@ -341,10 +341,9 @@ export function generateCompressedIndex(version, {coreDir, invocation = getCliIn
 
   // Rules — the top error-preventers.
   lines.push('RULES:');
-  lines.push('- No <div> — components do all layout/spacing. Full page → AppShell; sidebar nav → SideNav.');
-  lines.push('- Frame first: pick the shell (AppShell / Layout+LayoutPanel) and budget regions in px BEFORE writing content (`astryx docs layout`).');
-  lines.push('- Dense data = rows (Table, List/Item) edge-to-edge — never Card-wrapped list items. Card = dashboard widgets, galleries, settings groups only.');
-  lines.push('- Status → StatusDot/Token; Badge only for counts and enumerated states, never decoration.');
+  lines.push('- No <div> — components do all layout/spacing, page frame included.');
+  lines.push('- Frame first: read `astryx docs layout` before writing any page or screen — page frame, region widths, breakpoint behavior.');
+  lines.push('- Dense data = rows (Table, List/Item), never Card-wrapped list items; Card is for standalone widgets. Status = StatusDot/Token; Badge = counts only.');
   // Styling guidance tailored to the project's configured system — never
   // recommend a path that isn't compiled here (xstyle needs the StyleX compiler;
   // utilities need Tailwind). Tokens are always the source of truth.

package/foundation/agent-docs/agent-docs.test.mjs

@@ -46,6 +46,14 @@ describe('generateCompressedIndex', () => {
     expect(result).toMatch(/never override --color-/);
   });
 
+  it('sends frame choice to the layout doc rather than naming a shell', () => {
+    const result = generateCompressedIndex('1.0.0');
+    const frameRule = result.split('\n').find(l => l.includes('Frame first'));
+    expect(frameRule).toContain('astryx docs layout');
+    expect(result).not.toMatch(/AppShell/);
+    expect(frameRule).not.toMatch(/https?:/);
+  });
+
   it('includes the post-generation self-check rule', () => {
     const result = generateCompressedIndex('1.0.0');
     expect(result).toContain('SELF-CHECK before you finish');

package/foundation/discovery/template-adapter.mjs

@@ -153,14 +153,18 @@ const PLACEHOLDER_IMAGE =
   'data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20400%20300%22%20preserveAspectRatio%3D%22xMidYMid%20slice%22%3E%3Crect%20width%3D%22400%22%20height%3D%22300%22%20fill%3D%22%23f5f6f8%22%2F%3E%3Cg%20transform%3D%22translate%28200%20150%29%22%20fill%3D%22none%22%20stroke%3D%22%23c2cad6%22%20stroke-width%3D%225%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%3E%3Crect%20x%3D%22-44%22%20y%3D%22-44%22%20width%3D%2288%22%20height%3D%2288%22%20rx%3D%2216%22%2F%3E%3Ccircle%20cx%3D%2218%22%20cy%3D%22-18%22%20r%3D%222.5%22%20fill%3D%22%23c2cad6%22%20stroke%3D%22none%22%2F%3E%3Cpath%20d%3D%22M-34%2030%20L-8%200%20L10%2018%20L20%208%20L34%2024%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E';
 
 /**
- * Demo-image sources to strip from scaffolded projects — Meta's lookaside CDN
- * (a Meta-only network dependency). Genuine third-party URLs (e.g. brand logos
- * from paypalobjects.com) are intentionally left untouched.
+ * Demo-image sources to strip from scaffolded projects. Template demo imagery
+ * is self-hosted under the docsite's `/template-assets/*` dir (committed there,
+ * mirrored into the sandbox preview by scripts/sync-templates.js). Those paths
+ * only resolve inside the Astryx docsite/sandbox, so on scaffold they're
+ * replaced with a self-contained placeholder — a scaffolded project has no
+ * `/template-assets/` dir and would otherwise 404. Genuine third-party URLs
+ * (e.g. brand logos from paypalobjects.com) are intentionally left untouched.
  *
  * @type {RegExp[]}
  */
 const DEMO_IMAGE_PATTERNS = [
-  /https?:\/\/(?:[\w-]+\.)*lookaside\.facebook\.com\/[^\s'"`)]+/g,
+  /\/template-assets\/[\w-]+\.\w+/g,
 ];
 
 /**