pi-apexlang 0.2.2 → 0.4.0

package/skills/apexlang/templates/template-components/README.md

@@ -9,21 +9,33 @@ Catalog of canonical markdown-first template-component families and their routin
 - Use the dedicated owner `*_template_options.md` file when the request changes helper/template-component plugin attributes or settings.
 - When a row includes `values=`, pass the left-hand side of each `name=>return_value` pair, not the emitted CSS or return token.
 - Use `template-components.registry.json` for tooling discovery and preserve markdown-first conventions when updating workflow or registry links.
-- For report-type template components, use explicit child `column (...)` structures by default and keep them aligned with the delivered region source projection.
-  This default applies to Content Row, Metric Card, Media List, and Comments. Do not satisfy the compiler by adding only one placeholder child column when the source projects multiple fields.
+- For report-type template components, emit one compiler-appropriate child column for every delivered source projection. Resolve the active target-build grammar before choosing a child-column variant. Media List must use the single column declaration and property shape selected by that contract; do not hardcode a compiler component type across builds.
+- This default applies to Content Row, Metric Card, Media List, and Comments, while the target-build contract still determines each family's exact column declaration.
+- Do not mix template-component column variants or satisfy projection coverage with one placeholder child column.
 - For any template component that emits `rowSelection` with a non-null mode, mark one child column as the identity column with `source.primaryKey: true`.
+- For Metric Card, query-backed title, metric, and meta text uses `&COLUMN.` substitution.
+- Metric Card's nested Avatar/Badge groups use the Metric Card inventory; selector attributes use bare projected aliases and do not reuse standalone Avatar/Badge region settings.
+- Metric Card row navigation uses only the compiler-backed `link` action position and no action template.
+- Metric Card supports `partial` and `report`; partial mode omits report-only layout/item classes, grouping, row selection, messages, and pagination, while report pagination exposes only `entitiesPerPage`.
 
 ## Template Catalog
 - `actions/`
+- `avatar/`
 - `button/`
 - `content-row/`
 - `metric-card/`
-- `avatar._template_options.md`
-- `badge._template_options.md`
-- `comments._template_options.md`
-- `flexbox-container._template_options.md`
-- `media-list._template_options.md`
-- `timeline._template_options.md`
+- `badge/`
+- `comments/`
+- `flexbox-container/`
+- `media-list/`
+- `timeline/`
+- `avatar/avatar._template_options.md`
+  - Owns standalone Avatar settings and shared Avatar value inventories used by other components
+- `badge/badge._template_options.md`
+- `comments/comments._template_options.md`
+- `flexbox-container/flexbox-container._template_options.md`
+- `media-list/media-list._template_options.md`
+- `timeline/timeline._template_options.md`
 - `template-components.registry.json`
 
 ## Maintenance
@@ -43,15 +55,15 @@ These inventories come from `create_plugin_attribute` and `create_plugin_attr_va
   - Owns `contentRow`
 - `metric-card/metric-card._template_options.md`
   - Owns `metricCard`
-- `avatar._template_options.md`
+- `avatar/avatar._template_options.md`
   - Owns shared `avatar` settings used by multiple template components
-- `badge._template_options.md`
-  - Owns shared `badge` settings used by multiple template components
-- `comments._template_options.md`
+- `badge/badge._template_options.md`
+  - Owns shared `badge` settings used by the standalone Badge family and other template components
+- `comments/comments._template_options.md`
   - Owns `comments`
-- `flexbox-container._template_options.md`
+- `flexbox-container/flexbox-container._template_options.md`
   - Owns `flexboxContainer`
-- `media-list._template_options.md`
+- `media-list/media-list._template_options.md`
   - Owns `mediaList`
-- `timeline._template_options.md`
+- `timeline/timeline._template_options.md`
   - Owns `timeline`

package/skills/apexlang/templates/template-components/avatar/README.md

@@ -0,0 +1,56 @@
+# Avatar Templates
+
+## Purpose
+
+Canonical standalone Avatar template pack for `themeTemplateComponent/avatar` in report mode.
+
+## Usage
+
+- Load `avatar._common.md` first for the shared region, source, ordering, settings, and column contract.
+- Use `avatar._index.md` to select exactly one display scenario.
+- Use `avatar._template_options.md` for accepted Avatar attributes and enum values.
+- Emit one explicit child `column <UPPERCASE_SNAKE_CASE> (...)` for every projected source column; lowercase or hyphenated external identifiers fail live validation.
+- Keep SQL ordering in top-level `orderBy {}`; do not place `ORDER BY` inside `source.sqlQuery`.
+- Bind `settings.initials` with the direct uppercase source-column identifier. Use `&COLUMN_NAME.` only for free-text settings such as `description`, not for the initials column selector.
+- For restricted Avatar data, use `mustNotBePublicUser` or an `@alias` that resolves to an existing shared authorization declaration in the validation set.
+- Use report mode only in this pack. Partial mode requires separate compiler and runtime evidence.
+
+## Action Template Applicability
+
+The Avatar theme export declares the `link` action position but declares no action templates (`actionTemplates: []`). Therefore this pack does not apply an action-template scenario. The separate generic link-action shape remains deferred until its target mapping and security behavior have dedicated evidence.
+
+## Patterns and Anti-Patterns
+
+- Pattern: one report-mode Avatar family selected by initials, icon, or URL-column image.
+- Pattern: explicit source projection, deterministic top-level ordering, and one named template-component child column per projection.
+- Pattern: region authorization using an existing shared authorization scheme when the owning page or application contract restricts access.
+- Pattern: SQL image projections use canonical `:APP_FILES` or `:APEX_FILES` bind concatenation with a static relative path; template tokens, substitutions, BLOB endpoints, unsafe paths, and external URL forms are rejected.
+- Pattern: exact Font APEX catalog membership for literals and every output of a column-backed icon mapping.
+- Pattern: verified descriptions for meaningful Avatars with recorded evidence provenance; decorative templates omit both description property and column and carry the exact decorative-purpose comment.
+- Pattern: native shape, size, and spacing before static component-scoped custom CSS; custom CSS always carries a comments rationale.
+- Anti-pattern: falling back to Classic Report or Interactive Report to simulate Avatar rendering.
+- Anti-pattern: inventing authorization scheme names or relying on UI hiding as authorization.
+- Anti-pattern: raw URL or icon columns, arbitrary icon classes, dynamic CSS substitutions, visibility-changing CSS, or undocumented framework utilities.
+- Anti-pattern: emitting BLOB images, grouping, generic link actions, or partial mode without dedicated evidence.
+
+## Template Catalog
+
+- `avatar._common.md`
+- `avatar._index.md`
+- `avatar.report-initials.md`
+- `avatar.report-icon.md`
+- `avatar.report-image-url-column.md`
+
+## Deferred Variants
+
+- BLOB-backed images
+- report grouping
+- generic link actions (the export has a `link` position but no action templates)
+- partial mode
+
+These variants require dedicated policy or live-runtime confirmation before becoming canonical scenarios.
+
+## Maintenance
+
+- Keep this README, `avatar._index.md`, and `../template-components.registry.json` synchronized.
+- Do not add a scenario from prose or neighboring component behavior alone; require Avatar-specific compiler evidence.

package/skills/apexlang/templates/template-components/avatar/avatar._common.md

@@ -0,0 +1,149 @@
+---
+templateId: region.avatar.common
+componentType: region
+version: 1.0
+description: Shared contract for standalone Avatar report regions.
+---
+
+# Purpose
+
+Document the compiler-backed standalone Avatar region emitted as `themeTemplateComponent/avatar`.
+
+# Generation Rules (MANDATORY)
+
+1. Use `type: themeTemplateComponent/avatar`.
+2. Emit `componentAppearance { display: report }`.
+3. Emit an `appearance {}` block and default to `@/standard` unless an owning page contract proves another region template.
+4. For SQL-backed Avatar regions, keep `source.sqlQuery` unordered and emit deterministic sorting in top-level `orderBy {}`.
+5. Use `settings {}` for standalone Avatar attributes. Do not wrap standalone settings in `plugin-avatar {}`.
+6. Set exactly one Avatar type: `initials`, `icon`, or `image`.
+7. Emit only the payload property activated by the selected type: `initials`, `icon`, or `image`.
+8. For `settings.initials`, emit the direct uppercase source-column identifier such as `AVATAR_INITIALS`; this `sessionStateValue` property selects a column and must not use `&COLUMN_NAME.` substitution syntax.
+9. For initials, bind a declared `varchar2` source column; the Avatar export does not support non-character initials values. Free-text properties such as `settings.description` may use `&COLUMN_NAME.` substitution syntax.
+10. For icons, use exactly one icon from the canonical build-pinned `assets/indexes/font-apex-icon-index.json` plus only optional listed modifiers. Validate literals directly. For column-backed icons, project approved literals or an explicit `case` mapping whose every output satisfies the same contract; raw/unverified icon columns, multiple icons, and arbitrary classes are forbidden.
+11. The canonical image scenario in this pack uses `image.type: urlColumn` and a projected character URL column. In SQL, build every rendered value with the canonical bind form `:APP_FILES || 'relative/path'` or `:APEX_FILES || 'relative/path'`. Reject template and substitution tokens inside SQL literals, `AUTHENTICATED_URL_PREFIX`, BLOB endpoints, path traversal, raw URL columns, `javascript:`, `data:`, protocol-relative, and absolute external URLs.
+12. Emit one explicitly named `column <COLUMN_STATIC_ID> (...)` child for every delivered source projection.
+13. Every child column must define a unique uppercase snake_case declaration name, `layout.sequence`, `source.databaseColumn`, and `source.dataType`; the live compiler rejects lowercase or hyphenated external identifiers.
+14. Do not emit generic-column `columnName` or `show` properties on standalone Avatar child columns; use its template-component column contract instead.
+15. Use only shape, size, spacing, and type values listed in `avatar._template_options.md`.
+16. Require `settings.description` for every meaningful initials, icon, or image Avatar. It must be nonempty human-readable text or an `&UPPERCASE_COLUMN.` substitution backed by a declared `varchar2` source column whose meaning is verified from schema documentation, live metadata, or an explicit user assertion. For dynamic sources, persist the provenance as exactly one of `AVATAR_DESCRIPTION_EVIDENCE_SOURCE=schema_doc`, `AVATAR_DESCRIPTION_EVIDENCE_SOURCE=live_db`, or `AVATAR_DESCRIPTION_EVIDENCE_SOURCE=user_asserted`.
+17. Omit `settings.description` only when the Avatar is explicitly decorative and emit the exact region comment marker `AVATAR_PURPOSE_DECORATIVE`. Universal Theme 42 build `26.1.0+3102` renders description-less non-image Avatars with `aria-hidden="true"` and image Avatars with `alt=""`.
+18. Emit `cssClasses` only for an explicit styling requirement. Values must be static; custom classes must use the `avatar-` prefix; visibility-changing classes are forbidden. Add `AVATAR_CSS_RATIONALE=<reason>` to region comments. Framework utility classes also require the exact comment marker `AVATAR_FRAMEWORK_UTILITIES_EXPLICIT_REQUEST`.
+19. Prefer shape, size, spacing, templates, and template options over custom or framework CSS. Do not invent CSS to solve layout or composition.
+20. When the owning page or application contract restricts Avatar visibility, emit `security.authorizationScheme` as `mustNotBePublicUser` or an `@alias` that resolves to a declared shared authorization scheme in the validation set.
+21. Do not invent authorization schemes or treat visual hiding as access control.
+22. The Avatar theme export declares no action templates; do not emit an action-template scenario from the separate `link` action position.
+23. Do not emit BLOB image, grouping, link-action, or partial-mode structures from this contract.
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| regionStaticId | yes | string | Stable region identifier. |
+| name | yes | string | Region name. |
+| source.sqlQuery | yes for SQL mode | SQL | Must use verified database-object evidence when it references DB objects. |
+| orderBy.orderByClause | yes for SQL mode | string | Deterministic clause body without the `ORDER BY` keyword. |
+| layout.sequence | yes | number | Stable page-region sequence. |
+| settingsBlock | yes | block | Exact settings block from one selected Avatar scenario. |
+| settings.type | yes | enum | `initials`, `icon`, or `image`. |
+| settings.initials | conditional | source-column identifier | Required only when `settings.type: initials`; direct uppercase identifier without `&` or trailing `.`. |
+| settings.icon | conditional | string/substitution | Required only when `settings.type: icon`. |
+| settings.image | conditional | object | Required only when `settings.type: image`. |
+| settings.description | conditional | string/substitution | Required for meaningful Avatars; nonempty human-readable text or a declared `varchar2` description-column substitution. Omit only for an explicitly decorative Avatar. |
+| settings.shape | optional | enum | Accepted Avatar shape token. |
+| settings.size | optional | enum | Accepted Avatar size token. |
+| settings.spacing | optional | enum | Report-level spacing token. |
+| settings.cssClasses | optional | string | Static, documented, component-scoped classes only; never dynamic or visibility-changing. |
+| commentsBlock | conditional | block | Required for decorative intent, dynamic-description evidence, and whenever `cssClasses` is emitted; carries exact governance markers, evidence provenance, and CSS rationale. |
+| securityBlock | conditional | block | Required when the owning contract restricts access; omit only for intentionally unrestricted Avatar data. |
+| security.authorizationScheme | conditional | shared-component reference | Exact existing authorization scheme; never inferred. |
+| column.name | yes | identifier | Unique uppercase snake_case child declaration name that supplies `identification.name`. |
+| column.layout.sequence | yes | number | Stable column sequence. |
+| column.source.databaseColumn | yes | string | Exact projected source alias. |
+| column.source.dataType | yes | enum | Compiler-supported source datatype such as `varchar2` or `number`. |
+| columns | yes | list | One explicit child column for every delivered source projection. |
+
+# Output Template
+
+```apexlang
+region {{regionStaticId}} (
+    name: {{name}}
+    type: themeTemplateComponent/avatar
+    source {
+        location: localDatabase
+        type: sqlQuery
+        sqlQuery:
+            ```sql
+            {{source.sqlQuery}}
+            ```
+    }
+    orderBy {
+        type: staticValue
+        orderByClause: {{orderBy.orderByClause}}
+    }
+    layout {
+        sequence: {{layout.sequence}}
+        slot: body
+    }
+    appearance {
+        template: @/standard
+        templateOptions: #DEFAULT#
+    }
+    componentAppearance {
+        display: report
+    }
+    {{securityBlock}}
+    {{settingsBlock}}
+    {{commentsBlock}}
+    column {{column.nameUpperSnakeCase}} (
+        layout {
+            sequence: {{column.layout.sequence}}
+        }
+        source {
+            databaseColumn: {{column.source.databaseColumn}}
+            dataType: {{column.source.dataType}}
+        }
+    )
+    {{columns}}
+)
+```
+
+# Conditional Rendering Rules
+
+- `settings.type: initials` emits `initials` and omits `icon` and `image`.
+- `settings.type: icon` emits `icon` and omits `initials` and `image`.
+- `settings.type: image` emits `image: { ... }` and omits `initials` and `icon`.
+- Omit optional settings when no authoritative input requires them.
+- For a decorative Avatar, omit `settings.description` and emit:
+  ```apexlang
+  comments {
+      comments: AVATAR_PURPOSE_DECORATIVE
+  }
+  ```
+- For a dynamic description source, record the verified provenance with exactly one `AVATAR_DESCRIPTION_EVIDENCE_SOURCE=schema_doc|live_db|user_asserted` entry in region comments. A generic assertion-only marker is not evidence.
+- When custom CSS is required, keep the comment scalar semicolon-delimited when it carries multiple markers, for example `AVATAR_CSS_RATIONALE=Distinguishes approved support identities; AVATAR_FRAMEWORK_UTILITIES_EXPLICIT_REQUEST`.
+- Include one child column for every source alias, including hidden identity, description, icon, initials, and URL columns.
+- Keep uppercase snake_case declaration names unique within the Avatar region. Bind `settings.initials` through its direct projected database-column identifier; use substitutions only for free-text settings that support them.
+- Keep the selected payload column datatype compatible with the Avatar attribute: initials, icon, description, and URL-column image values are `varchar2` in this pack.
+- Require `description` unless the exact decorative-purpose region comment marker is present; do not emit both.
+- When `cssClasses` is present, require static safe classes and the matching comments rationale/approval evidence.
+- Emit `security { authorizationScheme: ... }` only with `mustNotBePublicUser` or an `@alias` resolving to an existing shared authorization scheme selected by the owning security contract.
+- If restricted access is required but the scheme cannot be resolved, stop with Missing Inputs.
+
+# Validation Checklist
+
+- Region type is exactly `themeTemplateComponent/avatar`.
+- Component display is `report`.
+- SQL contains no `ORDER BY`; top-level `orderBy` supplies deterministic sorting.
+- Exactly one type-specific payload is present.
+- Every query projection has an explicitly named `column <COLUMN_STATIC_ID> (...)` child.
+- Every column contains a declaration name, `layout.sequence`, `source.databaseColumn`, and `source.dataType`.
+- `settings.initials` uses a direct declared `varchar2` source-column identifier, while free-text values such as `settings.description` may use `&COLUMN_NAME.` substitutions.
+- Meaningful Avatars have a verified human-readable description; dynamic description sources record their evidence provenance, while decorative Avatars use the exact decorative marker and no description or description column.
+- Icon values are exact members of the build-pinned Font APEX index; column-backed values use a statically verified mapping.
+- URL-column image expressions are application-managed and reject unsafe or untrusted URL forms.
+- `cssClasses` are static, component-scoped, documented, and do not alter visibility.
+- Shape, size, spacing, and type tokens exist in `avatar._template_options.md`.
+- Restricted Avatar regions reference an existing shared authorization scheme.
+- No action template is emitted because the Avatar export defines none.
+- No deferred BLOB, grouping, link-action, or partial-mode structure is present.

package/skills/apexlang/templates/template-components/avatar/avatar._index.md

@@ -0,0 +1,42 @@
+---
+templateId: region.avatar.index
+componentType: region
+version: 1.0
+imports:
+  - avatar._common.md
+description: Routing entrypoint for standalone Avatar report regions.
+---
+
+# Purpose
+
+Select the narrowest standalone Avatar report scenario.
+
+# Load Order
+
+1. Load `avatar._common.md`.
+2. Load exactly one scenario file matching the requested Avatar type.
+3. Load `avatar._template_options.md` only when validating settings or enum values.
+
+# Scenario Routing
+
+- Initials: `avatar.report-initials.md`
+- Font APEX icon: `avatar.report-icon.md`
+- Image from a projected URL column: `avatar.report-image-url-column.md`
+
+# Unsupported Routing
+
+Do not route BLOB images, report grouping, link actions, or partial mode to this pack until their standalone Avatar contracts have dedicated evidence.
+
+# Action Template Decision
+
+The Avatar export contains no action templates, so `Apply Action Templates` is not applicable to the current report scenarios. Do not confuse the separate `link` action position with an action template.
+
+# Authorization Routing
+
+When the owning application or page restricts Avatar visibility, require the exact existing shared authorization scheme and emit it through the common contract. Stop with Missing Inputs rather than guessing a scheme name.
+
+# Security and Accessibility Routing
+
+- Route image URLs through the application-managed URL contract in `avatar.report-image-url-column.md`.
+- Route icons through the build-pinned Font APEX allowlist contract in `avatar.report-icon.md`.
+- Apply the common meaningful-description/decorative marker and safe `cssClasses` contracts to every scenario.

package/skills/apexlang/templates/template-components/{avatar._template_options.md → avatar/avatar._template_options.md}

@@ -2,7 +2,7 @@
 
 These entries come from `create_plugin_attribute` and `create_plugin_attr_value`, not from `wwv_flow_template_options`.
 
-Apply these values through the owning component's avatar settings block.
+For a standalone `themeTemplateComponent/avatar` region, apply these values through `settings {}`. For an owning component that embeds Avatar behavior, apply them through that component's documented avatar block such as `plugin-avatar {}`.
 Emit only exact accepted values from this inventory. Do not concatenate adjacent values into one token and do not substitute labels or implementation details.
 
 When a row includes `values=`, pass the left-hand side of each `name=>return_value` pair.

package/skills/apexlang/templates/template-components/avatar/avatar.report-icon.md

@@ -0,0 +1,48 @@
+---
+templateId: avatar.report-icon
+componentType: templateComponent
+imports:
+  - avatar._common.md
+version: 1.0
+description: Standalone report-mode Avatar using a Font APEX icon.
+---
+
+# Purpose
+
+Render one Avatar per source row using an approved Font APEX icon value.
+
+# Output Template
+
+```apexlang
+settings {
+    type: icon
+    icon: {{iconValue}}
+    {{descriptionProperty}}
+    shape: {{shape}}
+    size: {{size}}
+    spacing: {{spacing}}
+}
+
+{{iconColumnBlock}}
+
+{{descriptionColumnBlock}}
+```
+
+# Conditional Rendering Rules
+
+- The icon value must contain exactly one icon from `assets/indexes/font-apex-icon-index.json` and only optional modifiers listed there.
+- For literal mode, set `iconValue` to one allowlisted literal and omit `iconColumnBlock`.
+- For column mode, set `iconValue` to `&{{iconColumn}}.` and emit the complete `iconColumnBlock`; the source must project approved literals directly or use an explicit SQL `case` mapping whose every result satisfies that canonical contract. Raw dynamic columns, unknown icons or modifiers, multiple icons, and arbitrary classes are forbidden.
+- `iconColumnStaticId` and `descriptionColumnStaticId` must resolve to uppercase snake_case external identifiers.
+- For meaningful icons, set `descriptionProperty` to `description: &{{descriptionColumn}}.` and emit the complete `descriptionColumnBlock`; dynamic sources also record `AVATAR_DESCRIPTION_EVIDENCE_SOURCE=schema_doc|live_db|user_asserted` in comments.
+- For decorative icons, omit both description placeholders and emit `AVATAR_PURPOSE_DECORATIVE`; never leave an unused description column in the output.
+- Omit `initials` and `image`.
+- Add the remaining source projections as explicit child columns using `avatar._common.md`.
+
+# Validation Checklist
+
+- `settings.type` is `icon`.
+- `settings.icon` is one allowlisted literal or an `&COLUMN_NAME.` substitution whose source projection is a fully verified allowlisted mapping.
+- The icon and description source columns are declared as `varchar2` when column-backed.
+- Meaningful icons have a description; decorative icons omit it and use the exact marker so Universal Theme renders `aria-hidden="true"`.
+- Every Avatar child declaration identifier is uppercase snake_case.

package/skills/apexlang/templates/template-components/avatar/avatar.report-image-url-column.md

@@ -0,0 +1,62 @@
+---
+templateId: avatar.report-image-url-column
+componentType: templateComponent
+imports:
+  - avatar._common.md
+version: 1.0
+description: Standalone report-mode Avatar using an image URL supplied by a source column.
+---
+
+# Purpose
+
+Render one Avatar per source row using a projected image URL column.
+
+# Output Template
+
+```apexlang
+settings {
+    type: image
+    image: {
+        type: urlColumn
+        urlColumn: {{imageUrlColumn}}
+    }
+    {{descriptionProperty}}
+    shape: {{shape}}
+    size: {{size}}
+    spacing: {{spacing}}
+}
+
+column {{imageUrlColumnStaticId}} (
+    layout {
+        sequence: {{imageUrlColumnSequence}}
+    }
+    source {
+        databaseColumn: {{imageUrlColumn}}
+        dataType: varchar2
+    }
+)
+
+{{descriptionColumnBlock}}
+```
+
+# Conditional Rendering Rules
+
+- `imageUrlColumn` is required and must be projected by the region source.
+- `imageUrlColumnStaticId` and `descriptionColumnStaticId` must resolve to uppercase snake_case external identifiers.
+- In SQL projections, build every URL as `:APP_FILES || 'relative/path'` or `:APEX_FILES || 'relative/path'`. The bind is SQL syntax; do not quote it or replace it with `#...#` or `&...` syntax.
+- Do not pass through a raw database URL column. Reject `AUTHENTICATED_URL_PREFIX` because it may be absolute, BLOB endpoints because this scenario has no FILE-item/primary-key evidence contract, path traversal, `javascript:`, `data:`, protocol-relative (`//...`), and absolute external URLs.
+- For meaningful images, set `descriptionProperty` to `description: &{{descriptionColumn}}.` and emit the complete `descriptionColumnBlock`; dynamic sources also record `AVATAR_DESCRIPTION_EVIDENCE_SOURCE=schema_doc|live_db|user_asserted` in comments.
+- For decorative images, omit both placeholders and emit `AVATAR_PURPOSE_DECORATIVE`; never leave an unused description column in the output.
+- Omit `initials` and `icon`.
+- Do not convert this scenario into a BLOB image pattern; BLOB support is deferred.
+- Add the remaining source projections as explicit child columns using `avatar._common.md`.
+
+# Validation Checklist
+
+- `settings.type` is `image`.
+- `settings.image.type` is `urlColumn`.
+- `settings.image.urlColumn` names a projected character column.
+- The URL and description source columns are declared as `varchar2`.
+- Every URL projection branch is statically proven to stay within the application-managed APEX URL contract.
+- Meaningful images have a description; decorative images omit it and use the exact decorative-purpose comment marker so Universal Theme renders `alt=""`.
+- Every Avatar child declaration identifier is uppercase snake_case.

package/skills/apexlang/templates/template-components/avatar/avatar.report-initials.md

@@ -0,0 +1,54 @@
+---
+templateId: avatar.report-initials
+componentType: templateComponent
+imports:
+  - avatar._common.md
+version: 1.0
+description: Standalone report-mode Avatar using initials from a varchar2 source column.
+---
+
+# Purpose
+
+Render one Avatar per source row using character initials.
+
+# Output Template
+
+```apexlang
+settings {
+    type: initials
+    initials: {{initialsColumn}}
+    {{descriptionProperty}}
+    shape: {{shape}}
+    size: {{size}}
+    spacing: {{spacing}}
+}
+
+column {{initialsColumnStaticId}} (
+    layout {
+        sequence: {{initialsColumnSequence}}
+    }
+    source {
+        databaseColumn: {{initialsColumn}}
+        dataType: varchar2
+    }
+)
+
+{{descriptionColumnBlock}}
+```
+
+# Conditional Rendering Rules
+
+- `initialsColumn` is required and must resolve to a projected `varchar2` column; emit the direct column identifier without `&` or a trailing period.
+- `initialsColumnStaticId` and `descriptionColumnStaticId` must resolve to uppercase snake_case external identifiers.
+- For meaningful initials, set `descriptionProperty` to `description: &{{descriptionColumn}}.` and emit the complete `descriptionColumnBlock`; dynamic sources also record `AVATAR_DESCRIPTION_EVIDENCE_SOURCE=schema_doc|live_db|user_asserted` in comments.
+- For decorative initials, omit both placeholders and emit `AVATAR_PURPOSE_DECORATIVE`; never leave an unused description column in the output.
+- Omit `icon` and `image`.
+- Add the remaining source projections as explicit child columns using `avatar._common.md`.
+
+# Validation Checklist
+
+- `settings.type` is `initials`.
+- `settings.initials` uses the direct uppercase source-column identifier because the compiler metadata defines it as a `sessionStateValue` column selector.
+- The initials source column is named and declares `source.databaseColumn` plus `source.dataType: varchar2`.
+- Meaningful initials have a description; decorative initials omit it and use the exact marker so Universal Theme renders `aria-hidden="true"`.
+- Every Avatar child declaration identifier is uppercase snake_case.

package/skills/apexlang/templates/template-components/badge/README.md

@@ -0,0 +1,38 @@
+# Badge Templates
+
+## Purpose
+
+Canonical standalone report-mode Badge template-component guidance for `themeTemplateComponent/badge`.
+
+## Usage
+
+- Load `badge._index.md`, then `badge._common.md`.
+- Load `badge._template_options.md` for the compiler-derived Badge attribute inventory.
+- Use `badge.report-minimal.md` for a non-interactive Badge region.
+- Use `badge.report-link.md` only when the requirement includes one row-level Badge link.
+- Keep partial attachment and custom template-component authoring out of this family.
+- Keep labels as plain static text and icons limited to exactly one pinned Font APEX catalog icon with optional catalog-listed modifiers. Treat state as optional explicit intent: omit it when unspecified, and limit requested state results to exact lowercase `danger`, `warning`, `success`, or `info` from any supported projected source.
+- Before assigning an icon, load and consult `assets/indexes/font-apex-icon-index.json`; never invent an icon token.
+- Use reviewed structured targets. Badge generation must not emit `targetUrl`, arbitrary `linkAttributes`, or inline event handlers.
+
+## Template Catalog
+
+- `badge._index.md`
+- `badge._common.md`
+- `badge.report-minimal.md`
+- `badge.report-link.md`
+- `badge._template_options.md`
+
+## Permutation Harness
+
+Run the focused Badge harness from the repository root:
+
+`node --test --test-name-pattern='Badge permutation harness' the source package regression tests`
+
+The harness generates temporary fixtures for all 576 finite combinations of `style`, `shape`, `size`, `displayLabel`, semantic `state`, icon presence, and optional `link` action. It validates them in one pass and removes the fixtures afterward. Focused regression matrices separately validate plain static labels, exact state results, every compiler-supported 26.1 `source.location`/`source.type` shape, and pinned Font APEX icon/modifier membership.
+
+## Maintenance
+
+- Keep the attribute and action guidance aligned with compiler-backed Universal Theme metadata.
+- Every scenario must include purpose, output template, conditional rules, and validation checks.
+- Keep examples schema-neutral; generated object-specific SQL still requires schema, live DB, or explicit user evidence.