pi-apexlang 0.1.0

package/skills/apexlang/references/domains/business-logic/dynamic-actions/workflow-dynamic-actions-plsql-batch.md

@@ -0,0 +1,35 @@
+# Workflow: Dynamic Actions — Execute API Batch
+
+Purpose
+- Apply execute-API dynamic actions across multiple pages while enforcing process policy split (page process invokeApi-default with thin-wrapper exception; appProcess executeCode-only) and shared parameter contracts.
+
+Required inputs
+- `operation`: apply (default).
+- `targets`: list of page target objects (for example `{ page: 10, overrides?: { selector, target_region, message } }`).
+- Optional single-target convenience input: `target` (same structure as one `targets` entry; normalized to a one-item list).
+- Backward compatibility: accept `target_pages` and normalize to `targets` with page-only entries.
+- `api_package`: consolidated API package (for example, `app_process_api`).
+- `api_routine`: package procedure/function.
+- `items_to_submit`: list of page items submitted before execution.
+- Optional: confirmation text, success notification, refresh target region per page.
+
+Load
+- 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.logic.md
+- references/domains/business-logic/dynamic-actions/workflow-dynamic-actions-batch.md
+- Template: `templates/business-logic/dynamic-actions/dynamic-actions.execute-server-side-code.md`
+
+Execution model
+- Normalize `target`/`target_pages` -> `targets`.
+- Collect shared API contract once (`api_package`, `api_routine`, `items_to_submit`).
+- For each target in `targets`, merge page-specific identifiers (selector, target region, messages).
+- Generate execute-API DA blocks using the canonical dynamic-action template and per-page naming.
+
+Completion
+- Draft summaries are grouped per page under `the temp-runtime reports directory under `APEXLANG_OUTPUT_ROOT/reports/``, while the actual DSL changes are staged directly in the target app.
+- Revision writes final page updates and records `operation`, consolidated page list, and API contract in change log.
+
+Notes
+- Missing identifiers for any page must halt the batch with `Missing Inputs — Page <n>`.
+- For package calls in page processes, route to `references/domains/business-logic/processes/workflow-page-processes-batch.md`.

package/skills/apexlang/references/domains/business-logic/dynamic-actions/workflow-dynamic-actions.md

@@ -0,0 +1,45 @@
+# Workflow: Dynamic Actions
+
+Purpose
+- Generate or modify APEX dynamic actions using canonical templates while enforcing guardrails (page process invokeApi-default with thin-wrapper exception, appProcess executeCode-only, named notation, DA_ naming).
+
+Required inputs
+- Target page number and dynamic action identifier (new or existing).
+- Trigger definition (event + selection type + selector/region/items).
+- Affected elements (items, regions, DOM object, event source).
+- For server-side interactions: packaged API name or inline PL/SQL purpose, required itemsToSubmit, and target region(s).
+
+Clarify — progressive prompts
+- Does the dynamic action rely on existing items/regions/buttons? Identify each by static ID or name.
+- What condition governs execution (client-side condition, threshold, JavaScript expression)? Capture comparison values or expressions.
+- Are debounce, throttle, or plugin events required? Note plugin static IDs and interval settings.
+- For destructive/server operations, confirm confirmation messaging, notification text, and the API endpoint (package.procedure or invokeApi parameters).
+- If any attribute is missing, record “Missing Inputs” and halt rather than inventing values.
+ - When invoked from a natural sentence, ask only for data that was not supplied (e.g., “Which region should be refreshed?”) and echo back assumptions for confirmation before drafting.
+
+Load
+- 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.logic.md
+
+Templates
+- Primary catalog: `templates/business-logic/dynamic-actions/` (select archetype based on requested behavior).
+- For historical compatibility only, `templates/business-logic/dynamic-actions/dynamic-actions.refresh-region-after-dialog.md` (use when prompt explicitly references the legacy snippet).
+- Coordinate with apex-generation agents:
+  - Draft: `references/workflows/apex-generation/agents/20-agent-draft.md`
+  - Critique: `references/workflows/apex-generation/agents/30-agent-critique.md`
+  - Revision: `references/workflows/apex-generation/agents/40-agent-revision.md`
+
+Rules & checks
+- Enforce `DA_<Purpose>` naming (see apex.logic.md).
+- Enforce approved `when.event` values from `templates/business-logic/dynamic-actions/dynamic-actions._common.md`; do not invent aliases such as `dialogClosed`.
+- For modal dialog refresh, use `apexafterclosedialog`; use `apexafterclosecanceldialog` only when the behavior is explicitly tied to cancel-close flows.
+- Map action types to the closest template (show/hide, enable/disable, set value via SQL/PLSQL/JS, invoke API, timer, slider behaviors, focus, debounce/throttle, plugin styling).
+- Verify `itemsToSubmit` is scoped to required items; flag if omitted for server actions.
+- Ensure inline PL/SQL uses named notation and is marked for conversion to invokeApi when packaged APIs exist.
+- Confirm confirmation/notification sequence for destructive flows (Confirm → submit key item → execute API → refresh → notify).
+
+Completion
+- Draft updates go directly to the target page artifact; critique must reference template alignment, guardrail compliance, and any companion summary logged under `the temp-runtime reports directory under `APEXLANG_OUTPUT_ROOT/reports/``.
+- Revision updates final artifact under the target page path.
+- If new components were added, recommend updating Component Registry synonyms when novel phrases arise.

package/skills/apexlang/references/domains/business-logic/processes/workflow-page-processes-batch.md

@@ -0,0 +1,45 @@
+# Workflow: Page Processes — Invoke API Batch
+
+Purpose
+- Apply an `invokeApi` page process across multiple pages, wiring button guards, sequences, and parameters consistently.
+
+Required inputs
+- `operation`: apply (default).
+- `api_package`: consolidated package name (e.g., `app_process_api`).
+- `api_routine`: procedure/function name (e.g., `save_order`).
+- `api_kind`: `procedure` or `function`.
+- `targets`: list of page target objects (for example `{ page: 20, overrides?: { button_guard, parameters, sequence } }`).
+- Optional single-target convenience input: `target` (same structure as one `targets` entry; normalized to a one-item list).
+- Backward compatibility: accept `target_pages` and normalize to `targets` with page-only entries.
+- `button_guard`: button name guarding the process (if applicable).
+- `parameters`: list describing item/expression mappings per parameter.
+- Optional: success message, server-side condition, execution sequence overrides.
+
+Load
+- 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.logic.md
+- Template: `templates/business-logic/processes/processes.invoke-api.md`
+
+Execution model
+- Normalize `target`/`target_pages` -> `targets`.
+- Gather shared API details (package, routine, parameters, button guard).
+- If `api_kind = function`, use the validated page-process return mapping shape:
+  - nested `parameter { direction: out, dataType: <type>, ignoreOutput: false }`
+  - `value { item: <target item> }`
+  - `advanced { displaySequence: <n> }`
+- For this validated function-return shape, do not emit `value.type`, and do not move `direction`, `dataType`, or `ignoreOutput` to the top level of the `parameter (...)` block.
+- Iterate through each target in `targets`:
+  - Merge shared data with page-specific overrides (button names, condition tokens, parameter values).
+  - Insert or update an invokeApi process using the process template.
+- Name convention: `PROC_<PURPOSE>_P<page>`.
+
+Completion
+- Revision writes process definitions into each target page file and records `operation` plus page/process pairs in the change log.
+- Critique ensures invokeApi is used, parameters match the shared bundle, and no executeCode remains.
+
+Notes
+- Ensure buttons exist before binding the process; emit Missing Inputs if not provided.
+- For On Demand/AJAX variants, adjust execution point accordingly.
+- Combined with `20-data/apex.logic.md`, this workflow enforces consolidated package usage.
+- This function-return shape is validated for page `invokeApi` processes by live SQLcl `apex validate`; prefer it over thin `executeCode` wrappers when the goal is specifically to keep packaged function calls declarative.

package/skills/apexlang/references/domains/business-logic/registry.md

@@ -0,0 +1,10 @@
+# Component Registry Excerpts — Page Items
+
+| Keyword | Workflow / Component | Required Inputs |
+|---------|----------------------|-----------------|
+| `validation` | `validation` | Condition, error message |
+| `computation` | `computation-plsql` | Execution point, logic |
+| `computation-batch` | `computation-plsql-batch` | Items list, logic |
+| `help-text-batch` | `references/domains/universal-attr-config/workflow-help-text-batch.md` | Items, inline help text |
+
+Consult `components.registry.json` for synonyms and additional metadata per keyword.

package/skills/apexlang/references/domains/business-logic/reusable-prompts/computations.md

@@ -0,0 +1,30 @@
+# Item Computation Prompts
+
+Purpose
+- Structured prompts for computation batch workflows.
+
+Prompt scaffold
+- "Apply `<computation_type>` computation to items `<item list>` across pages `<pages>` with execution point `<point>` and logic `<logic>`."
+- Include:
+  - computation_type (`sqlQuery`, `sqlQueryMultipleValues`, `expression`, `functionBody`, `invokeApi`)
+  - execution_point
+  - sequence
+  - logic body
+  - targets and optional per-target overrides
+
+Example
+```
+Apply item computations across pages 1 and 2:
+- computation_type: expression
+- execution_point: beforeHeader
+- sequence: 30
+- logic_body: 'Hello ' || :APP_USER
+- target_items:
+  - { page: 1, item: P1_DISPLAY_EXP }
+  - { page: 2, item: P2_DISPLAY_EXP }
+```
+
+Checklist
+- Use bind syntax and avoid side effects.
+- Keep datatype compatibility with target items.
+- Ensure deterministic ordering for multi-value SQL.

package/skills/apexlang/references/domains/business-logic/reusable-prompts/validations.md

@@ -0,0 +1,30 @@
+# Sample Prompts for APEX Page Validations
+
+Template reminder
+- Before drafting validations, start from the reference skeleton defined in:
+  - `templates/business-logic/validations/validations._index.md`
+  - `templates/business-logic/validations/validations._common.md`
+
+## A. Required value prompts
+1. "Add validations so page items `P20_FIRST_NAME` and `P20_LAST_NAME` must both be populated before submit."
+2. "Check that `P50_AMOUNT` is provided and return 'Amount is required' when missing."
+
+## B. Expression comparisons / ranges
+3. "Create a validation ensuring `P80_END_DATE` is on or after `P80_START_DATE`, with error 'End Date must not precede Start Date'."
+4. "Require `P35_QUANTITY` to be between 1 and 999 using a single expression validation."
+
+## C. Function body logic
+5. "If `P40_STATUS` is not null, make `P40_DECISION_DATE` mandatory; otherwise skip. Return a clear message when it fails."
+6. "Validate `P60_CODE`: at least three characters and no spaces. Return an explanatory error."
+
+## D. Regex/format checks
+7. "Enforce email format on `P10_EMAIL` using `REGEXP_LIKE`; message 'Enter a valid corporate email address'."
+8. "Validate `P25_PHONE` to accept only digits and optional plus sign."
+
+## E. Lookup/existence checks
+9. "Ensure `P70_CUSTOMER_ID` exists in CUSTOMER_MASTER; if not, return 'Customer ID not found'."
+10. "Validate `P15_DEPT_CODE` by calling `APP_VALIDATION.check_dept(:P15_DEPT_CODE)` and surface returned message."
+
+## F. Multi-step sequencing
+11. "Add sequence 10 required, sequence 20 minimum length, and sequence 30 custom business logic validations on `P90_SERIAL`."
+12. "Combine two validations on `P45_USER`: first not null, then ensure value differs from `P45_OLD_USER`."

package/skills/apexlang/references/domains/business-logic/templates.md

@@ -0,0 +1,26 @@
+# Template References — Business Logic
+
+## Authoritative Policies
+- `references/policies/governance/00-governance.md`
+- `references/policies/memory-bank/00-guard/ai.guard.md`
+- `references/policies/memory-bank/20-data/apex.logic.md`
+- `references/policies/memory-bank/20-data/apex.sql.md`
+- `references/policies/memory-bank/20-data/apex.schema-modeling.md` (when schema constraints are involved)
+
+## Validations
+- `templates/business-logic/validations/validations._index.md`
+
+## Computations
+- `templates/business-logic/computations/`
+
+## Dynamic Actions
+- `templates/business-logic/dynamic-actions/`
+
+## Reusable Prompts
+- `references/domains/business-logic/reusable-prompts/validations.md`
+- `references/domains/business-logic/reusable-prompts/computations.md`
+- `references/ops/reusable-prompts/server-side-conditions.md`
+
+## Operational References
+- This file and `references/domains/business-logic/**` are operational guidance.
+- Policy decisions always defer to the authoritative files listed above.

package/skills/apexlang/references/domains/business-logic/validations/README.md

@@ -0,0 +1,25 @@
+# Validations Workflow Partition
+
+## Purpose
+
+This folder is reserved for validation-specific workflow references so the page-components business-logic partition mirrors the validation templates and rule sources used by the repo.
+
+## What is in this directory
+
+- No validation workflow reference files are currently present beyond this README.
+- The directory exists to preserve a stable partition for future validation-specific workflow docs.
+
+## How to use this directory
+
+- Do not treat this folder as the primary source of validation rules today.
+- Use the canonical validation sources below when you need real validation patterns or constraints.
+
+## Current source of truth
+
+- `templates/business-logic/validations/validations._index.md`
+- `references/policies/memory-bank/20-data/apex.logic.md`
+
+## Maintenance
+
+- If validation-specific workflow reference files are added here later, document them in this README.
+- Keep this file explicit about whether the folder is active content or a placeholder mirror.

package/skills/apexlang/references/domains/debugging/apex-debug-messages.md

@@ -0,0 +1,161 @@
+# APEX Debug Messages Workflow
+
+Use this workflow when the user gives an Oracle APEX runtime error message and a live DB connection is available.
+
+## Verified View Shape
+
+The `APEX_DEBUG_MESSAGES` public synonym can expose the following columns in the active APEX schema:
+
+| Column | Use |
+|---|---|
+| `ID` | Debug-message row id. Use it to resolve the owning `PAGE_VIEW_ID` when the user provides a row/debug-message id. |
+| `PAGE_VIEW_ID` | Correlation id for one page view or request. Use it to retrieve the complete execution log for the failed process. |
+| `MESSAGE_TIMESTAMP` | Message time. Use with `ID` for stable ordering and candidate recency. |
+| `ELAPSED_TIME` | Elapsed time since request start. |
+| `EXECUTION_TIME` | Execution time for the message step. |
+| `MESSAGE` | Debug text and error text. Search this from the supplied error message. |
+| `APPLICATION_ID` | Application filter. Ask only when the error text matches multiple apps and the user did not provide an app. |
+| `PAGE_ID` | Page filter. Ask only when needed to narrow multiple matches. |
+| `WORKFLOW_INSTANCE_ID` | Workflow correlation when present. |
+| `SESSION_ID` | APEX session id. Ask for this when the error text has multiple recent instances. |
+| `APEX_USER` | Runtime user. Use as a secondary narrowing signal. |
+| `MESSAGE_LEVEL` | Debug level. Sparse levels can indicate the request was not reproduced with Full trace. |
+| `WORKSPACE_ID` | Workspace filter and evidence field. |
+| `CALL_STACK` | Call stack when available. Use it to identify the owner before editing. |
+
+## Query Order
+
+1. Confirm the active connection is the intended live DB connection.
+2. Query `APEX_DEBUG_MESSAGES` for the supplied error text and collect candidate `PAGE_VIEW_ID` values.
+3. If exactly one recent candidate exists, use that `PAGE_VIEW_ID`.
+4. If multiple candidates exist, ask the user for one narrowing value: `PAGE_VIEW_ID` / debug id, `SESSION_ID`, application id, page id, user, or approximate timestamp.
+5. If the user supplies `ID`, resolve it to `PAGE_VIEW_ID` before reading the full log.
+6. Retrieve the full execution log for the selected `PAGE_VIEW_ID`, ordered by `MESSAGE_TIMESTAMP, ID`.
+7. Identify the nearest owner from the log: page process, validation, dynamic action Ajax callback, plugin, authorization, computation, report SQL, PL/SQL package, REST call, or runtime engine.
+8. If the log is too sparse to identify the owner, ask the user to reproduce the error with APEX debug level set to Full trace, then rerun the lookup.
+
+## Candidate Search
+
+Use the supplied error message as a literal substring. If the message contains volatile ids, timestamps, or quoted user data, search the stable part first.
+
+```sql
+select page_view_id,
+       session_id,
+       application_id,
+       page_id,
+       apex_user,
+       workspace_id,
+       min(message_timestamp) first_seen,
+       max(message_timestamp) last_seen,
+       count(*) matching_rows,
+       max(id) latest_message_id
+  from apex_debug_messages
+ where instr(upper(message), upper(q'[<stable error text>]')) > 0
+ group by page_view_id,
+          session_id,
+          application_id,
+          page_id,
+          apex_user,
+          workspace_id
+ order by last_seen desc
+ fetch first 20 rows only;
+```
+
+When many rows match, add only user-provided narrowing filters. Do not guess the right request.
+
+```sql
+   and session_id = <session_id>
+   and application_id = <application_id>
+   and page_id = <page_id>
+```
+
+## Resolve A Row Id
+
+Use this only when the user provides a debug-message row id rather than a page view id.
+
+```sql
+select id,
+       page_view_id,
+       session_id,
+       application_id,
+       page_id,
+       apex_user,
+       message_timestamp,
+       message
+  from apex_debug_messages
+ where id = <debug_message_row_id>;
+```
+
+## Full Execution Log
+
+After `PAGE_VIEW_ID` is known, fetch the full log for that request.
+
+```sql
+select id,
+       message_timestamp,
+       elapsed_time,
+       execution_time,
+       message_level,
+       message,
+       call_stack
+  from apex_debug_messages
+ where page_view_id = <page_view_id>
+ order by message_timestamp, id;
+```
+
+If the log is large, start with the error slice and then widen.
+
+```sql
+select id,
+       message_timestamp,
+       elapsed_time,
+       execution_time,
+       message_level,
+       message,
+       call_stack
+  from apex_debug_messages
+ where page_view_id = <page_view_id>
+   and (
+        instr(upper(message), upper(q'[<stable error text>]')) > 0
+        or call_stack is not null
+        or message_level <= 3
+       )
+ order by message_timestamp, id;
+```
+
+## Multiple Matches
+
+If the candidate query returns multiple plausible `PAGE_VIEW_ID` values, stop before diagnosis and ask:
+
+`I found multiple matching APEX debug entries for that error. Please provide the PAGE_VIEW_ID/debug id or SESSION_ID for the failed run, or the approximate time/user so I can narrow it down.`
+
+## Sparse Or Unhelpful Logs
+
+Treat the existing debug log as insufficient when:
+
+- The selected `PAGE_VIEW_ID` has only a few generic rows.
+- The error row appears without preceding process, SQL, validation, Ajax, or PL/SQL context.
+- `CALL_STACK` is empty and the surrounding messages do not identify the component or package.
+- `MESSAGE_LEVEL` values show only coarse messages.
+
+Ask for a Full trace reproduction:
+
+`The existing APEX debug log is too sparse to identify the failing owner. Please reproduce the error with APEX debug level set to Full trace, then share the new PAGE_VIEW_ID/debug id or SESSION_ID and I will pull the full execution log.`
+
+## Diagnosis Rules
+
+- Prefer the full `PAGE_VIEW_ID` execution log over the isolated error message.
+- Use `CALL_STACK` and the messages immediately before the error to identify the owner.
+- Do not patch APEXlang artifacts, SQL, or PL/SQL until the log points to an owning component or package.
+- If the log points to app PL/SQL, route the fix through the PL/SQL workflow.
+- If the log points to generated APEX page metadata, route through the relevant APEXlang page, component, or business-logic workflow.
+- If the log points to APEX runtime internals with no app-owned preceding operation, report the evidence and avoid speculative edits.
+
+## Response Shape
+
+- Matching `PAGE_VIEW_ID` / session evidence
+- Full-log signal used
+- Likely failing component or package
+- Error cause, if supported by the log
+- Smallest fix surface
+- Reproduction or re-check command

package/skills/apexlang/references/domains/debugging/checks-and-commands.md

@@ -0,0 +1,177 @@
+> All `node tools/apexctl.mjs ...` commands are package-root relative: run them from the packaged skill root, or invoke that script by explicit path.
+
+# Checks And Commands
+
+Use the smallest signal-bearing check first. Do not start with the broadest suite.
+
+## APEX Debug Messages Check
+
+Use this when the user provides an APEX/ORA runtime error message and the active task has a live DB connection.
+
+Load `references/domains/debugging/apex-debug-messages.md` for the full query workflow.
+
+Signal-bearing when:
+- The error appears in the running APEX app or an Ajax/page-process request.
+- The user provides an error message, debug id, `PAGE_VIEW_ID`, or `SESSION_ID`.
+- The next useful evidence is the execution log surrounding the failed process.
+
+Low signal when:
+- No live DB connection is available.
+- The issue is still a local `.apx` compiler or import failure.
+- The debug log exists but was captured at a low level and does not include the failing owner.
+
+Minimum checks:
+- Search `APEX_DEBUG_MESSAGES.MESSAGE` for the stable part of the error text.
+- Use the matching `PAGE_VIEW_ID` to fetch the full execution log ordered by `MESSAGE_TIMESTAMP, ID`.
+- If multiple matches exist, ask for `PAGE_VIEW_ID` / debug id or `SESSION_ID` before diagnosing.
+- If the selected log is sparse, ask for a new reproduction with debug level set to Full trace.
+
+## Runtime UI Verification
+
+Use this when validate/import already succeeded and the reported defect is visible only in the running app.
+
+Signal-bearing when:
+- The symptom is navigation expansion, current-state highlighting, missing visible content, focus behavior, or responsive layout drift.
+- The page renders but not in the expected runtime state.
+
+Low signal when:
+- The failure is still a direct validate/import/compiler error.
+- The issue is Builder auth or transport.
+
+## Canonical Same-Session Runtime Check
+
+Use this when validate/import behavior differs across execution paths or when SQLcl workspace context is suspected.
+
+Note:
+- The low-level `runtime roundtrip` command still blocks with `Missing Inputs` unless an import intent is supplied. Agent workflows should inject the check-only intent by default, then offer GUI import choices after the live APEXlang check passes.
+
+```sh
+node tools/apexctl.mjs runtime preflight --db-connection-name <db_connection_name>
+node tools/apexctl.mjs runtime roundtrip --app-path <absolute_app_path> --db-connection-name <db_connection_name> --import-intent validate-only --execution-mode auto
+```
+
+Fallback when you need to force PATH SQLcl:
+
+```sh
+node tools/apexctl.mjs runtime roundtrip --app-path <absolute_app_path> --db-connection-name <db_connection_name> --execution-mode path
+```
+
+Force the resolved build-root runtime explicitly:
+
+```sh
+node tools/apexctl.mjs runtime roundtrip --app-path <absolute_app_path> --db-connection-name <db_connection_name> --execution-mode build-root
+```
+
+Signal-bearing when:
+- A bridge, MCP, or wrapper path reports a failure that may not reproduce in a real SQLcl session.
+- SQLcl reports workspace ambiguity or other session-context differences.
+
+Low signal when:
+- Local DSL validators already fail before the live runtime path starts.
+- The issue is clearly inside one known SQL owner and does not depend on session context.
+
+Preferred checks:
+- Chrome DevTools MCP text snapshot of the runtime page
+- DOM or script inspection for `aria-current`, `aria-expanded`, selected classes, focus target, or region presence
+- Screenshot only when the text snapshot cannot express the symptom
+
+## Metadata Export Or Check Path
+
+Use this when the symptom suggests metadata defaults, dependencies, display groups, or property-model conflicts.
+
+```sh
+apex util export-metadata
+```
+
+Signal-bearing when:
+- The failure mentions metadata generation, MMD, display groups, child components, requiredness, or unexpected property validation.
+
+Low signal when:
+- The failure is pure Builder auth or transport.
+- The failure is a syntax error in a specific `.apx` file before metadata interpretation begins.
+
+## Targeted Property-Model Checks
+
+Use this when the symptom suggests property-model or metadata registration conflicts.
+
+```sh
+sql <db_connection_name>
+@internal_utilities/dev/sql/pe_data_checks.sql
+```
+
+Signal-bearing when:
+- The failure mentions display-group conflicts, naming conflicts, metadata validation, child-component conflicts, or unexpected property validation.
+
+Low signal when:
+- The defect is a re-export diff with no metadata validation error.
+- The defect is clearly a version-gate failure at import begin.
+
+## Compile A Specific SQL Surface
+
+Use this after identifying a concrete owning SQL file that must compile cleanly.
+
+```sh
+sql <db_connection_name>
+@<repo-relative-file>
+```
+
+Signal-bearing when:
+- You already know the owning SQL file and need to verify the candidate fix compiles in isolation.
+
+Low signal when:
+- Ownership is still unknown.
+- The defect is UI transport only.
+
+## Smallest Relevant Tests
+
+### Generator To APEXlang Coverage
+
+```sh
+apex test run test_gendev_bp_to_apexlang
+```
+
+Use when:
+- The symptom points to metadata generation or DSL emission shape coming from generation rather than import-only handling.
+
+Do not start here when:
+- The failure is clearly import-time version parsing or Builder transport.
+
+### Code Editor Coverage
+
+```sh
+apex test run codeEditor
+```
+
+Use when:
+- The symptom touches Builder import editing surfaces, code-editor mediated flows, or UI-side handling around import inputs.
+
+Do not start here when:
+- The error is already reproduced outside Builder with direct import or validation.
+
+### Import Coverage
+
+```sh
+apex test run test_app_import
+```
+
+Use when:
+- The symptom is compiler version mismatch, invalid version format, import begin failure, canonicalization drift, or legacy import coercion behavior.
+
+Do not start here when:
+- The defect is a pure metadata registration conflict already proven by `pe_data_checks.sql`.
+
+## Recommended Triage Sequence
+1. Quote the exact error text.
+2. Pick one bucket from `failure-map.md`.
+3. If the symptom is live validate/import behavior, start with the canonical same-session runtime check from the selected real runtime path.
+4. Run one smallest confirming check from this file.
+5. Escalate to the owning layer only after that check confirms the bucket.
+6. Re-run one smallest relevant test after the fix.
+
+## Command Selection Rules
+- Prefer `apex util export-metadata` and `pe_data_checks.sql` for metadata and property-model failures.
+- Prefer `APEX_DEBUG_MESSAGES` and the selected `PAGE_VIEW_ID` execution log for live APEX runtime errors with an error message.
+- Prefer `test_app_import` for version parsing, coercion, and canonicalization during import.
+- Prefer `codeEditor` only when the failure remains Builder-specific after ruling out backend import failure.
+- Prefer Chrome DevTools MCP text snapshots for runtime UI/UX issues that remain after successful import.
+- Prefer direct compile of one SQL file only after the owning surface is already known.