pi-apexlang 0.1.0

package/skills/apexlang/runtime/runtime_resolution.mjs

@@ -0,0 +1,234 @@
+/**
+ * Pure runtime resolution helpers for import intent, build-root lookup, and candidate selection.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const DOTTED_SIGNATURE_PATTERN = /(?<version>\d+(?:\.\d+){2,})[_-](?<build>\d+)/g;
+const UNDERSCORED_BUILD_SIGNATURE_PATTERN = /(?<major>\d+)_(?<minor>\d+)_(?<patch>\d+)_(?<build>\d+)/g;
+const EXECUTION_MODES = new Set(["auto", "path", "build-root"]);
+const RUNTIME_ACTIONS = new Set(["validate-only", "validate-and-import"]);
+/**
+ * Direct CLI reminder for explicit import intent; agent UX defaults to check-only and offers GUI import choices after the live APEXlang check.
+ */
+export const IMPORT_INTENT_PROMPT =
+  "Direct runtime roundtrip calls require an import intent. Codex workflows default to checking APEXlang code and offer GUI import choices after the live APEXlang check.";
+
+/**
+ * Normalize runtime execution mode input to auto, build-root, or path.
+ */
+export function normalizeExecutionMode(value) {
+  return EXECUTION_MODES.has(value) ? value : "auto";
+}
+
+/**
+ * Normalize legacy runtime action wording to import-intent-compatible values.
+ */
+export function normalizeRuntimeAction(value) {
+  return RUNTIME_ACTIONS.has(value) ? value : "";
+}
+
+/**
+ * Resolve and validate the per-run validate-only versus validate-and-import decision.
+ */
+export function resolveImportIntent({ importIntentChoice = "", importIntentSource = "" } = {}) {
+  const normalizedChoice = normalizeRuntimeAction(importIntentChoice);
+  if (!normalizedChoice) {
+    return {
+      status: "missing",
+      import_intent_prompted: false,
+      import_intent_choice: "unresolved",
+      import_intent_source: "",
+      note: `Missing Inputs: ${IMPORT_INTENT_PROMPT}`
+    };
+  }
+  return {
+    status: "pass",
+    import_intent_prompted: true,
+    import_intent_choice: normalizedChoice,
+    import_intent_source: importIntentSource || "test_injection",
+    note: ""
+  };
+}
+
+/**
+ * Extract the build-root connection signature from a saved SQLcl connection name.
+ */
+export function parseConnectionSignature(dbConnectionName = "") {
+  const dottedMatches = [...dbConnectionName.matchAll(DOTTED_SIGNATURE_PATTERN)];
+  const underscoredMatches = [...dbConnectionName.matchAll(UNDERSCORED_BUILD_SIGNATURE_PATTERN)];
+  if (dottedMatches.length === 0 && underscoredMatches.length === 0) {
+    return null;
+  }
+  const dottedMatch = dottedMatches.at(-1);
+  const underscoredMatch = underscoredMatches.at(-1);
+  const dottedIndex = dottedMatch?.index ?? -1;
+  const underscoredIndex = underscoredMatch?.index ?? -1;
+  const useUnderscored = underscoredIndex > dottedIndex;
+  const version = useUnderscored
+    ? `${underscoredMatch.groups.major}.${underscoredMatch.groups.minor}.${underscoredMatch.groups.patch}`
+    : dottedMatch.groups.version;
+  const build = useUnderscored ? underscoredMatch.groups.build : dottedMatch.groups.build;
+  const versionParts = version.split(".");
+  if (versionParts.length < 3) {
+    return null;
+  }
+  const buildVersion = versionParts.length > 3
+    ? `${versionParts.slice(0, -1).join(".")}-${versionParts.at(-1)}`
+    : version;
+  return {
+    version,
+    build,
+    build_version: buildVersion,
+    signature: `${buildVersion}+${build}`
+  };
+}
+
+/**
+ * Build the standard build-root diagnostic payload when no DB connection is supplied.
+ */
+export function buildMissingConnectionResult(apexRoot = path.resolve(path.join(os.homedir(), "apex"))) {
+  return {
+    status: "fail",
+    reason: "db_connection_name_required",
+    apex_root: apexRoot,
+    connection_signature: null,
+    available_build_paths: [],
+    candidate_paths: [],
+    resolved_apex_build_root: "",
+    recommended_cwd: "",
+    flow_sql_present: false,
+    next_action: "Provide --db-connection-name to resolve a matching build root."
+  };
+}
+
+/**
+ * Resolve the local APEX build root associated with a DB connection signature.
+ */
+export function resolveBuildRootInfo({ dbConnectionName = "", apexRoot = path.join(os.homedir(), "apex") } = {}) {
+  const resolvedApexRoot = path.resolve(apexRoot);
+  const signature = parseConnectionSignature(dbConnectionName);
+  const result = {
+    status: "fail",
+    reason: "",
+    apex_root: resolvedApexRoot,
+    connection_signature: signature,
+    available_build_paths: [],
+    candidate_paths: [],
+    resolved_apex_build_root: "",
+    recommended_cwd: "",
+    flow_sql_present: false,
+    next_action: ""
+  };
+
+  try {
+    const entries = readdirSync(resolvedApexRoot, { withFileTypes: true });
+    result.available_build_paths = entries
+      .filter((entry) => entry.isDirectory() && entry.name.startsWith("build-"))
+      .map((entry) => path.join(resolvedApexRoot, entry.name))
+      .sort();
+  } catch {
+    result.reason = "apex_root_missing";
+    result.next_action = "Provide a valid local apex root or override --apex-root.";
+    return result;
+  }
+
+  if (!signature) {
+    result.reason = "connection_alias_not_parseable";
+    result.next_action = "Use a db_connection_name that encodes the APEX version/build signature.";
+    return result;
+  }
+
+  const candidates = result.available_build_paths.filter((entry) =>
+    path.basename(entry).startsWith(`build-${signature.build_version}+${signature.build}`)
+  );
+  result.candidate_paths = candidates;
+
+  const validCandidates = candidates.filter((entry) => existsSync(path.join(entry, "core", "flow.sql")));
+  if (candidates.length === 0) {
+    result.reason = "matching_build_not_found";
+    result.next_action = "Install or restore the matching local APEX build.";
+    return result;
+  }
+  if (validCandidates.length === 0) {
+    result.reason = "matching_build_missing_core_flow";
+    result.next_action = "Use a complete APEX build root that contains core/flow.sql.";
+    return result;
+  }
+  if (validCandidates.length > 1) {
+    result.reason = "matching_build_ambiguous";
+    result.candidate_paths = validCandidates;
+    result.next_action = "Resolve the matching build root explicitly.";
+    return result;
+  }
+
+  result.status = "pass";
+  result.reason = "resolved";
+  result.resolved_apex_build_root = validCandidates[0];
+  result.recommended_cwd = validCandidates[0];
+  result.flow_sql_present = true;
+  result.next_action = "Use this build root for build-root runtime execution or diagnostics.";
+  return result;
+}
+
+/**
+ * Choose the usable runtime candidate according to requested execution mode.
+ */
+export function selectRuntimeCandidate(executionMode, pathSqlcl, buildRootRuntime) {
+  const normalizedMode = normalizeExecutionMode(executionMode);
+  if (normalizedMode === "path") {
+    return pathSqlcl.required_runtime_commands_available ? pathSqlcl : null;
+  }
+  if (normalizedMode === "build-root") {
+    return buildRootRuntime.required_runtime_commands_available ? buildRootRuntime : null;
+  }
+  if (buildRootRuntime.required_runtime_commands_available) {
+    return buildRootRuntime;
+  }
+  if (pathSqlcl.required_runtime_commands_available) {
+    return pathSqlcl;
+  }
+  return null;
+}
+
+/**
+ * Explain why a runtime candidate was selected or why none was available.
+ */
+export function describeRuntimeSelection({ executionMode, selectedRuntime, buildRootInfo, pathSqlcl }) {
+  const normalizedMode = normalizeExecutionMode(executionMode);
+  if (selectedRuntime?.candidate === "build-root") {
+    return {
+      reason: buildRootInfo.reason || "resolved",
+      note: "Selected the build-root runtime resolved from db_connection_name."
+    };
+  }
+  if (selectedRuntime?.candidate === "path") {
+    if (normalizedMode === "path") {
+      return {
+        reason: "path_runtime_forced",
+        note: "Selected PATH SQLcl because execution mode was forced to path."
+      };
+    }
+    if (buildRootInfo.status !== "pass") {
+      return {
+        reason: buildRootInfo.reason || "build_root_unavailable",
+        note: "Selected PATH SQLcl because no connection-derived build-root runtime was available."
+      };
+    }
+    return {
+      reason: "path_runtime_selected",
+      note: "Selected PATH SQLcl because the connection-derived build-root runtime was not capability-ready."
+    };
+  }
+  if (normalizedMode === "build-root") {
+    return {
+      reason: buildRootInfo.reason || "build_root_unavailable",
+      note: "Build-root mode failed because the connection-derived build-root runtime was unavailable."
+    };
+  }
+  return {
+    reason: pathSqlcl?.capability_state || buildRootInfo.reason || "runtime_unavailable",
+    note: "No executable runtime path was available after evaluating connection-derived build-root and PATH SQLcl candidates."
+  };
+}

package/skills/apexlang/runtime/sqlcl_preflight.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+
+/**
+ * Standalone SQLcl preflight probe for PATH and build-root runtime capabilities.
+ */
+
+import { spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import { dirname, resolve } from "node:path";
+import process from "node:process";
+import { apexlangOutputRoot, isPackagedSkillRuntime } from "./lib/common.mjs";
+import {
+  buildMissingConnectionResult,
+  describeRuntimeSelection,
+  normalizeExecutionMode,
+  resolveBuildRootInfo,
+  selectRuntimeCandidate
+} from "./runtime_resolution.mjs";
+
+/**
+ * Read a CLI option from process arguments for the standalone preflight script.
+ */
+function readOption(name, fallback = "") {
+  const index = process.argv.indexOf(name);
+  if (index === -1 || index + 1 >= process.argv.length) {
+    return fallback;
+  }
+  return process.argv[index + 1];
+}
+
+/**
+ * Run a probe command synchronously and return normalized output metadata.
+ */
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd,
+    encoding: "utf8",
+    input: options.input
+  });
+  return {
+    code: typeof result.status === "number" ? result.status : 1,
+    output: `${result.stdout ?? ""}${result.stderr ?? ""}`.trim(),
+    error: result.error ? String(result.error.message || result.error) : ""
+  };
+}
+
+/**
+ * Check command help output for a case-insensitive capability phrase.
+ */
+function hasWord(output, word) {
+  return new RegExp(`\\b${word}\\b`, "i").test(output);
+}
+
+/**
+ * Locate the sql executable on PATH and record the selected entrypoint.
+ */
+function pickPathSqlcl() {
+  const candidates = process.platform === "win32" ? ["sql.exe", "sql"] : ["sql", "sql.exe"];
+  for (const candidate of candidates) {
+    const result = run(candidate, ["-v"]);
+    if (!result.error) {
+      return { executable: candidate, version: result.output };
+    }
+  }
+  return null;
+}
+
+/**
+ * Probe PATH SQLcl for APEX validate, import, and export command support.
+ */
+function probePathSqlcl(executable) {
+  const apex = run(executable, ["/nolog"], { input: "help apex\nexit\n" });
+  const validate = run(executable, ["/nolog"], { input: "help apex validate\nexit\n" });
+  const imp = run(executable, ["/nolog"], { input: "help apex import\nexit\n" });
+  const exp = run(executable, ["/nolog"], { input: "help apex export\nexit\n" });
+  const result = {
+    candidate: "path",
+    runtime_entrypoint: "sql on PATH",
+    authenticated_connect_order: ["sql -name <db_connection_name>", "sql <db_connection_name>", "sql /nolog + connect <db_connection_name>"],
+    sqlcl_found: true,
+    executable,
+    version_raw: "",
+    version_recorded: false,
+    apex_command_available: hasWord(apex.output, "apex"),
+    apex_validate_available: hasWord(validate.output, "validate"),
+    apex_import_available: hasWord(imp.output, "import"),
+    apex_export_available: hasWord(exp.output, "export"),
+    required_runtime_commands_available: false,
+    runtime_validate_enabled: false,
+    runtime_import_enabled: false,
+    runtime_export_enabled: false,
+    capability_state: "sqlcl_missing",
+    notes: []
+  };
+
+  const version = run(executable, ["-v"]);
+  result.version_raw = version.output;
+  result.version_recorded = Boolean(version.output);
+  result.runtime_validate_enabled = result.apex_command_available && result.apex_validate_available;
+  result.required_runtime_commands_available =
+    result.apex_command_available && result.apex_validate_available && result.apex_import_available;
+  result.runtime_import_enabled = result.required_runtime_commands_available;
+  result.runtime_export_enabled = result.apex_command_available && result.apex_export_available;
+  if (result.required_runtime_commands_available) {
+    result.capability_state = "path_sqlcl_apex_validate_import";
+  } else if (result.runtime_validate_enabled) {
+    result.capability_state = "path_sqlcl_apex_validate_only";
+  } else if (result.apex_command_available) {
+    result.capability_state = "path_sqlcl_apex_base";
+  } else {
+    result.capability_state = "path_sqlcl_db_only";
+  }
+  if (!result.required_runtime_commands_available) {
+    result.notes.push("PATH SQLcl is present, but validate/import capability is incomplete.");
+  }
+  return result;
+}
+
+/**
+ * Probe the resolved build-root APEX CLI for SQLcl-backed runtime capabilities.
+ */
+function probeBuildRootRuntime(buildRootInfo) {
+  const result = {
+    candidate: "build-root",
+    runtime_entrypoint: "apex sql from resolved build root",
+    authenticated_connect_order: ["apex sql (resolved build root)", "sql -name <db_connection_name>", "sql <db_connection_name>", "sql /nolog + connect <db_connection_name>"],
+    resolved_apex_build_root: buildRootInfo.resolved_apex_build_root,
+    recommended_cwd: buildRootInfo.recommended_cwd,
+    apex_cli_found: false,
+    executable: "apex",
+    version_raw: "",
+    version_recorded: false,
+    apex_command_available: false,
+    apex_validate_available: false,
+    apex_import_available: false,
+    apex_export_available: false,
+    required_runtime_commands_available: false,
+    runtime_validate_enabled: false,
+    runtime_import_enabled: false,
+    runtime_export_enabled: false,
+    capability_state: "build_root_unavailable",
+    notes: []
+  };
+
+  if (buildRootInfo.status !== "pass") {
+    result.capability_state = "build_root_unresolved";
+    result.notes.push(buildRootInfo.reason || "build_root_unresolved");
+    return result;
+  }
+
+  const help = run("apex", ["--help"], { cwd: buildRootInfo.recommended_cwd });
+  if (help.error || (!help.output && help.code !== 0)) {
+    result.capability_state = "build_root_apex_cli_missing";
+    result.notes.push(help.error || "apex CLI is not available from the resolved build root.");
+    return result;
+  }
+
+  const sqlHelp = run("apex", ["sql", "--help"], { cwd: buildRootInfo.recommended_cwd });
+  const validateHelp = run("apex", ["validate", "--help"], { cwd: buildRootInfo.recommended_cwd });
+  const importHelp = run("apex", ["import", "--help"], { cwd: buildRootInfo.recommended_cwd });
+  const exportHelp = run("apex", ["export", "--help"], { cwd: buildRootInfo.recommended_cwd });
+  result.apex_cli_found = true;
+  result.version_raw = help.output;
+  result.version_recorded = Boolean(help.output);
+  result.apex_command_available = hasWord(sqlHelp.output, "SQLcl");
+  result.apex_validate_available = hasWord(validateHelp.output, "Validate APEX");
+  result.apex_import_available = hasWord(importHelp.output, "Import one or more apps");
+  result.apex_export_available = hasWord(exportHelp.output, "Export one or more apps");
+  result.runtime_validate_enabled = result.apex_command_available && result.apex_validate_available;
+  result.required_runtime_commands_available =
+    result.apex_command_available && result.apex_validate_available && result.apex_import_available;
+  result.runtime_import_enabled = result.required_runtime_commands_available;
+  result.runtime_export_enabled = result.apex_export_available;
+  if (result.required_runtime_commands_available) {
+    result.capability_state = "build_root_apex_sql_validate_import";
+  } else if (result.runtime_validate_enabled) {
+    result.capability_state = "build_root_apex_sql_validate_only";
+  } else if (result.apex_cli_found) {
+    result.capability_state = "build_root_apex_cli_only";
+  }
+  if (!result.required_runtime_commands_available) {
+    result.notes.push("Resolved build root is present, but apex CLI validate/import capability is incomplete.");
+  }
+  return result;
+}
+
+const dbConnectionName = readOption("--db-connection-name", readOption("--db-connection", ""));
+const executionMode = normalizeExecutionMode(readOption("--execution-mode", "auto"));
+const apexRoot = resolve(readOption("--apex-root", resolve(os.homedir(), "apex")));
+const defaultReportPath = isPackagedSkillRuntime()
+  ? resolve(apexlangOutputRoot(), "logs", "runtime-preflight.json")
+  : resolve(process.cwd(), "artifacts/logs/runtime-preflight.json");
+const reportPath = resolve(readOption("--report-path", defaultReportPath));
+
+const pathSqlcl = (() => {
+  const sqlcl = pickPathSqlcl();
+  if (!sqlcl) {
+    return {
+      candidate: "path",
+      runtime_entrypoint: "sql on PATH",
+      authenticated_connect_order: ["sql -name <db_connection_name>", "sql <db_connection_name>", "sql /nolog + connect <db_connection_name>"],
+      sqlcl_found: false,
+      executable: "",
+      version_raw: "",
+      version_recorded: false,
+      apex_command_available: false,
+      apex_validate_available: false,
+      apex_import_available: false,
+      apex_export_available: false,
+      required_runtime_commands_available: false,
+      runtime_validate_enabled: false,
+      runtime_import_enabled: false,
+      runtime_export_enabled: false,
+      capability_state: "sqlcl_missing",
+      notes: ["sql was not found on PATH."]
+    };
+  }
+  return probePathSqlcl(sqlcl.executable);
+})();
+
+const buildRootInfo = dbConnectionName
+  ? resolveBuildRootInfo({ dbConnectionName, apexRoot })
+  : buildMissingConnectionResult(apexRoot);
+
+const buildRootRuntime = probeBuildRootRuntime(buildRootInfo);
+const selectedRuntime = selectRuntimeCandidate(executionMode, pathSqlcl, buildRootRuntime);
+const selection = describeRuntimeSelection({
+  executionMode,
+  selectedRuntime,
+  buildRootInfo,
+  pathSqlcl
+});
+
+const status = {
+  timestamp: new Date().toISOString(),
+  platform: process.platform,
+  db_connection_name: dbConnectionName,
+  connection_signature: buildRootInfo.connection_signature,
+  execution_mode_requested: executionMode,
+  execution_mode_used: selectedRuntime?.candidate ?? "",
+  reason: selection.reason,
+  runtime_selection_note: selection.note,
+  runtime_entrypoint: selectedRuntime?.runtime_entrypoint ?? "",
+  resolved_apex_build_root: buildRootInfo.resolved_apex_build_root,
+  authenticated_connect_order: selectedRuntime?.authenticated_connect_order ?? [],
+  sqlcl_found: Boolean(selectedRuntime?.required_runtime_commands_available),
+  sqlcl_executable: selectedRuntime?.executable ?? "",
+  sqlcl_version_raw: selectedRuntime?.version_raw ?? "",
+  sqlcl_version_recorded: Boolean(selectedRuntime?.version_recorded),
+  apex_command_available: Boolean(selectedRuntime?.apex_command_available),
+  apex_validate_available: Boolean(selectedRuntime?.apex_validate_available),
+  apex_import_available: Boolean(selectedRuntime?.apex_import_available),
+  apex_export_available: Boolean(selectedRuntime?.apex_export_available),
+  required_runtime_commands_available: Boolean(selectedRuntime?.required_runtime_commands_available),
+  runtime_validate_enabled: Boolean(selectedRuntime?.runtime_validate_enabled),
+  runtime_import_enabled: Boolean(selectedRuntime?.runtime_import_enabled),
+  runtime_export_enabled: Boolean(selectedRuntime?.runtime_export_enabled),
+  capability_state: selectedRuntime?.capability_state ?? "runtime_unavailable",
+  path_sqlcl: pathSqlcl,
+  build_root_runtime: {
+    ...buildRootInfo,
+    ...buildRootRuntime
+  },
+  notes: []
+};
+
+if (!selectedRuntime) {
+  status.notes.push(selection.note);
+}
+status.notes.push(...pathSqlcl.notes);
+status.notes.push(...buildRootRuntime.notes);
+
+mkdirSync(dirname(reportPath), { recursive: true });
+writeFileSync(reportPath, JSON.stringify(status, null, 2));
+process.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
+process.exitCode = selectedRuntime ? 0 : 1;

package/skills/apexlang/templates/README.md

@@ -0,0 +1,72 @@
+# APEXlang Templates
+
+## Purpose
+Central index for the canonical APEXlang template families used by routers, skills, and memory-bank guided generation.
+
+## What is in this directory
+
+- `base-app-structure/`
+  - Root Markdown and JSON files are the canonical documentation and metadata contract.
+  - Runtime seed metadata stays at `base-app-structure/base-app-runtime-seed.manifest.json`.
+  - Executable scaffold payload lives under `base-app-structure/scaffold-example/`.
+- `business-logic/`
+  - Computation, dynamic action, and validation template families.
+- `buttons/` and `items/`
+  - Canonical button and item template families.
+- `page-examples/`
+  - Full page examples that combine layout, regions, and common behaviors.
+- `page-layout-templates/`
+  - Markdown-first Universal Theme layout contracts, shared page-template guidance, and family variants.
+- `region-components/`
+  - Region-family templates such as reports, forms, charts, cards, and maps.
+- `shared-components/`
+  - Shared APEX component templates such as LOVs, lists, breadcrumbs, and app-level settings.
+- `template-components/`
+  - Reusable UI-oriented template components.
+- `workspace-components/`
+  - Workspace-level templates when present.
+- `_common_variables.template.md`
+  - Shared variable catalog used across template families.
+
+## How to use this directory
+
+- Start with the family directory that matches the requested component or workflow scope.
+- For page-scoped generation, start in `page-examples/` before drilling into region, item, button, or shared-component families.
+- Load the family `_common.md` contract first, then load variant/scenario markdown files.
+- Use markdown families as canonical targets in routers and registries.
+- Use `template-family-registry.json` as the machine-readable template family registry for family discovery; it is not a domain routing catalog.
+- Keep references aligned with `assets/rules-mapping.json` and skill entrypoints.
+- Do not use `applications/**` as a pattern source or scaffold reference for any template family in this directory.
+
+## Core DSL Shape Rules
+
+- `name { ... }` means `name` is a nested block or section.
+- `name: ...` means `name` is a property assignment.
+- `name: { ... }` means `name` is a property whose value is an object.
+- Do not normalize between block syntax and property-object syntax by analogy. Follow compiler-backed truth and the emitted shape from the owning template family.
+- Keep structural DSL multiline and block-safe:
+  - emit one property assignment per line
+  - do not place two sibling properties on the same line
+  - for object-valued properties, emit `name: {` on its own line, then nested properties on following lines
+  - do not compress nested objects onto one line such as `viewEditLink: { page: 16 items: { P16_ID: &ID. } }`
+  - do not open a property-object and emit nested property content on the same line
+  - do not rely on inline compact object syntax even when it looks unambiguous; use expanded multiline object syntax instead
+
+## Template Catalog
+- `base-app-structure/`
+- `business-logic/`
+- `buttons/`
+- `items/`
+- `page-examples/`
+- `page-layout-templates/`
+- `region-components/`
+- `shared-components/`
+- `template-components/`
+- `workspace-components/`
+- `template-family-registry.json`
+- `_common_variables.template.md`
+
+## Maintenance
+- Keep this README synchronized with actual files in the directory.
+- Update catalogs and usage notes whenever templates are added, removed, or renamed.
+- Ensure top-level guidance remains consistent with governance, routing assets, and canonical template path policy.

package/skills/apexlang/templates/_common_variables.template.md

@@ -0,0 +1,27 @@
+# Component Common Variables
+Canonical lookup for shared attributes. Replace bracketed placeholders and catalog entries with component-specific details.
+
+## Gospel Skeleton
+```apexlang
+[component] [staticId] (
+    name: [name]
+    -- add component sections here
+)
+```
+
+### Placeholders
+- `[staticId]` — unique identifier guidance.
+- `[name]` — primary label guidance.
+- Add bullets for each placeholder defined in the skeleton.
+
+## Sections
+- Document recurring sections (e.g., `serverCache`, `error`, `comments`).
+- Briefly explain when to include or omit each section.
+
+## Attribute Catalog
+- `attribute.path` — required/optional notes, accepted values, dependencies.
+- Repeat for each attribute relevant to the component type.
+
+## Usage Notes
+- Add cross-cutting rules (e.g., formatting, quoting, caching behavior).
+- Clarify expectations like triple backticks, button alias references, etc.