@ankhorage/devtools 1.10.11 → 1.10.13

package/dist/tools/skills/assets/zora-designer/SKILL.md

@@ -1,29 +1,33 @@
 ---
 name: zora-designer
 description: >
-  Design one application screen or an ordered screen series, audit a URL or supplied image
-  evidence, and author an Ankhorage Templates manifest or starter using installed ZORA metadata
-  and theme APIs. Use for category-driven design decisions, design audits and scoring, visual
-  reconstruction with ZORA elements, or template creation. Do not use for illustration-only work.
+  Configure an owner-backed application design, generate one screen or a coherent screen series,
+  audit supplied evidence, and author portable Ankhorage templates. Use for category-driven design
+  decisions, ZORA screen generation, visual audits, or template creation.
 ---
 
 # ZORA Designer
 
-Design, audit, and author through the target repository's released owner APIs. Keep
-`zora-designer.md` as review evidence; the application manifest and owner contracts remain runtime
-authority.
+Design, audit, and author through the target repository's released owner APIs. The complete
+`AppManifest` is runtime authority; `zora-designer.md` and generated screen images are design
+evidence.
 
 ## Route the request
 
-- `interactive`: resolve a design configuration without silently creating code or images.
-- `screen`: design one screen and, when requested, produce a concept image or implementation.
-- `screens`: design a coherent ordered series with shared navigation, state, and tokens.
-- `audit`: evaluate a URL, one supplied image, or an ordered image series with explicit evidence.
-- `template`: compose a canonical `AppManifest`; in Templates, scaffold the normal starter source
-  and registry entry.
-
-Natural language is enough. Ask only when an unresolved choice would materially change the output.
-Read [workflow.md](references/workflow.md) for the ordered process and capability gates.
+- `interactive`: run the progressive configuration conversation in
+  [workflow.md](references/workflow.md). Do not create code or images before confirmation.
+- `screen`: resolve the configuration, then read [screens.md](references/screens.md) and design one
+  screen.
+- `screens`: resolve the configuration, then read [screens.md](references/screens.md) and design an
+  ordered series with shared navigation, state, geometry, and tokens.
+- `audit`: read [audit.md](references/audit.md) and evaluate supplied image or runtime evidence.
+- `template`: resolve the configuration and screen model, then author one portable template through
+  the workflow below.
+
+Natural language is enough. Treat short replies as answers to the current question, not permission
+to infer later decisions. A reply such as “go on” advances to the next unresolved decision. Only an
+explicit request such as “accept all recommended values” resolves the remaining recommendations at
+once.
 
 ## Start with the owners
 
@@ -33,57 +37,60 @@ From the target repository, run:
 bun .agents/skills/zora-designer/scripts/owner-api.mjs inspect
 ```
 
-The helper loads public exports from installed `@ankhorage/templates`, `@ankhorage/zora/theme`, and
-`@ankhorage/zora/metadata`. If it reports a missing or outdated owner, update the released package
-through the repository's normal dependency workflow. Never copy a catalog, token inventory, color
-algorithm, theme compiler, component schema, or manifest implementation into this skill.
-
-Use owner terminology verbatim: `GeneratedColorRole`, `ThemeTokens.colors`, `ThemeSemantics`, and
-`SemanticColorToken`. Do not introduce aliases or naming cleanup here.
+Use its installed owner output for categories, recommendations, harmonies, tone pairs, navigation
+types, ZORA elements, events, recipes, and version provenance. Never copy owner catalogs, component
+schemas, token inventories, color algorithms, action types, or manifest implementations into this
+skill.
 
-## Preserve decisions and evidence
+Compile chosen values with the same helper before composing screens. Inspect both computed modes,
+including their resolved Surface themes and all owner diagnostics. Never hand-calculate a value the
+owner exposes.
 
-Resolve values in this order: current request, current session, verified project state, confirmed
-existing brief target, category preset, then safe global default. Record an origin for each value.
-Keep target design separate from observed runtime state and report drift rather than overwriting one
-with the other.
+## Preserve the complete UX
 
-For scoring, evidence limits, release gates, and finding rules, read
-[audit.md](references/audit.md). For deterministic `zora-designer.md` shape and serialization, read
-[artifact.md](references/artifact.md).
+For every screen region, prefer the exact semantic ZORA element supported by current metadata.
+Visual resemblance alone is insufficient. If no exact element exists, preserve the requested UX
+with an obvious supported placeholder such as a secondary-surface `Box`, and record the capability
+gap. Do not invent props, application components, or successful behavior.
 
-## Compose only supported ZORA elements
+Bind every interaction expressible by installed Contracts and ZORA event metadata. Leave an
+unsupported interaction visibly present and explicitly unbound without blocking unrelated design
+work. Release validation still decides whether the complete manifest is shippable.
 
-Inspect `ZORA_COMPONENT_META` and `ZORA_THEME_RECIPE_META`. Map a source region only when the
-element's semantic responsibility, structure, states/interactions, accessibility contract, props,
-events, and data requirements fit. Visual resemblance alone is insufficient.
+## Template output
 
-If no exact element fits:
+A Templates repository template is exactly one portable unit:
 
-1. use the metadata-backed `MissingElement` draft node at that location;
-2. record the evidence, warning, requested capability, and application blocker;
-3. create or link a ZORA owner issue;
-4. stop release application until a released real element replaces it.
+```text
+src/templates/categories/{appCategory}/{slug}/
+  createAppManifest.ts
+  assets/
+    screens/
+    images/
+```
 
-Never disguise the gap with a generic container, invented prop, or custom application workaround.
+`createAppManifest.ts` default-exports a function returning the complete `AppManifest`.
+`assets/screens/` contains design evidence only. Runtime media uses real application image regions
+under `assets/images/`; rebuild text, controls, icons, surfaces, and layout with ZORA.
 
-## Capability truthfulness
+Scaffold only a reviewed, release-valid manifest:
 
-- Concept image output requires an available image-generation capability.
-- URL intake and authoritative runtime screenshots require a browser/runtime capture capability.
-- Image audits require the supplied original image or ordered series.
+```text
+bun .agents/skills/zora-designer/scripts/scaffold-template.mjs scaffold-input.json
+```
 
-When a required capability or source is unavailable, report that deliverable or evidence scope as
-blocked. Do not simulate an image, browser observation, or runtime proof. Clearly distinguish
-generated concept images from authoritative runtime captures.
+The helper creates the template directory and regenerates discovery from the filesystem. Do not add
+category registries, seed definitions, fallback templates, compatibility paths, or per-template
+barrels.
 
 ## Validate before handoff
 
-- Compile the category design and both theme modes through installed owner APIs.
-- Validate manifest composition and preserve every owner diagnostic.
-- Confirm every manifest node and recipe against current ZORA metadata.
-- Run deterministic audit arithmetic when an audit is in scope.
-- Keep screenshot-only behavior `not-assessable`.
-- Require a ready application gate before release; a score never overrides a blocker.
-- Update `zora-designer.md` and report target/runtime drift, unsupported capabilities, and owner
-  issues.
+- confirm the interactive decision sequence completed or the user explicitly accepted remaining
+  recommendations;
+- compile light and dark independently through installed owner APIs;
+- validate selected ZORA nodes, props, events, actions, and complete manifest contracts;
+- run the screen composition gate from [screens.md](references/screens.md) before returning screen
+  output;
+- keep unsupported interactions and capability gaps explicit;
+- keep concept screens separate from runtime assets;
+- for deterministic artifact shape, read [artifact.md](references/artifact.md).

package/dist/tools/skills/assets/zora-designer/references/artifact.md

@@ -67,8 +67,10 @@ Aggregate validation in this order: blocker, failure, not run, pass with non-blo
 pass. Resolve the application gate separately. A runtime blocker affects aggregate status only when
 runtime application is in the requested scope.
 
-Every unresolved `MissingElement` records a blocker, owner issue link when one exists, and the
-condition for replacing it with a released real ZORA element.
+Every capability that lacks an exact metadata-supported ZORA element records a non-blocking
+capability gap and uses a visible `Box` placeholder in the concept composition. An owner diagnostic
+with `severity: error` is a blocker. Record an owner issue link when one exists and the condition
+for replacing the placeholder with a released real ZORA element.
 
 ## Deterministic audit fields
 
@@ -89,5 +91,5 @@ state that it was not persisted.
 
 Before returning, confirm the artifact matches the requested mode, every resolved value has an
 origin, owner identifiers were inspected, exact measurements came from tools, invisible behavior
-was not passed from screenshots, gaps block application, and the manifest remains canonical runtime
-authority.
+was not passed from screenshots, owner errors block release, capability gaps are explicit, and the
+manifest remains canonical runtime authority.

package/dist/tools/skills/assets/zora-designer/references/screens.md

@@ -0,0 +1,90 @@
+# Screen and Screen-Series Design
+
+Read this reference for `screen` and `screens` after the interactive configuration is confirmed.
+Generated images are concept evidence; the manifest and ZORA metadata remain implementation
+authority.
+
+## Preconditions
+
+Do not generate or implement a screen until these are resolved:
+
+- audience and primary task;
+- platform, input modes, theme coverage, and an explicit target viewport or responsive range;
+- primary color, harmony, per-mode tone pairs, typography/profile, and compiled owner themes;
+- ordered screen list with one purpose and primary action per screen;
+- navigator type, route topology, and back/cancel behavior.
+
+If the user supplies only `mobile`, recommend a neutral 390 by 844 logical-point portrait concept
+viewport. Ask about iOS- or Android-specific chrome only when it changes the requested result.
+
+## Compose the series before rendering
+
+For every screen record:
+
+1. purpose, primary task, primary action, and success outcome;
+2. content hierarchy and exact visible copy;
+3. default plus relevant loading, empty, partial, error, offline, disabled, pressed, selected, and
+   focus states;
+4. route relationship and continuity of selected item, filters, progress, drafts, or other state;
+5. exact metadata-backed ZORA elements, supported events/actions, data needs, and capability gaps;
+6. safe areas, keyboard/overlay behavior, scroll ownership, and narrow/wide behavior;
+7. real image content that must become an application asset rather than screenshot UI.
+
+Create one shared shell specification for a series: viewport, safe areas, gutters, header geometry,
+navigation geometry, surface treatment, type roles, icon family, content density, and state styling.
+Reuse it unchanged unless a screen has a documented immersive or modal exception.
+
+## Mobile geometry and typography gate
+
+Use compiled Surface/ZORA tokens when they define these values. Where the owner leaves a design-
+brief decision open, use these starting constraints and record them rather than asking an image
+model to improvise:
+
+- 16–24 logical-point horizontal gutters and preserved top/bottom safe areas;
+- at least 44 by 44 pt touch bounds, or the stricter target-platform convention;
+- screen title uses the semantic `h1` role, normally near 32/40 on mobile, one line when practical
+  and never more than two; reserve `display` for splash, onboarding, or genuine marketing moments;
+- section titles use `h2`/`h3`; body content normally starts near 16/24; metadata never becomes tiny
+  merely to fit more content;
+- prose measures approximately 45–75 characters per line, with reading surfaces optimized near the
+  comfortable middle of that range;
+- bottom navigation uses one stable height, label baseline, icon family, selected treatment, and
+  safe-area inset across the series;
+- a screen must expose its purpose, primary content, and primary action without competing giant
+  headings or decorative elements.
+
+Inspect the skill-owned design rules before rendering:
+
+```text
+bun .agents/skills/zora-designer/scripts/audit.mjs catalog
+```
+
+Apply every relevant `generation` rule from that catalog. The rubric belongs to this skill; owner
+catalogs and design-system algorithms do not.
+
+## Concept-image specification
+
+Generate one image per distinct screen or state. Every prompt must include:
+
+- exact logical viewport and portrait/landscape orientation;
+- shared shell and active navigator item;
+- resolved owner palette and type-role sizes, not only mood adjectives;
+- exact screen title, copy that must be legible, hierarchy, components, and primary action;
+- content quantity that fits the viewport at the declared type scale;
+- invariants shared with the other screens;
+- prohibitions against device frames, presentation boards, watermarks, illegible labels, invented
+  tabs, and oversized marketing typography on ordinary application screens.
+
+For a series, keep the resolved configuration and shell verbatim across prompts. Do not generate a
+single contact sheet as a substitute for individual screens unless the user explicitly requests one.
+
+## Review and iterate
+
+Inspect each output at its original dimensions. Reject and regenerate a screen when its title,
+navigation, copy, safe areas, hierarchy, component semantics, or geometry diverges from the brief.
+Use one targeted correction per iteration. Review the full ordered series together for shared shell,
+type scale, navigation, color allocation, state continuity, and visual rhythm.
+
+A visual review can validate visible composition only. It cannot prove runtime actions,
+accessibility semantics, focus order, text scaling, or responsive behavior; record those as
+not-assessable until implementation evidence exists.

package/dist/tools/skills/assets/zora-designer/references/workflow.md

@@ -1,137 +1,95 @@
-# Design, Composition, and Template Workflow
-
-Use this workflow for `interactive`, `screen`, `screens`, and `template`. Audit uses the same
-compiled target baseline when a redesign is requested; it never fills unknown observed values with
-presets and pretends they were measured.
-
-## 1. Establish mode, intent, and evidence
-
-Record the audience, primary task, requested screen or ordered series, platform, input modes,
-viewport constraints, target theme modes, available source artifacts, and requested deliverable.
-Inspect the current manifest, theme, installed packages, ZORA metadata, fonts, and existing
-`zora-designer.md` before prompting.
-
-For an input image or series, decompose each screen into semantic regions. Give each region a stable
-evidence ID, purpose, content/data responsibility, state and interaction needs, accessibility needs,
-and its relationship to other regions. Preserve image order and original dimensions. Do not map by
-appearance alone.
-
-## 2. Build the design in dependency order
-
-Interactive questions and compiler calls follow this exact order. Skip a question only when the
-answer is already supplied or reliably discovered.
-
-1. **Category and intent.** Read `APP_CATEGORIES` and `CATEGORY_PRESETS` from Templates. Show the
-   preset's ordered primary-color and font-family recommendations and explain that they are starting
-   points, not user stereotypes. Defer font activation until its availability and owning loader are
-   verified.
-2. **Primary color.** Offer the preset's first recommended primary color and any verified project
-   brand color. Let the user accept or supply a color. The owner normalizes and validates it.
-3. **Harmony.** Only after primary is resolved, show `recommendedHarmonies` and the installed owner
-   harmony catalog. Preserve the selected canonical identifier.
-4. **Per-mode tone combination.** Show the preset recommendation first, then read all valid choices
-   from `TONE_PAIR_CATALOG`. Resolve light and dark independently with `resolveTonePair`; do not copy
-   a list into prose or code.
-5. **Generated colors.** Call `resolveCategoryDesignPreset` or `compileCategoryDesign`. Inspect
-   generated owner roles and diagnostics; never hand-calculate secondary, accent, severity,
-   background, neutral, or on-colors.
-6. **Computed Surface output.** Inspect `computedTheme.light.surfaceTheme` and
-   `computedTheme.dark.surfaceTheme`, including `ThemeTokens.colors`, `ThemeSemantics`, provenance,
-   selections, and diagnostics. Record `GeneratedColorRole` and `SemanticColorToken` names exactly.
-7. **Composition.** Resolve density, shape, layout, navigation, content hierarchy, states, and exact
-   ZORA elements from metadata. Typography recommendations remain advisory until the chosen font is
-   verified and the owning app/module can load it; never install or bundle a font implicitly.
-8. **Confirmation and output.** Show high-impact choices, their origins, diagnostics, gaps, and the
-   requested artifact. Persist runtime state only through the canonical manifest/contracts.
-
-Use separate light/dark tone pairs and owner compilation even when the two modes share a primary
-seed. Never generate dark mode by inversion.
-
-## 3. Inspect installed owner APIs
-
-Run from the target repository:
+# Owner-Backed Interactive and Template Workflow
 
-```text
-bun .agents/skills/zora-designer/scripts/owner-api.mjs inspect
-```
-
-The output reports installed versions, category presets, tone pairs, component metadata, recipe
-metadata, and required exports. An error names the missing package/export, minimum owner release,
-and update action. There is no fallback calculation.
-
-For deterministic composition, provide JSON to:
-
-```text
-bun .agents/skills/zora-designer/scripts/owner-api.mjs compose design-input.json
-```
-
-The input contains `category`, optional `theme` overrides, `navigator`, `screens`, and optional
-`regions`. Each region has `id`, `requestedCapability`, `screenId`, `parentNodeId`, an optional exact
-`component`, explicit `props`, and `evidenceId`. The helper:
-
-- compiles the category through Templates and the released ZORA compiler;
-- validates exact component names and props against `ZORA_COMPONENT_META`;
-- emits metadata-derived `MissingElement` nodes for unresolved regions;
-- composes the canonical manifest in draft mode while a gap exists;
-- reports `applicationGate: blocked` and owner actions for every gap;
-- preserves Templates and ZORA diagnostics.
-
-The agent remains responsible for semantic matching. A requested component name is an explicit
-decision to validate, not a fuzzy-search request.
+Use this workflow for `interactive`, `screen`, `screens`, and `template`. Ask only about unresolved
+decisions, one decision at a time. Show the owner recommendation first with a short reason. Do not
+silently accept later recommendations because an earlier answer was brief.
 
-## 4. Design one screen or a series
+## 1. Inspect intent and owners
 
-For each screen define purpose, information hierarchy, primary action, navigation relationship,
-data needs, and relevant default/loading/empty/partial/error/offline/success/disabled/hover/pressed/
-selected/focus states. Define narrow and wide behavior where applicable.
-
-For a series also define the shared shell, canonical route topology, state continuity, back/cancel
-behavior, shared recipes and terminology, and one common theme. A concept image series must remain
-ordered and visually coherent. Label every generated image as a concept; replace it with an actual
-runtime capture only after running the manifest.
-
-## 5. Audit a URL, image, or series
-
-For a URL, capture the relevant modes, viewports, and states using a browser/runtime tool. For one
-image or a series, retain original dimensions and input order. Every evidence item records location,
-observation, evidence level, confidence factor, reproduction, and limitations.
-
-Read [audit.md](audit.md), create a criterion input JSON, and run:
+Read repository instructions, an existing manifest or `zora-designer.md`, installed fonts, platform
+configuration, and relevant screens. Run:
 
 ```text
-bun .agents/skills/zora-designer/scripts/audit.mjs audit-input.json zora-designer.md
+bun .agents/skills/zora-designer/scripts/owner-api.mjs inspect
 ```
 
-Invisible behavior remains `not-assessable` unless source, accessibility-tree, browser, or runtime
-evidence supports it. A recommended redesign baseline may use the category workflow but must be
-clearly separated from observed implementation.
-
-## 6. Author a canonical template
-
-Use `composeCategoryAppManifest`, `validateTemplateManifest`, and
-`assertTemplateManifestReady`. Draft output may contain `MissingElement`; release output may not.
-
-When the target repository is `@ankhorage/templates`, scaffold reviewed composition output with:
+The output is the choice source. Do not use remembered categories, color options, tone pairs,
+navigator types, ZORA elements, or events. Resolve explicit user input before project state,
+existing brief values, category recommendations, and global defaults. Record the origin of every
+resolved decision.
+
+## 2. Ask in dependency order
+
+Advance through this sequence. Skip only a value already supplied or reliably discovered.
+
+1. **Category and intent.** Resolve the canonical app category, product name, audience, and primary
+   task. For `screen` and `screens`, audience and primary task are required.
+2. **Platform and theme coverage.** Resolve mobile, desktop, or responsive scope; technology;
+   input modes; target viewport or content constraints; light, dark, or both; and the default mode
+   when relevant.
+3. **Primary color.** Show the category recommendations in owner order and any verified project
+   brand color. Let the user accept one or supply a CSS color. Preserve the brand seed; the owner
+   compiler selects accessible functional steps.
+4. **Harmony.** After primary is resolved, show the category recommendation first and only the
+   harmony identifiers reported by Color Theory. Explain the visual energy and complexity using the
+   owner catalog descriptions.
+5. **Tone pairs.** After harmony is resolved, offer the category's separate light and dark
+   recommendations, followed by mode-compatible owner entries. Explain that `X-on-Y` means accent
+   family on foundation family; structural foregrounds remain independently resolved semantic
+   tokens.
+6. **Typography and profile.** Resolve a verified body font, optional heading pairing, density,
+   shape, motion, and contrast target. Do not install fonts. Offer the category/profile
+   recommendation first and allow the user to accept the recommended system settings together.
+7. **Screens.** Ask for the ordered screen list and purpose of each screen. Then establish the
+   primary action, essential content, required data states, and continuity across the series. Do not
+   generate images yet.
+8. **Navigator.** After the screen topology exists, offer only Contracts navigator types and map
+   every route, initial route, hidden/detail route, back/cancel path, and primary-navigation label.
+9. **Compile and confirm.** Compile both theme modes through the owner helper. Summarize high-impact
+   decisions, origins, diagnostics, unsupported capabilities, screen order, and route topology. Ask
+   for confirmation before creating screen images, code, or a template.
+
+If the user changes an earlier decision, invalidate and revisit only dependent later decisions.
+Changing primary invalidates harmony-derived compilation and tone output but does not erase the
+screen brief. Changing the screen list invalidates navigator confirmation.
+
+## 3. Compile owner output
+
+Provide the resolved `category`, theme overrides, navigator, screens, and region decisions to:
 
 ```text
-bun .agents/skills/zora-designer/scripts/scaffold-template.mjs scaffold-input.json
+bun .agents/skills/zora-designer/scripts/owner-api.mjs compose design-input.json
 ```
 
-The scaffold input provides the ready manifest, category, template ID, label, description, and
-target root. The helper verifies the Templates repository and owner validation, creates a normal
-variant `manifest.ts`, `template.ts`, and `index.ts`, and updates the category registry import and
-definition deterministically. It refuses existing targets, unsafe identifiers, blocked manifests,
-and non-Templates repositories. Review and validate the generated production diff; do not hand-hide
-a systemic skill or owner defect.
-
-## 7. Delivery gates
-
-Before application or release:
-
-- every visible/interactive region has an exact metadata-supported element;
-- every gap has evidence and a linked ZORA owner issue;
-- both modes compile without owner errors;
-- the manifest is owner-validated and release-ready;
-- required concept-image, runtime-capture, or supplied-image capabilities were actually available;
-- target and observed state are clearly separated;
-- `zora-designer.md` is deterministic and contains no runtime authority or copied owner catalogs.
+Use owner-returned theme configuration, generated roles, computed Surface themes, diagnostics,
+component metadata, and manifest composition. Light and dark are independent compilations; never
+derive dark mode by inversion. A failed owner diagnostic remains visible. Do not replace it with
+local math or an undocumented token.
+
+For every region, validate its exact component name, props, allowed-parent relationship, and event
+metadata. Use supported navigation and actions when available. Represent missing capability without
+removing the intended flow or inventing a contract.
+
+## 4. Produce the requested deliverable
+
+- `interactive`: write or return the confirmed `zora-designer.md`; do not produce screen images or
+  implementation unless requested.
+- `screen` or `screens`: read [screens.md](screens.md), create the screen specification, then produce
+  only the requested image, code, or manifest deliverable.
+- `template`: author a complete `AppManifest`, validate it in release mode, generate or extract every
+  required runtime image, and run the Templates scaffolder.
+
+For design-first templates, store reference images under `assets/screens/` and crop only real image
+content into `assets/images/`. For direct authoring, generate application images directly under
+`assets/images/`. Runtime media never references a complete screen image.
+
+## 5. Delivery checks
+
+- every decision is explicit, discovered, or carries a recorded default origin;
+- both theme modes compile without hidden local fallback calculations;
+- the screen model and navigator agree;
+- every selected ZORA node and prop is metadata-supported;
+- supported events/actions are bound and unsupported behavior is recorded;
+- screen generation passes the composition gate;
+- release templates contain one default-exported `createAppManifest()` and bundled media paths;
+- the complete manifest validates against the installed owner contract.

package/dist/tools/skills/assets/zora-designer/scripts/generate-template-catalog.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env bun
+
+import { access, readdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+import { loadContractsApi } from './owner-api.mjs';
+
+const CATEGORY_ROOT = 'src/templates/categories';
+
+/*** Regenerate the portable template catalog from canonical template directories. */
+export async function generateTemplateCatalog(targetDirectory = process.cwd(), appCategories) {
+  const root = resolve(targetDirectory);
+  const canonicalAppCategories = appCategories ?? (await loadContractsApi(root)).APP_CATEGORIES;
+  const categoriesRoot = join(root, CATEGORY_ROOT);
+  const definitions = [];
+
+  for (const categoryEntry of await readDirectories(categoriesRoot)) {
+    const category = categoryEntry.name.replaceAll('-', '_');
+    if (!canonicalAppCategories.includes(category)) {
+      throw new Error(`Unknown app category directory: ${categoryEntry.name}`);
+    }
+
+    const categoryRoot = join(categoriesRoot, categoryEntry.name);
+    for (const templateEntry of await readDirectories(categoryRoot)) {
+      const manifestPath = join(categoryRoot, templateEntry.name, 'createAppManifest.ts');
+      if (!(await pathExists(manifestPath))) continue;
+      definitions.push({
+        category,
+        categoryDirectory: categoryEntry.name,
+        slug: templateEntry.name,
+      });
+    }
+  }
+
+  definitions.sort((left, right) =>
+    `${left.category}/${left.slug}`.localeCompare(`${right.category}/${right.slug}`),
+  );
+
+  const imports = definitions
+    .map(
+      (definition, index) =>
+        `import createAppManifest${index} from './categories/${definition.categoryDirectory}/${definition.slug}/createAppManifest';`,
+    )
+    .join('\n');
+  const entries = definitions
+    .map(
+      (definition, index) => `  {
+    category: '${definition.category}',
+    slug: '${definition.slug}',
+    sourceRoot: '${CATEGORY_ROOT}/${definition.categoryDirectory}/${definition.slug}',
+    createAppManifest: createAppManifest${index},
+  },`,
+    )
+    .join('\n');
+  const definitionsSource = definitions.length === 0 ? '[]' : `[\n${entries}\n]`;
+
+  const source = `${imports}${imports ? '\n\n' : ''}import type { TemplateDefinition } from './catalog';
+
+export const TEMPLATE_DEFINITIONS: readonly TemplateDefinition[] = ${definitionsSource};
+`;
+
+  const outputPath = join(root, 'src/templates/catalog.generated.ts');
+  await writeFile(outputPath, source, 'utf8');
+  return { outputPath, templateCount: definitions.length };
+}
+
+/*** Read child directories in stable lexical order. */
+async function readDirectories(directory) {
+  return (await readdir(directory, { withFileTypes: true }))
+    .filter((entry) => entry.isDirectory())
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+/*** Return whether a filesystem path exists. */
+async function pathExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+if (import.meta.main) {
+  const targetDirectory = process.argv[2] ?? process.cwd();
+  const result = await generateTemplateCatalog(targetDirectory);
+  console.log(`Generated ${result.templateCount} template catalog entries.`);
+}

package/dist/tools/skills/assets/zora-designer/scripts/owner-api.mjs

@@ -5,11 +5,23 @@ import { dirname, join, parse, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 const OWNER_RELEASES = {
+  colorTheory: { packageName: '@ankhorage/color-theory', minimumVersion: '0.3.0' },
+  contracts: { packageName: '@ankhorage/contracts', minimumVersion: '8.2.0' },
   templates: { packageName: '@ankhorage/templates', minimumVersion: '8.0.0' },
   zora: { packageName: '@ankhorage/zora', minimumVersion: '4.0.0' },
 };
 
 const OWNER_REQUIREMENTS = {
+  colorTheory: {
+    ...OWNER_RELEASES.colorTheory,
+    specifier: '@ankhorage/color-theory',
+    exports: ['COLOR_HARMONIES', 'COLOR_HARMONY_CATALOG'],
+  },
+  contracts: {
+    ...OWNER_RELEASES.contracts,
+    specifier: '@ankhorage/contracts',
+    exports: ['APP_CATEGORIES', 'NAVIGATOR_TYPES'],
+  },
   templates: {
     ...OWNER_RELEASES.templates,
     specifier: '@ankhorage/templates',
@@ -45,35 +57,58 @@ export async function loadOwnerApis(targetDirectory = process.cwd()) {
   }
 
   return {
+    colorTheory: loaded.colorTheory.module,
+    contracts: loaded.contracts.module,
     templates: loaded.templates.module,
     zoraTheme: loaded.zoraTheme.module,
     zoraMetadata: loaded.zoraMetadata.module,
     versions: {
+      colorTheory: loaded.colorTheory.version,
+      contracts: loaded.contracts.version,
       templates: loaded.templates.version,
       zora: loaded.zoraTheme.version,
     },
   };
 }
 
+/*** Load only Contracts for tooling that runs before another owner package has been built. */
+export async function loadContractsApi(targetDirectory = process.cwd()) {
+  return (await loadOwnerModule(targetDirectory, OWNER_REQUIREMENTS.contracts)).module;
+}
+
 /*** Return installed catalogs and metadata names without copying owner definitions. */
 export async function inspectOwnerApis(targetDirectory = process.cwd()) {
   const owners = await loadOwnerApis(targetDirectory);
+  const componentMetadata = Object.values(owners.zoraMetadata.ZORA_COMPONENT_META);
   return {
     versions: owners.versions,
-    categories: Object.values(owners.templates.CATEGORY_PRESETS).map((preset) => ({
-      category: preset.category,
-      label: preset.label,
-      recommendedPrimaryColors: preset.recommendedPrimaryColors,
-      recommendedHarmonies: preset.recommendedHarmonies,
-      tonePairs: preset.tonePairs,
-    })),
+    appCategories: owners.contracts.APP_CATEGORIES,
+    categoryPresets: owners.templates.CATEGORY_PRESETS,
+    harmonyIds: owners.colorTheory.COLOR_HARMONIES,
+    harmonies: owners.colorTheory.COLOR_HARMONY_CATALOG,
     tonePairs: owners.templates.TONE_PAIR_CATALOG,
-    components: Object.keys(owners.zoraMetadata.ZORA_COMPONENT_META).sort(),
+    navigatorTypes: owners.contracts.NAVIGATOR_TYPES,
+    components: componentMetadata.map((meta) => meta.name).sort(),
+    events: componentMetadata
+      .flatMap((meta) =>
+        Object.values(meta.events ?? {}).map((event) => ({
+          component: meta.name,
+          eventType: event.eventType,
+          label: event.label,
+          description: event.description,
+          payloadFields: event.payloadFields,
+        })),
+      )
+      .sort((left, right) =>
+        `${left.component}:${left.eventType}`.localeCompare(
+          `${right.component}:${right.eventType}`,
+        ),
+      ),
     themeRecipes: Object.keys(owners.zoraMetadata.ZORA_THEME_RECIPE_META).sort(),
   };
 }
 
-/*** Compile category design, validate region nodes, and compose one canonical draft or release manifest. */
+/*** Compose one design without turning missing runtime/UI capabilities into a design blocker. */
 export async function composeDesign(input, targetDirectory = process.cwd()) {
   const owners = await loadOwnerApis(targetDirectory);
   assertRecord(input, 'Design input');
@@ -90,7 +125,6 @@ export async function composeDesign(input, targetDirectory = process.cwd()) {
   const design = owners.templates.compileCategoryDesign(input.category, input.theme ?? {});
   const { computedTheme, ...resolvedDesign } = design;
   const requestedAuthoringState = input.authoringState === 'release' ? 'release' : 'draft';
-  const authoringState = regionResult.gaps.length === 0 ? requestedAuthoringState : 'draft';
   const composition = owners.templates.composeCategoryAppManifest({
     category: input.category,
     name: input.name,
@@ -103,14 +137,14 @@ export async function composeDesign(input, targetDirectory = process.cwd()) {
     modules: input.modules,
     modulesConfig: input.modulesConfig,
     theme: input.theme,
-    authoringState,
+    authoringState: requestedAuthoringState,
   });
   const ownerDiagnostics = [
     ...design.diagnostics,
     ...computedTheme.diagnostics,
     ...composition.diagnostics,
   ];
-  const blocked = regionResult.gaps.length > 0 || composition.status === 'blocked';
+  const blockers = ownerDiagnostics.filter((diagnostic) => diagnostic.severity === 'error');
 
   return {
     owners: owners.versions,
@@ -118,14 +152,15 @@ export async function composeDesign(input, targetDirectory = process.cwd()) {
     computedTheme,
     composition,
     regionDiagnostics: regionResult.diagnostics,
+    capabilityGaps: regionResult.gaps,
     ownerDiagnostics,
     requestedAuthoringState,
-    applicationGate: blocked ? 'blocked' : 'pass',
-    blockers: regionResult.gaps,
+    applicationGate: composition.status === 'blocked' ? 'blocked' : 'pass',
+    blockers,
   };
 }
 
-/*** Resolve explicit region-to-component decisions and insert validated nodes into cloned screens. */
+/*** Resolve explicit region decisions using exact metadata or a visible non-blocking Box placeholder. */
 export function resolveRegionNodes(screens, regions, componentMeta) {
   const resolvedScreens = structuredClone(screens);
   const diagnostics = [];
@@ -152,7 +187,6 @@ export function resolveRegionNodes(screens, regions, componentMeta) {
   return { screens: resolvedScreens, diagnostics, gaps };
 }
 
-/*** Resolve one exact metadata-backed component or the owner-defined MissingElement placeholder. */
 function resolveRegionNode(region, componentMeta) {
   const component = typeof region.component === 'string' ? region.component : null;
   const meta = component === null ? null : componentMeta[component];
@@ -170,36 +204,30 @@ function resolveRegionNode(region, componentMeta) {
     };
   }
 
-  const missingMeta = componentMeta.MissingElement;
-  if (!missingMeta || missingMeta.manifestPolicy?.kind !== 'unresolved-element') {
-    throw new Error(
-      'Installed @ankhorage/zora metadata does not expose the canonical MissingElement contract.',
-    );
+  const placeholderMeta = componentMeta.Box;
+  if (!placeholderMeta?.directManifestNode) {
+    throw new Error('Installed @ankhorage/zora metadata does not expose Box as a manifest node.');
   }
-  const props = {
-    ...(missingMeta.blueprint?.defaultProps ?? {}),
-    requestedCapability: region.requestedCapability,
-    reason:
-      typeof region.reason === 'string' && region.reason.trim() !== ''
-        ? region.reason
-        : `No exact metadata-supported ZORA element was selected for region "${region.id}".`,
-    ...(typeof region.evidenceId === 'string' ? { evidenceId: region.evidenceId } : {}),
-  };
-  assertSupportedProps(props, missingMeta, region.id);
+  const reason =
+    typeof region.reason === 'string' && region.reason.trim() !== ''
+      ? region.reason
+      : `No exact metadata-supported ZORA element was selected for region "${region.id}".`;
   const gap = {
-    id: `missing-element:${region.id}`,
-    scope: 'composition',
-    owner: '@ankhorage/zora',
+    id: `capability-gap:${region.id}`,
+    scope: 'capability',
     regionId: region.id,
     requestedCapability: region.requestedCapability,
     evidenceId: region.evidenceId ?? null,
-    ownerIssueUrl: region.ownerIssueUrl ?? null,
-    reason: props.reason,
-    unblockCondition: 'Replace MissingElement with a released exact ZORA element and revalidate.',
+    reason,
   };
   return {
-    node: { id: region.id, type: missingMeta.name, props },
-    diagnostic: { regionId: region.id, status: 'missing', component: missingMeta.name, ...gap },
+    node: { id: region.id, type: placeholderMeta.name, props: {} },
+    diagnostic: {
+      regionId: region.id,
+      status: 'placeholder',
+      component: placeholderMeta.name,
+      ...gap,
+    },
     gap,
   };
 }

package/dist/tools/skills/assets/zora-designer/scripts/scaffold-template.mjs

@@ -1,22 +1,20 @@
 #!/usr/bin/env bun
 
-import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { access, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { join, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
+import { generateTemplateCatalog } from './generate-template-catalog.mjs';
 import { loadOwnerApis } from './owner-api.mjs';
 
-/*** Validate and scaffold one ready authored manifest into the normal Templates variant layout. */
+/*** Scaffold one complete portable template and refresh filesystem discovery. */
 export async function scaffoldTemplate(input) {
   assertRecord(input, 'Scaffold input');
-  for (const field of ['targetDirectory', 'category', 'templateId', 'label', 'description']) {
+  for (const field of ['targetDirectory', 'category', 'slug']) {
     assertNonEmptyString(input[field], field);
   }
-  if (
-    !/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(input.templateId) ||
-    ['default', 'starter'].includes(input.templateId)
-  ) {
-    throw new Error('templateId must be a non-reserved kebab-case identifier.');
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(input.slug)) {
+    throw new Error('slug must be a kebab-case identifier.');
   }
   assertRecord(input.manifest, 'manifest');
 
@@ -30,165 +28,85 @@ export async function scaffoldTemplate(input) {
   if (input.manifest.metadata?.category !== input.category) {
     throw new Error('Scaffold category must match manifest.metadata.category.');
   }
+  if (input.manifest.metadata?.slug !== input.slug) {
+    throw new Error('Scaffold slug must match manifest.metadata.slug.');
+  }
 
   const owners = await loadOwnerApis(targetDirectory);
   const composition = owners.templates.validateTemplateManifest(input.manifest, 'release');
-  if (composition.status !== 'ready') {
-    throw new Error(
-      `Manifest is not release-ready: ${composition.diagnostics.map((item) => item.message).join('; ')}`,
-    );
-  }
   const manifest = owners.templates.assertTemplateManifestReady(composition);
-  const categoryDirectoryName = input.category.replaceAll('_', '-');
+
   const categoryDirectory = resolve(
     targetDirectory,
-    'src/templates/starter/categories',
-    categoryDirectoryName,
+    'src/templates/categories',
+    input.category.replaceAll('_', '-'),
   );
   assertInside(targetDirectory, categoryDirectory);
-  const variantDirectory = resolve(categoryDirectory, input.templateId);
-  assertInside(categoryDirectory, variantDirectory);
-  if (await pathExists(variantDirectory)) {
+
+  const templateDirectory = resolve(categoryDirectory, input.slug);
+  assertInside(categoryDirectory, templateDirectory);
+  if (await pathExists(templateDirectory)) {
     throw new Error(
-      `Template source already exists: ${relative(targetDirectory, variantDirectory)}`,
+      `Template source already exists: ${relative(targetDirectory, templateDirectory)}`,
     );
   }
 
-  const registryPath = join(categoryDirectory, 'index.ts');
-  const registrySource = await readFile(registryPath, 'utf8');
-  const symbol = toPascalCase(input.templateId);
-  const factoryBase = symbol.endsWith('Starter') ? symbol.slice(0, -'Starter'.length) : symbol;
-  const factoryName = `create${factoryBase}StarterTemplate`;
-  const manifestName = `AUTHORED_${toConstantCase(input.templateId)}_MANIFEST`;
-  const registrySourceUpdated = updateCategoryRegistry(registrySource, {
-    templateId: input.templateId,
-    label: input.label,
-    description: input.description,
-    factoryName,
-  });
-  const files = createTemplateFiles({ manifest, manifestName, factoryName });
-
-  await mkdir(variantDirectory, { recursive: true });
-  for (const [fileName, contents] of Object.entries(files)) {
-    await writeFile(join(variantDirectory, fileName), contents);
-  }
-  await writeFile(registryPath, registrySourceUpdated);
+  const screensDirectory = join(templateDirectory, 'assets', 'screens');
+  const imagesDirectory = join(templateDirectory, 'assets', 'images');
+  await mkdir(screensDirectory, { recursive: true });
+  await mkdir(imagesDirectory, { recursive: true });
+  await writeFile(
+    join(templateDirectory, 'createAppManifest.ts'),
+    createManifestSource(manifest),
+    'utf8',
+  );
+  await rm(join(categoryDirectory, '.gitkeep'), { force: true });
+  await generateTemplateCatalog(targetDirectory, owners.contracts.APP_CATEGORIES);
 
   return {
     targetDirectory,
-    registryPath: relative(targetDirectory, registryPath),
-    createdFiles: Object.keys(files).map((fileName) =>
-      relative(targetDirectory, join(variantDirectory, fileName)),
-    ),
-    factoryName,
+    templateDirectory: relative(targetDirectory, templateDirectory),
+    createdFiles: [relative(targetDirectory, join(templateDirectory, 'createAppManifest.ts'))],
+    assetDirectories: [
+      relative(targetDirectory, screensDirectory),
+      relative(targetDirectory, imagesDirectory),
+    ],
   };
 }
 
-/*** Create normal manifest, factory, and entrypoint source for one authored starter variant. */
-function createTemplateFiles({ manifest, manifestName, factoryName }) {
-  const manifestSource = `import type { AppManifest } from '@ankhorage/contracts';
-
-export const ${manifestName} = ${JSON.stringify(manifest, null, 2)} satisfies AppManifest;
-`;
-  const templateSource = `import type { AppManifest } from '@ankhorage/contracts';
+/*** Serialize one complete manifest as the template's canonical default export. */
+function createManifestSource(manifest) {
+  return `import type { AppManifest } from '@ankhorage/contracts';
 
-import type { TemplateSeed } from '../../../starter.types';
-import { ${manifestName} } from './manifest';
+const manifest = ${JSON.stringify(manifest, null, 2)} satisfies AppManifest;
 
-/*** Create the authored starter while applying the caller's canonical app identity and theme. */
-export function ${factoryName}(seed: TemplateSeed): AppManifest {
-  const theme = seed.theme ?? ${manifestName}.themes[0];
-  if (theme === undefined) {
-    throw new Error('The authored template requires one resolved theme.');
-  }
-  return {
-    ...${manifestName},
-    metadata: {
-      ...${manifestName}.metadata,
-      name: seed.appName,
-      slug: seed.slug,
-      version: seed.version ?? ${manifestName}.metadata.version,
-      themeId: theme.id,
-    },
-    themes: [theme],
-    activeThemeId: theme.id,
-  };
+/*** Create the complete portable application manifest for this template. */
+export default function createAppManifest(): AppManifest {
+  return structuredClone(manifest);
 }
 `;
-  return {
-    'index.ts': `export { ${factoryName} } from './template';\n`,
-    'manifest.ts': manifestSource,
-    'template.ts': templateSource,
-  };
-}
-
-/*** Add one stable import and definition to an existing category registry. */
-function updateCategoryRegistry(source, definition) {
-  const importLine = `import { ${definition.factoryName} } from './${definition.templateId}';`;
-  if (source.includes(`id: '${definition.templateId}'`) || source.includes(importLine)) {
-    throw new Error(`Template is already registered: ${definition.templateId}`);
-  }
-  const exportMarker = '\nexport const ';
-  const exportIndex = source.indexOf(exportMarker);
-  if (exportIndex < 0) {
-    throw new Error('Category registry does not expose its canonical template array.');
-  }
-  const prefixLines = source.slice(0, exportIndex).trimEnd().split('\n');
-  const relativeImports = [
-    ...prefixLines.filter((line) => /^import .* from '\.\//u.test(line)),
-    importLine,
-  ].sort((left, right) => left.localeCompare(right));
-  const preservedPrefix = prefixLines.filter((line) => !/^import .* from '\.\//u.test(line));
-  const withImport = `${[...preservedPrefix, ...relativeImports].join('\n')}\n${source.slice(exportIndex + 1)}`;
-  const closeMarker = '] satisfies readonly CategoryStarterTemplateDefinition[];';
-  const closeIndex = withImport.indexOf(closeMarker);
-  if (closeIndex < 0) {
-    throw new Error('Category registry is missing its canonical definition-array terminator.');
-  }
-  const entry = `  {
-    id: '${escapeSingleQuoted(definition.templateId)}',
-    label: '${escapeSingleQuoted(definition.label)}',
-    description: '${escapeSingleQuoted(definition.description)}',
-    create: ${definition.factoryName},
-  },
-`;
-  return `${withImport.slice(0, closeIndex)}${entry}${withImport.slice(closeIndex)}`;
-}
-
-/*** Convert kebab-case identifiers to a PascalCase source symbol. */
-function toPascalCase(value) {
-  return value
-    .split('-')
-    .map((segment) => segment[0].toUpperCase() + segment.slice(1))
-    .join('');
-}
-
-/*** Convert kebab-case identifiers to an uppercase constant name. */
-function toConstantCase(value) {
-  return value.replaceAll('-', '_').toUpperCase();
-}
-
-/*** Escape content placed in generated single-quoted TypeScript strings. */
-function escapeSingleQuoted(value) {
-  return value.replaceAll('\\', '\\\\').replaceAll("'", "\\'");
 }
 
 /*** Assert that a resolved output remains inside its declared owner directory. */
-function assertInside(parentDirectory, childPath) {
-  const relativePath = relative(parentDirectory, childPath);
-  if (relativePath === '' || relativePath.startsWith(`..${sep}`) || relativePath === '..') {
-    throw new Error(`Scaffold path escapes its owner directory: ${childPath}`);
+function assertInside(parentPath, childPath) {
+  const relativePath = relative(parentPath, childPath);
+  if (
+    relativePath === '' ||
+    relativePath === '..' ||
+    relativePath.startsWith(`..${sep}`) ||
+    relativePath.startsWith('../')
+  ) {
+    throw new Error(`Template path escapes its owner directory: ${childPath}`);
   }
 }
 
-/*** Return whether a filesystem path already exists. */
-async function pathExists(path) {
+/*** Return whether a filesystem path exists. */
+async function pathExists(filePath) {
   try {
-    await access(path);
+    await access(filePath);
     return true;
-  } catch (error) {
-    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return false;
-    throw error;
+  } catch {
+    return false;
   }
 }
 
@@ -209,8 +127,10 @@ function assertNonEmptyString(value, label) {
 /*** Run deterministic Templates source scaffolding from one JSON input. */
 async function main() {
   const [inputPath] = process.argv.slice(2);
-  if (!inputPath) throw new Error('Usage: scaffold-template.mjs <scaffold-input.json>');
-  const input = JSON.parse(await readFile(inputPath, 'utf8'));
+  if (!inputPath) {
+    throw new Error('Usage: scaffold-template.mjs <scaffold-input.json>');
+  }
+  const input = JSON.parse(await readFile(resolve(inputPath), 'utf8'));
   console.log(JSON.stringify(await scaffoldTemplate(input), null, 2));
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.10.11",
+  "version": "1.10.13",
   "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",