pi-apexlang 0.1.0

package/skills/apexlang/references/policies/memory-bank/40-components/apex.items.md

@@ -0,0 +1,154 @@
+# Items (APEXlang Components)
+
+## Purpose
+- Define deterministic, template-driven guidance for adding items to pages while honoring governance:
+- Snippets containing `{{...}}` are `metavariable_template` examples. Bind every variable from schema evidence before emitting SQL or APEXlang.
+- When generating items, load the matching template under `templates/items/` or `template-components/` first.
+  - Follow references/policies/memory-bank/00-guard/ai.guard.md and 10-global/apex.global.md.
+  - Never invent attributes or UT classes; use only what exists in templates/items/*.
+  - Prefer declarative behavior; push heavy logic to DB packages/views; guard DML by button/process.
+  - SQL must be in triple backticks.
+
+## Scope and Types
+- Item categories:
+  - Form items: placed on data-entry/detail regions (e.g., page/form). Participate in DML guarded by button/process.
+  - Filter items: placed on list/report regions (e.g., interactive report) to filter/query; do not perform DML.
+- Router/NLU uses assets/apex-generation/components.registry.json and assets/rules-mapping.json item keywords to select these rules.
+
+## Templates Index (authoritative)
+- Use only existing templates from templates/items/:
+  - Text
+    - text-field/_index.md
+    - text-area/_index.md
+    - text-autocomplete/_index.md
+  - Choice/LOV
+    - select-one/standard.md
+    - select-many/standard.md              # canonical multi-select reference
+    - select-list-static.md
+    - select-list/_index.md                 # canonical select-list reference (static, dynamic-form, dynamic-filter)
+    - combobox/_index.md
+    - shuttle/_index.md
+    - radio-group/_index.md
+    - checkbox/_index.md
+  - Date/Time
+    - date-picker/_index.md
+  - Numeric and Special
+    - number-field/_index.md
+    - switch/_index.md
+    - star-rating/standard.md
+    - color-picker/standard.md
+  - Display and Upload
+    - display-only/standard.md
+    - file-upload/_index.md
+    - hidden-item/_index.md
+  - Rich Editing
+    - rich-text-editor/_index.md
+- Selection rules:
+  - Use the most specific template that matches the requested control and context (form vs filter).
+  - For select lists (static or dynamic), use select-list/_index.md and choose the matching variant markdown file in that family.
+  - If a requested visual lacks a template, fall back to the nearest supported template and record a Limitation in Critique; do not invent.
+
+## General Rules (non-negotiable)
+- Always start from the template file under templates/items/* and adapt only allowed properties present in that template.
+- Also validate against `assets/component-attributes.json` when a schema entry exists for the item type. Schema is authoritative over template prose/examples.
+- Builder visibility is not a complete validity test. Some item properties may be hidden in specific Builder states yet still remain compiler-valid DSL properties; prefer compiler-backed metadata and `assets/component-attributes.json` over Builder UI visibility when those disagree.
+- Do not introduce properties or attributes that do not exist in the chosen template.
+- Visible item-template defaults, label treatment defaults, and other template-driven presentation choices are composition policy. Resolve those defaults from `references/policies/memory-bank/40-components/apex.templates.md` before applying item-family specifics here.
+- Do not invent CSS classes. Resolve visible template, label, spacing, and framing choices through `references/policies/memory-bank/40-components/apex.templates.md`.
+- Validate names and labeling via 10-global/apex.global.md conventions.
+- Hidden item guardrail: for `type: hidden`, do not emit a `label { ... }` block.
+- For form items that drive DML, ensure there is an explicit button/process guard (see 20-data/apex.logic.md) rather than side effects in item definitions.
+
+## Layout Scope
+- Generated application page items are linted against this local-scope contract; visible app artifacts do not bypass the equal-width rule.
+- Page items use a local 12-column grid inside their parent region, grouped by `layout.region + layout.slot`.
+- The total explicit `columnSpan` of sibling items in one row must not exceed 12 within that item scope.
+- Do not add item spans to the parent region span; the item scope resets to 12 columns inside the parent region.
+- For equal-width item rows, omit `column` / `columnSpan` and use `startNewRow: false` on second-and-later siblings.
+- Treat `layout.labelColumnSpan` as an optional override, not a default-to-emit property. Use the canonical name `labelColumnSpan` when a deliberate label-grid override is needed; never use the legacy alias `labelColSpan`.
+- Common repo usage emits `labelColumnSpan: 0` for hidden/control-shell or certain non-floating optional item layouts, but other visible templates can also use non-zero values when label-grid width needs an explicit override.
+
+## Case Sensitivity and Item Types
+- Item types are case-sensitive; use names exactly as provided by templates in templates/items/*.
+- Known pitfalls:
+  - textarea must be lowercase (not text area).
+  - numberField and datePicker follow camelCase exactly as templates.
+- When uncertain, cross-check existing generated artifacts and templates rather than guessing.
+
+## LOV Patterns (deterministic)
+- Shared LOV reference names in pages must exactly match those defined in shared-components/lovs.md (case and underscores are significant).
+- In columnMapping, return and display must match actual database column case (typically uppercase).
+- Table and SQL LOV definitions must expose parser-visible top-level display and return mappings; do not hide them only in prose or comments.
+- SQL LOVs must project deterministic display and return aliases and the item/column mapping must reference those aliases exactly.
+- Static LOV:
+  - Use select-list-static.md.
+  - Populate static entries exactly as the template demonstrates; do not invent attribute names.
+  - Represent each entry with both display and return values; do not use scalar-only entries when the template supports structured entries.
+  - When schema metadata clearly represents a finite enum, prefer a Static LOV over SQL that selects constants from `dual`.
+- Dynamic LOV (Form context):
+  - Use select-list/_index.md (dynamic form variant).
+  - Provide SQL as a triple-backticked multi-line string; specify value/display mapping conceptually as per the template (e.g., value=id, display=name), using only properties that exist in the template.
+  - If using shared LOVs, coordinate with shared-components/lovs.md or shared-components/lovs.md; do not duplicate definitions.
+- Dynamic LOV (Filter context):
+  - Use select-list/_index.md (dynamic filter variant) with the same SQL and mapping requirements.
+- Autocomplete/Combobox:
+  - Use text-autocomplete/_index.md or combobox/_index.md according to desired UX; supply SQL source in triple backticks if the template expects it.
+
+Example (conceptual, align strictly with template properties)
+```
+-- Dynamic LOV SQL (triple backticks required)
+```
+```
+select {{lookup.valueColumn}} as value, {{lookup.displayColumn}} as display
+from {{lookup.table}}
+order by {{lookup.displayColumn}}
+```
+```
+- Reference the template for how to attach this SQL to the item; do not add new properties.
+```
+
+## Item Selection Guidance
+- Text input → text-field/_index.md; multi-line → text-area/_index.md.
+- Numbers → number-field/_index.md.
+- Single choice from small set → radio-group/_index.md (form), or select-one/standard.md.
+- Multiple choice → checkbox (boolean) / checkbox group (if template available) / select-many/standard.md / shuttle/_index.md depending on cardinality and UX.
+- Dates → date-picker/_index.md.
+- Boolean toggle → switch/_index.md.
+- Read-only → display-only/standard.md.
+- Files → file-upload/_index.md (ensure storage/process is handled declaratively or via DB/logic rules; do not embed heavy logic in item).
+- Rich content → rich-text-editor/_index.md.
+- Colors → color-picker/standard.md.
+- Ratings → star-rating/standard.md.
+
+## Filter vs Form Context
+- Form items:
+  - Participate in Create/Update; bind to record keys and columns.
+  - DML must be guarded by explicit buttons/processes; validations should be declarative where possible.
+- Filter items:
+  - Do not perform DML; they alter query conditions.
+  - Pair with page logic that refreshes target report/region declaratively (see dynamic-action templates if applicable).
+
+## Data and Validations
+- Use declarative validations when supported; otherwise push complex checks to DB packages or views (20-data/apex.logic.md).
+- For default values and computations, prefer declarative mechanisms or DB expressions; avoid inline procedural logic in item definitions.
+
+## Accessibility and Naming
+- Labels should express the field name; help text carries the “why/how.”
+- Every user-editable item and every filter/control item should carry concise help by default unless the item is purely technical or hidden.
+- Treat `simple`, `quick`, `starter`, or similar prompt wording as a content-density signal only. It is not an exemption from default help text on visible user-facing items.
+- Prefer authoritative help sources first. When those are missing, provisional concise copy is allowed if it remains neutral, translation-ready, and tied to a Text Message key or planned key.
+- Inline help must stay within template allowances and reference Text Messages for localization.
+- Detailed help dialogs (when template exposes `helpText`) should stay under ~400 characters and explain why the value matters, key validation expectations, or interpretation notes.
+- Repeated help wording across items should be centralized in shared Text Messages rather than duplicated inline.
+- Item names should follow global naming conventions; avoid ambiguous or overloaded identifiers.
+
+## Governance and Safety
+- Never invent attributes; adhere to the exact attribute structure in the selected template under templates/items/*.
+- Use only existing templates listed in this document; if a requested type is not available, select the nearest supported one and record a limitation.
+- SQL in triple backticks only; sanitize inputs by relying on APEX declarative features and DB-side logic rather than ad-hoc code.
+
+## Artifacts and Orchestration
+- Draft → Critique → Revision pipeline:
+  - Agent 2 validates that selected item templates exist and flags any missing inputs (e.g., LOV mapping) and emits PASS/CONFIDENCE headers.
+  - Agent 3 applies only accepted notes and writes finals to generated application pages/ (or app_###/pages/ for whole app runs).
+- Critical pages and shared components are enforced by the master workflow; items must not bypass those gates.

package/skills/apexlang/references/policies/memory-bank/40-components/apex.region-contracts.md

@@ -0,0 +1,26 @@
+# APEX Region Contracts
+
+## Purpose
+Index for cross-region APEXlang contracts that apply before component-specific templates. Use this file first for region selection and invariant routing, then load the specialized files for data-source, media/BLOB, and interaction/filter details.
+
+## Canonical Region Selection
+- Choose the narrowest native APEX region that satisfies the request; do not add helper or summary regions unless the prompt or a dependency requires them.
+- Prefer `Interactive Report` for user-driven search, personalization, saved reports, and ad hoc analysis.
+- Prefer `Classic Report` for stable tabular output, contextual info, printable summaries, and report fragments with fixed columns.
+- Prefer `Cards` or `Content Row` for browse/list experiences where a row is primarily represented as a title, subtitle, image, badge, or short description.
+- Prefer `Metric Card` for single numeric KPIs and `Chart` for aggregate trend/category visualization; connect drilldown through nearby report/card links rather than chart or metric actions.
+- Prefer `Faceted Search` for structured filter panels over known columns and `Smart Filters` for compact keyword/filter search experiences.
+
+## Core Invariants
+- Region type must come from the active APEXlang templates and component attribute catalogs; do not invent aliases.
+- Emit qualifiers only where the region contract supports them. `Classic Report` supports `Standard` and `Contextual Info`; `Chart`, `Map`, and `List` require their valid qualifier; most other region types omit qualifier.
+- `breadcrumb-bar` is reserved for non-modal `Classic Report` regions with `Qualifier: Contextual Info`; modal dialog pages must not use `breadcrumb-bar`.
+- Region `Position` must be one of the template-supported positions for the page and region; do not move regions to satisfy invalid block combinations.
+- `Data Source Type: Static` is not a valid data source for data-backed APEXlang region components; use static-content templates for static UI sections.
+
+## Specialized Files
+- `references/policies/memory-bank/40-components/apex.region-data-source.md`: table/view/SQL source semantics, schema UI hints, order-by ownership, and display/format mask guidance.
+- `references/policies/memory-bank/40-components/apex.region-media.md`: BLOB display, storage companion columns, file/image upload constraints, icon allowlists, and visual-token rules.
+- `references/policies/memory-bank/40-components/apex.region-interactions.md`: Cards/List/Metric/Chart action rules, filter/search namespaces, contextual info, parent-child layout, and comments.
+
+Tags: apexlang, region, qualifier, data-source, blob, contextual-info, faceted-search, smart-filters, cards, metric-card, chart, list

package/skills/apexlang/references/policies/memory-bank/40-components/apex.region-data-source.md

@@ -0,0 +1,25 @@
+# APEX Region Data Sources
+
+## Purpose
+Defines reusable APEXlang region data-source contracts for table/view/SQL ownership, schema hints, ordering, and display semantics.
+
+## Data Source Semantics
+- Use `Table` or `View` for simple single-object report, cards, and content-row regions; use `SQL` only for joins, aggregation, computed columns, contextual info, bind predicates, BLOB projection, map/calendar shaping, or explicit SQL behavior.
+- SQL data sources must not emit a data-source object name; table and view data sources must name a verified schema object.
+- A region heading is UI identity only and must not be interpreted as the data source name.
+- Every data-backed region with row-level navigation or BLOB lookup must have deterministic primary keys from schema metadata.
+- For table/view `Order By`, every sort token must be a real source column that also exists in the region columns block; expressions belong in SQL-backed sources only when the region supports SQL ordering.
+
+## Schema UI Hints
+- Treat schema comments and metadata tokens such as `apex:display`, `apex:filter`, `apex:lov`, `apex:link`, `apex:badge`, `apex:image`, `apex:hidden`, and `apex:format` as UI hints when they are present and unambiguous.
+- Schema UI hints never override verified datatype, PK/FK, security, or component-template constraints.
+- If multiple hints conflict, prefer the stricter/safest native component behavior and record the ambiguity instead of inventing a hybrid control.
+- Use hints to refine render role, label, visibility, LOV/display choice, and format mask; do not use them to invent missing schema columns or unsupported attributes.
+
+## Format Masks and Display Semantics
+- Emit schema-driven date, timestamp, number, percent, and currency format masks when datatype and business meaning are clear.
+- Do not use format masks to coerce incompatible datatypes; fix source projection or item type instead.
+- Metric cards require numeric display semantics; apply compact KPI masks only to numeric metric values.
+- Interactive Report context/comments should mirror important executable display settings such as format masks, display labels, read-only behavior, authorization, and LOV context when those settings are emitted.
+
+Tags: apexlang, region, data-source, table, view, sql, schema-hint, format-mask, order-by

package/skills/apexlang/references/policies/memory-bank/40-components/apex.region-interactions.md

@@ -0,0 +1,43 @@
+# APEX Region Interactions
+
+## Purpose
+Defines reusable APEXlang region interaction contracts for links, actions, filters, contextual regions, parent-child layout, and comments.
+
+## Interaction and Action Constraints
+- Metric Card and Chart regions do not own links or actions; use adjacent cards, reports, buttons, or list entries for navigation.
+- Cards `fullCard` links must not emit a label; Cards `button` links must emit a concise label.
+- Native Cards actions are row navigation actions using `label` plus declarative `behavior.target`; do not emit `position` or attach processes directly to Cards actions.
+- List regions are navigation-only; they bind to shared list entries and must not emit data sources, filters, hidden page items, columns, links, or actions.
+- Management and launcher hub shared list entries should include `icon.imageIconCssClasses` with a conservative `fa-*` token and `userDefinedAttributes { 1: ... }` description text so media-list hubs render as scannable launch cards.
+- Report drilldown should be modeled as report/column links or region-level links, not as unsupported report actions.
+
+## Filter and Search Namespaces
+- Only Faceted Search and Smart Filters regions may emit filter blocks; filter regions must not emit columns.
+- Filter item names are page item tokens, not labels. Derive them from page number and database column: `P{page}_F_{UPPER_DB_COLUMN}`.
+- Range filters use the same single canonical filter name as the database column; do not create `_FROM` and `_TO` item pairs for one range filter.
+- Smart Filters search item token defaults to `P{page}_F_SEARCH`; avoid legacy `P{page}_SEARCH` for generated search items.
+- Filter item names must not collide with same-page hidden items or form page item names; suffix deterministically only when there is a real collision.
+
+## Contextual and Parent-Child Layout
+- Contextual Info regions must be Classic Reports with `Qualifier: Contextual Info`, SQL data source, and one effective row for the current context.
+- Parent-child pages should keep parent context narrow and child detail broad inside the standard page body grid: parent Content Row at the body start and child regions in the remaining body columns.
+- Master-detail Content Row pages must use `appearance.pageTemplate: @/standard`. Reserve `@/left-side-column` and `layout.slot: leftColumn` for faceted-search and filter/sidebar pages, not master-detail workbenches.
+- Do not create full-width parent context plus full-width child regions when the page intent is parent-child comparison or maintenance.
+- Treat a parent list/detail row that filters a child report by PK/FK as a master-detail page even when the prompt does not use the words "master detail".
+- For master-detail pages, model parent selection with a report-mode Content Row plus a `fullRowLink` action that updates the same-page hidden context item, for example `P{page}_{PARENT_PK}` from `&PARENT_PK.`, and refreshes dependent child regions through dynamic-action behavior.
+- Do not implement primary master-detail parent selection with `redirectUrl`, `targetUrl`, or an `f?p=` reload of the same page.
+- Do not replace the parent row selector with a visible select list when the page already has or should have a parent Content Row. The parent context item must be hidden unless the user explicitly requests an editable selector.
+- Child reports that bind to the selected parent item must include that item in `source.pageItemsToSubmit`.
+- Child map layers that bind to the selected parent item must use normal `:P...` binds, must be refreshed explicitly after the parent context changes, and must not read selected context through `v()`/`nv()` session-state functions. Do not require or emit map-layer `source.pageItemsToSubmit` unless direct compiler truth for the active build proves it valid for the selected layer shape.
+- When a child map requirement says marker selection opens a form, the map layer must expose a declarative link to the modal form and pass the map feature primary key.
+- Master-detail action buttons such as create/edit child records belong in the child report toolbar slot, typically `rightOfInteractiveReportSearchBar`, not as free-floating body-grid buttons beside the regions.
+- Master-detail workbenches must realize every required action: parent edit, child create, child edit/detail links, and page-level create actions. Page-level create actions belong in the breadcrumb/title-bar region when present.
+- On non-modal management, search, and report pages with a breadcrumb/title-bar region, primary page-level create actions belong in that breadcrumb/title-bar region. Region toolbars are for region-scoped child/detail actions.
+- Use `primaryActions` only for visible row-level menus/buttons. Use `fullRowLink` for row selection and drill-down of a Content Row master list.
+
+## Comments and Context Cues
+- Application, page, and region comments should be short functional sentences with purpose plus workflow, data role, navigation, or security context.
+- Do not emit placeholder comments such as `todo`, `tbd`, `n/a`, `none`, `test`, `placeholder`, or lorem ipsum.
+- When requirements are sparse, synthesize comments from application purpose, page goal, region function, and primary data/interaction responsibility.
+
+Tags: apexlang, region, links, actions, filters, smart-filters, faceted-search, contextual-info, parent-child, comments

package/skills/apexlang/references/policies/memory-bank/40-components/apex.region-media.md

@@ -0,0 +1,31 @@
+# APEX Region Media and BLOBs
+
+## Purpose
+Defines reusable APEXlang BLOB, file/image, storage companion, and visual-token contracts for region components.
+
+## BLOB Display Contract
+- `Datatype: blob` is supported only in Form, Cards, Content Row, Classic Report, and Interactive Report regions.
+- Valid render roles are Form: `fileUpload`, `imageUpload`, `displayImage`; Cards/Content Row/Classic Report/Interactive Report: `displayImage`.
+- Any region displaying a BLOB must include primary keys for lookup.
+- Companion storage columns such as MIME type, alt text, filename, last-updated, and character set must appear in the same region columns block; hide them when they are metadata-only.
+- SQL-backed Classic Report and Interactive Report BLOB display aliases must project `dbms_lob.getlength(<blob_expr>)`; Cards and Content Row must project the raw BLOB expression for display-image aliases.
+- Raw LOB projection is display-only. Do not sort, group, distinct, join, analytically partition/order, or compare raw LOB aliases; follow `SQL_PLSQL_LOB_COMPARISON_KEY_FORBIDDEN_001` in `20-data/apex.sql.md`.
+- Cards image display uses the native Cards media block, not report-style child columns.
+- Cards BLOB display uses `media { source: blobColumn blobColumn: <BLOB_COLUMN_ALIAS> }`.
+- Cards URL-column display uses `media { source: urlColumn urlColumn: <URL_COLUMN_ALIAS> }`.
+- Cards direct URL display uses `media { source: imageUrl url: <STATIC_IMAGE_URL_OR_COLUMN_SUBSTITUTION> }`; `url` may be a static URL or an APEX substitution such as `&IMAGE_URL_COLUMN.`.
+- Cards BLOB metadata uses `blobAttributes { mimeTypeColumn: <MIME_TYPE_ALIAS> lastUpdatedColumn: <LAST_UPDATED_ALIAS> }`, and that block is valid only when `media.source: blobColumn` is present.
+- Cards media presentation defaults are represented by omission; do not emit APEXlang-side `position`, `appearance`, or `sizing` for default Cards media.
+- Cards media presentation properties are valid optional controls only for explicit non-default requirements: `position: first | background`, `appearance: square | widescreen`, and `sizing: cover`. Never emit `position: first`, `appearance: square`, or `sizing: cover` just to mirror APEX defaults.
+- Cards regions with BLOB media must define `card.primaryKeyColumn1` and keep companion image metadata columns projected in SQL when available, but must not invent additional `media` or `blobAttributes` properties.
+- `Storage -> File Types` is Form-only for upload render roles and must be a comma-separated MIME-type list; `File Name Column` must be normalized to `Filename Column`.
+- `Alt Text Column` applies only to image upload/display flows and must not be used for plain file upload.
+
+## Icons and Visual Tokens
+- When the prompt specifies an icon allowlist file, use only `fa-*` tokens from that file for menu/list icons, metric icons, report link icons, and button icons.
+- If no allowlist is available, choose conservative Font APEX-style `fa-*` tokens and avoid custom CSS classes as semantic icons.
+- Generated icon-bearing properties must use Font APEX `fa-*` classes only. Do not emit image icons, Material/Oracle JET icon aliases, custom CSS icon aliases, or framework-specific icon classes in `icon`, `imageIconCssClasses`, `iconCssClasses`, `linkIcon`, or `noDataFoundIcon`.
+- Do not invent icon aliases or translate icon tokens; keep icon strings literal and template-compatible.
+- Use icons to reinforce navigation/action meaning, not as the only accessible label.
+
+Tags: apexlang, region, blob, file-upload, image-upload, display-image, icon, icon-allowlist

package/skills/apexlang/references/policies/memory-bank/40-components/apex.templates.md

@@ -0,0 +1,240 @@
+# Templates
+
+## Purpose
+- Define the single active UI composition contract for Oracle APEX page templates, region templates, item templates, template options, and structural layout defaults.
+- Own default visual composition decisions that change layout, framing, label treatment, disclosure, spacing, or behavior through native APEX templates and template options.
+- Keep active guidance structure-first: solve presentation through template, template-option, slot, grid, and alignment choices before considering any non-structural skinning.
+
+## Scope Boundary
+- This file owns structural UI composition defaults expressed through templates, template options, slot placement, layout coordinates, and alignment attributes.
+- Use this file to decide default page layout shells, default region templates, default visible item templates, header behavior, framing, density, padding, scroll-body behavior, heading levels, and button-container placement.
+- Non-structural skinning is not part of the active APEXlang contract. Do not solve layout, composition, or hierarchy problems with custom CSS classes.
+- Context-specific rules may refine these defaults, but they must point back to this file as the canonical owner:
+  - `references/policies/memory-bank/40-components/apex.items.md`
+  - `references/policies/memory-bank/30-pages/apex.form.md`
+
+## Canonical Ownership
+- Template family choice for pages, regions, buttons, and visible items.
+- Template-option defaults that affect framing, layout, density, disclosure, heading presence, body behavior, or label presentation.
+- Button icon placement as a template-option composition concern; keep the concrete button default, override, and icon-only exception in `references/policies/memory-bank/40-components/apex.buttons.md`.
+- Region button position semantics and allowed placements by template.
+- Shared interpretation rules for whitespace-joined template-option tokens and other template serialization requirements.
+- The composition-first boundary so shared UI defaults remain in one canonical place.
+
+## Default Page Composition
+- Use `appearance.pageTemplate: @/standard` for normal non-modal pages unless a page-specific rule or template family requires another shell.
+- Use `appearance.pageMode: modalDialog` for modal form/detail workflows that are explicitly modal by contract.
+- Place breadcrumbs/title-bar content in the title-bar template region and keep application navigation updates aligned with the page template example being used.
+- Breadcrumb/title-bar regions must not expose generic chrome labels such as `Breadcrumb`, `Breadcrumbs`, `Title Bar`, or `Page Header` as visible titles. Use the current breadcrumb entry/page title as the region name, keep `appearance.template: @/title-bar`, and use live-valid template options such as standalone `#DEFAULT#`. Do not emit stale `use-current-breadcrumb-entry` or `t-BreadcrumbRegion--useBreadcrumbTitle`.
+- Keep page-level composition decisions consistent with the chosen page example and region templates; do not mix unrelated shells on the same page without an explicit page-pattern rule.
+
+## Default Item Template Choices
+- Use `@/optional-floating` as the default visible item template for non-required form-style page items unless a page-specific rule explicitly requires another presentation.
+- Use `@/required-floating` for required visible form items.
+- Keep `@/optional`, `@/optional-above`, or other non-floating label templates only when the page is intentionally demonstrating alternate label layouts, when a component-specific contract explicitly requires a different template, or when the UX requires a deliberate exception.
+- For filter bars, search controls, and other visible query inputs embedded in report-oriented pages, prefer `@/optional-floating` unless the template or page pattern documents a deliberate alternative.
+- Hidden items and non-visible control shells continue to use their dedicated hidden or control-specific templates rather than visible floating-label templates.
+
+## Default Region Template Choices
+- Use `appearance.template: @/standard` as the default for content-bearing regions unless a family-specific rule explicitly requires another shell.
+- Classic Report hard default: every generated Classic Report region must emit these exact default blocks:
+  ```apexlang
+  appearance {
+      template: @/standard
+      templateOptions: #DEFAULT#
+  }
+
+  componentAppearance {
+      template: @/standard
+      templateOptions: [
+          #DEFAULT#
+          t-Report--stretch
+          t-Report--horizontalBorders
+      ]
+  }
+  ```
+  `appearance` owns the outer region wrapper. `componentAppearance` owns the Classic Report component template required by runtime validation; the 26.1 compiler reports the missing template as property `411`. The default component options stretch the report, use horizontal borders only, and intentionally omit alternating-row tokens such as `t-Report--altRowsDefault` and `t-Report--staticRowColors`.
+- Contextual Info Classic Reports are the Classic Report wrapper exception: use `appearance.template: @/contextual-info` with `templateOptions` exactly `#DEFAULT#`, `t-Region--hideHeader js-addHiddenHeadingRoleDesc`, and `t-Region--noUI`, while keeping the same Classic Report `componentAppearance` defaults.
+- Keep these families on their own canonical region templates by default:
+  - Interactive Report -> `@/interactive-report`
+  - Interactive Grid -> family-specific Interactive Grid template
+  - Cards -> family-specific Cards template
+  - Dashboard KPI Metric Card strips -> `@/blank-with-attributes`
+- Metric Card regions may use `@/standard` only when the requested design explicitly needs a titled or landmarked visible region wrapper.
+- Keep utility shells on their purpose-built templates rather than forcing `@/standard`, including:
+  - breadcrumb or title-bar regions
+  - buttons-container regions
+  - collapsible helper/explainer regions
+  - other structural wrappers whose template choice exists to support page chrome instead of the main content body
+- When a prompt does not explicitly ask for a special shell, content regions such as Classic Report, Form, Chart, Calendar, Map, Dynamic Content, Static Content, Help Text, Faceted Search, Search Config, Smart Filter Search, and similar body content regions should emit `appearance.template: @/standard`.
+
+## Grid and Column Layout Rules
+- These rules apply to generated application artifacts as well as templates and prompts.
+- Page regions use the page-level 12-column grid. Item rows use a separate local 12-column grid inside their parent item container region.
+- Never add child item spans to parent region spans. Grid scope resets inside each parent region or lane.
+- For equal-width sibling rows across standard regions, template-component regions, visible page items, and buttons, prefer sequence ordering plus `startNewRow: false` on second-and-later siblings. Omit `column` and `columnSpan`.
+- Use explicit `column` and `columnSpan` only when the layout is intentionally asymmetric or when the template/example requires precise coordinates.
+- For true filter/sidebar shell patterns such as faceted search, prefer page-template semantic slots such as `leftColumn` + `body` before using body-grid coordinates to simulate the shell.
+- Do not use `@/left-side-column` or `leftColumn` for master-detail Content Row workbenches; use `@/standard` with a body-grid split instead.
+- Use body-grid coordinates for sidebar/main only when the required width ratio or stacking behavior cannot be matched cleanly by the page template shell.
+- Treat a first sibling with `columnSpan` only plus later siblings with `column` as a valid anchored asymmetric row pattern; do not classify that recipe as invalid mixed layout.
+- Keep recurring outer lanes stable with minimal structural placeholder regions when that preserves layout more cleanly than repeating explicit coordinates row by row.
+- Use native alignment attributes for report/grid columns and region/item placement before considering any class-based workaround.
+- For faceted-search pages, prefer the page template's left-column slot (`leftColumn`) plus the results body slot (`body`) instead of using `body` `columnSpan` values to mimic a sidebar.
+
+## Template-Driven Mandate
+- Region/component requests must load the corresponding templates in `templates/region-components/` or `template-components/` and follow their structure exactly.
+- Always start from the most suitable file under templates/* when creating pages, regions, items, or shared components.
+- Make only strict, minimal edits required by the task (identifiers, page number, alias, name, regions, tableName, columns, LOV references, labels).
+- Do not change, omit, or invent DSL structure or attributes not represented in the template. Follow the block and attribute order as shown in the template.
+- Navigation, breadcrumbs, and components must match the templates and project governance guidance.
+- Formatting fidelity: Where a template demonstrates a specific literal format (e.g., htmlExpression, sqlQuery with triple backticks), mirror that format exactly. Do not substitute YAML-style literals or alternate encodings.
+- SQL-backed template component regions, including `themeTemplateComponent/contentRow`, must put deterministic ordering in top-level `orderBy {}` and must not place `ORDER BY` inside `source.sqlQuery`.
+- Default template component ordering to `orderBy { type: staticValue orderByClause: ... }`. Use `type: item` only when the sort is intentionally controlled by an available same-page page item.
+
+## Composition vs Styling
+- Treat a choice as composition-owned when it changes structure or interaction through templates, including:
+  - Which template is used.
+  - Which template options are enabled by default.
+  - Whether labels float, sit above, or align left/right when that behavior is template-driven.
+  - Whether a header is shown, removed, visually hidden, or assigned a heading level.
+  - Whether padding, scroll body behavior, maximize affordances, form density, or stretch behavior are enabled through template options.
+  - Where standard buttons live within a region template.
+- Treat non-structural skinning as out of active scope when it changes colors, palette, token mapping, or selector-level polish without changing the template contract.
+- When a prompt mixes structural and visual language, resolve all layout/composition decisions from this file first and keep the emitted artifact on native template/template-option paths.
+
+## Report/Grid Column Alignment Standard
+- Numeric data columns and their headings: right align (layout.columnAlignment: end, heading.alignment: end).
+- Textual (VARCHAR) data columns and their headings: left align (layout.columnAlignment: start, heading.alignment: start).
+- Apply in all report-like components (Interactive Report, Classic Report, Interactive Grid).
+- Prefer native alignment attributes over CSS. Do not invent CSS classes to solve alignment.
+
+## Template Options
+
+Regions have Template Options that can be modified to change the look and feel of the region.  Template Options appear in a section like this:
+
+```
+appearance {
+            template: @/standard
+            templateOptions: [
+                #DEFAULT#
+                t-Region--removeHeader js-removeLandmark
+                t-Region--scrollBody
+            ]
+        }
+```
+
+If a valid-value catalog or template example shows a whitespace-joined UT value such as
+`t-Region--hideHeader js-addHiddenHeadingRoleDesc` or
+`t-Region--removeHeader js-removeLandmark`, emit that value as one
+`templateOptions` array entry. Do not split combined values into multiple lines.
+
+When a `templateOptions` array contains more than one accepted value, emit it as a
+bracketed multi-line array with exactly one accepted value per line. Do not use
+inline comma-separated arrays such as `templateOptions: [#DEFAULT#, t-Report--stretch]`.
+
+Accepted-value contract:
+- Emit only exact accepted values.
+- `#DEFAULT#` is a standalone sentinel value only. Never concatenate it with another token.
+- For true Theme 42 template-option catalogs, pass the exact accepted emitted value documented by the owning family. Some families document a caller-facing `static_id`, while others document the emitted CSS/composite value for this build. Do not substitute a different form, label text, or group name.
+- For presets and documented composite UT values, pass the full documented composite string as one `templateOptions` entry when that exact combined value is the accepted emitted value.
+- Do not compose new values by joining `#DEFAULT#` with another token or by converting catalog metadata into inferred output.
+- For button template options, pass emitted values such as `t-Button--iconLeft` rather than caller-facing aliases/static_ids such as `left`; keep component-specific defaults in `references/policies/memory-bank/40-components/apex.buttons.md`.
+
+Anti-Patterns:
+- Invalid: `templateOptions: [#DEFAULT#t-Report--stretch]`
+- Invalid: `templateOptions: [t-Region--hideHeader, js-addHiddenHeadingRoleDesc]` when the accepted value is `t-Region--hideHeader js-addHiddenHeadingRoleDesc`
+- Invalid: passing `style-a` when the cards catalog says to pass `t-CardsRegion--styleA`
+- Invalid: `templateOptions: [#DEFAULT#, t-Report--stretch]`
+- Valid:
+  ```apexlang
+  templateOptions: [
+      #DEFAULT#
+      t-Report--stretch
+  ]
+  ```
+- Valid:
+  ```apexlang
+  templateOptions: [
+      #DEFAULT#
+      t-CardsRegion--styleA
+  ]
+  ```
+- Valid: `templateOptions: [t-Region--hideHeader js-addHiddenHeadingRoleDesc]`
+
+Visible page-item template defaults are also composition-owned. When item templates expose label presentation or other visible framing choices, use this file as the canonical owner and let `references/policies/memory-bank/40-components/apex.items.md` document only the item-specific application of those defaults.
+
+### Common Template Options
+
+These template options are available on common region templates. Use them only when they solve a structural presentation need.
+
+#### Region Body
+- `t-Region--noPadding`: remove body padding.
+- `js-showMaximizeButton`: show a maximize affordance.
+- `t-Region--showIcon`: show the region icon when one is defined.
+- `t-Region--hiddenOverflow`: hide body overflow.
+
+#### Region Height
+- `i-h240`: set the body height to 240 pixels.
+- `i-h320`: set the body height to 320 pixels.
+- `i-h480`: set the body height to 480 pixels.
+- `i-h640`: set the body height to 640 pixels.
+
+#### Region Items
+- `t-Form--slimPadding`: reduce item spacing.
+- `t-Form--noPadding`: remove item spacing.
+- `t-Form--large`: use large item sizing.
+- `t-Form--xlarge`: use extra-large item sizing.
+- `t-Form--stretchInputs`: stretch form fields to full width.
+- `t-Form--leftLabels`: align labels left.
+- `t-Form--rightLabels`: align labels right.
+
+#### Region Layout
+- `margin-[location]-[size]`: set structural margins where location is top, bottom, left, or right and size is sm, md, lg, or none.
+- `t-Region--removeHeader js-removeLandmark`: emit this combined template option entry when the visible region header and landmark should both be removed.
+- `js-headingLevel-[n]`: assign heading level 1-5.
+
+## Template List
+
+1. **Standard**
+
+This is the most common templates.  It includes a border as well as a title.
+
+  ### Button Positions
+  The following are button position names and descriptions
+
+  - EDIT: upper right, next to the title
+  - COPY: upper right, left of Edit, next to the title
+  - PREVIOUS: upper left, below the title
+  - NEXT: upper right, below the title
+  - SORT_ORDER: upper left, below PREVIOUS
+  - REGION_BODY: Before the region content
+  - CLOSE: lower left, below region content
+  - HELP: lower left, to the right of CLOSE, below region content
+  - DELETE: lower right, to the left of CHANGE, below region content
+  - CHANGE: lower right, to the left of CREATE, below region content
+  - CREATE: lower right, below region content
+  - RIGHT_OF_IR_SEARCH_BAR: to the right of an interactive report search bar; only use when region type is Interactive Report
+
+  ### Template Options
+
+   #### Region Title
+
+   - t-Region--removeHeader js-removeLandmark: emit this combined template option entry to remove the visible region header and landmark
+   - js-headingLevel-[n]: where n is a number from 1 to 5, this is the "H" level of the heading
+
+   #### Region Color
+  - t-Region--accentX: where X is a number from 1 to 15, this sets the accent color of the region header
+
+2. **Interactive Report**
+
+Commonly used with Interactive Reports, this template is fairly common and does not have a title / header.
+
+  ### Button Positions
+  The following are button position names and descriptions
+
+  - PREVIOUS: upper left, above the title
+  - NEXT: lower left, below the content
+  - SORT_ORDER: upper left, above PREVIOUS
+  - REGION_BODY: upper left, below PREVIOUS
+  - RIGHT_OF_IR_SEARCH_BAR: to the right of an interactive report search bar; only use when region type is Interactive Report

package/skills/apexlang/references/policies/memory-bank/systemPatterns.md

@@ -0,0 +1,70 @@
+# System Patterns and Architecture
+
+## Purpose
+- Provide a reference-only architecture summary for how this repository organizes agentic APEXlang workflows.
+- Describe relationships between canon, routing assets, skills, templates, and logs without redefining startup or enforcement rules.
+
+## Canonical Sources
+- Startup and task routing:
+  - `SKILL.md`
+- Hard-stop behavioral guardrails and enforcement IDs:
+  - `references/policies/memory-bank/00-guard/ai.guard.md`
+- Load order, path canonicalization, and template/schema precedence:
+  - `references/policies/governance/00-governance.md`
+- Minimal rule selection:
+  - `assets/rules-mapping.json`
+
+## Repository Layers
+- `references/policies/governance/`
+  - Repo-level policy anchor for precedence, path rules, and template/schema authority.
+- `references/policies/memory-bank/`
+  - Partitioned rule corpus:
+    - `00-guard/`
+    - `10-global/`
+    - `20-data/`
+    - `30-pages/`
+    - `40-components/`
+- `skills/`
+  - Direct-entrypoint skills, domain skills, agents, references, and assets.
+- `templates/`
+  - Canonical template families and scenario docs.
+- `applications/app_###/`
+  - Final output root for generated application artifacts.
+- `artifacts/`
+  - Optional output root for compact runtime reports, transcripts, validation outputs, workflow-specific audit artifacts, and export backups. It is created only when a workflow writes outputs.
+
+## Execution Model
+- APEX artifact runs:
+  - enter through a direct-entrypoint skill documented in `SKILL.md`
+  - resolve prerequisite metadata source through `assets/workspace-intelligence.json` plus `references/ops/sqlcl-agents/00-connection-gate.md`
+  - load only the minimal rule set required for the request
+  - run one internal generate -> review -> fix loop, then runtime gates when applicable
+
+## Deterministic Routing
+- Natural-language routing relies on:
+  - `assets/apex-generation/components.registry.json`
+  - `assets/rules-mapping.json`
+- Direct-entrypoint skills that support one-message invocation should expose a `Router Contract` section in `SKILL.md`.
+- Secondary reference docs must not redefine router behavior; they should point back to the owning skill.
+
+## Template Contract Model
+- Family-level surfaces:
+  - `README.md`
+  - `<family>._index.md`
+  - `<family>._common.md`
+- Helper partials such as `_axis._common.md`, `_columns._common.md`, and `_saved-report._common.md` are subcontracts, not family entrypoints.
+- Scenario files should assume the family `_index.md` and `_common.md` establish the selection and shared contract context first.
+- Template-option inventories and shared contracts must agree on emitted values. The accepted value can be a caller-facing token such as a documented `static_id`, a standalone sentinel like `#DEFAULT#`, or a full documented composite string. Concatenated hybrids such as `#DEFAULT#t-Report--stretch` are contract defects, not alternate spellings.
+
+## Logging Model
+- Canonical log root:
+  - `the temp-runtime logs directory under `APEXLANG_OUTPUT_ROOT/logs/`` when logs are written
+- Common artifacts:
+  - `runtime-run.json`
+  - `runtime-run.log`
+- Documentation retirements and other non-log durable artifacts may be recorded under `the temp-runtime reports directory under `APEXLANG_OUTPUT_ROOT/reports/`` when a workflow explicitly persists that evidence.
+
+## Maintenance Rules For This File
+- Keep this file descriptive, not normative.
+- Do not restate startup sequences, gate ownership, or enforcement settings that already belong to `SKILL.md`, `ai.guard.md`, or `00-governance.md`.
+- Historical path removals should live in dedicated legacy or revision-history sections elsewhere, not in this architecture summary.