pi-apexlang 0.1.0

package/skills/apexlang/references/domains/debugging/example-scenarios.md

@@ -0,0 +1,101 @@
+> All `node tools/apexctl.mjs ...` commands are package-root relative: run them from the packaged skill root, or invoke that script by explicit path.
+
+# Example Scenarios
+
+## 1. Compiler Version Newer Than Runtime
+- Symptom: import reports that the artifact was created for a newer APEX version than the current runtime.
+- Bucket: `import version-gate failure`
+- First checks:
+  - reproduce the smallest import path
+  - run `apex test run test_app_import`
+- Owner: `wwv_flow_imp*` version validation
+- Fix pattern: adjust legacy import-path version gating or compatibility handling; do not start in upgrade logic.
+- Re-check: smallest direct import reproducer plus `test_app_import`
+
+## 2. Invalid Version Format
+- Symptom: import begin rejects compiler or runtime version format.
+- Bucket: `import version-gate failure`
+- First checks:
+  - inspect `wwv_flow_imp.import_begin`
+  - run `apex test run test_app_import`
+- Owner: import begin parsing
+- Fix pattern: repair import-path parsing and coercion for the supported legacy format.
+- Re-check: `test_app_import`
+
+## 3. Metadata Display-Group Conflict
+- Symptom: metadata validation fails with a display-group or child-component naming conflict.
+- Bucket: `plugin/display-group/identifier conflict`
+- First checks:
+  - `apex util export-metadata`
+  - `sql <db_connection_name>`
+  - `@internal_utilities/dev/sql/pe_data_checks.sql`
+- Owner: property-model metadata surfaces
+- Fix pattern: align display-group metadata and related registrations without masking the conflict in writer or Builder layers.
+- Re-check: metadata export or check path first, then the nearest metadata-related automated coverage
+
+## 4. Successful Import Followed By Large Re-Export Diff
+- Symptom: import succeeds, but exporting the app again creates large churn.
+- Bucket: start with `import canonicalization/upgrade failure`, then fall back to `export/writer round-trip drift` if import normalization is complete
+- First checks:
+  - reproduce the smallest import-plus-export cycle
+  - inspect canonicalization in `wwv_flow_imp*` or `wwv_flow_upgrade*`
+- Owner: import canonicalization first, writer second
+- Fix pattern: complete import normalization if legacy shape should be canonicalized on import; only then patch writer semantics for remaining null, default, or ordering drift.
+- Re-check: the same small import-plus-export cycle until the diff stabilizes
+
+## 5. Builder Import Screen Shows ORDS Or JWT Error
+- Symptom: Builder import UI shows ORDS, JWT, or auth-style failure even though the metadata itself appears valid.
+- Bucket: `Builder transport/auth issue` unless backend import confirms a deeper failure
+- First checks:
+  - verify whether direct import reproduces a backend error
+  - inspect `images/apex_ui/js/f4000_apexlang_import.js`
+  - run `apex test run codeEditor` if the issue stays Builder-specific
+- Owner: Builder transport layer first, backend import path second only if direct import fails
+- Fix pattern: patch Builder JavaScript only for transport, fetch, or auth behavior; otherwise route back to the real backend owner.
+- Re-check: reproduce the Builder flow and confirm the surfaced error is now accurate
+
+## 6. Deep Link Opens The Page But Navigation Does Not Expand
+- Symptom: a deep link opens a level-3 page, but the side navigation does not expand to the correct level-2 parent or mark the leaf entry current.
+- Bucket: `runtime UI/UX verification failure`
+- First checks:
+  - confirm validate/import already succeeded
+  - open the runtime page with Chrome DevTools MCP
+  - capture a text snapshot and inspect current-state plus `aria-expanded`
+- Owner: shared navigation/list metadata first, runtime rendering second only if the metadata is already correct
+- Fix pattern: correct the shared-component hierarchy or current-state rules, then re-check the same deep link in runtime.
+- Re-check: re-open the same deep link and confirm the level-2 branch is expanded and the level-3 leaf is selected
+
+## 7. Wrapper Path Fails But Real SQLcl Session Succeeds
+- Symptom: an MCP, bridge, or wrapper path reports validate/import failure, but the same app path succeeds in a real PATH SQLcl session for the same saved connection.
+- Bucket: `runtime session/wrapper artifact`
+- First checks:
+  - run `node tools/apexctl.mjs runtime preflight`
+  - reproduce with `sql <db_connection_name>`
+  - if needed, retry with `sql /nolog` plus `connect <db_connection_name>`
+  - compare workspace context and command shape
+- Owner: runtime execution path, not the DSL
+- Fix pattern: make the runtime contract and evidence collection use the real SQLcl session as the source of truth
+- Re-check: rerun the same app path through the real SQLcl path and the corrected wrapper path
+
+## 8. Legacy Page-Level Slot Drift
+- Symptom: real SQLcl validate/import reports invalid or deprecated top-level page-region slot values such as `regionBody`, `contentBody`, `REGION_POSITION_01`, or `REGION_POSITION_02` on standard, left-side-column, or login page scaffolds.
+- Bucket: `compiler metadata or property-model failure`
+- First checks:
+  - run `node tools/apexctl.mjs runtime preflight`
+  - reproduce the warning in a real PATH SQLcl session using `sql <db_connection_name>` or the documented `/nolog` fallback
+  - test runtime-aligned replacements on a temporary app copy with validate-only
+- Owner: active APEXlang compiler/property model for the current build, not the wrapper path
+- Fix pattern: for top-level page regions, migrate to the validated semantic slot names for the page family (`breadcrumbBar`, `leftColumn`, `body`) and keep region-local item/button slots unchanged unless the live CLI proves they are also invalid.
+- Re-check: rerun validate/import on the corrected app copy and confirm the top-level slot warnings are gone in the real SQLcl session
+
+## 9. Widespread Missing Theme References
+- Symptom: validation reports many `REFERENCE_NOT_FOUND` errors for `@/standard`, `@/title-bar`, `@/breadcrumb`, `@/text`, `@/login`, `@/side-navigation-menu`, or similar template and default references across many pages at once.
+- Bucket: `theme default/reference drift`
+- First checks:
+  - inspect the target app `shared-components/themes/**/theme.apx` before patching any page
+  - if Universal Theme references like `@/standard` and `@/login` are missing broadly, check first whether `baseTheme` is missing and a legacy `version` field is present instead
+  - confirm the theme uses the current base-theme property/value contract for the active APEX build
+  - compare the app theme against a known-good app exported by the same compiler/runtime build
+- Owner: the app theme contract first, downstream page files second only if the theme defaults are already valid
+- Fix pattern: repair the theme-level contract first, such as replacing stale theme-version fields with the current base-theme shape and value expected by the active build; a missing Universal Theme `baseTheme` should be treated as the primary suspect before editing any page or shared-component reference. Only then revisit any remaining page-local reference failures.
+- Re-check: rerun the local first-pass check and confirm the broad missing-reference set collapses before editing individual pages.

package/skills/apexlang/references/domains/debugging/failure-map.md

@@ -0,0 +1,40 @@
+# APEXlang Debugging Failure Map
+
+Use this matrix after capturing the exact symptom. The goal is to identify the owning layer before opening unrelated code.
+
+| Symptom or error text | Bucket | Owning layer | First confirming check |
+|---|---|---|---|
+| `created for APEX X, current version is Y` | `import version-gate failure` | `wwv_flow_imp*` version validation | Reproduce with the smallest import path and inspect version-gate handling in `wwv_flow_imp*` before touching upgrade logic. |
+| Invalid compiler version or runtime version format | `import version-gate failure` | `wwv_flow_imp.import_begin` plus `test_app_import` coverage | Run `apex test run test_app_import` and inspect version parsing at import begin. |
+| Widespread `REFERENCE_NOT_FOUND` errors for page templates, region templates, template components, labels, lists, or theme defaults such as `@/standard`, `@/title-bar`, `@/breadcrumb`, `@/text`, or `@/side-navigation-menu` | `theme default/reference drift` | The app's `shared-components/themes/**/theme.apx` contract and its base-theme mapping | Inspect the target app `theme.apx` first, check for a missing Universal Theme `baseTheme` binding or a stale `version` field, confirm the theme uses the current base-theme property/value contract, then re-check whether the missing references are downstream symptoms. |
+| Unexpected property validation, metadata dependency failure, requiredness conflict, or default conflict | `compiler metadata or property-model failure` | `apex_install_pe_data.sql`, `wwv_meta_meta_data*`, `pe_data_checks.sql` | Export metadata and run `internal_utilities/dev/sql/pe_data_checks.sql` before changing writer or Builder code. |
+| APEXlang compile errors such as `INVALID_PROPERTY`, `MINIMUM_COMPONENTS_ERROR`, or `MISSING_REQUIRED_PROPERTY` | `compiler metadata or property-model failure` | The `.apx` artifact shape plus component metadata requiredness | Reproduce with direct `apex validate -input` or `apex import -input`, map the property/component to the template or generator that emitted it, then patch the source rule before retrying. |
+| Display-group conflict, child-component naming conflict, or property-model object-name conflict | `plugin/display-group/identifier conflict` | `pe_data_checks.sql` and the property-model layer | Run the targeted metadata checks and verify the conflicting display-group or child-component registration. |
+| Explicit nulls disappear, defaults churn, or omitted fields reappear after export | `export/writer round-trip drift` | `wwv_flow_apx*`, `gen_api_pkg.plb`, export semantics | Diff the smallest reproducer and check writer handling for null, default, and omission semantics. |
+| Import succeeds but re-export produces large churn | `import canonicalization/upgrade failure` or `export/writer round-trip drift` | `wwv_flow_imp*` / `wwv_flow_upgrade*` first, writer second | Confirm whether import canonicalization normalized the legacy shape fully before changing the writer. |
+| Builder import screen shows ORDS, JWT, fetch, or auth failure | `Builder transport/auth issue` | `images/apex_ui/js/f4000_apexlang_import.js` | Verify whether the failure is transport-only or whether the underlying import call is failing with a real import error. |
+| `Multiple workspaces available, use the workspaceId or the workspace option.` | `runtime session/workspace routing issue` | Real SQLcl runtime contract and workspace selection for the active run | Reproduce from a real PATH SQLcl session after capability probing before touching DSL or import logic. |
+| Bridge, MCP, or wrapper execution reports a failure, but the equivalent real PATH SQLcl session succeeds | `runtime session/wrapper artifact` | Runtime execution path, not the APEXlang artifact | Reproduce with the same app path and connection using a real PATH SQLcl session. |
+| A running APEX app reports an APEX/ORA error and the error text can be found in `APEX_DEBUG_MESSAGES` | `runtime APEX execution-log failure` | The app component, PL/SQL surface, plugin, SQL query, Ajax callback, or APEX runtime layer identified by the `PAGE_VIEW_ID` execution log | Search `APEX_DEBUG_MESSAGES.MESSAGE` for the stable error text, resolve `PAGE_VIEW_ID`, then fetch the full log for that page view. |
+| The same APEX/ORA error appears in multiple `APEX_DEBUG_MESSAGES` page views | `runtime APEX execution-log failure` | Unknown until the failed run is narrowed | Ask for `PAGE_VIEW_ID` / debug id, `SESSION_ID`, application id, page id, user, or approximate timestamp before diagnosing. |
+| `APEX_DEBUG_MESSAGES` contains the error row but no useful preceding process, SQL, PL/SQL, Ajax, or call-stack context | `runtime APEX execution-log failure` | Unknown until a higher-debug reproduction exists | Ask the user to reproduce with APEX debug level set to Full trace and provide the new `PAGE_VIEW_ID` / debug id or `SESSION_ID`. |
+| Parser or file-shape failure on `.apx` input before import semantics apply | `APX syntax or file-shape failure` | The `.apx` artifact shape and local validators | Run the smallest local validator and inspect file shape before touching import packages. |
+| Validate/import succeeds but runtime navigation, current-state, focus, or visible page structure is wrong | `runtime UI/UX verification failure` | Shared components, page composition, templates, or runtime rendering depending on the snapshot evidence | Run the Chrome DevTools MCP verification loop first and map the observed runtime state before touching Builder transport or import code. |
+
+## Owner Selection Rules
+- Prefer `import version-gate failure` when the message is about runtime version, compiler version, or import begin.
+- Prefer `theme default/reference drift` when many pages or shared components suddenly lose template references that should be provided by the active Universal Theme defaults.
+- Prefer `compiler metadata or property-model failure` when the message names a property, default, dependency, display group, or child-component rule.
+- Prefer `export/writer round-trip drift` when import works but the serialized output is unstable.
+- Prefer `import canonicalization/upgrade failure` when successful import still leaves legacy shape drift that should have been normalized during import.
+- Prefer `Builder transport/auth issue` only for fetch, ORDS, JWT, auth, or UI transport symptoms.
+- Prefer `runtime session/workspace routing issue` when the SQLcl runtime path blocks on workspace ambiguity before compile or import semantics.
+- Prefer `runtime session/wrapper artifact` when the real SQLcl session and a bridge path disagree for the same artifact and connection.
+- Prefer `runtime APEX execution-log failure` when a live running app emits an APEX/ORA error and `APEX_DEBUG_MESSAGES` can correlate it to a `PAGE_VIEW_ID`.
+- Prefer `runtime UI/UX verification failure` when the defect remains only in the running app after validate/import are already green.
+
+## Anti-Patterns
+- Do not jump to Builder JavaScript because the first visible symptom appeared in Builder.
+- Do not patch upgrade logic for a problem that happens only during import of transient input.
+- Do not patch writer ordering or omission rules before ruling out missing import canonicalization.
+- Do not treat a runtime UI symptom as an import failure when the app metadata already validates and imports cleanly.

package/skills/apexlang/references/domains/debugging/fix-patterns.md

@@ -0,0 +1,66 @@
+# Fix Patterns
+
+Apply the fix pattern that matches the failure bucket. Do not spread one defect across multiple layers unless the contract truly spans them.
+
+## Import Version-Gate Failure
+- Put version-gated import fixes on the legacy import path.
+- Fix parsing, coercion, and compatibility handling in `wwv_flow_imp*` before considering upgrade logic.
+- Verify with `apex test run test_app_import` and the smallest direct import reproducer.
+
+## APX Syntax Or File-Shape Failure
+- Fix the emitted or edited `.apx` shape first.
+- Do not patch import packages to accept malformed shape unless the format is intentionally supported.
+- Re-run the smallest local validator before any broader import test.
+
+## Compiler Metadata Or Property-Model Failure
+- Keep dependency, requiredness, default, and display-group changes aligned across `apex_install_pe_data.sql`, `wwv_meta_meta_data*`, Builder emitters, and import or export paths.
+- If metadata rules change, confirm `pe_data_checks.sql` passes before touching broader flows.
+- Treat MMD and property-model contracts as the source of truth for allowed structure.
+
+## Import Canonicalization Or Upgrade Failure
+- Use import canonicalization when transient legacy input should normalize during import.
+- Use upgrade logic only when persisted legacy rows must be repaired after storage.
+- Confirm the chosen layer removes re-export churn without moving drift into the writer.
+
+## Export Or Writer Round-Trip Drift
+- Preserve canonical defaults, omission semantics, and explicit-null semantics.
+- Fix missing, null, default, or ordering drift in the writer and export surfaces, not in unrelated metadata files.
+- Re-check with the smallest import-plus-export reproducer until the diff stabilizes.
+
+## Plugin, Display-Group, Or Identifier Conflict
+- Clean up plugin JSON or related metadata while preserving `compute_attributes` parity.
+- Fix identifier and static-id issues in a way that preserves deterministic ID handling.
+- Re-run metadata checks first, then the smallest owning test.
+
+## Builder Transport Or Auth Issue
+- Only patch Builder JavaScript when the failure is fetch, auth, ORDS, JWT, or UI transport.
+- If Builder merely exposes a backend import error, fix the backend owner and keep the UI change limited to better surfacing when needed.
+
+## Runtime Session Or Workspace Routing Issue
+- Reproduce from a real PATH SQLcl session after capability probing before changing the DSL.
+- Add a run-scoped `-workspaceid` only after SQLcl explicitly reports multiple-workspace ambiguity, and resolve that workspace id automatically for the active `db_connection_name` before rerunning.
+- Keep the fix in the runtime contract or invocation path; do not mutate the APEXlang artifact to compensate for workspace selection.
+
+## Runtime Session Or Wrapper Artifact
+- Treat the real PATH SQLcl session as the source of truth when it disagrees with a bridge or wrapper path.
+- Fix the execution path, session handling, or evidence collection first; do not patch the DSL to satisfy a false negative from the wrapper path.
+- Re-check with the same artifact and connection in a real SQLcl session before declaring the issue fixed.
+
+## Runtime APEX Execution-Log Failure
+- Start from the `APEX_DEBUG_MESSAGES.PAGE_VIEW_ID` full execution log, not from the isolated error message.
+- If multiple page views match, ask for `PAGE_VIEW_ID` / debug id or `SESSION_ID` before picking an owner.
+- If the existing log is sparse, ask for a Full trace reproduction before editing.
+- Fix only the owner indicated by the full log: page process, validation, computation, dynamic action Ajax callback, report SQL, plugin, PL/SQL package, REST integration, or runtime configuration.
+- Reproduce the failing flow with debug enabled after the fix and confirm the new `PAGE_VIEW_ID` log no longer contains the error.
+
+## Runtime UI Or UX Verification Failure
+- Confirm the defect in the running app with Chrome DevTools MCP before changing code or metadata.
+- Fix the owning layer that the snapshot evidence points to: shared components, page composition, templates, or runtime rendering.
+- Re-run the same runtime page and interaction path after the fix; do not accept validate/import success alone as proof.
+
+## Cross-Layer Alignment Rules
+- Do not change only one surface when the contract spans metadata declarations, Builder emitters, and import or export behavior.
+- Do not use upgrade logic as a shortcut for import-path compatibility.
+- Do not use writer normalization to hide a missing import canonicalization step.
+- Do not patch Builder transport or import code to compensate for a runtime UI state issue that is already visible in snapshot evidence.
+- Do not patch from a live APEX error message alone when `APEX_DEBUG_MESSAGES` can provide the full execution log.

package/skills/apexlang/references/domains/debugging/owning-surfaces.md

@@ -0,0 +1,37 @@
+# Owning Surfaces
+
+Use this map to keep changes in the correct layer and to verify in the closest existing coverage.
+
+| Owning layer | Change here | Verify there |
+|---|---|---|
+| Property model | `apex_install_pe_data.sql`, `wwv_meta_meta_data*`, `internal_utilities/dev/sql/pe_data_checks.sql` | Re-run metadata export or checks first, then the smallest metadata-related test that covers the changed rule. |
+| APEXlang architecture or writer | `wwv_flow_apx*`, `gen_api_pkg.plb`, export semantics | Re-run the smallest reproducer that shows null, default, or ordering drift, then confirm the re-export stabilizes. |
+| Import path | `wwv_flow_imp*`, especially `wwv_flow_imp.import_begin` for version parsing and import-time coercion | Re-run `apex test run test_app_import`, then the smallest direct validate or import reproducer. |
+| Upgrade path | `wwv_flow_upgrade*` only when persisted legacy rows must be normalized in storage | Re-run the legacy-row upgrade scenario plus the import or export check that proved the defect. |
+| Builder import UI | `images/apex_ui/js/f4000_apexlang_import.js` | Reproduce the Builder-side transport behavior and confirm the backend import path is either healthy or now surfaces the correct message. |
+| Runtime APEX execution log | App page process, validation, computation, dynamic action Ajax callback, report SQL, plugin, PL/SQL package, REST call, or runtime layer named by the selected `APEX_DEBUG_MESSAGES.PAGE_VIEW_ID` log | Re-query the same `PAGE_VIEW_ID` for diagnosis, apply the smallest owner-specific fix, then reproduce with debug enabled and confirm the new run no longer emits the error. |
+| Runtime UI or UX behavior | Shared components, page `.apx` composition, templates, or runtime widget/rendering layer depending on snapshot evidence | Re-run the same runtime page with Chrome DevTools MCP and confirm the visible state, selected item, focus target, or region presence is corrected. |
+
+## Change Here, Verify There
+- Property-model changes should verify in metadata checks before import tests.
+- Import-package changes should verify in import tests before broader round-trip checks.
+- Writer changes should verify with the smallest drift reproducer, not just a generic import pass.
+- Upgrade changes should prove persisted-data repair, not merely transient import coercion.
+- Builder UI changes should verify the transport symptom and the surfaced backend error shape.
+- Runtime APEX execution-log fixes should verify against a new reproduced request, not only the old debug rows.
+- Runtime UI fixes should verify the exact user-visible page state, not just a successful import or compile.
+
+## Nearest Existing Coverage
+- `apex test run test_app_import`: nearest automated coverage for import begin, version gating, and import-time coercion.
+- `apex test run test_gendev_bp_to_apexlang`: nearest automated coverage for generation-to-APEXlang metadata emission paths.
+- `apex test run codeEditor`: nearest automated coverage for Builder-adjacent code editor and import UI flows.
+- `internal_utilities/dev/sql/pe_data_checks.sql`: nearest targeted check for property-model and display-group conflicts.
+- Chrome DevTools MCP text snapshots: nearest runtime verification for navigation state, visible composition, focus behavior, and post-import UI drift.
+- `APEX_DEBUG_MESSAGES` full log by `PAGE_VIEW_ID`: nearest live evidence for page-process, Ajax, SQL, PL/SQL, and plugin runtime errors.
+
+## Ownership Boundaries
+- If a fix changes how legacy input is accepted during import, start in import code, not upgrade code.
+- If a fix changes what metadata is legal, keep property-model declarations, metadata validation, and emitters aligned.
+- If the failure only appears after export, do not start in Builder.
+- If a live APEX error has a debug log, do not diagnose from the standalone error text before reading the full `PAGE_VIEW_ID` log.
+- If the failure appears only in the running app after validate/import succeed, start with runtime verification evidence before assigning ownership.

package/skills/apexlang/references/domains/debugging/runtime-ui-verification.md

@@ -0,0 +1,60 @@
+# Runtime UI Verification
+
+Use this path when validate/import succeeded but the reported defect is still visible in the running app.
+
+## Use When
+- The page loads but the surrounding navigation state is wrong.
+- A deep link opens the target page but not the expected level-2 or level-3 current state.
+- Runtime content is missing, hidden, out of order, or rendered in the wrong region.
+- Keyboard focus, selected state, or expand/collapse behavior is incorrect.
+- The issue is responsive or layout-related and must be verified in the running app.
+
+## Do Not Use When
+- The failure is still a direct `apex validate` or `apex import` error.
+- The issue is Builder transport, auth, ORDS, or JWT behavior.
+- The task is non-structural skinning verification rather than runtime behavior debugging.
+
+## Evidence Order
+1. Use Chrome DevTools MCP text snapshots first.
+2. If Chrome DevTools MCP is unavailable, use the inferred runtime page URL plus HTTP/HTML capture from the runtime verifier.
+3. Use DOM or JavaScript inspection second to confirm current-state classes, `aria-expanded`, `aria-current`, focus target, or region presence.
+4. Use screenshots only when the text snapshot is insufficient for the visible symptom.
+
+## Verification Loop
+1. Open the runtime page that reproduces the issue.
+2. Capture a text snapshot, or use the recorded HTTP/HTML artifact when MCP is unavailable.
+3. Record the visible symptom in user-facing terms.
+4. Inspect the nearest runtime state:
+   - navigation tree expansion and current item
+   - `aria-current`, `aria-expanded`, and selected classes
+   - visible headings, cards, lists, tabs, or regions
+   - focus target after load or interaction
+5. Interact only as needed:
+   - click the relevant nav parent or control
+   - navigate to the deep link
+   - trigger the tab, menu, drawer, or disclosure state
+6. Capture a second text snapshot after the interaction.
+7. Map the observed runtime behavior to the owning layer before proposing a fix.
+8. Re-run the same runtime check after the fix.
+
+## Standard Symptoms To Catch
+- Level-2 or level-3 navigation entries do not expand for the active page.
+- The current page is not marked selected or current.
+- A restored shared-component structure imports successfully but runtime behavior stays flat.
+- Content exists in metadata but is not visible in the intended region, order, or pattern block.
+- Keyboard focus lands on the wrong element after page load or interaction.
+- Responsive layout behavior hides, collapses, or reorders the wrong content.
+
+## Owning-Layer Hints
+- Shared navigation/list issue: shared components and runtime navigation state.
+- Wrong page composition or region placement: page composition and template usage.
+- Current-state or expand/collapse mismatch after otherwise correct metadata: runtime rendering or list current-state configuration.
+- Focus or keyboard issue with correct structure: runtime rendering, accessibility behavior, or Builder/runtime widget layer.
+
+## Response Shape
+- Runtime page tested
+- User-visible symptom
+- Snapshot evidence
+- DOM or runtime state observed
+- Likely owning layer
+- Smallest re-check after the fix

package/skills/apexlang/references/domains/page-components/business-logic.md

@@ -0,0 +1,5 @@
+# Business Logic Alias
+
+This compatibility alias exists for older packaged references.
+
+Use `references/domains/README.md` as the canonical domain workflow entrypoint and load the Business Logic section.

package/skills/apexlang/references/domains/page-components/buttons/registry.md

@@ -0,0 +1,14 @@
+# Component Registry — Buttons
+
+| Keyword/Synonym | Template/Skill | Notes |
+|-----------------|----------------|-------|
+| button | `templates/buttons/buttons._index.md` | Generic button dispatcher |
+| translation button | `references/domains/page-components/buttons/workflow-button-batch.md` | Clarify runtime language switching vs localization; runtime switch defaults to submit button plus guarded page process |
+| primary button | `templates/buttons/buttons.appearance-icon.md` | Primary action styling; emits `hot: true` |
+| delete button | `templates/buttons/buttons.submit.md` + `templates/buttons/buttons.confirmation.md` | Delete confirmation |
+| menu button | `templates/buttons/buttons.menu.md` | Menu entries and nested options |
+| remove button component | `references/domains/page-components/buttons/workflow-button-batch.md` | Hard-delete button component with dependency checks (single or batch) |
+| button actions batch | `references/domains/page-components/buttons/workflow-button-batch.md` | Apply/remove actions and component removals (single or batch) |
+| dynamic action refresh | `templates/business-logic/dynamic-actions/dynamic-actions.refresh-region-after-dialog.md` | For button-triggered refresh |
+
+When business logic (invokeApi, SSC, validations) is required, coordinate with `references/domains/README.md` and `references/domains/README.md`.

package/skills/apexlang/references/domains/page-components/buttons/reusable-prompts.md

@@ -0,0 +1,11 @@
+# Button Reusable Prompts
+
+## Standard button prompts
+- "Create a primary submit button with confirmation and DML action."
+- "Add a disabled primary button that triggers downloadable SQL."
+- "Generate a button menu with redirect and PL/SQL execution entries."
+- "Replicate this redirect button across pages 5, 10, and 12."
+
+## Batch workflow notes
+- For batch updates use `references/domains/page-components/buttons/workflow-button-batch.md`.
+- Capture action type, layout, appearance, behavior, security, and target scope.

package/skills/apexlang/references/domains/page-components/buttons/templates.md

@@ -0,0 +1,25 @@
+# Template References — Buttons
+
+## Authoritative Policies
+- `references/policies/governance/00-governance.md`
+- `references/policies/memory-bank/00-guard/ai.guard.md`
+- `references/policies/memory-bank/10-global/apex.global.md`
+- `references/policies/memory-bank/40-components/apex.buttons.md`
+- `references/policies/memory-bank/20-data/apex.logic.md`
+
+## Operational References
+- `templates/buttons/buttons._common.md`
+- `templates/buttons/buttons._index.md`
+- `templates/buttons/buttons.submit.md`
+- `templates/buttons/buttons.redirect-this-app.md`
+- `templates/buttons/buttons.redirect-other-app.md`
+- `templates/buttons/buttons.defined-by-da.md`
+- `templates/buttons/buttons.trigger-action.md`
+- `templates/buttons/buttons.menu.md`
+- `templates/buttons/buttons.confirmation.md`
+- `templates/buttons/buttons.server-side-condition.md`
+- `templates/buttons/buttons.appearance-icon.md`
+- `templates/business-logic/dynamic-actions/dynamic-actions.refresh-region-after-dialog.md` (for button-triggered refresh)
+- `references/domains/page-components/buttons/reusable-prompts.md`
+
+Use `assets/rules-mapping.json` to load the minimal subset for each button request.

package/skills/apexlang/references/domains/page-components/buttons/workflow-button-actions-batch.md

@@ -0,0 +1,44 @@
+# Workflow: Button Actions — Batch Apply
+
+Purpose
+- Apply shared button configurations (submit, redirect, triggerAction, menu) across multiple pages while enforcing guardrails.
+
+Required inputs
+- `action_type`: submitPage | redirectThisApp | redirectOtherApp | triggerAction | menu.
+- `layout_defaults`: slot, sequence, region static id (overridable per target).
+- `appearance_defaults`: template, hot/showAsDisabled flags, icons, and canonical emitted `templateOptions` values from the button contract (for example `t-Button--iconLeft`, not `left`).
+- `behavior_defaults`: confirmation settings, databaseAction, targets, warnOnUnsavedChanges.
+- `target_buttons`: list of `{ page, region, buttonName, overrides? { layout, appearance, behavior, confirmation, serverSideCondition } }`.
+- Optional: nested menu entries or triggerAction payloads (SQL/PLSQL bodies, itemsToSubmit/Return).
+
+Load
+- references/policies/memory-bank/00-guard/ai.guard.md
+- references/policies/memory-bank/10-global/apex.global.md
+- references/policies/memory-bank/40-components/apex.buttons.md
+- Templates:
+  - `templates/buttons/buttons._common.md`
+  - `templates/buttons/buttons._index.md`
+  - Action-specific template selected by `action_type`:
+    - submitPage -> `templates/buttons/buttons.submit.md`
+    - redirectThisApp -> `templates/buttons/buttons.redirect-this-app.md`
+    - redirectOtherApp -> `templates/buttons/buttons.redirect-other-app.md`
+    - definedByDynamicAction -> `templates/buttons/buttons.defined-by-da.md`
+    - triggerAction -> `templates/buttons/buttons.trigger-action.md`
+    - menu -> `templates/buttons/buttons.menu.md`
+
+Execution model
+- Validate `action_type` and ensure required attributes are provided (e.g., target for redirects, databaseAction for submit DML, nested entries for menus).
+- Merge shared defaults with per-target overrides before invoking the button template.
+- For triggerAction/menu entries, capture nested definitions and ensure they meet guardrails (no side effects, proper itemsToSubmit/Return).
+- Produce a compact run summary under `the temp-runtime logs directory under `APEXLANG_OUTPUT_ROOT/logs/`` only when the workflow explicitly needs durable evidence, summarising targets, action_type, layout slot, and confirmation state.
+- Do not apply direct page-file changes until the approval loop is satisfied.
+
+Completion
+- Record a compact status entry only when the workflow explicitly persists durable evidence.
+- Revision agent applies approved changes, updates page files, and records applied or reverted state only when needed.
+
+Notes
+- Ensure layout.slot is valid for each target region (consult apex.templates.md).
+- For `appearance_defaults.templateOptions`, use canonical emitted button UT class values from `templates/buttons/buttons._common.md` and `references/policies/memory-bank/40-components/apex.buttons.md`; do not use aliases/static_ids.
+- When action_type = submitPage, remind users to guard related processes; batch invokeApi handling remains in `references/domains/business-logic/processes/workflow-page-processes-batch.md`.
+- For menu entries, gather child behaviors in structured inputs (redirect targets, triggerAction bodies) and validate icons/template options.

package/skills/apexlang/references/domains/page-components/buttons/workflow-button-batch.md

@@ -0,0 +1,58 @@
+# Workflow: Button Actions — Apply/Remove (Single + Batch)
+
+Purpose
+- Apply or remove button components across one or many pages/regions while enforcing guardrails.
+
+Required inputs
+- `operation`: apply | remove (default `apply`).
+- `action_type`: submitPage | redirectThisApp | redirectOtherApp | triggerAction | menu. Required when `operation = apply`.
+- `layout_defaults`: slot, sequence, region static id (overridable per target). Used when `operation = apply`.
+- `appearance_defaults`: template, hot/showAsDisabled flags, icons, and canonical emitted `templateOptions` values from the button contract (for example `t-Button--iconLeft`, not `left`). Used when `operation = apply`.
+- `behavior_defaults`: confirmation settings, databaseAction, targets, warnOnUnsavedChanges. Used when `operation = apply`.
+- `targets`: list of `{ page, region, buttonName, overrides? { layout, appearance, behavior, confirmation, serverSideCondition } }`.
+- Optional single-target convenience input: `target` (same structure as one `targets` entry; normalize to a one-item list).
+- Backward compatibility: accept `target_buttons` / `target_button` and normalize to `targets`.
+- Optional: nested menu entries or triggerAction payloads (SQL/PLSQL bodies, itemsToSubmit/Return).
+
+Load
+- references/policies/memory-bank/00-guard/ai.guard.md
+- references/policies/memory-bank/10-global/apex.global.md
+- references/policies/memory-bank/40-components/apex.buttons.md
+- Templates:
+  - `templates/buttons/buttons._common.md`
+  - `templates/buttons/buttons._index.md`
+  - Action-specific template selected by `action_type`:
+    - submitPage -> `templates/buttons/buttons.submit.md`
+    - redirectThisApp -> `templates/buttons/buttons.redirect-this-app.md`
+    - redirectOtherApp -> `templates/buttons/buttons.redirect-other-app.md`
+    - definedByDynamicAction -> `templates/buttons/buttons.defined-by-da.md`
+    - triggerAction -> `templates/buttons/buttons.trigger-action.md`
+    - menu -> `templates/buttons/buttons.menu.md`
+
+Execution model
+- Normalize `target`/`target_buttons`/`target_button` -> `targets`.
+- Validate operation mode:
+  - `apply`: validate `action_type` and required attributes (target for redirects, databaseAction for submit DML, nested entries for menus), then merge shared defaults with per-target overrides before invoking templates.
+  - `remove`: perform hard-delete prechecks before removal.
+- Remove prechecks (fail-fast, deterministic):
+  - Resolve exact target button by page + region + buttonName.
+  - Reject `not_found` and `ambiguous` targets.
+  - Scan dependencies and block removal when references exist, including:
+    - Dynamic actions using button aliases (`when.selectionType: button`)
+    - `serverSideCondition.whenButtonPressed`
+    - Process/request guards that depend on the button request semantics
+- Produce a compact run summary under `the temp-runtime logs directory under `APEXLANG_OUTPUT_ROOT/logs/`` only when the workflow explicitly needs durable evidence, summarising targets, operation, and per-target status (`applied`, `removed`, `blocked`, `not_found`, `ambiguous`) with blockers.
+- Do not apply direct page-file changes until the approval loop is satisfied.
+
+Completion
+- Record a compact status entry only when the workflow explicitly persists durable evidence.
+- Revision agent applies approved changes, updates page files, and records applied or reverted state only when needed.
+
+Notes
+- Ensure layout.slot is valid for each target region (consult apex.templates.md).
+- For `appearance_defaults.templateOptions`, use canonical emitted button UT class values from `templates/buttons/buttons._common.md` and `references/policies/memory-bank/40-components/apex.buttons.md`; do not use aliases/static_ids.
+- When `operation = apply` and action_type = submitPage, remind users to guard related processes; batch invokeApi handling remains in `references/domains/business-logic/processes/workflow-page-processes-batch.md`.
+- If the prompt asks for a translation/language button, do not reinterpret it as navigation/menu generation. Clarify whether the user wants runtime language switching or text-message localization.
+- When the user confirms a runtime language-switch button, default to `action_type = submitPage` and pair it with a page process guarded by `whenButtonPressed`; do not default to redirect actions for this pattern.
+- For menu entries, gather child behaviors in structured inputs (redirect targets, triggerAction bodies) and validate icons/template options.
+- Remove mode default is hard delete + reference checks; do not auto-clean dependent dynamic actions/processes/server-side conditions in the same run.

package/skills/apexlang/references/domains/page-components/buttons.md

@@ -0,0 +1,67 @@
+---
+name: buttons
+description: Configure Oracle APEX buttons, confirmation dialogs, and apply/remove actions using canonical templates and guardrails. Use when Codex must add, update, or remove buttons within Apex Developer flows.
+---
+
+# Reference Package — Buttons & Actions
+
+**Parent Entries:** `references/domains/README.md` (domain), `SKILL.md` (router)
+
+## Purpose
+- Apply or remove button components with consistent layout, behavior, and confirmations.
+- Enforce button-specific guardrails before integrating with business logic or process batches.
+
+## When to Trigger
+- The user requests button additions/updates/removals across pages or regions, including one-target operations.
+- Combine with Business Logic or Universal Attribute skills for validations, SSC, or help text.
+
+## Required Inputs
+- `operation`: apply | remove (default apply).
+- `action_type`: submitPage | redirectThisApp | redirectOtherApp | triggerAction | menu (required for apply).
+- Layout defaults (slot, sequence, region static ID).
+- Appearance defaults (template, icon, hot/disabled flags, and canonical emitted `templateOptions` values from the button contract).
+- Behavior defaults (confirmations, targets, warnOnUnsavedChanges, nested entries).
+- Canonical `targets` list with per-target overrides, or a single `target` convenience object.
+- Backward compatibility: `target_buttons` / `target_button` are accepted and normalized to `targets`.
+
+## Authoritative Policies
+- `references/policies/memory-bank/00-guard/ai.guard.md`
+- `references/policies/memory-bank/10-global/apex.global.md`
+- `references/policies/memory-bank/40-components/apex.buttons.md`
+- `references/policies/memory-bank/20-data/apex.logic.md`
+- `references/policies/governance/00-governance.md`
+
+## Operational References
+- Templates from `templates/buttons/`
+- `references/domains/page-components/buttons/templates.md`
+- `references/domains/page-components/buttons/registry.md`
+- `assets/domains/page-components/buttons/button-actions.md`
+- Optional workflow coupling: `references/domains/README.md`, `references/domains/README.md`
+
+## Execution Agents
+- `references/ops/sqlcl-agents/00-connection-gate.md` (when DB-aware validation is required).
+- `references/ops/runtime-gates/02-direct-sqlcl-validate-gate.md` for import-ready completion checks.
+- The internal generate/review/fix loop remains under `references/workflows/apex-generation/agents/`.
+
+## Guardrails
+- Validate action_type requirements (targets for redirects, databaseAction for submit DML, nested menus for children).
+- Require canonical emitted button templateOptions values such as `t-Button--iconLeft` and reject aliases/static_ids such as `left`.
+- For `@/text-with-icon` buttons with icons, default to `t-Button--iconLeft`; use `t-Button--iconRight` only when explicitly requested and omit both for `@/icon`.
+- For remove operations, perform hard-delete dependency checks before applying changes; block on dangling references (DA aliases, whenButtonPressed, request guards).
+- Confirmation messages must follow governance: no hard-coded PII, inline help < 60 chars.
+- Ensure layout slots exist for the target region template.
+- For submitPage actions, remind to guard processes via invokeApi (Business Logic skill).
+- Record Missing Inputs when required overrides are absent.
+
+## Outputs & Workflow
+1. Generate button changes in the transient temp workspace and keep the review summary compact.
+2. Review ensures guardrails (template attributes, nested behaviors, confirmation text) are satisfied.
+3. Apply approved fixes and publish only after the run clears the required gates.
+4. For import-ready runs, execute `references/ops/runtime-gates/02-direct-sqlcl-validate-gate.md` before completion.
+
+## References
+- `references/domains/page-components/buttons/templates.md`
+- `references/domains/page-components/buttons/registry.md`
+- Reusable prompts: `assets/domains/page-components/buttons/button-actions.md`
+
+Use this package whenever button configuration or batch actions are required in Apex Developer flows.

package/skills/apexlang/references/domains/page-components/page-items/registry.md

@@ -0,0 +1,23 @@
+# Component Registry — Page Items
+
+| Keyword/Synonym | Template Path | Notes |
+|-----------------|---------------|-------|
+| text field, input text, native input | `templates/items/text-field/text-field._index.md` | Basic text input |
+| text area | `templates/items/text-area/text-area._index.md` | Multi-line input |
+| text autocomplete | `templates/items/text-autocomplete/text-autocomplete._index.md` | Autocomplete-enabled field |
+| select list | `templates/items/select-list/select-list._index.md` | Single-select LOV |
+| select-one | `templates/items/select-one/standard.md` | LOV single-select variant |
+| select-many, multi-select, multi select | `templates/items/select-many/standard.md` | LOV multi-select |
+| combobox | `templates/items/combobox/combobox._index.md` | Type-ahead combo |
+| checkbox | `templates/items/checkbox/checkbox._index.md` | Checkbox group |
+| radio group | `templates/items/radio-group/radio-group._index.md` | Radio group |
+| switch | `templates/items/switch/switch._index.md` | Toggle switch |
+| star rating | `templates/items/star-rating/standard.md` | Rating input |
+| shuttle | `templates/items/shuttle/shuttle._index.md` | Shuttle selector |
+| date picker | `templates/items/date-picker/date-picker._index.md` | Date input |
+| number field | `templates/items/number-field/number-field._index.md` | Numeric input |
+| color picker | `templates/items/color-picker/standard.md` | Color selection |
+| hidden item | `templates/items/hidden-item/hidden-item._index.md` | Hidden value |
+| display only | `templates/items/display-only/standard.md` | Display-only item |
+| file upload | `templates/items/file-upload/file-upload._index.md` | File upload |
+| rich text editor | `templates/items/rich-text-editor/rich-text-editor._index.md` | RTE editor |

package/skills/apexlang/references/domains/page-components/page-items/templates.md

@@ -0,0 +1,37 @@
+# Template References — Page Items
+
+## Authoritative Policies
+- `references/policies/governance/00-governance.md`
+- `references/policies/memory-bank/00-guard/ai.guard.md`
+- `references/policies/memory-bank/10-global/apex.global.md`
+- `references/policies/memory-bank/20-data/apex.sql.md`
+- `references/policies/memory-bank/20-data/apex.logic.md`
+- `references/policies/memory-bank/40-components/apex.templates.md`
+- `references/policies/memory-bank/40-components/apex.items.md`
+
+## Operational References
+All item templates live under `templates/items/`. Use the entries below to load the minimal template you need:
+
+- `templates/items/text-field/text-field._index.md`
+- `templates/items/text-area/text-area._index.md`
+- `templates/items/text-autocomplete/text-autocomplete._index.md`
+- `templates/items/select-list/select-list._index.md`
+- `templates/items/select-one/standard.md`
+- `templates/items/select-many/standard.md`
+- `templates/items/combobox/combobox._index.md`
+- `templates/items/checkbox/checkbox._index.md`
+- `templates/items/radio-group/radio-group._index.md`
+- `templates/items/switch/switch._index.md`
+- `templates/items/star-rating/standard.md`
+- `templates/items/shuttle/shuttle._index.md`
+- `templates/items/date-picker/date-picker._index.md`
+- `templates/items/number-field/number-field._index.md`
+- `templates/items/color-picker/standard.md`
+- `templates/items/hidden-item/hidden-item._index.md`
+- `templates/items/display-only/standard.md`
+- `templates/items/file-upload/file-upload._index.md`
+- `templates/items/rich-text-editor/rich-text-editor._index.md`
+
+Combine these rule files with the business-logic reference package (`references/domains/README.md`) for validations, computations, and dynamic actions associated with items.
+
+Default visible item-template choices, label presentation, and other template-driven UI composition decisions come from `references/policies/memory-bank/40-components/apex.templates.md`.