@yahoo/uds-create-config 2.45.0 → 3.0.1

package/dist/entities/system/Composite.d.ts

@@ -0,0 +1,12 @@
+import { SubEntityClass } from "../../framework/defineSubEntity.js";
+import { EntityClass } from "../../framework/defineEntity.js";
+import { StyleValue } from "./style-bag.js";
+import { z } from "zod";
+
+//#region src/entities/system/Composite.d.ts
+/** A composite variant (`overlays/elevation/1`) — the style-prop bag it applies. */
+declare const Composite: EntityClass<z.ZodObject<{
+  styles: SubEntityClass<z.ZodType<StyleValue, unknown, z.core.$ZodTypeInternals<StyleValue, unknown>>>;
+}, z.core.$strip>, z.ZodObject<Record<never, never>, z.core.$strip>, "composite", Record<never, never>, Record<never, never>, false>;
+//#endregion
+export { Composite };

package/dist/entities/system/Composite.js

@@ -0,0 +1,26 @@
+import { defineEntity } from "../../framework/defineEntity.js";
+import { Style, bagNameEdges, bagRewriteName, collectBag } from "./style-bag.js";
+import { z } from "zod";
+//#region src/entities/system/Composite.ts
+/** A composite's one bag. Same shape as a component's, so the same hooks read it. */
+const compositeBags = (data) => {
+	const body = data;
+	const out = [];
+	collectBag(body?.styles, (next) => {
+		if (body) body.styles = next;
+	}, out);
+	return out;
+};
+/** A composite variant (`overlays/elevation/1`) — the style-prop bag it applies. */
+const Composite = defineEntity({
+	kind: "composite",
+	label: "Composite style",
+	labelPlural: "Composite styles",
+	fields: z.object({ styles: Style }),
+	subEntities: { styles: Style },
+	nameEdges: bagNameEdges(compositeBags),
+	styleBags: compositeBags,
+	rewriteName: bagRewriteName(compositeBags)
+});
+//#endregion
+export { Composite };

package/dist/entities/system/Device.d.ts

@@ -0,0 +1,11 @@
+import { EntityClass } from "../../framework/defineEntity.js";
+import { z } from "zod";
+
+//#region src/entities/system/Device.d.ts
+declare const Device: EntityClass<z.ZodObject<{
+  width: z.ZodNumber;
+  height: z.ZodNumber;
+  name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<Record<never, never>, z.core.$strip>, "device", Record<never, never>, Record<never, never>, false>;
+//#endregion
+export { Device };

package/dist/entities/system/Device.js

@@ -0,0 +1,18 @@
+import { defineEntity } from "../../framework/defineEntity.js";
+import { z } from "zod";
+//#region src/entities/system/Device.ts
+/**
+* `Device` — a named viewport size (mobile / tablet / desktop / …). A SYSTEM entity, so devices
+* are configurable design-system DATA, not a hardcoded constant. A design-file node's `size` can
+* be `{ type: 'device', ref: Device.ref('mobile') }` to be powered by one of these.
+*/
+const Device = defineEntity({
+	kind: "device",
+	fields: z.object({
+		width: z.number(),
+		height: z.number(),
+		name: z.string().optional()
+	})
+});
+//#endregion
+export { Device };

package/dist/entities/system/File.d.ts

@@ -0,0 +1,72 @@
+import { Ref } from "../../framework/utils/refs.js";
+import { SubEntityClass } from "../../framework/defineSubEntity.js";
+import { EntityClass } from "../../framework/defineEntity.js";
+import { ComputedInput } from "../../framework/registry.js";
+import { z } from "zod";
+
+//#region src/entities/system/File.d.ts
+/** The extensions a module resolver will try, and the ones {@link isBinaryAsset} therefore counts as
+ *  text. Exported because codegen's resolver walks the same list — two copies would drift the first
+ *  time a runtime adds an extension, and they would drift silently. */
+declare const SCRIPT_EXTENSIONS: ReadonlySet<string>;
+/**
+ * Whether a path is bytes rather than text — the one place that is decided.
+ *
+ * An extension that is neither absent, nor `.json`, nor a script is an asset: an image, a font.
+ * This was Metro's rule, applied only when the graph was built for native, which made the same
+ * `icon.png` an asset there and a source file on web — and a restore then wrote the web one back
+ * through a text encoder. It is a fact about the file, so it does not get to depend on which
+ * platform asked, and it lives beside the kind whose path it reads rather than in the build that
+ * happens to call it first.
+ *
+ * Spelled out rather than taken from `node:path`, because nothing in this package imports `node:`
+ * — Studio runs the config in a browser. The rule is `extname`'s: the last dot in the last segment,
+ * and a leading dot is a dotfile (`.gitignore`) rather than an extension.
+ */
+declare function isBinaryAsset(filePath: string): boolean;
+/**
+ * File (`file:components/card.tsx`) — one artifact the seal owns.
+ *
+ * A component is a definition plus the React that renders it, and `config.json` cannot hold JSX, so
+ * some of what a system publishes travels as bytes. `uds push` bounds the source graph to the Git
+ * checkout and the config directory, hashes those files, and uploads them; a consumer pulls them
+ * down and verifies the hash. That whole lifecycle — hashed, uploaded, restored, verified — is one
+ * thing, and it is what this kind is for.
+ *
+ * **Sealed repo source is a `File`; anything remote stays a URL.** A `FontFile`'s `src` is something
+ * somebody uploaded to a cdn: there is no hash to check, no seal that owns it, and no build that
+ * produced it. Folding both into one kind would put two provenance models and two trust models
+ * behind one name.
+ *
+ * **The path is the src**, so there is no `src` field. Config-relative is the same key space the seal
+ * converts to, so an entry and a sealed file name the same thing with no translation and nothing to
+ * keep in step. The extension is part of the path deliberately: a helper authored as `.ts` is not
+ * JSX, and a bundler resolving `./tone` looks for what the closure actually holds.
+ *
+ * Ordinary authoring does not maintain this graph — the build derives it from the source it just
+ * walked, the way it derives `Package` groups from the same walk. Nobody picks a file out of a
+ * picker, so the kind has no group metadata and its groups stay emergent from the path.
+ */
+declare const File: EntityClass<z.ZodObject<{
+  hash: z.ZodString;
+  imports: z.ZodOptional<SubEntityClass<z.ZodObject<{
+    target: z.ZodType<Ref, unknown, z.core.$ZodTypeInternals<Ref, unknown>>;
+    names: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  }, z.core.$strip>>>;
+}, z.core.$strict>, z.ZodObject<Record<never, never>, z.core.$strip>, "file", Record<never, never>, {
+  /**
+   * Bytes rather than text, so a restore knows how to write it — derived from the path, because
+   * the path is the only thing that decides it.
+   *
+   * Stored, it was a second copy of what the extension already says, and the two could disagree:
+   * an artifact could carry `binary: true` on a `.tsx` and nothing would catch it. Computed, that
+   * state does not exist, and a build has one less field to remember to write. It also answers
+   * `false` for text rather than `undefined` — the writer omitted the field, which made an honest
+   * boolean read as a tri-state at every call site.
+   */
+  readonly binary: ({
+    path
+  }: ComputedInput) => boolean;
+}, false>;
+//#endregion
+export { File, SCRIPT_EXTENSIONS, isBinaryAsset };

package/dist/entities/system/File.js

@@ -0,0 +1,136 @@
+import { defineEntity } from "../../framework/defineEntity.js";
+import { defineSubEntity } from "../../framework/defineSubEntity.js";
+import { Package } from "./Package.js";
+import { z } from "zod";
+//#region src/entities/system/File.ts
+/** The extensions a module resolver will try, and the ones {@link isBinaryAsset} therefore counts as
+*  text. Exported because codegen's resolver walks the same list — two copies would drift the first
+*  time a runtime adds an extension, and they would drift silently. */
+const SCRIPT_EXTENSIONS = new Set([
+	".ts",
+	".tsx",
+	".mts",
+	".cts",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs"
+]);
+/**
+* Whether a path is bytes rather than text — the one place that is decided.
+*
+* An extension that is neither absent, nor `.json`, nor a script is an asset: an image, a font.
+* This was Metro's rule, applied only when the graph was built for native, which made the same
+* `icon.png` an asset there and a source file on web — and a restore then wrote the web one back
+* through a text encoder. It is a fact about the file, so it does not get to depend on which
+* platform asked, and it lives beside the kind whose path it reads rather than in the build that
+* happens to call it first.
+*
+* Spelled out rather than taken from `node:path`, because nothing in this package imports `node:`
+* — Studio runs the config in a browser. The rule is `extname`'s: the last dot in the last segment,
+* and a leading dot is a dotfile (`.gitignore`) rather than an extension.
+*/
+function isBinaryAsset(filePath) {
+	const base = filePath.slice(filePath.lastIndexOf("/") + 1);
+	const dot = base.lastIndexOf(".");
+	const extension = dot > 0 ? base.slice(dot).toLowerCase() : "";
+	return extension !== "" && extension !== ".json" && !SCRIPT_EXTENSIONS.has(extension);
+}
+/** What an import resolved to — a sealed sibling, or a package the consumer installs. `z.lazy` on
+*  `File` because it is a self-reference through the collection `File` declares; the explicit
+*  annotation breaks the circular type inference, the same way a token's value schema does. */
+const importTarget = z.union([z.lazy(() => File), Package]);
+/**
+* One import — keyed by the specifier as authored (`'./tone'`, `'@/uds/hooks/use-tone'`,
+* `'motion/react'`), holding what that specifier resolved to.
+*
+* **Both halves, because they come apart.** The specifier decides whether the target relocates when
+* a module is emitted into `.uds` — a relative import has to be mirrored beside the generated
+* module, an aliased one resolves through the consumer's own `paths` from anywhere — and
+* `file:components/tone.ts` does not say which of the two the render wrote. The specifier is the key
+* rather than a field beside one because it is the import's identity: a module imported twice is one
+* edge, and storing it in both places would be one string with two homes and no rule for which wins.
+*
+* **One list, not two.** An import is an import; splitting it by what it happens to resolve to gives
+* two lists that must be kept in step and throws away source order, which decides evaluation for a
+* side-effect import. `kindOf(ref)` is the discriminator, the same one that tells every other union
+* in the config apart.
+*/
+const FileImport = defineSubEntity({
+	name: "import",
+	label: "Import",
+	labelPlural: "Imports",
+	fields: z.object({
+		/** A local file the seal owns, or a package the consumer provides. */
+		target: importTarget,
+		/**
+		* The bindings this file took from that module, as the target names them — `Card` for
+		* `import { Card as C }`, `default` for a default import, `*` for a namespace or `export *`.
+		* The local alias is a fact about this file's scope rather than about the edge, so it is not
+		* what is recorded.
+		*
+		* Absent for an edge with no static bindings: a side-effect import (`import './reset.css'`) and
+		* a dynamic `import()`/`require()`, which name a module and take nothing from it by name.
+		*
+		* Not a ref, even where the target is a `Package` whose exports are entities
+		* (`package:react#useState`). A `Package` member exists only for an export a render placed in
+		* JSX, and this records every binding the source took — including a hook, a type, and a helper
+		* no JSX mentions. Pointing at members would silently drop those, and minting members to
+		* receive them would make the group claim a render surface it never had.
+		*/
+		names: z.array(z.string()).optional()
+	})
+});
+/**
+* File (`file:components/card.tsx`) — one artifact the seal owns.
+*
+* A component is a definition plus the React that renders it, and `config.json` cannot hold JSX, so
+* some of what a system publishes travels as bytes. `uds push` bounds the source graph to the Git
+* checkout and the config directory, hashes those files, and uploads them; a consumer pulls them
+* down and verifies the hash. That whole lifecycle — hashed, uploaded, restored, verified — is one
+* thing, and it is what this kind is for.
+*
+* **Sealed repo source is a `File`; anything remote stays a URL.** A `FontFile`'s `src` is something
+* somebody uploaded to a cdn: there is no hash to check, no seal that owns it, and no build that
+* produced it. Folding both into one kind would put two provenance models and two trust models
+* behind one name.
+*
+* **The path is the src**, so there is no `src` field. Config-relative is the same key space the seal
+* converts to, so an entry and a sealed file name the same thing with no translation and nothing to
+* keep in step. The extension is part of the path deliberately: a helper authored as `.ts` is not
+* JSX, and a bundler resolving `./tone` looks for what the closure actually holds.
+*
+* Ordinary authoring does not maintain this graph — the build derives it from the source it just
+* walked, the way it derives `Package` groups from the same walk. Nobody picks a file out of a
+* picker, so the kind has no group metadata and its groups stay emergent from the path.
+*/
+const File = defineEntity({
+	kind: "file",
+	label: "File",
+	labelPlural: "Files",
+	authoredRefs: false,
+	linkable: false,
+	fields: z.strictObject({
+		/** SHA-256 of the exact bytes — what the seal hashed, so a restore verifies rather than trusts. */
+		hash: z.string(),
+		/** What this file imports — keyed by the text the source wrote, in the order it wrote it. Every
+		*  local edge, plus each bare specifier a `Package` group already names; one the config names
+		*  nowhere is left out rather than pointed at a group minted to receive it. */
+		imports: FileImport.optional()
+	}),
+	computed: { 
+	/**
+	* Bytes rather than text, so a restore knows how to write it — derived from the path, because
+	* the path is the only thing that decides it.
+	*
+	* Stored, it was a second copy of what the extension already says, and the two could disagree:
+	* an artifact could carry `binary: true` on a `.tsx` and nothing would catch it. Computed, that
+	* state does not exist, and a build has one less field to remember to write. It also answers
+	* `false` for text rather than `undefined` — the writer omitted the field, which made an honest
+	* boolean read as a tri-state at every call site.
+	*/
+binary: ({ path }) => isBinaryAsset(path) },
+	subEntities: { imports: FileImport }
+});
+//#endregion
+export { File, SCRIPT_EXTENSIONS, isBinaryAsset };

package/dist/entities/system/Font.d.ts

@@ -0,0 +1,48 @@
+import { SubEntityClass } from "../../framework/defineSubEntity.js";
+import { EntityClass } from "../../framework/defineEntity.js";
+import { z } from "zod";
+
+//#region src/entities/system/Font.d.ts
+/**
+ * One FILE of a font family — the unit `@font-face` needs a rule for. Named `files` rather than
+ * `weights` because the two don't line up: a roman and an italic at 400 are two files sharing one
+ * weight, and a variable font is one file covering many (`weight: '100 900'`). `weightCount` is the
+ * derivation over these, not their count.
+ *
+ * `postscriptName` names this exact file (`YahooSans-BoldItalic`). CSS never needs it — a stylesheet
+ * addresses the FAMILY and lets the browser pick by weight/style — but a native platform references
+ * a file directly, and it can't be derived from the family name. Optional because nothing that feeds
+ * a config records one today; it's author/upload-supplied.
+ */
+declare const FontFile: SubEntityClass<z.ZodObject<{
+  src: z.ZodString;
+  format: z.ZodOptional<z.ZodString>;
+  weight: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+  style: z.ZodOptional<z.ZodString>;
+  postscriptName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+/**
+ * Font (`fonts/yas`) — one family in a font library. The library (`fonts`) is an EMERGENT group from
+ * the path, carrying only its version; a family carries its own CSS-facing name, its files, and the
+ * governance/rendering flags a picker and `@font-face` emission need.
+ *
+ * A font is its own kind rather than a variant of a generic `asset` so that a `font:` ref is typed:
+ * only a font can be referenced where a family is expected, which is what the old config could
+ * only enforce by throwing at resolve time ("only font groups can be referenced as a token value").
+ */
+declare const Font: EntityClass<z.ZodObject<{
+  fontFamily: z.ZodString;
+  files: z.ZodOptional<SubEntityClass<z.ZodObject<{
+    src: z.ZodString;
+    format: z.ZodOptional<z.ZodString>;
+    weight: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    style: z.ZodOptional<z.ZodString>;
+    postscriptName: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  fallbackStack: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  isVariableFont: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+  version: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, "font", Record<never, never>, Record<never, never>, false>;
+//#endregion
+export { Font, FontFile };

package/dist/entities/system/Font.js

@@ -0,0 +1,56 @@
+import { defineEntity } from "../../framework/defineEntity.js";
+import { defineSubEntity } from "../../framework/defineSubEntity.js";
+import { z } from "zod";
+//#region src/entities/system/Font.ts
+/**
+* One FILE of a font family — the unit `@font-face` needs a rule for. Named `files` rather than
+* `weights` because the two don't line up: a roman and an italic at 400 are two files sharing one
+* weight, and a variable font is one file covering many (`weight: '100 900'`). `weightCount` is the
+* derivation over these, not their count.
+*
+* `postscriptName` names this exact file (`YahooSans-BoldItalic`). CSS never needs it — a stylesheet
+* addresses the FAMILY and lets the browser pick by weight/style — but a native platform references
+* a file directly, and it can't be derived from the family name. Optional because nothing that feeds
+* a config records one today; it's author/upload-supplied.
+*/
+const FontFile = defineSubEntity({
+	name: "file",
+	label: "Font file",
+	labelPlural: "Files",
+	fields: z.object({
+		src: z.string(),
+		format: z.string().optional(),
+		/** `400`, or a RANGE (`'100 900'`) for a variable font's single file. */
+		weight: z.union([z.number(), z.string()]).optional(),
+		style: z.string().optional(),
+		postscriptName: z.string().optional()
+	})
+});
+/**
+* Font (`fonts/yas`) — one family in a font library. The library (`fonts`) is an EMERGENT group from
+* the path, carrying only its version; a family carries its own CSS-facing name, its files, and the
+* governance/rendering flags a picker and `@font-face` emission need.
+*
+* A font is its own kind rather than a variant of a generic `asset` so that a `font:` ref is typed:
+* only a font can be referenced where a family is expected, which is what the old config could
+* only enforce by throwing at resolve time ("only font groups can be referenced as a token value").
+*/
+const Font = defineEntity({
+	kind: "font",
+	label: "Font",
+	labelPlural: "Fonts",
+	fields: z.strictObject({
+		/** The CSS-facing family name (`'YA Sans'`) — required; a family without one can't be used. */
+		fontFamily: z.string(),
+		/** One entry per font file. */
+		files: FontFile.optional(),
+		/** Families to fall back to after this one, for a `font-family` stack. */
+		fallbackStack: z.array(z.string()).optional(),
+		/** Set explicitly; otherwise inferred from a file declaring a weight RANGE. */
+		isVariableFont: z.boolean().optional()
+	}),
+	groupFields: z.strictObject({ version: z.string().optional() }),
+	subEntities: { files: FontFile }
+});
+//#endregion
+export { Font, FontFile };

package/dist/entities/system/GlobalStyle.d.ts

@@ -0,0 +1,26 @@
+import { EntityClass } from "../../framework/defineEntity.js";
+import { z } from "zod";
+
+//#region src/entities/system/GlobalStyle.d.ts
+/** A declared value, or a nested block of them — an at-rule (`@keyframes`) and a grouped selector
+ *  both hold rules rather than declarations, and they nest to any depth. */
+type Declared = string | number | {
+  __ref: string;
+} | {
+  [key: string]: Declared;
+};
+declare const GlobalStyle: EntityClass<z.ZodObject<{
+  selector: z.ZodString;
+  declarations: z.ZodRecord<z.ZodString, z.ZodType<Declared, unknown, z.core.$ZodTypeInternals<Declared, unknown>>>;
+}, z.core.$strict>, z.ZodObject<Record<never, never>, z.core.$strip>, "global-style", Record<never, never>, Record<never, never>, false>;
+/**
+ * A stable name for a rule, from its selector — `@keyframes bounce` → `bounce`, `.prompt-editor p`
+ * → `promptEditorP`. Suffixed on collision, so two selectors that slug alike both land.
+ *
+ * For CONVERTING, not for authoring: an author names a rule by writing the key, and a migration has
+ * only the selector to go on. Exported so every converter derives the name the same way — two
+ * spellings of one rule is a system that can't tell they're the same one.
+ */
+declare function globalStyleName(selector: string, taken?: ReadonlySet<string>): string;
+//#endregion
+export { GlobalStyle, globalStyleName };

package/dist/entities/system/GlobalStyle.js

@@ -0,0 +1,54 @@
+import { refSchema } from "../../framework/utils/refs.js";
+import { defineEntity } from "../../framework/defineEntity.js";
+import { z } from "zod";
+//#region src/entities/system/GlobalStyle.ts
+/**
+* `GlobalStyle` — a CSS rule a system declares outright, for the things no component owns.
+*
+* A design system is mostly components, and a component's styling belongs to the component. What's
+* left over is real all the same: the page itself (`html, body`), a keyframe sequence, and the
+* chrome around content a component can't reach into — a contenteditable's typography, which is
+* styled by selector because there is no element to hand props to.
+*
+* v1 expressed this as `defineGlobalStyles((tokens) => ({ … }))` — a callback, because its values
+* had to resolve tokens at config time and be baked to `var(…)` strings. Here a value may be a REF,
+* so the dependency graph sees the edge and renaming a token cascades into the rule that uses it.
+*
+* The selector is a FIELD rather than the entity's path: a path's `/` means grouping, and a CSS
+* selector may contain one (`[href="/home"]`). Naming each rule also reads better than a bare
+* selector as a key — `page`, `bounce`, `promptEditor`.
+*/
+const declared = z.lazy(() => z.union([
+	z.string(),
+	z.number(),
+	refSchema,
+	z.record(z.string(), declared)
+]));
+const GlobalStyle = defineEntity({
+	kind: "global-style",
+	label: "Global style",
+	labelPlural: "Global styles",
+	fields: z.strictObject({
+		/** What the rule applies to — `html, body`, `@keyframes bounce`, `.prompt-editor p`. */
+		selector: z.string(),
+		/** Property → value, camelCase as it's authored; a nested record is a nested rule. */
+		declarations: z.record(z.string(), declared)
+	})
+});
+/**
+* A stable name for a rule, from its selector — `@keyframes bounce` → `bounce`, `.prompt-editor p`
+* → `promptEditorP`. Suffixed on collision, so two selectors that slug alike both land.
+*
+* For CONVERTING, not for authoring: an author names a rule by writing the key, and a migration has
+* only the selector to go on. Exported so every converter derives the name the same way — two
+* spellings of one rule is a system that can't tell they're the same one.
+*/
+function globalStyleName(selector, taken = /* @__PURE__ */ new Set()) {
+	const words = selector.replace(/[^A-Za-z0-9]+/g, " ").trim().split(/\s+/).filter(Boolean);
+	const base = selector.startsWith("@keyframes") ? words.at(-1) ?? "rule" : words.map((word, index) => index === 0 ? word.toLowerCase() : word.charAt(0).toUpperCase() + word.slice(1)).join("") || "rule";
+	let name = base;
+	for (let n = 2; taken.has(name); n++) name = `${base}${n}`;
+	return name;
+}
+//#endregion
+export { GlobalStyle, globalStyleName };

package/dist/entities/system/Guidance.d.ts

@@ -0,0 +1,85 @@
+import { GuidanceLane } from "../../ai-lanes.js";
+import { Ref } from "../../framework/utils/refs.js";
+import { EntityClass } from "../../framework/defineEntity.js";
+import { Config } from "../../framework/Config.js";
+import { z } from "zod";
+
+//#region src/entities/system/Guidance.d.ts
+/**
+ * A `Guidance` — one piece of authoring guidance the design SYSTEM gives an AI (or a human) that
+ * composes with it: "use a brand variant for the primary action", "build the whole request", etc.
+ * It lives on the system (not hardcoded in the pipeline) so each design system can shape how it
+ * wants to be used, and the pipeline stays a pure transformer that just derives them into the
+ * prompt.
+ *
+ * Grouping is the path, not a field. A rule is filed under the topic it belongs to, so
+ * `semantics/typography` is a semantics rule the same way `color/brand` is a color token:
+ *
+ * ```ts
+ * guidance: {
+ *   semantics: Guidance.group({
+ *     label: 'Semantics',
+ *     items: { typography: Guidance.item({ text: ['…'] }) },
+ *   }),
+ * }
+ * ```
+ *
+ * The path is what makes a topic reorderable against its siblings, renameable with its rules following
+ * along, and addressable as `guidance:semantics/typography`.
+ *
+ * `fields` is non-strict (`z.object`) because older artifacts still store a `category` key; a
+ * non-strict shape drops it on load where a strict one would refuse the whole artifact.
+ */
+/**
+ * One piece of a rule's text: a run of prose, or an `@mention` of a token or component stored as a
+ * {@link Ref}. `collectRefs`/`rewriteRefs` walk every entity's fields for the `{ __ref }` shape, so a
+ * mention follows renames, counts as a dependent and blocks deletes like any other ref.
+ */
+type GuidanceSegment = string | Ref;
+/**
+ * A rule's text flattened for display, each mention resolved to its target's current path. A mention
+ * whose target is missing (a source no longer attached) prints the ref's last-known path.
+ */
+declare function guidanceTextOf(config: Config, text: readonly GuidanceSegment[]): string;
+declare const Guidance: EntityClass<z.ZodObject<{
+  text: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    __ref: z.ZodString;
+  }, z.core.$strip>]>>;
+}, z.core.$strip>, z.ZodObject<{
+  label: z.ZodOptional<z.ZodString>;
+  description: z.ZodOptional<z.ZodString>;
+  appliesTo: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+    chat: "chat";
+    huddle: "huddle";
+    "paint-style": "paint-style";
+    "figma-import": "figma-import";
+  }>>>;
+}, z.core.$strict>, "guidance", Record<never, never>, Record<never, never>, false>;
+/**
+ * A topic's effective reach, and which topic decided it. `appliesTo === undefined` means every
+ * lane. `declaredBy` is the topic the answer was read from, so a lane can say "inherited from
+ * Semantics" rather than showing an override the sub-topic never chose.
+ */
+interface GuidanceScope {
+  readonly appliesTo: readonly GuidanceLane[] | undefined;
+  /** The topic that stored it: this topic, an ancestor, or `null` when nothing did. */
+  readonly declaredBy: string | null;
+}
+/**
+ * Which surfaces a topic's rules are fed to: its own `appliesTo`, else the nearest ancestor's, so
+ * scoping "Semantics" to chat scopes `semantics/color` too. An ungrouped rule keys on `''`, has no
+ * ancestor, and reaches everywhere.
+ */
+declare function guidanceScopeOf(config: Config, topic: string): GuidanceScope;
+/** Whether a topic's rules reach `lane`, inheritance included. */
+declare function guidanceReaches({
+  config,
+  topic,
+  lane
+}: {
+  config: Config;
+  topic: string;
+  lane: GuidanceLane;
+}): boolean;
+//#endregion
+export { Guidance, GuidanceScope, GuidanceSegment, guidanceReaches, guidanceScopeOf, guidanceTextOf };

package/dist/entities/system/Guidance.js

@@ -0,0 +1,59 @@
+import { GUIDANCE_LANES } from "../../ai-lanes.js";
+import { isRef, kindOf, pathOf, refSchema } from "../../framework/utils/refs.js";
+import { defineEntity } from "../../framework/defineEntity.js";
+import { z } from "zod";
+//#region src/entities/system/Guidance.ts
+/**
+* A rule's text flattened for display, each mention resolved to its target's current path. A mention
+* whose target is missing (a source no longer attached) prints the ref's last-known path.
+*/
+function guidanceTextOf(config, text) {
+	return text.map((segment) => isRef(segment) ? config.resolve(kindOf(segment), pathOf(segment))?.path ?? pathOf(segment) : segment).join("");
+}
+const Guidance = defineEntity({
+	kind: "guidance",
+	label: "Guidance",
+	labelPlural: "Guidance",
+	fields: z.object({ text: z.array(z.union([z.string(), refSchema])) }),
+	groupFields: z.strictObject({
+		/** Display name for the topic; falls back to the group's own path segment. */
+		label: z.string().optional(),
+		/** What the topic covers, for the editor, not the prompt. */
+		description: z.string().optional(),
+		/**
+		* Which AI lanes this topic is fed to. Absent means every lane. An empty array is a topic
+		* turned off everywhere, which is what unchecking the last box stores.
+		*/
+		appliesTo: z.array(z.enum(GUIDANCE_LANES)).optional()
+	})
+});
+/** Nothing up the chain scoped anything, so the rules reach every surface. */
+const UNSCOPED = {
+	appliesTo: void 0,
+	declaredBy: null
+};
+/**
+* Which surfaces a topic's rules are fed to: its own `appliesTo`, else the nearest ancestor's, so
+* scoping "Semantics" to chat scopes `semantics/color` too. An ungrouped rule keys on `''`, has no
+* ancestor, and reaches everywhere.
+*/
+function guidanceScopeOf(config, topic) {
+	let current = topic;
+	while (current !== "") {
+		const appliesTo = config.groupMeta("guidance", current)?.appliesTo;
+		if (Array.isArray(appliesTo)) return {
+			appliesTo,
+			declaredBy: current
+		};
+		const slash = current.lastIndexOf("/");
+		current = slash === -1 ? "" : current.slice(0, slash);
+	}
+	return UNSCOPED;
+}
+/** Whether a topic's rules reach `lane`, inheritance included. */
+function guidanceReaches({ config, topic, lane }) {
+	const { appliesTo } = guidanceScopeOf(config, topic);
+	return appliesTo === void 0 || appliesTo.includes(lane);
+}
+//#endregion
+export { Guidance, guidanceReaches, guidanceScopeOf, guidanceTextOf };

package/dist/entities/system/GuidanceStyle.d.ts

@@ -0,0 +1,14 @@
+import { EntityClass } from "../../framework/defineEntity.js";
+import { z } from "zod";
+
+//#region src/entities/system/GuidanceStyle.d.ts
+declare const guidanceStyleFields: z.ZodObject<{
+  text: z.ZodString;
+}, z.core.$strip>;
+/** A style guide's stored body. */
+type GuidanceStyleBody = z.infer<typeof guidanceStyleFields>;
+declare const GuidanceStyle: EntityClass<z.ZodObject<{
+  text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<Record<never, never>, z.core.$strip>, "guidance-style", Record<never, never>, Record<never, never>, false>;
+//#endregion
+export { GuidanceStyle, GuidanceStyleBody };

package/dist/entities/system/GuidanceStyle.js

@@ -0,0 +1,8 @@
+import { defineEntity } from "../../framework/defineEntity.js";
+import { z } from "zod";
+const GuidanceStyle = defineEntity({
+	kind: "guidance-style",
+	fields: z.object({ text: z.string() })
+});
+//#endregion
+export { GuidanceStyle };