pi-apexlang 0.1.0

package/skills/apexlang/references/policies/memory-bank/30-pages/apex.classic-report.md

@@ -0,0 +1,65 @@
+## Classic Report Page Standards
+
+### Purpose
+- Produce classic report pages with deterministic layout, region templates, and column alignment.
+
+### Rules (Non-Negotiable)
+1. Use `pageTemplate: @/standard` (or other documented layout) with `templateOptions: #DEFAULT#`.
+2. Main report region must use `type: classicReport` and follow the canonical Classic Report `appearance` and `componentAppearance` blocks owned by `references/policies/memory-bank/40-components/apex.templates.md`.
+   - Classic Report `componentAppearance.templateOptions` defaults to `#DEFAULT#`, `t-Report--stretch`, and `t-Report--horizontalBorders`.
+   - Alternating rows are disabled by omission; do not emit `t-Report--altRowsDefault` or `t-Report--staticRowColors`.
+   - Do not emit row-highlighting by default.
+   - Contextual Info Classic Reports are the documented appearance override: use `appearance.template: @/contextual-info` and `appearance.templateOptions` exactly `#DEFAULT#`, `t-Region--hideHeader js-addHiddenHeadingRoleDesc`, and `t-Region--noUI`.
+3. Default pagination is `rowRangesXToYNoPagination` with a `whenNoDataFound` message; switch to another catalog type only when user intent demands it or performance requirements warrant.
+4. Apply navigation/breadcrumb requirements from `apex.page.md`.
+5. When report navigation is added or changed, ask every time which link mode is required: same application page, another application page, or URL redirect.
+6. For same-application navigation, prefer declarative page targets on the region or column link definition when the DSL supports it; do not default to SQL-computed `apex_page.get_url(...)` or `type: url`.
+7. Every delivered SQL or table projection must have an explicit `column (...)` definition before finals. Do not rely on implicit generated columns for delivered Classic Reports.
+8. Hidden Classic Report columns must omit the `heading` block entirely. This differs from Interactive Report, where hidden columns still require `heading { heading: ... }`.
+9. Classic Report columns with a column-level `link {}` block must also emit top-level `type: link`.
+
+### DB-First Source Verification (Required)
+- For `source.location: localDatabase`, verify source object metadata before writing SQL:
+  - object exists (table/view)
+  - selected columns exist
+  - `ORDER BY` column(s) exist
+- Use `db_connection_name` metadata evidence before drafting final SQL; do not assume names.
+- If metadata is missing/unverified, stop with Missing Inputs and do not emit final SQL.
+- The same DB-first expectation applies to interactive report work when it uses `localDatabase`.
+
+### Guidance
+- Mirror `templates/page-examples/classic-report-page/classic-report-page._index.md` for structure, column ordering, and the canonical Classic Report `appearance` and `componentAppearance` blocks.
+- Keep classic report `appearance.templateOptions` to exact accepted values. `#DEFAULT#` stays standalone, documented composite values remain one atomic entry when the catalog/runtime lists them that way, and inline comma arrays remain invalid.
+- Emit the canonical Classic Report `componentAppearance` block with `template: @/standard` and a multi-line `templateOptions` array containing `#DEFAULT#`, `t-Report--stretch`, and `t-Report--horizontalBorders`. `appearance` controls the outer region wrapper; `componentAppearance` controls the report component template required by runtime validation. In the 26.1 compiler metadata this is property `411`, and live validation reports omissions as `Missing required parameter (411): componentAppearance - template (string)`.
+- For interactive behaviours, add dynamic actions via the appropriate component templates rather than inline code.
+- For HTML-rendered status badges/highlights, use `columnFormatting.htmlExpression` with implicit plain-text columns.
+- Do not emit `type: richText` for `columnFormatting.htmlExpression` patterns.
+- Follow `references/policies/memory-bank/30-pages/apex.report-column-rendering.md` for all SQL-vs-column rendering behavior, formatting-block placement, and HTML literal rules.
+- For same-app drill navigation, define the target declaratively on the report column whenever the component contract supports it. Keep SQL URL columns only for explicit URL mode or components that genuinely require a URL string.
+- For Classic Report column links, keep the report projection column explicit and emit `type: link` next to `reportColumnQueryId` and `derivedColumn`; do not rely on the `link {}` block alone to imply link rendering.
+- Make the primary-key decision explicit:
+  - when row navigation or row identity is part of the page behavior, keep the PK as an explicit report column and wire the target declaratively
+  - when navigation is not intended, keep the PK hidden as a technical column
+- Keep the stronger "all delivered projections need explicit columns" rule limited to Classic Report, Interactive Report, and report-type template components whose family guidance requires projection-aligned child columns by default, such as Metric Card and Content Row.
+- Classic reports should include a default guidance layer. Provide concise user-facing guidance for business-significant columns and all derived, status, and action columns using the supported guidance hook in the selected template family; when no dedicated column-level runtime hook exists, surface that user-facing guidance in page or region help.
+- Apply that default guidance layer even to simple or lightweight classic reports. Keep it concise, but do not omit it merely because the page has one report region or a small column set.
+- Include `comments { comments: ... }` by default on key report columns and high-value report regions. Treat it as descriptive metadata, not help text. For report columns, require the attributes `Display Label`, `Display in Report`, `Display in Form`, `Format Mask`, `Value Required`, `Read Only`, `Primary Display Column`, and `Authorization Scheme`; include `Summary` only when a short leading business-intent sentence materially helps maintenance. When `Summary` is present, keep the field order `Summary`, `Display Label`, `Display in Report`, `Display in Form`, `Format Mask`, `Value Required`, `Read Only`, `Primary Display Column`, `Authorization Scheme`. Mirror executable settings such as `appearance.formatMask` and `security.authorizationScheme` when those blocks are emitted.
+- Hidden technical IDs may skip user-facing guidance, but important technical, derived, status, and action columns still require developer comments.
+- Hidden Classic Report columns should remain structurally lean: omit `heading`, keep explicit sequence/order metadata, and keep comments only when the technical column remains important for maintenance.
+- Critique should fail when a business-significant visible column lacks its expected guidance layer or maintainability comment without an explicit exemption.
+- Column-level `security { authorizationScheme: ... }` is optional but must reference an existing scheme from `{your-app-alias}/shared-components/authorizations.apx` when present; do not invent scheme names. `@authorization-scheme-placeholder` represents the authorization scheme name of choice from user should it be prompted.
+- Column types must align with the canonical catalog in `region-components/classic-report/classic-report._common.md` (plainText, plainTextBasedOnLov, richText, link, image, downloadBlob, hidden). When using `plainTextBasedOnLov`, include `lov { type: sharedComponent|static listOfValues: ... }` with a valid Shared Component (e.g., `@BOOLEAN`).
+
+### Filtering with Page Items
+- Use `templates/region-components/classic-report/classic-report._common.md` for the region contract and pair filter controls with the matching item template (for text search, `templates/items/text-field/text-field._index.md`).
+- When demonstrating filtering patterns, keep the SQL source deterministic and include bind predicates with leading commas and deterministic ordering. Example predicate:
+  ```sql
+  where (:P3_SEARCH is null
+     or upper(p.name) like '%' || upper(:P3_SEARCH) || '%')
+  order by p.name
+  ```
+- Set `pageItemsToSubmit` on the report region to the filtering items (`P3_SEARCH`) so the bind value is sent with each refresh.
+- Create a filter item with `settings { subtype: search }`, place it in a dedicated container region, and follow naming conventions (`P[page]_[name]`). Reference `40-components/apex.items.md` for additional item attributes.
+- Add a dynamic action that listens to the filter item (e.g., `event: keypress`) and runs a `native-refresh` action on the target report region. Maintain pagination preferences and rely on declarative refresh instead of ad-hoc JavaScript.
+- Document any authorization on filtered columns, mirroring the report column rules. Keep process logic separate; filtering does not require `invokeApi` processes, but downstream submit logic must still honor `20-data/apex.logic.md`.
+- When promoting this pattern, mention alternatives (Interactive Report search, Faceted Search) and note that classic report filtering remains useful for lightweight, single-field searches.

package/skills/apexlang/references/policies/memory-bank/30-pages/apex.dashboard.md

@@ -0,0 +1,245 @@
+# Dashboard Standards
+
+Rules and conventions for creating and maintaining Oracle APEX Dashboard Pages.
+All dashboard pages must be a non-modal page and based on `templates/page-examples/dashboard-page/dashboard-page.example.md`.
+
+Keywords: dashboard, kpi, summary, cards, chart, filters, smart filters
+
+---
+
+## Purpose and Scope
+Define a consistent pattern for Dashboard pages that surface KPIs, charts, and summary information. Dashboards prioritize glanceable metrics and quick filtering, not data entry.
+
+---
+
+## General
+- Always start from `templates/page-examples/dashboard-page/dashboard-page._index.md`, then load the shared contract and example as needed.
+- Dashboard pages are non-modal (normal pages)
+- Refer to `apex.page.md` for navigation and naming
+  - Add Navigation List entry (non-modal)
+  - Add Breadcrumb entry (non-modal)
+- Avoid custom behaviors when a standard region type or attribute is available
+
+---
+
+## Standard Composition (Recommended Pattern)
+Top to bottom, left to right:
+1) Hero alert / intro region (static content) to frame the dashboard’s purpose.
+2) Filters at the top of BODY
+   - Option A: Smart Filters region (for multi-attribute search across many regions). Follow `apex.smart-filter-search.md`.
+   - Option B: Simple select list/s as page items driving refresh of regions
+3) Primary results region (classic report or media list) for contextual detail.
+4) KPI Metric Cards (themeTemplateComponent/metricCard) for aggregate KPIs, summary counters, and metric strips.
+5) One or two Charts (side-by-side on the same grid row when space allows)
+
+Grid and layout rules:
+- APEX 12-column grid applies
+- Apply `30-pages/apex.layout.md` as the default contract
+- Keep each row’s total `columnSpan` ≤ 12 when explicit spans are intentionally used
+- Use `startNewRow: false` to place equal-width siblings side-by-side
+- Omit `column`/`columnSpan` unless the row is intentionally asymmetric
+- Dashboard pages with KPI strips, chart rows, report/detail rows, or side-by-side component rows must define a `layout_row_plan` before emitting regions.
+- The artifact must match the `layout_row_plan`: first region in each row omits `startNewRow`; second-and-later regions in the same row set `startNewRow: false`.
+- Treat `startNewRow: false` on the first region of a planned dashboard row as a layout failure because it collapses the row into the previous visual group.
+- A `layout_row_plan` entry represents one physical row, not a group of stacked rows. Full-width stacked detail, contextual summary, and cards sections must be separate one-region row-plan entries; never list multiple stacked full-width regions in one entry.
+- Do not use a generic `dashboard-chart-flow` recipe. Split dashboard charts into explicit `two-up-equal` and `three-up-equal` row entries.
+- Default dashboard rows:
+  - KPI strips: equal-width implicit flow
+  - 2 charts: one `two-up-equal` row
+  - 3 charts: one `three-up-equal` row
+  - 4 charts: two `two-up-equal` rows
+  - 5 charts: one `two-up-equal` row, then one `three-up-equal` row
+  - More than 5 charts: repeat `two-up-equal` and `three-up-equal` rows, preferring balanced rows
+  - detail regions below analytics: stacked full-width, one row-plan entry per full-width region
+- For each chart row, the first chart omits `startNewRow`; second-and-later charts in that row use `startNewRow: false`.
+- Do not literally stack multiple dashboard charts unless the user explicitly requests vertical stacking or a chart is intentionally a detail/full-width section.
+
+Example layout row plan:
+```yaml
+layout_row_plan:
+  - slot: body
+    row: kpi-strip
+    recipe: metric-card-strip
+    regions: [dashboard-kpis]
+  - slot: body
+    row: analytics-1
+    recipe: two-up-equal
+    regions: [orders-by-status, sales-share-by-store]
+  - slot: body
+    row: analytics-2
+    recipe: three-up-equal
+    regions: [orders-by-month, top-products, sales-trend]
+```
+
+---
+
+## KPI / Detail Regions
+Authoritative references:
+- Metric Card template component:
+  - Use `themeTemplateComponent/metricCard` for aggregate numeric KPI strips, summary counters, and normalized multi-metric dashboard widgets.
+  - A single Metric Card region can render multiple KPI cards from one normalized SQL source.
+  - Dashboard KPI Metric Card strips default to `appearance.template: @/blank-with-attributes`; use `@/standard` only when explicitly titled or landmarked visible region chrome is required.
+  - Supported `settings.layout` values are `stacked`, `2Columns`, `3Columns`, `4Columns`, `5Columns`, `autoWrapping`, and `overflow`.
+  - Omit `settings.layout` by default; emit it only when the user requests a specific layout/count behavior or the page pattern has a concrete layout requirement.
+- Managing Cards (Oracle APEX App Builder documentation)
+  - Use native `type: cards` only when the user explicitly asks for Cards/native cards or when the dashboard content is an entity, media, or navigation card grid.
+  - Native Cards support icons, badges, media, and actions for entity-style lists.
+- Managing Classic Reports / Media Lists for summary views
+
+Rules and guidance:
+- Default aggregate KPI strips to one Metric Card region backed by one SQL query.
+- Normalize multi-metric KPI strips with one row per metric, commonly using `UNION ALL` across per-metric SELECTs that project the same aliases in the same order.
+- Do not emit aggregate KPI tiles as `classicReport` regions. A query that projects `metric_value`, `metric_title`, or similar single-value KPI aliases belongs in `themeTemplateComponent/metricCard`.
+- Display concise metric values with a short title and optional meta text.
+- Emit explicit Metric Card child `column (...)` metadata for every projected field.
+- Use native `type: cards` for KPI-like tiles only when the user explicitly specifies Cards/native cards; otherwise reserve Cards for entity/media/navigation card grids.
+- If the dashboard centers on a task/status list, use a classic report or template-component content row/media-list pattern and keep KPI Metric Cards optional.
+- Use minimal SQL that returns only the fields needed by the Metric Card, card, report, or chart attributes.
+
+---
+
+## Charts
+See `apex.chart-page.md` for chart options and patterns.
+
+Rules and guidance:
+- Choose chart type appropriate to the metric: `bar`, `line`, `area`, `pie`, `combination`.
+- Combination charts must specify the correct series type (line/area/bar) and supply axis definitions (x, y, y2) when dual axes are used.
+- Before emitting dashboard KPI strips, chart rows, report/detail rows, or side-by-side component rows, create a `layout_row_plan` that assigns each region to a row recipe.
+- Follow the dashboard chart row defaults from this file and `apex.layout.md`; for five charts, use one `two-up-equal` row followed by one `three-up-equal` row.
+- Vertical chart stacking is valid only when the prompt explicitly requests it or when a chart is intentionally a full-width detail section below the analytical row set.
+- If the dashboard has filter items, ensure each chart series’ source submits filter items:
+```
+    source {
+        ...
+        pageItemsToSubmit: PXX_FILTER
+    }
+```
+- Keep chart queries aggregated and performant (aggregate in SQL; avoid row-by-row logic).
+- Use `legend.position: end` and `hideAndShowBehavior: noRescaling` when mimicking the canonical dashboard to preserve layout stability.
+
+---
+
+## Filters
+Two approved filter patterns:
+
+1) Smart Filters (Oracle APEX)
+   - Single search field with compact UI; results can be cards, classic report, map, or calendar
+   - Use when users need multi-attribute search across multiple regions
+   - Create a Smart Filters region and associate it with the target result region
+   - Adhere to standards in `apex.smart-filter-search.md`
+
+2) Page Item Filters + Dynamic Actions
+   - Use one or more select-list (or similar) items to filter charts/cards
+   - Add a Dynamic Action on item change to refresh affected regions
+   - Each affected region must submit the filter items in its source (`pageItemsToSubmit`)
+   - Example pattern is implemented in `templates/page-examples/dashboard-page/dashboard-page.example.md` using `P60_FILTER` and a refresh DA
+
+Selection guidance:
+- Prefer Smart Filters for search-like dashboards and many facets.
+- Prefer simple page items for one or two clear filter dimensions.
+- When a dashboard is sourced from demo schemas (`EBA_DEMO_*`), ensure filter LOVs return the correct demo values (e.g., project names, stores) and wrap them in views if re-used.
+
+---
+
+## Dynamic Actions (Refresh Pattern)
+- Create a DA with event scope dynamic on filter item change
+- Add a refresh action per affected region (cards, charts, reports)
+- Ensure the targeted regions list all controlling items in `pageItemsToSubmit`
+
+---
+
+## Navigation and Breadcrumb
+- Non-modal dashboards require:
+  - Navigation List entry (see `shared-components/lists.apx`)
+  - Breadcrumb entry (see `shared-components/breadcrumbs.apx`)
+- Follow `apex.page.md` for naming and hierarchy
+
+---
+
+## AI Assistant (Chatbot) — Dashboard Entry Pattern
+- If a prompt asks to “add a chatbot/AI assistant to the dashboard”, **do not** create a custom chat UI region by default.
+- Implement as:
+  - A Breadcrumb/Title Bar button (top of page), and
+  - A Dynamic Action on that button click to open the AI Assistant (template: `templates/business-logic/dynamic-actions/dynamic-actions.show-ai-assistant.md`, prefer `genAI { agent: @AGENT }`).
+  - Resolve the target AI agent from `/shared-components/ai-agents/`.
+- Only implement inline embedded assistant rendering when the user explicitly requests it and provides/approves the container selector + DOM id pattern.
+
+---
+
+## Data and Performance
+- Minimize query cost on dashboards; prefer aggregated views or materialized views
+- Push heavy logic to SQL views/packages (see `20-data/apex.sql.md`, `20-data/apex.logic.md`)
+- Avoid expensive per-card queries; one well-structured query per region is preferred
+- For time-series charts, aggregate at appropriate granularity (for example, TRUNC(date) for daily)
+
+---
+
+## Styling
+- Use only UT region classes documented in memory bank:
+  - `t-Region`, `t-Region-header`, `t-Region-body`
+- Do not invent CSS classes. If additional classes are required, they must be added to the memory bank first
+- Keep template defaults for region appearance unless a documented standard requires change
+
+---
+
+## Implementation Defaults
+- Template path: `templates/page-examples/dashboard-page/dashboard-page.example.md`
+- Include:
+  - A Breadcrumb region using the title-bar template.
+  - An optional hero/alert region for dashboard context.
+  - Filters: either Smart Filters or one/more select list items (example: `P60_FILTER`).
+  - A primary detail region (classic report/media list) or KPI Metric Card region.
+  - Chart regions arranged by `layout_row_plan`; side-by-side by default for multi-chart dashboards.
+  - A Dynamic Action to refresh all affected regions when a filter changes.
+- For each region affected by filters, set `pageItemsToSubmit` to all controlling page items.
+- When duplicating demo dashboards, preserve template option combinations (e.g., `t-Region--scrollBody`, `i-h320`) for consistent height/scrolling.
+
+---
+
+## Example From Template (what to emulate)
+From `templates/page-examples/dashboard-page/dashboard-page.example.md`:
+- A Metric Card KPI strip backed by normalized SQL with one row per metric.
+- Chart regions for visual analytics.
+- For equal-width sibling rows, rely on sequence plus `startNewRow: false` instead of explicit `column` / `columnSpan`
+
+---
+
+## Do and Don’t
+Do:
+- Keep dashboards glanceable: short labels, large values, minimal chrome
+- Reuse the shared template and patterns for consistency
+- Use native Cards actions to drill into details when the dashboard intentionally contains entity/media/navigation cards
+
+Don’t:
+- Add components to Global Page 0 for dashboard-specific needs
+- Bypass Smart Filters when complex multi-attribute search is needed
+- Embed heavy PL/SQL in region sources; prefer SQL with views
+
+---
+
+## Policy — Cards Regions (Non-negotiable)
+- This policy applies only when a native `type: cards` region is intentionally selected, such as for entity, media, or navigation card grids. It does not make native Cards the default for aggregate KPI strips.
+- For regions with type: cards:
+  - Set appearance.template: cards-container on the Cards region.
+  - Do not use @/cards; always use @/cards-container.
+  - Use only cards attributes validated by the current compiler contract.
+  - `componentAppearance.gridColumns` is optional and may be set only to `2`, `3`, `4`, or `5` when the dashboard needs a fixed cards grid.
+  - Omit `componentAppearance.gridColumns` when cards should auto-determine the column count.
+  - When `title.htmlExpression`, `subtitle.htmlExpression`, `body.htmlExpression`, or `secondaryBody.htmlExpression` is emitted, set that same block's `advancedFormatting: true`.
+  - Inside cards `title.htmlExpression`, `subtitle.htmlExpression`, `body.htmlExpression`, and `secondaryBody.htmlExpression`, use `&COLUMN.` substitution strings, not `#COLUMN#`. Prefer escaped substitutions such as `&COLUMN!HTML.` for text values.
+  - Do not emit report-style pagination or inferred card key properties unless parser-confirmed.
+  - Do not emit `performance.maxRowsToProcess` for cards regions unless the cards DSL contract explicitly allows it.
+  - Card action links must use &EDIT_LINK (never #EDIT_LINK#).
+  - The region SQL must compute EDIT_LINK using apex_page.get_url and expose it in the SELECT list, for example:
+    ```sql
+    apex_page.get_url(
+      p_page   => :TARGET_PAGE,
+      p_items  => :TARGET_ITEMS,
+      p_values => :TARGET_VALUES
+    ) as EDIT_LINK
+    ```
+  - Set action.behavior.target: &EDIT_LINK
+
+## References
+- Oracle APEX Cards documentation
+- Oracle APEX Smart Filters documentation

package/skills/apexlang/references/policies/memory-bank/30-pages/apex.faceted-search.md

@@ -0,0 +1,61 @@
+## Faceted Search Page Standards
+
+### Purpose
+- Ensure faceted search pages generate deterministically with Universal Theme defaults.
+- Clarify when to use Faceted Search versus Smart Filters. See `apex.smart-filter-search.md` for the Smart Filter pattern.
+
+### Rules (Non-Negotiable)
+1. **Page Template**
+   - Use `pageTemplate: @/left-side-column` with `templateOptions: #DEFAULT#`.
+   - Include a Breadcrumb region in `slot: breadcrumbBar` using the title-bar template and the standard breadcrumb component appearance.
+2. **Faceted Region Placement**
+   - Place the faceted search region in `slot: leftColumn` with `sequence: 10`.
+   - Region `appearance.template` must be `@/standard`.
+   - Keep `appearance.templateOptions: #DEFAULT#` unless a page-specific exception is explicitly documented.
+3. **Results Region**
+   - Use a Classic Report region located in `slot: body` with `sequence: 20`.
+   - Set `appearance.template: @/standard` and `componentAppearance.template: @/standard`.
+   - Preserve the column ordering from `page-examples/faceted-search/faceted-search._index.md` and align numeric columns to the end.
+4. **Facet Definitions**
+   - Emit child facet metadata with `facet (...)` blocks for this page family; do not guess between `facet` and `filter`.
+   - Use the canonical emitted facet type names from the checked-in example and shared template family: `search`, `checkboxGroup`, `radioGroup`, `selectList`, and `range`.
+   - Include `lov { type: distinctValues }` for all discrete-value facets (checkbox, select list, etc.).
+   - Use page-scoped/static facet names to avoid item-name collisions during import (for example `P2_FACET_SEARCH`, `P2_FACET_CITY`, or `FS_SEARCH_TEXT`).
+   - Do not use generic facet names such as `FACET_SEARCH` that may conflict with existing application-level items.
+   - Type-scoped `listEntries` rule:
+     - Emit `listEntries { maxDisplayedEntries: <n> }` only for `checkboxGroup` and `radioGroup`.
+     - Use `maxDisplayedEntries: 10` by default, with a permitted range of 5-15 when requirements justify a denser or shorter list.
+     - For likely high-cardinality facets such as Product, Customer, Store, Assignee, Owner, User, Employee, Supplier, Email, SKU, or name/title facets, set `displayFilterInitially: true` in `listEntries` so users can search facet values immediately.
+     - Do not emit `listEntries` for any other facet type (for example `range`, `selectList`, `search`).
+   - Use consistent facet sequencing: search → categorical facets → range facets.
+   - Facet `source.dataType` is runtime-sensitive:
+     - For date/time range facets, emit `source.dataType: date` even when the schema column is `TIMESTAMP`.
+     - For numeric range or numeric ID facets, emit `source.dataType: number`.
+     - For text/discrete string facets, omit `source.dataType`; do not emit `varchar2`, `VARCHAR2`, `STRING`, or other SQL/report data-type labels in faceted-search facet sources.
+5. **Linkage**
+   - `filteredRegion` must reference the results region static ID.
+   - Standard faceted-search regions must emit the default settings block:
+     `compactNosThreshold: 10000`, `showCurrentFacets: true`, and `showTotalRowCount: true`.
+   - Treat selector-mode current facets as opt-in only. Emit `showCurrentFacets: selector` only when explicitly requested, and emit `settings.currentFacetsSelector` only with selector mode.
+   - Selector mode requires a concrete selector value supplied by the request or a clearly named generated target.
+   - Emit `settings.displayChartForTopNValues` only for explicit chart/top-N requests; use a positive integer such as `10`.
+   - Do not emit internal runtime tokens such as `NATIVE_SEARCH` or `NATIVE_SELECT_LIST` unless a compiler-validated example explicitly requires them.
+6. **Metadata Validation Gate**
+   - For `localDatabase` sources, all result columns and `facet.source.databaseColumn` values must be metadata-validated via `db_connection_name` in SQLcl; otherwise STOP.
+7. **Canonical Composition**
+   - Keep the faceted-search region in the left-column slot instead of simulating a sidebar with BODY grid coordinates.
+   - Mirror the canonical page example when choosing declaration order and slot usage for breadcrumb, results, and faceted-search regions.
+
+### Guidance
+- Mirror the example DSL in `templates/page-examples/faceted-search/faceted-search._index.md`.
+- Apply navigation/breadcrumb standards from `apex.page.md` when creating new pages.
+- Default facet presentation is inline. Only switch to `appearance { display: addFilterDialog }` when a documented page-specific exception requires it.
+- Use the navigation list entry and breadcrumb patterns documented in the blank page rule (`apex.blank.md`) when scaffolding new faceted pages.
+- Faceted Search result columns mirror classic report rules: provide concise user-facing guidance for business-significant, derived, status, and action columns using the supported guidance hook in the selected template family or page/region help when no dedicated runtime hook exists.
+- Emit `comments { comments: ... }` by default as descriptive metadata. Require the attributes `Display Label`, `Display in Report`, `Display in Form`, `Format Mask`, `Value Required`, `Read Only`, `Primary Display Column`, and `Authorization Scheme`; include `Summary` only when a short leading business-intent sentence materially helps maintenance. When `Summary` is present, keep the field order `Summary`, `Display Label`, `Display in Report`, `Display in Form`, `Format Mask`, `Value Required`, `Read Only`, `Primary Display Column`, `Authorization Scheme`. Mirror executable settings such as `appearance.formatMask` and `security.authorizationScheme` when those blocks are emitted. Only add `security { authorizationScheme: ... }` blocks when needed, and always reference registered schemes from `{your-app-alias}/shared-components/authorizations.apx`.
+
+### Anti-Patterns
+- Do not place the faceted-search region in `slot: body` with `columnSpan` values to simulate a sidebar.
+- Do not pair the standard faceted-search page pattern with an optional page-header wrapper region such as `FS_PAGE_HEADER`.
+- Do not hide the faceted-search region header by default with `t-Region--removeHeader js-removeLandmark`.
+- Do not use `parentRegion` breadcrumb wrappers for the standard faceted-search pattern; place the breadcrumb directly in `breadcrumbBar`.

package/skills/apexlang/references/policies/memory-bank/30-pages/apex.form.md

@@ -0,0 +1,166 @@
+# APEX Form Standards
+
+Rules and conventions for creating and maintaining Oracle APEX **Form Pages** and form regions.
+Form targets may be modal dialogs, drawers, or normal embedded/detail pages based on the routed workflow, and must be based on the shared page-form templates under `/templates/page-examples/` and region form templates under `/templates/region-components/form/`.
+
+---
+
+## General
+- Always start from page form examples in `templates/page-examples/` (for example, `form-page.md`) and pair with `templates/region-components/form/form.basic.md`.
+- Default single-row create/edit form pages launched from reports to drawer end/right; use standard modal dialog, alternate drawer positions, or normal embedded/detail pages only when the routed workflow or page design requires that page mode.
+- Refer to `apex.page.md` for page creation steps
+- Maintain naming consistency and follow the form generation flow defined in global standards
+
+---
+
+## Page Items
+- Non-negotiable: When instantiating regions/items/buttons, load the corresponding templates in `templates/region-components/` or `template-components/` before drafting.
+- **Naming Convention:** `P[page_number]_[column_name]`
+  Example: `P3_TITLE`, `P5_NAME`
+- **Supported Item Types:**
+  `textarea`, `textField`, `selectList`, `radioGroup`, `checkboxGroup`, `datePicker`, `numberField`, `displayOnly`
+- **Required Fields:**
+  - Use `@/required-floating` template
+  - Add `valueRequired: true` to the `validation {}` section
+- **Optional Fields:**
+  - Use `@/optional-floating` template by default
+  - Only use non-floating alternatives when the page is intentionally demonstrating another label layout or a component-specific exception is documented
+- **Visible Item Template Defaults:**
+  - Resolve default item-template and label-treatment choices from `references/policies/memory-bank/40-components/apex.templates.md`.
+  - Keep form-specific exceptions in this file only when the form workflow needs a stricter rule than the shared composition default.
+- **List of Values (LOVs):**
+  - **Static LOVs** → `lovType: static`
+    Prefix values with:
+    - `STATIC:` for sorted
+    - `STATIC2:` for unsorted
+  - **Dynamic LOVs** → `lovType: sqlQuery`
+  - Always confirm column names with the **data dictionary**
+
+---
+
+## Data Types
+- Always set the dataType attribute to lowercase
+
+## Layout
+- To align items horizontally → `startNewRow: false`
+- Key layout attributes:
+
+  | Attribute | Description |
+  |------------|-------------|
+  | `sequence` | Controls display order |
+  | `startNewRow` | Determines new row (true/false) |
+  | `column` | Column position (1–12) |
+  | `columnSpan` | Columns spanned (1–12) |
+
+- The total of `columnSpan` per row should never exceed 12
+- A form region creates its own local 12-column grid for page items inside `layout.region`
+- Child item spans are validated against sibling items in that form region, not against the parent page or parent region span
+- Strive to get the total `columnSpan` to 12 as much as possible; leaving space is not optimal
+- If the items are the same width, then omit `columnSpan`
+- Omit `column` and `columnSpan` unless necessary
+- Use `startNewRow: false` for items on the same grid line
+
+### Buttons Region Placement
+- Default: Place the Buttons region in `BODY` using the `@/buttons-container` template (as in `templates/page-examples/form-page/form-page._index.md`).
+- Allowed variant: Place the Buttons region in the page `BODY` slot when the page layout requires buttons inline with content (e.g., single-column forms or specific aesthetic/composition needs).
+- Constraints for BODY placement:
+  - Keep the region template as `@/buttons-container` and preserve the standard buttons (Cancel, Create/Save, Delete) with their sequences and behaviors.
+  - Do not add custom CSS classes. Keep spacing, alignment, and density inside the shared template/template-option defaults from `references/policies/memory-bank/40-components/apex.templates.md`.
+  - Maintain keyboard accessibility and focus order; ensure buttons remain visible and logically grouped with the form.
+  - Ensure responsive behavior (stacking on small screens) is not impeded.
+
+---
+
+## Foreign Keys
+- For **foreign key columns**, use a **selectList** item
+- The LOV source must be **dynamic SQL**
+- Follow `templates/page-examples/form-page/form-page._index.md` for standard examples.
+
+---
+
+## Help Text
+- Form pages should include page-level help on major user-facing workflows plus concise help text on every user-editable item and filter/control item by default.
+- This default remains in force for simple forms, starter forms, quick CRUD dialogs, and small admin pages. Reduce verbosity when needed, but do not omit help text solely because the form is simple.
+- Use authoritative sources for help content first: prefer reviewed table column comments, approved documentation, or existing Text Messages.
+- When authoritative sources are missing, provisional concise copy is allowed if it stays neutral, translation-ready, and tied to a Text Message key or planned key.
+- Inline help (`inlineHelpText`) must be concise (≤60 characters) and clarify format or intent without repeating the label.
+- Detailed item help (`helpText`) should cover why the value matters, validation highlights, and example values; cap at ~400 characters and reference the Text Message key in drafts.
+- Primary create/save buttons should include concise guidance when the selected button pattern exposes a supported help or annotation hook without cluttering the page.
+- Repeated help text across forms should be centralized in Text Messages so batch wording changes stay easy.
+- Batch updates must rely on the Help Text workflow to ensure consistent sourcing and logging.
+- Critique should fail when visible editable items or visible filter/control items are missing default help text without an explicit exemption.
+
+---
+
+## Implementation Defaults
+- Template paths:
+  - `templates/page-examples/form-page/form-page._index.md`
+  - `templates/region-components/form/form.basic.md`
+- Modal: `true`
+- Use Required Floating: `true`
+- LOV Verification: Always confirm SQL and column sources
+- Examples:
+  - `templates/page-examples/form-page/form-page._index.md`
+  - `templates/region-components/form/form.basic.md`
+
+---
+
+## Deterministic CRUD Form Routing
+- Detection (from parent regions):
+  - If a Classic Report, Interactive Report, or any SQL-generated link (e.g., apex_page.get_url) passes a primary key/ROWID to a target page, the target is a Form page for that base table/view.
+  - If the parent region is an Interactive Grid already configured as editable (edit.enabled), prefer inline IG CRUD with interactiveGridAutoRowProcessing instead of generating a separate form.
+
+- Modal vs Standard target:
+  - Default to a drawer end/right form for single-row edit/create flows initiated from a report row link or an “Add/Create …” button.
+  - Use a non-modal “detail” page with an embedded form region only when the design requires composite layouts with additional IG subregions (e.g., drill-down detail pages). Such pages still use the same ARP (Auto Row DML) for the form region.
+  - Use standard modal dialog only when the requirements or completed application spec explicitly request centered dialog behavior; drawer forms must explicitly set the end/right drawer option, and require explicit evidence for start/left, top, or bottom positions.
+  - Treat "popout" as a standard modal-dialog presentation unless the requirements define a specific drawer or wizard behavior.
+
+- Required form scaffolding (normal, modal, or drawer):
+  - Start from `templates/page-examples/form-page/form-page._index.md`; use `appearance.pageMode: modalDialog` for modal dialogs and the drawer template/page-mode contract when the target is a drawer.
+  - Form region source: tableName + includeRowidCol: true (or explicit PK mapping).
+  - Every generated form region must include an authoritative PK-backed page item mapped to that form region.
+  - For a single-column primary key, generate one hidden PK item with `source.formRegion`, `source.column`, `source.dataType`, and `primaryKey: true`.
+  - For composite primary keys, generate one hidden item for each PK column and set `primaryKey: true` on each PK source mapping.
+  - Do not emit `primaryKey: false` placeholders on non-PK form items; omit the property unless the item is a true primary-key mapping.
+  - Keep the form region edit block minimal: `edit { enabled: true }`.
+  - Do not emit `edit.add`, `edit.update`, or `edit.delete` on form regions; those operation flags belong to interactive grid edit contracts, not regular forms.
+- Buttons:
+    - CANCEL (definedByDynamicAction)
+    - CREATE (`serverSideCondition.type: itemIsNull` on the PK item; databaseAction: insert)
+    - APPLY-CHANGES (`serverSideCondition.type: itemIsNotNull` on the PK item; databaseAction: update)
+    - DELETE (`serverSideCondition.type: itemIsNotNull` on the PK item; uses apex.confirm(...); databaseAction: delete)
+  - Processes:
+    - formInitialization (afterHeader)
+    - exactly one `formAutoRowProcessing` (Auto Row DML) for the form region
+    - when action-specific success text is required, use a transient hidden item such as `P<page>_SUCCESS_MESSAGE` plus a lightweight pre-DML process that sets the item from `:REQUEST`, then reference that item in the single ARP `successMessage`
+    - Close Dialog (showSuccessMessages: false)
+
+- Create vs Edit inference:
+  - “Add/Create …” buttons do not pass a PK → show CREATE, hide APPLY-CHANGES/DELETE.
+  - Row edit links pass PK/ROWID → show APPLY-CHANGES/DELETE, hide CREATE.
+  - Foreign keys needed by the target form should be populated via defaults from parent items (e.g., project_id), matching examples.
+
+- Dialog refresh contract (parent page):
+  - Always register a Dynamic Action on `apexafterclosedialog` to refresh the originating region(s) and optionally show a page success message.
+  - Do not emit aliases such as `dialogClosed`; the event token must match the approved dynamic-action event contract exactly.
+  - Use the standard template: templates/business-logic/dynamic-actions/dynamic-actions.refresh-region-after-dialog.md.
+  - Bind to the specific region(s) affected (e.g., classic report, IR, or IG) as shown in examples.
+  - If you need additional runtime checks, use a `serverSideCondition` from the catalog (references/policies/memory-bank/20-data/apex.logic.md) and follow the syntax examples documented there when combining DA and component conditions.
+
+- Security and protection:
+  - Set pageAccessProtection: argumentsMustHaveChecksum on both parent and form pages.
+  - PK/critical items: sessionStateProtection: checksumRequiredSessionLevel.
+  - Keep warnOnUnsavedChanges disabled for dialog navigations to mirror examples.
+
+- Special case — IG inline CRUD:
+  - For editable Interactive Grids (edit.enabled with allowedOperations), do not generate a separate form:
+    - Provide interactiveGridAutoRowProcessing.
+    - Ensure PK/ROWID columns are hidden and correctly marked as primaryKey.
+    - Set foreign keys via defaults (e.g., item defaults) when appropriate.
+
+## Notes
+- Consistency > creativity — all APEX forms should look and behave the same
+- Validate required fields and dynamic LOVs before deployment
+- Align layout grid to APEX 12-column structure
+- Keep form SQL minimal and offload logic to views or packages when possible

package/skills/apexlang/references/policies/memory-bank/30-pages/apex.interactive-grid-page.md

@@ -0,0 +1,51 @@
+## Interactive Grid Page Standards
+
+### Purpose
+- Guarantee Interactive Grid pages ship with consistent layout, processing, and inline edits.
+
+### Rules (Non-Negotiable)
+1. Set `pageTemplate: @/standard` with `templateOptions: #DEFAULT#` (per the interactive grid page example).
+2. Main region must be `type: interactiveGrid` with `appearance.template: @/standard` and all grid options sourced from `page-examples/interactive-grid/interactive-grid._index.md`.
+3. Every Interactive Grid region must include at least one `savedReport` child block. The default emitted shape is `savedReport PRIMARY`.
+4. Every Interactive Grid `savedReport` must use `singleRowView.displayedColumns` and explicit `displayColumn` children. Cover every declared Interactive Grid column except `APEX$ROW_SELECTOR`, and include `APEX$ROW_ACTION` whenever the region declares it.
+5. Default pagination is `scroll`; use `page` only when inline editing or user requirements call for explicit page-style pagination controls.
+6. Enable automatic row processing (`process type: interactiveGridAutomaticRowProcessing`) with named notation and matching primary key items.
+7. Define column metadata (dataType, heading alignment, editable properties) consistent with the active machine-readable schema in `assets/component-attributes.json`; do not invent unsupported Interactive Grid column blocks even when older prose examples still mention them.
+8. When `source.orderByClause` is used, reference only declared Interactive Grid columns in the same region. Hidden columns are allowed; raw SQL expressions and undeclared columns are not.
+9. When Interactive Grid navigation is added or changed, ask every time which link mode is required: same application page, another application page, or URL redirect.
+10. For same-application navigation, prefer declarative page targets when the component DSL supports them; do not default to URL-style targets when they are unnecessary.
+11. When row-level update protection is required, use `edit.allowedRowOperationsColumn` only if the request/spec explicitly identifies a control column from the region source; declare that column in the grid, usually as hidden.
+12. Apply navigation/breadcrumb standards from `apex.page.md` and ensure the grid has a static ID when referenced by dynamic actions.
+13. Interactive Grid columns use grid item `type` values and saved-report `displayColumn` metadata. Do not copy Classic Report `type: link`, Classic query-position metadata, or Interactive Report column-link syntax into Interactive Grid columns unless compiler-backed metadata for the active build proves a supported grid navigation hook.
+
+### Guidance
+- Follow `templates/page-examples/interactive-grid/interactive-grid._index.md` for column sequencing, toolbar options, and editable settings.
+- Use `savedReport PRIMARY` as the baseline emitted contract unless a different named saved report is explicitly required.
+- Keep the canonical single-row property name as `displayedColumns`; do not emit legacy `displayedCols`.
+- Treat the active compiler/validator behavior as the source of truth for Interactive Grid column blocks. If the machine-readable schema does not allow a column block such as `comments` or `appearance`, surface guidance at the page or region level instead of inventing unsupported DSL.
+- Keep grid navigation separate from report-column rendering until compiler-backed metadata identifies the supported grid navigation contract. Saved-report `displayColumn` coverage is display metadata, not link/navigation metadata.
+- For table-backed grids, use `source.orderByClause` only with declared Interactive Grid columns. For query-backed grids, keep ordering in `source.sqlQuery` unless the sorted value is projected and declared as a grid column.
+- In the v1 row-operations contract, `edit.allowedRowOperationsColumn` gates updates only: `U` means the row is editable for update, and any other value means the row is not updatable.
+- Complement with Interactive Report or Form rules when combining grids with additional regions on the same page.
+- Follow `references/policies/memory-bank/30-pages/apex.report-column-rendering.md` for SQL data-only behavior and column formatting markup placement when grid columns need styled output.
+- Interactive Grids should include a default guidance layer. Provide concise user-facing guidance for business-significant columns and all derived, status, and action columns using the supported guidance hook in the selected template family; when the runtime shape has no dedicated column-help hook, surface that guidance in page or region help.
+
+### Filtering with Page Items
+- Use `templates/region-components/interactive-grid/interactive-grid._common.md` for the region contract and pair filter controls with the matching item templates (for text search, `templates/items/text-field/text-field._index.md`; for select-list and date filters, `templates/items/select-list/select-list._index.md` and `templates/items/date-picker/date-picker._index.md`).
+- When demonstrating filtering patterns, include bind predicates in `source.sqlQuery` or `source.whereClause` with deterministic ordering. Example predicate:
+  ```sql
+  where (:P3_SEARCH is null
+     or upper(employee_name) like '%' || upper(:P3_SEARCH) || '%'
+     or upper(department) like '%' || upper(:P3_SEARCH) || '%')
+  order by employee_name
+  ```
+- Set `pageItemsToSubmit` on the grid region to every filtering item (`P3_SEARCH`, `P3_DEPARTMENT`, `P3_HIRE_DATE_FROM`) so the bind values are sent with each refresh.
+- Create page-level filter items in a dedicated container region, follow naming conventions (`P[page]_[name]`), and reference `40-components/apex.items.md` for supported item attributes.
+- Reuse `templates/business-logic/dynamic-actions/dynamic-actions.refresh-region-on-change.md` so item changes refresh the target grid declaratively; use `keyup` for live text search and `change` for select-list or date-driven filters.
+- Keep page-item filtering orthogonal to grid mechanics: do not change `keyColumn`, do not remove the matching `primaryKey: true` column definition, and do not alter editable-row behavior or ARP request guards solely to support filtering.
+- Native toolbar search and column `columnFilter` remain valid and should continue to be used where appropriate; page-item filtering is for business-driven search, reusable cross-region filters, or default scoping requirements.
+
+### Process Guidance
+- Use `process interactiveGridAutomaticRowProcessing` from the template to handle DML; do not substitute custom PL/SQL unless invoking a dedicated API.
+- Hidden technical IDs may skip user-facing guidance, but important technical, derived, status, and action columns still require either supported column metadata or page/region help text.
+- Column-level `security { authorizationScheme: ... }` is optional and must reference `{your-app-alias}/shared-components/authorizations.apx` when visibility is restricted.