@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

package/authoring/doctypes/parse.d.mts

@@ -1,15 +1,16 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('./types').ComponentDoc} ComponentDoc */
-/** @typedef {import('./types').HookDoc} HookDoc */
-/** @typedef {import('./types').FunctionDoc} FunctionDoc */
-/** @typedef {import('./types').ReferenceDoc} ReferenceDoc */
-/** @typedef {import('./types').TemplateDoc} TemplateDoc */
-/** @typedef {import('./types').SchemaDoc} SchemaDoc */
-/** @typedef {import('./types').CommandDoc} CommandDoc */
-/** @typedef {import('./types').EnumDoc} EnumDoc */
-/** @typedef {import('./types').NamespaceDoc} NamespaceDoc */
+/** @typedef {import('./types.js').ComponentDoc} ComponentDoc */
+/** @typedef {import('./types.js').HookDoc} HookDoc */
+/** @typedef {import('./types.js').FunctionDoc} FunctionDoc */
+/** @typedef {import('./types.js').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('./types.js').TemplateDoc} TemplateDoc */
+/** @typedef {import('./types.js').SchemaDoc} SchemaDoc */
+/** @typedef {import('./types.js').CommandDoc} CommandDoc */
+/** @typedef {import('./types.js').EnumDoc} EnumDoc */
+/** @typedef {import('./types.js').NamespaceDoc} NamespaceDoc */
+/** @typedef {import('./types.js').ThemeDoc} ThemeDoc */
 /**
  * Validate an unknown loaded doc value into its typed shape, or throw.
  * Dispatches on the stamped `type`; unstamped docs fall back to
@@ -18,15 +19,16 @@
  *
  * @param {unknown} input
  * @param {string} [label]
- * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc}
+ * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc | ThemeDoc}
  */
-export function parseDoc(input: unknown, label?: string): ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc;
-export type ComponentDoc = import("./types").ComponentDoc;
-export type HookDoc = import("./types").HookDoc;
-export type FunctionDoc = import("./types").FunctionDoc;
-export type ReferenceDoc = import("./types").ReferenceDoc;
-export type TemplateDoc = import("./types").TemplateDoc;
-export type SchemaDoc = import("./types").SchemaDoc;
-export type CommandDoc = import("./types").CommandDoc;
-export type EnumDoc = import("./types").EnumDoc;
-export type NamespaceDoc = import("./types").NamespaceDoc;
+export function parseDoc(input: unknown, label?: string): ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc | ThemeDoc;
+export type ComponentDoc = import("./types.js").ComponentDoc;
+export type HookDoc = import("./types.js").HookDoc;
+export type FunctionDoc = import("./types.js").FunctionDoc;
+export type ReferenceDoc = import("./types.js").ReferenceDoc;
+export type TemplateDoc = import("./types.js").TemplateDoc;
+export type SchemaDoc = import("./types.js").SchemaDoc;
+export type CommandDoc = import("./types.js").CommandDoc;
+export type EnumDoc = import("./types.js").EnumDoc;
+export type NamespaceDoc = import("./types.js").NamespaceDoc;
+export type ThemeDoc = import("./types.js").ThemeDoc;

package/authoring/doctypes/parse.mjs

@@ -4,8 +4,8 @@
  * @file The doc load boundary. `parseDoc` validates an unknown loaded doc value
  * into its typed shape (or throws a readable error), dispatching on the stamped
  * `type` and falling back to legacy shape-sniffing for unstamped docs. Its
- * acceptance set matches the old permissive `ComponentDocSchema` exactly, so
- * every existing `.doc.*` keeps loading unchanged.
+ * acceptance set preserves the old permissive `ComponentDocSchema` while new
+ * stamped kinds, including `theme`, use their sealed parser.
  */
 
 import {parseComponent} from './component/parse.mjs';
@@ -16,17 +16,19 @@ import {parseSchema} from './schema/parse.mjs';
 import {parseCommand} from './command/parse.mjs';
 import {parseEnum} from './enum/parse.mjs';
 import {parseNamespace} from './namespace/parse.mjs';
+import {parseTheme} from './theme/parse.mjs';
 import {parseLegacyDoc} from './legacy.mjs';
 
-/** @typedef {import('./types').ComponentDoc} ComponentDoc */
-/** @typedef {import('./types').HookDoc} HookDoc */
-/** @typedef {import('./types').FunctionDoc} FunctionDoc */
-/** @typedef {import('./types').ReferenceDoc} ReferenceDoc */
-/** @typedef {import('./types').TemplateDoc} TemplateDoc */
-/** @typedef {import('./types').SchemaDoc} SchemaDoc */
-/** @typedef {import('./types').CommandDoc} CommandDoc */
-/** @typedef {import('./types').EnumDoc} EnumDoc */
-/** @typedef {import('./types').NamespaceDoc} NamespaceDoc */
+/** @typedef {import('./types.js').ComponentDoc} ComponentDoc */
+/** @typedef {import('./types.js').HookDoc} HookDoc */
+/** @typedef {import('./types.js').FunctionDoc} FunctionDoc */
+/** @typedef {import('./types.js').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('./types.js').TemplateDoc} TemplateDoc */
+/** @typedef {import('./types.js').SchemaDoc} SchemaDoc */
+/** @typedef {import('./types.js').CommandDoc} CommandDoc */
+/** @typedef {import('./types.js').EnumDoc} EnumDoc */
+/** @typedef {import('./types.js').NamespaceDoc} NamespaceDoc */
+/** @typedef {import('./types.js').ThemeDoc} ThemeDoc */
 
 /**
  * Validate an unknown loaded doc value into its typed shape, or throw.
@@ -36,7 +38,7 @@ import {parseLegacyDoc} from './legacy.mjs';
  *
  * @param {unknown} input
  * @param {string} [label]
- * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc}
+ * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc | ThemeDoc}
  */
 export function parseDoc(input, label = 'doc') {
   const type =
@@ -62,9 +64,12 @@ export function parseDoc(input, label = 'doc') {
       return parseEnum(input, label);
     case 'namespace':
       return parseNamespace(input, label);
+    case 'theme':
+      return parseTheme(input, label);
     case undefined:
-      return parseLegacyDoc(input, label);
     default:
-      throw new Error(`${label} has unsupported type ${JSON.stringify(type)}.`);
+      // 0.6.x shape-sniffed unknown stamps. Keep accepting them through the
+      // patch compatibility window; canonical writers emit a known stamp.
+      return parseLegacyDoc(input, label);
   }
 }

package/authoring/doctypes/reference/parse.d.mts

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('../types').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('../types.js').ReferenceDoc} ReferenceDoc */
 /**
  * Validate an unknown value as a stamped reference/topic doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {ReferenceDoc}
  */
 export function parseReference(input: unknown, label?: string): ReferenceDoc;
-export type ReferenceDoc = import("../types").ReferenceDoc;
+export type ReferenceDoc = import("../types.js").ReferenceDoc;

package/authoring/doctypes/reference/parse.mjs

@@ -9,7 +9,7 @@
 import {GenericDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('../types.js').ReferenceDoc} ReferenceDoc */
 
 /**
  * Validate an unknown value as a stamped reference/topic doc, or throw.

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

@@ -62,7 +62,7 @@ export const doc = {
       name: 'extends',
       type: 'string',
       description:
-        'Name of an existing topic this doc merges onto, section by section: a section whose title matches one in the base replaces it, a section the base does not have is appended. For correcting or adding to a topic rather than owning it. Exclusive with `replaces`.',
+        "Name of an existing topic this doc merges onto, section by section: a section whose title matches one in the base replaces it, a section the base does not have is appended. The topic keeps the base's title and description. For correcting or adding to a topic rather than owning it. Exclusive with `replaces`.",
       example: "'theme'",
     },
     {
@@ -93,9 +93,9 @@ export const doc = {
         },
         {
           name: 'sections[].content',
-          type: 'ReferenceContentBlock[]',
+          type: '(ReferenceContentBlock | ReferenceDocBlock)[]',
           description:
-            'Ordered content blocks. Existing prose, heading, code, table, list, and token-ref blocks remain; V1 adds workflow, collection, and reference.',
+            "Ordered content blocks: prose, heading, code, table, list, token-ref, and reference. A `reference` block (`{type: 'reference', target, projection?, presentation?}`) includes another doc from its canonical source instead of a copy: a schema, command, function, or enum doc as `astryx docs` prints it, then the command that opens it. `projection.fields` keeps only those fields of a schema; `presentation` is `full` (the default), `compact` (no code blocks), or `summary` (only the doc's title, summary, and command). Any other doc shows as a summary. Graph-only workflow and collection blocks are available through GraphContentBlock on NamespaceDoc, without widening the stable ReferenceContentBlock union. Inside text, `{@link <target>}` links another doc by identity (`[<provider>:]<kind>:<name>`): the CLI prints the command that opens it, and `astryx doctor` warns on one that names no doc.",
           required: true,
         },
         {
@@ -140,7 +140,31 @@ export const docs = {
   notes: [
     {
       type: 'prose',
-      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, a discriminated union. V1 adds only workflow, collection, and reference; choice, callout, and checklist remain invalid. The same union is reused by the `notes` field on SchemaDoc and CommandDoc.',
+      text: 'A stamped generic doc without `title`, `description` or `sections` still loads, as older codemod output does; its title falls back to `displayName` or `name`. Without a description and sections it is not a usable topic, and `astryx doctor` reports it.',
+    },
+    {
+      type: 'prose',
+      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, the stable discriminated union of prose, heading, code, table, list, and token-ref, plus the reference block (ReferenceDocBlock). A read inlines a reference block the way it inlines a token-ref, so `astryx docs`, in text and in `--json`, returns only the stable block kinds. Docs-graph-only workflow and collection blocks are exported separately as GraphContentBlock and accepted by NamespaceDoc. choice, callout, and checklist remain invalid. ReferenceContentBlock is also reused by the `notes` field on SchemaDoc and CommandDoc. Inside text, `{@link <target>}` links another doc by identity (`[<provider>:]<kind>:<name>`): the CLI prints the command that opens it, and `astryx doctor` warns on one that names no doc.',
+    },
+    {
+      type: 'prose',
+      text: "A reference block includes content, where a link only points at it: `astryx doctor integration docs` fails when its target names no doc, when `projection.fields` names a field the schema does not have, or when the doc cannot take the projection or presentation it sets, and a read marks the missing content. A target without a provider names a doc of the package that wrote it, so an integration names the CLI's docs with the CLI's provider, as in `@astryxdesign/cli:schema:integration`.",
+    },
+    {
+      type: 'code',
+      lang: 'js',
+      label: 'A section that includes two fields of the integration manifest',
+      code: `{
+  title: 'Point the manifest at your folders',
+  content: [
+    {type: 'prose', text: 'Add these fields to astryx.integration.mjs.'},
+    {
+      type: 'reference',
+      target: '@astryxdesign/cli:schema:integration',
+      projection: {fields: ['components', 'docs']},
+    },
+  ],
+}`,
     },
     {
       type: 'code',
@@ -152,10 +176,19 @@ export const docs = {
   | { type: 'code'; lang: string; code: string; label?: string }
   | { type: 'table'; headers: string[]; rows: string[][] }
   | { type: 'list'; style: 'ordered' | 'unordered' | 'do' | 'dont'; items: string[] }
-  | { type: 'token-ref'; topic: string; section: string }
+  | { type: 'token-ref'; topic: string; section: string };
+
+type ReferenceDocBlock = {
+  type: 'reference';
+  target: string;
+  projection?: { fields?: string[]; sections?: string[] };
+  presentation?: 'summary' | 'compact' | 'full';
+};
+
+type GraphContentBlock =
   | { type: 'workflow'; title?: string; steps: WorkflowStep[] }
   | { type: 'collection'; source: {slot: string}; presentation?: 'list' | 'cards' | 'compact'; whenEmpty?: 'show' | 'omit' }
-  | { type: 'reference'; target: string; projection?: {fields?: string[]; sections?: string[]} };`,
+  | ReferenceDocBlock;`,
     },
     {
       type: 'prose',

package/authoring/doctypes/reference/type.ts

@@ -4,7 +4,7 @@
  * @file Reference/topic doc types.
  */
 
-import type {AuthoredDocGraphFields} from '../base/type';
+import type {AuthoredDocGraphFields} from '../base/type.js';
 
 /** One step in a renderer-neutral workflow. */
 export interface WorkflowStep {
@@ -30,19 +30,37 @@ export interface CollectionDocBlock {
   whenEmpty?: 'show' | 'omit';
 }
 
-/** A bounded projection of one canonical doc. */
+/**
+ * A bounded projection of one canonical doc. In a namespace doc's `blocks` it
+ * is layout the docs tree renders later. In a topic section, a read includes
+ * the doc it names in place of the block: a schema, command, function, or
+ * enum doc as `astryx docs` prints it (`projection.fields` keeps only those
+ * fields of a schema), then the command that opens that doc. Any other doc
+ * shows its title and summary.
+ */
 export interface ReferenceDocBlock {
   type: 'reference';
+  /** The doc it names, by identity: `[<provider>:]<kind>:<name>`. */
   target: string;
   projection?: {
     fields?: string[];
     sections?: string[];
   };
+  /** `summary`: only the doc's title, summary, and the command that opens it.
+   *  `compact`: the included doc without its code blocks. `full`, the default:
+   *  the included doc. */
   presentation?: 'summary' | 'compact' | 'full';
 }
 
+/** Graph-only content blocks, for a namespace doc's `blocks`. These are
+ * additive and do not widen the stable {@link ReferenceContentBlock} union
+ * consumed by existing exhaustive renderers. A topic section accepts the
+ * `reference` block too, and a read inlines it as stable blocks. */
+export type GraphContentBlock =
+  WorkflowDocBlock | CollectionDocBlock | ReferenceDocBlock;
+
 /**
- * A content block within a reference doc section or namespace.
+ * A content block within a reference doc section.
  * Ordered arrays of these blocks form renderer-neutral documentation content.
  * A new semantic kind must ship with every renderer or fail visibly at a legacy
  * reader boundary until that renderer is available.
@@ -55,12 +73,12 @@ export interface ReferenceDocBlock {
  * { type: 'table', headers: ['Token', 'Value'], rows: [['--spacing-4', '16px']] }
  * { type: 'list', style: 'do', items: ['Use semantic tokens'] }
  * { type: 'token-ref', topic: 'tokens', section: 'Color Tokens' }
- * { type: 'workflow', steps: [{title: 'Validate', references: ['command:doctor']}] }
- * { type: 'collection', source: {slot: 'guides'}, presentation: 'cards' }
- * { type: 'reference', target: 'schema:integration', projection: {fields: ['docs']} }
+ * { type: 'prose', text: 'Check it with {@link command:doctor}.' }
  * ```
  */
 export type ReferenceContentBlock =
+  /** Text. `{@link [<provider>:]<kind>:<name>}` inside it links another doc
+   *  by identity; `astryx docs` prints the command that opens that doc. */
   | {type: 'prose'; text: string}
   | {type: 'heading'; level: 3 | 4 | 5 | 6; text: string}
   | {type: 'code'; lang: string; code: string; label?: string}
@@ -80,10 +98,7 @@ export type ReferenceContentBlock =
       topic: string;
       /** Section title to pull from that topic. e.g. `'Color Tokens'` */
       section: string;
-    }
-  | WorkflowDocBlock
-  | CollectionDocBlock
-  | ReferenceDocBlock;
+    };
 
 /**
  * A reference documentation file (.doc.mjs).
@@ -93,10 +108,10 @@ export type ReferenceContentBlock =
  * they aren't tied to a specific component — just drop a .doc.mjs file
  * in the docs/ directory and it shows up in `astryx docs`.
  *
- * Every reference .doc.mjs must export a single `docs` constant:
+ * Every new reference .doc.mjs default-exports a stamped object:
  *
  *   /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} *\/
- *   export const docs = { ... };
+ *   export default { type: 'generic', ... };
  */
 export interface ReferenceDoc extends AuthoredDocGraphFields {
   /** Doc-kind discriminant for the stamped default-export format
@@ -146,8 +161,10 @@ export interface ReferenceSection {
   /** Navigation category ('guide' | 'foundations'). Mirrors the parent doc's
    *  category so sections can be grouped independently in the docsite nav. */
   category?: string;
-  /** Ordered content blocks. Mix prose, code, tables, and lists freely. */
-  content: ReferenceContentBlock[];
+  /** Ordered content blocks. Mix prose, code, tables, and lists freely. A
+   *  `reference` block includes another doc from its canonical source, so a
+   *  guide never copies a schema's fields or a command's options. */
+  content: (ReferenceContentBlock | ReferenceDocBlock)[];
   /** Preview type for token tables in this section. When set, the docsite
    *  renders a visual preview column using the token's computed CSS value
    *  from the current theme. Omit for non-token sections. */

package/authoring/doctypes/schema/parse.d.mts

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('../types').SchemaDoc} SchemaDoc */
+/** @typedef {import('../types.js').SchemaDoc} SchemaDoc */
 /**
  * Validate an unknown value as a stamped schema doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {SchemaDoc}
  */
 export function parseSchema(input: unknown, label?: string): SchemaDoc;
-export type SchemaDoc = import("../types").SchemaDoc;
+export type SchemaDoc = import("../types.js").SchemaDoc;

package/authoring/doctypes/schema/parse.mjs

@@ -8,7 +8,7 @@
 import {SchemaDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').SchemaDoc} SchemaDoc */
+/** @typedef {import('../types.js').SchemaDoc} SchemaDoc */
 
 /**
  * Validate an unknown value as a stamped schema doc, or throw.

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

@@ -49,7 +49,7 @@ export const doc = {
       name: 'namespace',
       type: 'string',
       description:
-        "Docs namespace path (e.g. 'cli' | 'authoring'). Defaults are applied by the docs index; set explicitly to place the schema.",
+        "The group that reads this doc: 'authoring' for a file an author writes (a section of `astryx docs authoring`), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
     },
     {
       name: 'aliases',

package/authoring/doctypes/schema/type.ts

@@ -6,8 +6,8 @@
  * response envelope). Colocated as a `.doc.mjs` next to the schema it describes.
  */
 
-import type {AuthoredDocGraphFields} from '../base/type';
-import type {ReferenceContentBlock} from '../reference/type';
+import type {AuthoredDocGraphFields} from '../base/type.js';
+import type {ReferenceContentBlock} from '../reference/type.js';
 
 /**
  * One documented field of a schema. Object fields nest via `fields`, so a whole
@@ -47,8 +47,7 @@ export interface SchemaDoc extends AuthoredDocGraphFields {
   displayName: string;
   /** One-line summary shown in listings. */
   description: string;
-  /** Docs namespace path (e.g. 'cli' | 'authoring'). Defaults are applied by
-   *  the docs index; set explicitly to place the schema. */
+  /** The group that reads this doc: 'authoring' for a file an author writes (a section of `astryx docs authoring`), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads. */
   namespace?: string;
   /** Alternate slugs that also resolve to this doc (back-compat). */
   aliases?: string[];

package/authoring/doctypes/template/parse.d.mts

@@ -11,4 +11,97 @@
  * @returns {TemplateDoc}
  */
 export function parseTemplate(input: unknown, label?: string): TemplateDoc;
-export type TemplateDoc = import("../types").TemplateDoc;
+export type TemplateDoc = import("../types.js").TemplateDoc;
+export type PageTemplateDoc = import("./type.js").PageTemplateDoc;
+export type BlockTemplateDoc = import("./type.js").BlockTemplateDoc;
+/**
+ * Templates as they load. Integration templates already published omit
+ * `displayName` and `aspectRatio` and group themselves under their own
+ * `category`, so the loader accepts those (template discovery falls back to an
+ * aspect ratio of 1). The published types keep asking authors for all three.
+ */
+export type LoadedPageTemplateDoc = Omit<PageTemplateDoc, "displayName" | "category"> & {
+    displayName?: string;
+    category?: string;
+};
+/**
+ * Templates as they load. Integration templates already published omit
+ * `displayName` and `aspectRatio` and group themselves under their own
+ * `category`, so the loader accepts those (template discovery falls back to an
+ * aspect ratio of 1). The published types keep asking authors for all three.
+ */
+export type LoadedBlockTemplateDoc = Omit<BlockTemplateDoc, "displayName" | "aspectRatio" | "category"> & {
+    displayName?: string;
+    aspectRatio?: number;
+    category?: string;
+};
+export type _PageTemplateDocDriftLock = import("../../_shared/contract.js").Expect<import("../../_shared/contract.js").MutuallyAssignable<import("../../_shared/contract.js").NamedFields<z.infer<typeof pageTemplateSchema>>, import("../../_shared/contract.js").NamedFields<LoadedPageTemplateDoc>>>;
+export type _BlockTemplateDocDriftLock = import("../../_shared/contract.js").Expect<import("../../_shared/contract.js").MutuallyAssignable<import("../../_shared/contract.js").NamedFields<z.infer<typeof blockTemplateSchema>>, import("../../_shared/contract.js").NamedFields<LoadedBlockTemplateDoc>>>;
+import { z } from 'zod';
+declare const pageTemplateSchema: z.ZodObject<{
+    type: z.ZodLiteral<"page">;
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    componentsUsed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    preview: z.ZodOptional<z.ZodObject<{
+        image: z.ZodOptional<z.ZodString>;
+        aspectRatio: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    isReady: z.ZodOptional<z.ZodBoolean>;
+    scaffold: z.ZodOptional<z.ZodBoolean>;
+    isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
+    registry: z.ZodOptional<z.ZodObject<{
+        slug: z.ZodOptional<z.ZodString>;
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    replaces: z.ZodOptional<z.ZodString>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
+}, z.core.$strict>;
+declare const blockTemplateSchema: z.ZodObject<{
+    type: z.ZodLiteral<"block">;
+    exampleFor: z.ZodOptional<z.ZodString>;
+    alsoExampleFor: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    alsoShowcaseFor: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aspectRatio: z.ZodOptional<z.ZodNumber>;
+    scale: z.ZodOptional<z.ZodNumber>;
+    isShowcase: z.ZodOptional<z.ZodBoolean>;
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    componentsUsed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    preview: z.ZodOptional<z.ZodObject<{
+        image: z.ZodOptional<z.ZodString>;
+        aspectRatio: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    isReady: z.ZodOptional<z.ZodBoolean>;
+    scaffold: z.ZodOptional<z.ZodBoolean>;
+    isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
+    registry: z.ZodOptional<z.ZodObject<{
+        slug: z.ZodOptional<z.ZodString>;
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    replaces: z.ZodOptional<z.ZodString>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
+}, z.core.$strict>;
+export {};

package/authoring/doctypes/template/parse.mjs

@@ -12,7 +12,9 @@ import {z} from 'zod';
 import {AuthoredDocGraphFields} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').TemplateDoc} TemplateDoc */
+/** @typedef {import('../types.js').TemplateDoc} TemplateDoc */
+/** @typedef {import('./type.js').PageTemplateDoc} PageTemplateDoc */
+/** @typedef {import('./type.js').BlockTemplateDoc} BlockTemplateDoc */
 
 const previewSchema = z
   .object({
@@ -49,6 +51,10 @@ const baseTemplateFields = {
   scaffold: z.boolean().optional(),
   isHiddenFromOverview: z.boolean().optional(),
   registry: registryIdentitySchema.optional(),
+  replaces: z
+    .string()
+    .min(1, 'replaces must name a Core template id')
+    .optional(),
 };
 
 const pageTemplateSchema = z
@@ -67,6 +73,36 @@ const blockTemplateSchema = z
   })
   .strict();
 
+/**
+ * Templates as they load. Integration templates already published omit
+ * `displayName` and `aspectRatio` and group themselves under their own
+ * `category`, so the loader accepts those (template discovery falls back to an
+ * aspect ratio of 1). The published types keep asking authors for all three.
+ *
+ * @typedef {Omit<PageTemplateDoc, 'displayName' | 'category'>
+ *   & {displayName?: string, category?: string}} LoadedPageTemplateDoc
+ * @typedef {Omit<BlockTemplateDoc, 'displayName' | 'aspectRatio' | 'category'>
+ *   & {displayName?: string, aspectRatio?: number, category?: string}} LoadedBlockTemplateDoc
+ */
+
+/**
+ * @typedef {import('../../_shared/contract.js').Expect<
+ *   import('../../_shared/contract.js').MutuallyAssignable<
+ *     import('../../_shared/contract.js').NamedFields<z.infer<typeof pageTemplateSchema>>,
+ *     import('../../_shared/contract.js').NamedFields<LoadedPageTemplateDoc>
+ *   >
+ * >} _PageTemplateDocDriftLock
+ */
+
+/**
+ * @typedef {import('../../_shared/contract.js').Expect<
+ *   import('../../_shared/contract.js').MutuallyAssignable<
+ *     import('../../_shared/contract.js').NamedFields<z.infer<typeof blockTemplateSchema>>,
+ *     import('../../_shared/contract.js').NamedFields<LoadedBlockTemplateDoc>
+ *   >
+ * >} _BlockTemplateDocDriftLock
+ */
+
 const templateEnvelopeSchema = z
   .discriminatedUnion('type', [pageTemplateSchema, blockTemplateSchema])
   .superRefine((template, context) => {

package/authoring/doctypes/template/parse.test.mjs

@@ -22,6 +22,24 @@ function reason(value, label = 'template') {
 }
 
 describe('parseTemplate (load boundary)', () => {
+  it('accepts replaces on page and block templates', () => {
+    for (const type of ['page', 'block']) {
+      const parsed = parseTemplate({
+        type,
+        name: 'Acme shell',
+        description: 'Replaces a Core template.',
+        replaces: 'shell-side-nav',
+      });
+      expect(parsed.replaces).toBe('shell-side-nav');
+    }
+  });
+
+  it('rejects an empty replaces', () => {
+    expect(reason({type: 'page', name: 'Acme shell', replaces: ''})).toMatch(
+      /replaces must name a Core template id/,
+    );
+  });
+
   it('accepts a stamped page template', () => {
     const parsed = parseTemplate({
       type: 'page',

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

@@ -18,7 +18,7 @@ export const doc = {
     "(type: 'page') for full page templates and BlockTemplateDoc (type: 'block') for " +
     'editable compositions. A block can stand alone or use `exampleFor` to attach ' +
     'to one component; `isShowcase` requires that component ownership.',
-  appliesTo: '<Name>.template.mjs',
+  appliesTo: '<Name>.doc.mjs',
   fields: [
     {
       name: 'type',
@@ -52,6 +52,12 @@ export const doc = {
       type: 'string',
       description: 'One-sentence description of what the template provides.',
     },
+    {
+      name: 'replaces',
+      type: 'string',
+      description:
+        "Integration templates only: the exact id of the Core template this one replaces for unqualified lookup. Find it with `astryx --json template --list --package @astryxdesign/core`; the Core original stays selectable with `--package @astryxdesign/core`. A page replaces only a Core page and a block only a Core block. Needs @astryxdesign/cli 0.7.0 or later: earlier CLIs reject the field and withhold the package's templates and doc topics.",
+    },
     {
       name: 'isReady',
       type: 'boolean',
@@ -123,7 +129,7 @@ export const doc = {
     {
       label: 'Page template',
       code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export const doc = {
+export default {
   type: 'page',
   name: 'Dashboard',
   displayName: 'Dashboard',
@@ -135,7 +141,7 @@ export const doc = {
     {
       label: 'Block template (component example)',
       code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export const doc = {
+export default {
   type: 'block',
   name: 'ButtonGroupExample',
   displayName: 'Button Group Example',
@@ -148,6 +154,10 @@ export const doc = {
     },
   ],
   notes: [
+    {
+      type: 'prose',
+      text: 'When it loads, a template may leave out `displayName` and `aspectRatio` and use its own `category`, as integration templates already published do; a block with no `aspectRatio` previews at 1. Write to the type anyway; it is the contract.',
+    },
     {
       type: 'prose',
       text: "TemplateDoc is a discriminated union keyed by `type`. Set `type: 'page'` for a full page template. Set `type: 'block'` for an editable composition; add `exampleFor` only when one component owns the example.",

package/authoring/doctypes/template/type.ts

@@ -4,7 +4,10 @@
  * @file Template doc types.
  */
 
-import type {AuthoredDocGraphFields, RegistryDocIdentity} from '../base/type';
+import type {
+  AuthoredDocGraphFields,
+  RegistryDocIdentity,
+} from '../base/type.js';
 
 export interface BaseTemplateDoc extends AuthoredDocGraphFields {
   /** Identifier name for the template. For block templates this matches
@@ -25,6 +28,14 @@ export interface BaseTemplateDoc extends AuthoredDocGraphFields {
 
   /** Optional stable slug override and prior aliases for registry output. */
   registry?: RegistryDocIdentity;
+
+  /** Integration templates only: the exact id of the Core template this one
+   *  replaces for unqualified lookup (find it with
+   *  `astryx --json template --list --package @astryxdesign/core`). The Core
+   *  original stays selectable with `--package @astryxdesign/core`. Needs
+   *  `@astryxdesign/cli` 0.7.0 or later: earlier CLIs reject the field and
+   *  withhold the package's templates and doc topics. */
+  replaces?: string;
   /** Whether this template is ready for use. Templates with
    *  isReady: false show as "(WIP)" in the gallery and CLI. */
   isReady?: boolean;