pi-apexlang 0.1.0

package/skills/apexlang/references/workflows/apex-generation/nlu/nlu-routing-test-matrix.md

@@ -0,0 +1,264 @@
+# NLU Routing — Test Matrix (Inputs → Expected Routing and Outputs)
+
+## Purpose
+- Verify the NLU Router behavior defined by `SKILL.md` while loading `references/workflows/apex-generation.md`, using the Component Registry (`assets/apex-generation/components.registry.json`) and rule loading via `assets/rules-mapping.json`.
+- Each test lists expected: target_type, matched components, rules, templates, required inputs to ask for, and outputs.
+
+## Conventions
+- Message 1: references/workflows/apex-generation.md
+- Message 2: Auto-computed by the NLU Router or supplied manually.
+- Inputs containing `{{...}}` are `illustrative_prompt` grammar examples. Substitute verified identifiers for the variables during a real run; do not treat the variables as schema evidence.
+- Outputs:
+  - Working copy: transient temp workspace outside the repo
+  - Durable runtime evidence: compact report + transcript under `the temp-runtime logs directory under `APEXLANG_OUTPUT_ROOT/logs/`` when needed
+  - Final: applications/{target_app}/pages/... or shared-components/... (page/component scope)
+
+## Legend
+- Rules are union-loaded: 00-guard + 10-global + matched 20-data/30-pages/40-components.
+- Only templates present under templates/* may be used.
+
+1) Page with Interactive Report + Form (same page) + LOV + Refresh
+- Input: “Build a page with an interactive report and a form on {{source.table}}; use Lookup LOV for {{lookup.valueColumn}}; refresh report after submit”
+- target_type: page
+- Components: [interactive-report, form, lov-shared, dynamic-action-refresh-report]
+- Rules:
+  - 00-guard/ai.guard.md
+  - 10-global/apex.global.md
+  - 30-pages/apex.page.md
+  - 30-pages/apex.interactive-report.md
+  - 30-pages/apex.form.md
+  - 40-components/apex.items.md
+  - 20-data/apex.sql.md
+  - 20-data/apex.logic.md
+- Templates:
+  - templates/page-examples/interactive-report-page/interactive-report-page._index.md
+  - templates/page-examples/form-page/form-page._index.md
+  - templates/shared-components/lovs/lovs.dynamic.query.md
+  - templates/business-logic/dynamic-actions/dynamic-actions.refresh-region-after-dialog.md
+- Required inputs to ask/validate:
+  - {{source.table}}: table, pk, columns
+  - LOV: source table/view={{lookup.table}}, value={{lookup.valueColumn}}, display={{lookup.displayColumn}}
+  - DA: target region identifier (IR region), trigger (after form submit)
+- Outputs: internal generate/review/fix loop, then final written under pages/
+
+2) Interactive Report only ({{source.table}} with {{lookup.valueColumn}} filter LOV)
+- Input: “Interactive report on {{source.table}} with a {{lookup.valueColumn}} select list filter using Lookup LOV”
+- target_type: interactive-report (or page if the user prefers a composed page)
+- Components: [interactive-report, lov-shared]
+- Rules:
+  - 00-guard, 10-global
+  - 30-pages/apex.page.md
+  - 30-pages/apex.interactive-report.md
+  - 40-components/apex.items.md
+  - 20-data/apex.sql.md
+- Templates:
+  - templates/page-examples/interactive-report-page/interactive-report-page._index.md
+  - templates/shared-components/lovs/lovs.dynamic.query.md
+- Required inputs: {{source.table}}, optional columns; LOV mapping ({{lookup.valueColumn}}->{{lookup.displayColumn}})
+- Outputs: internal generate/review/fix loop, then final page
+
+2b) Classic Report region (explicit phrase precedence)
+- Input: “Create me a classic report region on Page 1”
+- target_type: page
+- Components: [classic-report]
+- Rules:
+  - 00-guard, 10-global
+  - 30-pages/apex.page.md
+  - 30-pages/apex.classic-report.md
+  - 20-data/apex.sql.md
+- Templates:
+  - templates/region-components/classic-report/classic-report._common.md
+  - templates/page-examples/classic-report-page/classic-report-page._index.md
+- Required inputs: SQL or table source, optional selected columns
+- Routing assertion:
+  - Exact phrase `classic report` must route to `classic-report`
+  - Must not fall back to generic `interactive-report` mapping
+- Outputs: internal generate/review/fix loop, then final page
+
+3) Form only (Modal CRUD on {{source.table}})
+- Input: “Modal CRUD form on {{source.table}}; use Lookup LOV for {{lookup.valueColumn}}”
+- target_type: form
+- Components: [form, lov-shared]
+- Rules:
+  - 00-guard, 10-global
+  - 30-pages/apex.page.md
+  - 30-pages/apex.form.md
+  - 40-components/apex.items.md
+  - 20-data/apex.sql.md
+- Templates:
+  - templates/page-examples/form-page/form-page._index.md
+  - templates/items/select-list/select-list._index.md (if item-level LOV is desired)
+  - templates/shared-components/lovs/lovs.dynamic.query.md (if page-level LOV is desired)
+- Required inputs: {{source.table}}, pk, columns; LOV mapping
+- Outputs: internal generate/review/fix loop, then final page
+
+4) Dashboard with cards (record count by category)
+- Input: “Create a dashboard with cards summarizing record count by category”
+- target_type: page (or dashboard)
+- Components: [dashboard]
+- Rules:
+  - 00-guard, 10-global
+  - 30-pages/apex.page.md
+  - 30-pages/apex.dashboard.md
+- Templates:
+  - templates/page-examples/dashboard-page/dashboard-page._index.md
+  - Optional: templates/page-examples/classic-report-page/classic-report-page._index.md (tile-like classic report)
+- Required inputs: SQL or table/view for aggregation
+- Outputs: internal generate/review/fix loop, then final page
+
+5) Single Chart (amount by category)
+- Input: “Chart showing amount by category”
+- target_type: chart
+- Components: [chart]
+- Rules:
+  - 00-guard, 10-global
+  - 30-pages/apex.chart-page.md
+- Templates: (per charts page rules; page template selection happens in that rule logic)
+- Required inputs: SQL defining series/category, or table + columns
+- Outputs: internal generate/review/fix loop, then final page
+
+6) Calendar ({{source.table}} events)
+- Input: “Add a calendar of {{source.table}} events”
+- target_type: page
+- Components: [calendar]
+- Rules:
+  - 00-guard, 10-global
+  - 30-pages/apex.page.md
+- Templates:
+  - templates/page-examples/calendar-page/calendar-page._index.md
+- Required inputs: date column (e.g., {{source.dateColumn}}), SQL or table mapping
+- Outputs: internal generate/review/fix loop, then final page
+
+7) Map (office locations)
+- Input: “Create a map for office locations”
+- target_type: page
+- Components: [map]
+- Rules:
+  - 00-guard, 10-global
+  - 30-pages/apex.page.md
+- Templates:
+  - templates/page-examples/map-page/map-page._index.md
+- Required inputs: lat column, lng column (or geocode source)
+- Artifacts: Draft → Critique → Final page
+
+8) Shared LOV (Lookup values)
+- Input: “Create a shared LOV that maps {{lookup.valueColumn}} to {{lookup.displayColumn}}”
+- target_type: items
+- Components: [lov-shared]
+- Rules:
+  - 00-guard, 10-global
+  - 40-components/apex.items.md
+  - 20-data/apex.sql.md
+- Templates:
+  - templates/shared-components/lovs/lovs.dynamic.query.md
+  - templates/shared-components/lovs/lovs.dynamic.query.md (if also added to a page)
+- Required inputs: table/view={{lookup.table}}, value={{lookup.valueColumn}}, display={{lookup.displayColumn}}
+- Outputs: internal generate/review/fix loop, then final under shared-components/
+
+9) Dynamic Action — Refresh IR after submit
+- Input: “After form submit, refresh the Interactive Report region”
+- target_type: dynamic-action (or included within page composition)
+- Components: [dynamic-action-refresh-report]
+- Rules:
+  - 00-guard, 10-global
+  - 20-data/apex.logic.md
+- Templates:
+  - templates/business-logic/dynamic-actions/dynamic-actions.refresh-region-after-dialog.md
+- Required inputs: IR region identifier, trigger = after submit
+- Outputs: internal generate/review/fix loop, then final page (DA added to the page artifact)
+
+9b) Translation button intent must clarify before localization routing
+- Input: “Create a button to translate to Spanish”
+- target_type: unresolved until clarification
+- Components: [button-actions-batch, translation]
+- Rules:
+  - 00-guard, 10-global
+  - 40-components/apex.buttons.md
+  - 30-pages/apex.page.md
+- Templates:
+  - none before clarification
+- Required inputs:
+  - Clarify whether the user wants runtime language switching or text-message localization
+  - If runtime switching: target page/region and language
+- Routing assertion:
+  - Must not auto-route to navigation/menu generation
+  - Must not auto-route directly to shared-components localization
+  - Must use one simple-English clarification round
+- Outputs: no working copy before clarification
+
+9c) Runtime language-switch button
+- Input: “Create a button that switches the session language to Spanish”
+- target_type: page
+- Components: [button-actions-batch]
+- Rules:
+  - 00-guard, 10-global
+  - 40-components/apex.buttons.md
+  - 20-data/apex.logic.md
+- Templates:
+  - templates/buttons/buttons.submit.md
+  - templates/business-logic/processes/processes.execute-code.md
+- Required inputs:
+  - Target page number/alias
+  - Region static ID / slot for button placement
+  - Button label and target language if not already explicit
+- Routing assertion:
+  - Default to submit button + guarded page process
+  - Must not default to redirect/navigation generation
+- Outputs: internal generate/review/fix loop, then final page
+
+10) Negative — Unknown component keyword
+- Input: “Add a hexagon grid region with neural shimmer”
+- target_type: page
+- Components: none matched
+- Rules:
+  - 00-guard, 10-global, 30-pages/apex.page.md
+- Behavior:
+  - Agent 1 drafts a static region fallback or asks for clarification
+  - Agent 2 flags unsupported component; Agent 3 omits or records deferral
+
+11) AI Assistant Launcher (button + DA + AI agent)
+- Input: “Add an AI assistant/chatbot to the home page”
+- target_type: page
+- Components: [ai-chatbot]
+- Rules:
+  - 00-guard, 10-global
+  - 30-pages/apex.page.md
+  - 40-components/apex.buttons.md
+  - 20-data/apex.logic.md
+- Templates:
+  - templates/business-logic/dynamic-actions/dynamic-actions.show-ai-assistant.md
+- Required inputs:
+  - Target page number/alias
+  - Button placement (Breadcrumb/Title Bar) + button identifier
+  - AI agent reference (for example `@home`); do not invent missing agent aliases
+  - Chatbot agent artifact location: `/shared-components/ai-agents/`
+- Behavior:
+  - Default implementation is a button + Dynamic Action to open the AI Assistant (no custom chat UI region by default).
+- Artifacts: Draft → Critique → Final (DA + button added to the target page)
+
+12) Whole application skeleton creation
+- Input: “Create a new APEX application skeleton for project ACME”
+- target_type: application
+- Components: [application-skeleton]
+- Rules:
+  - 00-guard/ai.guard.md
+  - 10-global/apex.global.md
+  - Application output policy from 00-governance.md
+- Expected behavior:
+  - Provision only the named runtime artifacts for `###/` from `templates/base-app-structure/scaffold-example/`: `.apex/`, `application.apx`, `deployments/`, `page-groups.apx`, `pages/`, `shared-components/`, and `supporting-objects/`.
+  - Ensure pages/ contains `p00000-*.apx`, `p00001-*.apx`, and `p09999-*.apx`; `shared-components/` contains the runtime shared-component seed (authentications, lists, breadcrumbs, LOVs, static-files, themes, etc.).
+  - Ensure template-family docs and registries such as `README.md`, `_common.md`, `_index.md`, and `.registry.json` do not appear in the generated app root.
+  - Omit documentation-only placeholders and optional example attributes unless the prompt explicitly requests them.
+  - Update metadata (app name, parsing schema, substitutes) per user context but do not delete skeleton files unless the user explicitly requests it.
+- Required inputs to ask/validate:
+  - Target schema (parsingSchema)
+  - Desired application name/ID or confirm defaults
+- Artifacts: Draft → Critique → Final under `###/` preserving only the named runtime-artifact set.
+
+### Validation Checklist per test
+- Component keywords resolve to registry entries (synonyms included)
+- Union rule loading matches components and respects minimal styling load
+- Only existing templates are used
+- Missing inputs are requested and logged (no fabrication)
+- Artifacts written to the correct locations
+- APEXlang runs do not generate unrelated helper source files unless the user explicitly requested tooling/scripts

package/skills/apexlang/references/workflows/apex-generation/nlu/nlu-routing-validation-notes.md

@@ -0,0 +1,171 @@
+# NLU Routing — Internal Dry‑Run Validation Notes (No Execution)
+
+Objective
+- Validate that natural one‑liner inputs are routed deterministically to a structured “Message 2” and that minimal rule loading, templates selection, and “Missing Inputs” handling align with governance.
+- Validate that fragmentary or free-form prompts are accepted as first-class input, normalized once, and clarified only when critical blockers remain.
+- No actual generation is executed here; this is a step‑by‑step checklist to simulate and verify behavior.
+- Inputs containing `{{...}}` are `illustrative_prompt` grammar examples. Substitute verified identifiers during a real run; never treat the variables as schema evidence or final output text.
+
+Prerequisites
+- Master workflow consolidated:
+-  - SKILL.md plus references/workflows/apex-generation.md (authoritative)
+- Component Registry:
+-  - assets/apex-generation/components.registry.json
+- Rule routing:
+  - assets/rules-mapping.json (updated with synonyms for calendar, map, cards, form/report region)
+- Skeletons and examples:
+-  - references/workflows/apex-generation.md (includes One-liner guidance and “J) Page — IR + Form”)
+
+Validation Process
+
+1) Confirm Master + Registry Presence
+- Verify files exist:
+-  - references/workflows/apex-generation.md
+-  - assets/apex-generation/components.registry.json
+- Check the master’s “One‑liner Mode (NLU Router)” section includes:
+  - Keyword extraction
+  - Component lookup via registry
+  - Target_type decision rules
+  - Union rule loading + styling conditional
+  - Template selection from templates/*
+  - Required inputs prompting (“Missing Inputs” policy)
+  - Message 2 synthesis
+
+2) Confirm Keyword → Rule Loading Mapping
+- Open assets/rules-mapping.json
+- Ensure the following keywords appear in match clauses:
+  - Page standards: ["calendar", "calendar region", "map", "map region", "new page", "breadcrumb", "page standard", "page naming"]
+  - IR: ["interactive report", "report", "ir", "interactive report region", "report region"]
+  - Form: ["form", "crud form", "modal form", "form region", "edit page", "insert page"]
+  - Dashboard/cards: ["dashboard", "kpi", "summary", "cards", "cards region"]
+  - Logic: ["process", "validation", "logic", "dynamic action", "da"]
+  - Items/LOV: ["item", "select list", "lov"]
+- Expected: Each keyword set maps to the correct 20/30/40 rule files.
+
+3) Manual Simulation — One‑Liner Inputs → Expected Routing
+- Use the test cases in references/workflows/apex-generation/nlu/nlu-routing-test-matrix.md and validate:
+
+Free-form prompt checks
+- `source ir lookup filter`
+  - Expected behavior: route toward interactive report + LOV interpretation, ask only for the minimum missing target details if critical.
+- `page report form refresh`
+  - Expected behavior: infer mixed page composition intent, normalize to page scope, and ask for only the missing identifiers that block drafting.
+- `crud source modal`
+  - Expected behavior: route toward form/modal CRUD generation and request PK/column metadata only if not already available from verified context.
+- `translate page 12 japanese`
+  - Expected behavior: route to shared-components translation flow, preserve simple-English follow-up style, and avoid asking for bundle-shaped input unless explicitly needed.
+- `create a button to translate to spanish`
+  - Expected behavior: do not route directly to shared-components localization or navigation/menu generation; ask one simple-English clarification to separate runtime language switching from localization.
+- `create a button that switches the session language to spanish`
+  - Expected behavior: route toward button + page-process behavior, not navigation/menu generation.
+- `dashboard category record count`
+  - Expected behavior: infer dashboard intent from fragments and request only missing data-source blockers.
+
+A) “Page with an interactive report and a form on {{source.table}}; use Lookup LOV for {{lookup.valueColumn}}; refresh report after submit”
+- Expected components: [interactive-report, form, lov-shared, dynamic-action-refresh-report]
+- target_type: page
+- Rules: page + interactive-report + form + items/sql + logic (+ guard + global)
+- Templates: templates/page-examples/interactive-report-page/interactive-report-page._index.md, templates/page-examples/form-page/form-page._index.md, templates/shared-components/lovs/lovs.dynamic.query.md, templates/business-logic/dynamic-actions/dynamic-actions.refresh-region-after-dialog.md
+- Required inputs to ask/validate:
+  - {{source.table}}: table, pk, columns
+  - LOV: {{lookup.valueColumn}}->{{lookup.displayColumn}}
+  - DA: IR region identifier, trigger = after submit
+- Expected Message 2: Structured object with target_type=page, intent summarizing both regions, data_contract populated where provided, styling=none unless specified, output_path default.
+
+B) “Interactive report on {{source.table}} with a {{lookup.valueColumn}} select list filter using Lookup LOV”
+- Components: [interactive-report, lov-shared]
+- target_type: interactive-report (or page, if desired)
+- Rules: page + interactive-report + items/sql (+ guard + global)
+- Templates: templates/page-examples/interactive-report-page/interactive-report-page._index.md, templates/shared-components/lovs/lovs.dynamic.query.md
+- Required inputs: {{source.table}}, LOV mapping
+- Message 2: Matches registry requirements.
+
+C) “Modal CRUD form on {{source.table}}; use Lookup LOV for {{lookup.valueColumn}}”
+- Components: [form, lov-shared]
+- target_type: form
+- Rules: page + form + items/sql (+ guard + global)
+- Templates: templates/page-examples/form-page/form-page._index.md + either templates/items/select-list/select-list._index.md (item-level) or templates/shared-components/lovs/lovs.dynamic.query.md (page-level)
+- Required inputs: table, pk, columns, LOV mapping.
+
+D) “Create a dashboard with cards summarizing record count by category”
+- Components: [dashboard]
+- target_type: page (or dashboard)
+- Rules: page + dashboard (+ guard + global)
+- Templates: templates/page-examples/dashboard-page/dashboard-page._index.md (optionally templates/page-examples/classic-report-page/classic-report-page._index.md)
+- Required inputs: aggregation SQL/table.
+
+E) “Add a calendar of {{source.table}} events”
+- Components: [calendar]
+- target_type: page
+- Rules: page (+ guard + global)
+- Templates: templates/page-examples/calendar-page/calendar-page._index.md
+- Required inputs: date column (e.g., {{source.dateColumn}}).
+
+F) “Create a map for office locations”
+- Components: [map]
+- target_type: page
+- Rules: page (+ guard + global)
+- Templates: templates/page-examples/map-page/map-page._index.md
+- Required inputs: lat/lng columns or geocode input.
+
+G) Negative: “Add a hexagon grid region with neural shimmer”
+- Components: none matched
+- Rules: page (+ guard + global)
+- Behavior:
+  - Draft: fallback static region or request clarification
+  - Critique: flags unsupported component
+  - Revision: omit unsupported part or record deferral
+
+H) “Add an AI assistant/chatbot to the home page”
+- Expected components: [ai-chatbot]
+- target_type: page
+- Rules: page + buttons + logic (+ guard + global)
+- Templates: templates/business-logic/dynamic-actions/dynamic-actions.show-ai-assistant.md
+- Required inputs to ask/validate:
+  - Target page number/alias and where to place the button (Breadcrumb/Title Bar)
+  - AI agent reference: use an existing alias (for example `@home`); do not invent missing agent names
+  - Chatbot agent assets resolve from `/shared-components/ai-agents/`
+  - Inline embedded rendering is opt-in only; if requested, confirm container selector and presence of `advanced.htmlDomId` (example: `chat`)
+
+4) Composition Load Check
+- Template, layout, grid, floating-label, and region-framing prompts should load `40-components/apex.templates.md`.
+- Archived styling materials must not be auto-loaded by adjacent wording.
+- Negative routing checks that must not trigger any archived styling route:
+  - `Build a dashboard with driver performance KPIs`
+  - `Create a report with conditional formatting`
+  - `Use a color picker item`
+  - `Show current theme information`
+  - `Add a dark-mode data source`
+  - `Make the login process secure`
+  - `Use a theme template component`
+
+5) Templates Integrity Check
+- For each test, ensure every referenced template exists in:
+  - templates/page-examples/*
+  - templates/business-logic/*
+  - templates/items/*
+  - templates/shared-components/*
+- If a requested visual (e.g., “cards variant”) lacks a template:
+  - Expect a fallback to a supported template.
+  - Critique to record limitation; Revision to apply supported subset only.
+
+6) Output Expectations (when executed)
+- Working copy: transient temp workspace outside the repo
+- Durable runtime evidence: compact report + transcript under `the temp-runtime logs directory under `APEXLANG_OUTPUT_ROOT/logs/`` when needed
+- Final: 
+  - If it is a page or page-based component, or a shared component, then output will be within {target_root}/pages/... or shared-components/... respectively; else
+-  - A whole app final output will be in {target_root} = ### where ### is the next available zero‑padded sequence (e.g., app_001, app_002, …)
+- output_path? (defaults per scope)
+    - Sequence computation: scan applications/ for existing app_* folders and pick the next integer.
+7) Documentation Cross‑refs
+-  - SKILL.md plus references/workflows/apex-generation.md (authoritative spec)
+-  - assets/apex-generation/components.registry.json (synonyms → components → rules/templates/requirements)
+-  - references/workflows/apex-generation.md and references/workflows/apex-generation/nlu/nlu-routing-test-matrix.md
+
+Sign‑off Criteria
+- All sample inputs map deterministically to components and rules.
+- Fragmentary prompts are accepted without requiring the user to restate them in structured form.
+- At most one clarification round is used for unresolved critical blockers.
+- No invented attributes/UT classes; missing inputs are requested, not fabricated.
+- Only existing templates are referenced; unsupported visuals trigger documented fallbacks.
+- Styling rules are conditionally loaded only when styling is provided.

package/skills/apexlang/references/workflows/apex-generation/registry.md

@@ -0,0 +1,14 @@
+# Component Registry Excerpts — Apex Developer
+
+| Keyword | Component | Notes |
+|---------|-----------|-------|
+| `interactive report` | interactive-report | Loads IR template & SQL rules |
+| `form` | form | Modal CRUD or page form |
+| `dashboard` | dashboard | Cards/KPI layout |
+| `chart` | chart-* | Chart variants via templates |
+| `calendar` | calendar | Date column and primary key column required |
+| `map` | map | Lat/Long or geocode |
+| `lov` | lov-shared / lov-sql | Shared or SQL LOV definitions |
+| `dynamic action` | dynamic-action-* | Refresh/report invocation |
+
+Refer to `assets/apex-generation/components.registry.json` for full list and synonyms.

package/skills/apexlang/references/workflows/apex-generation/templates.md

@@ -0,0 +1,49 @@
+> All `node tools/apexctl.mjs ...` commands are package-root relative: run them from the packaged skill root, or invoke that script by explicit path.
+
+# Template & Sub-Skill References — Apex Developer
+
+## Authoritative Policies
+- `references/policies/governance/00-governance.md`
+- `references/policies/memory-bank/00-guard/ai.guard.md`
+- `assets/rules-mapping.json`
+- `references/policies/memory-bank/systemPatterns.md`
+- `references/policies/memory-bank/10-global/apex.global.md`
+- `references/policies/memory-bank/40-components/apex.templates.md`
+
+## Operational References
+
+
+## Canonical Page Templates
+- `templates/page-examples/global_page_0/global_page_0._index.md`
+- `templates/page-examples/home-page/home-page._index.md`
+- `templates/page-examples/login-page/login-page._index.md`
+- `templates/page-examples/blank-page/blank-page._index.md`
+- `templates/page-examples/interactive-report-page/interactive-report-page._index.md`
+- `templates/page-examples/form-page/form-page._index.md`
+- `templates/page-examples/dashboard-page/dashboard-page._index.md`
+- `templates/page-examples/classic-report-page/classic-report-page._index.md`
+- `templates/page-examples/calendar-page/calendar-page._index.md`
+- `templates/page-examples/map-page/map-page._index.md`
+
+Calendar note:
+- Keep calendar examples aligned with compiler-truth-backed runtime guidance and the local validator behind `node tools/apexctl.mjs apexlang validate --app-path <resolved_app_path>`; use `assets/component-attributes.json` only as fallback/internal validator context when stronger runtime-backed proof is unavailable.
+- Calendar `createLink` and `viewEditLink` examples should use structured object syntax with required `page` and optional `items`, and should never invent target pages or target item mappings when the user did not provide them.
+
+## Delegate to Sub-Skills
+- **Page Patterns** — `references/domains/page-components/page-patterns.md`
+  - Navigation, breadcrumbs, page groups; see `references/domains/page-components/page-patterns/templates.md`.
+- **Regions** — `references/domains/page-components/regions.md`
+  - Interactive Reports (IRs), Interactive Grids (IGs), faceted search, dashboards, charts, classic reports, form, etc.; templates listed in `references/domains/page-components/regions/templates.md`.
+- **Template Components** — `references/domains/README.md`
+  - Layout slots, template options, button archetypes.
+- **Page Items** — `references/domains/page-components/page-items.md`
+  - Item types, LOVs, validations, computations.
+- **Shared Components** — `references/domains/README.md`
+  - Navigation lists, breadcrumbs, shared LOVs, translations.
+
+## Guardrails & Loading
+- Always load `references/policies/memory-bank/00-guard/ai.guard.md` and `references/policies/memory-bank/10-global/apex.global.md`.
+- Use `assets/rules-mapping.json` to fetch additional rules per component keyword.
+- Treat default help text, report-column guidance, and developer comments as baseline generation concerns; load the matching form/report rule files even when the prompt does not explicitly ask for annotations.
+- Treat `simple`, `basic`, `starter`, or similar prompt wording as a request for concise output, not as permission to skip the default guidance layer.
+- Skill-local agents live in `references/workflows/apex-generation/agents/*.md` (Draft, Critique, Revision).

package/skills/apexlang/references/workflows/apex-generation/workflow-manifests/apex-generation-agent-suite.md

@@ -0,0 +1,40 @@
+# Workflow Manifest: apex-generation-agent-suite
+
+## Agent 1 — Draft (`apex-generation-agent-draft`)
+- **Source:** `references/workflows/apex-generation/agents/20-agent-draft.md`
+- **Purpose:** Generate initial APEXlang artifact using templates and rule corpus.
+- **Inputs:** `target_type`, `intent`, `data_contract`, `styling`, `output_path`
+- **Outputs:** `Compiler Truth Evidence` when required, `Generation Plan` for non-trivial structural work, then transient temp app updates outside the repo
+- **Policies:** invokeApi-first, named notation, minimal rule loading, reuse templates only.
+
+## Agent 2 — Critique (`apex-generation-agent-critique`)
+- **Source:** `references/workflows/apex-generation/agents/30-agent-critique.md`
+- **Purpose:** Validate draft, enforce governance gates, record findings with citations.
+- **Inputs:** Draft path, `target_type`, `data_contract`, `styling`, `output_path`, `app_root`
+- **Outputs:** internal review findings plus confidence score; must enforce compiler-truth, Generation Plan, and stop-condition contracts before durable evidence is recorded
+- **Policies:** Confidence ≥ 0.95, missing inputs handling, critical page checks.
+
+## Agent 3 — Revision (`apex-generation-agent-revision`)
+- **Source:** `references/workflows/apex-generation/agents/40-agent-revision.md`
+- **Purpose:** Apply critique findings, ensure governance compliance, produce final artifact.
+- **Inputs:** Critique log, draft, structured inputs, target paths.
+- **Outputs:** Final artifact (`pages/`, `shared-components/`, etc.) plus compact runtime/report output when the workflow persists durable evidence; preserve or explicitly repair the frozen Generation Plan and compiler-truth evidence
+- **Policies:** No scope expansion, deterministic edits, respect invocation loops.
+
+## Post-Agent 4 — Direct SQLcl Validate Gate (`apex-generation-agent-direct-sqlcl-validate-gate`)
+- **Source:** `references/ops/runtime-gates/02-direct-sqlcl-validate-gate.md`
+- **Purpose:** Enforce completion checks using the local first-pass check plus direct SQLcl runtime semantics for check-only or import-approved runs.
+- **Inputs:** `resolved_app_path`, `db_connection_name`
+- **Outputs:** recorded direct SQLcl runtime outcome in run notes or change log
+- **Policies:** Hard-block on gate failures; feed failures back into critique/revision retry loop with up to 2 additional live retries after the first failure (3 total live rounds).
+
+## Pre-Agent 0 — Connection Gate (`apex-generation-agent-connection`)
+- **Source:** `references/ops/sqlcl-agents/00-connection-gate.md`
+- **Purpose:** Resolve database connection requirements before draft execution.
+- **Inputs:** `db_connection_name`, execution mode
+- **Outputs:** ``APEXLANG_OUTPUT_ROOT/logs/runtime-preflight.json``, gating signal.
+- **Policies:** Do not fabricate connections; stop and request `db_connection_name` when live prerequisites are missing.
+
+## Codex Integration Notes
+- Skill manifest should map agent IDs to these workflow files for modular execution.
+- Ensure agents can be invoked individually if Codex requires custom sequencing (e.g., planner-only runs).

package/skills/apexlang/references/workflows/apex-generation/workflow-manifests/apex-generation-master-workflow.md

@@ -0,0 +1,38 @@
+# Workflow Manifest: apex-generation-master-workflow
+
+- **Workflow ID:** `apex-generation-master-workflow`
+- **Source:** `references/workflows/apex-generation.md`
+- **Purpose:** Orchestrate APEXlang generation via the internal generate -> review -> fix loop with governance enforcement.
+- **Entry Modes:**
+  - Root router loads `references/workflows/apex-generation.md`
+  - Direct package loading (`references/workflows/apex-generation.md`) in internal repo workflows
+- **Inputs:**
+  - `target_type` (application | page | form | interactive-report | chart | dashboard | items | templates | dynamic-action)
+  - `intent` (free text)
+  - `data_contract` (tables, columns, LOV mappings)
+  - `styling` (default `none`)
+  - `output_path` (default `applications/app_###/`)
+  - `db_connection_name` (required for live metadata validation or runtime roundtrips)
+- **Agents:**
+  - Pre-Agent 0: Connection resolver (`references/ops/sqlcl-agents/00-connection-gate.md`)
+  - Agent 1: Draft (`references/workflows/apex-generation/agents/20-agent-draft.md`)
+  - Agent 2: Critique (`references/workflows/apex-generation/agents/30-agent-critique.md`)
+  - Agent 3: Revision (`references/workflows/apex-generation/agents/40-agent-revision.md`)
+  - Post-Agent 4: Direct SQLcl validate gate (`references/ops/runtime-gates/02-direct-sqlcl-validate-gate.md`)
+- **Rule Loading:** Determined via `assets/rules-mapping.json`; always guard + global, optional 20/30/40/50 based on inputs.
+- **Templates:** References under `templates/**` per component registry mapping.
+- **Outputs:**
+  - Working copy: transient temp app updates outside the repo
+  - Durable runtime evidence: `validation-report.json`, `validation-transcript.log`, `problems.json`, and `component-contracts/<build>.json`
+  - Final artifacts: `applications/app_###/pages/` and `applications/app_###/shared-components/` (or app-root files for whole-application runs) after the resolved live runtime action succeeds
+- **Quality Gates:**
+  - Critical pages (0, 1, 9999)
+  - Base shared components for new applications
+  - Confidence score ≥ 0.95 (two-pass cap)
+  - InvokeAPI-first policy, named notation in PL/SQL
+  - `runtime validate` pass for generated apps before publish/import eligibility
+  - Required validation source: live APEX validation evidence from the selected target build
+  - Repair loop: up to 2 additional live retries after the first failure (3 total live rounds), each patching only `problems.json` findings before rerun
+- **Codex Notes:**
+  - Manifest provides minimal metadata for skill integration.
+  - Codex should honor dry-run defaults and leverage component registry for structured inputs.

package/skills/apexlang/references/workflows/apex-generation.md

@@ -0,0 +1,65 @@
+---
+name: apex-developer
+description: Orchestrate the APEXlang internal generate, review, and fix loop for application and page generation.
+---
+> All `node tools/apexctl.mjs ...` commands are package-root relative: run them from the packaged skill root, or invoke that script by explicit path.
+
+
+# Constitutional Master Playbook — APEX Developer Reference Package
+
+## Purpose
+- Single authoritative orchestration for APEXlang generation using the internal generate -> review -> fix loop.
+- Enforce minimal rule loading, no fabrication, template-first drafting, and direct SQLcl runtime gates when a live roundtrip is required.
+
+## Authoritative Policies
+- `references/policies/memory-bank/00-guard/ai.guard.md`
+- `references/policies/governance/00-governance.md`
+- `assets/rules-mapping.json`
+- `references/policies/memory-bank/systemPatterns.md`
+
+## Operational References
+- `references/workflows/apexlang/prompt-contracts.md`
+- `references/workflows/apexlang/workflow-create-app-from-fr-and-model.md`
+- `references/workflows/apexlang/application-spec.template.md`
+- `references/workflows/apex-generation/templates.md`
+- `references/workflows/apex-generation/registry.md`
+- `references/workflows/apex-generation/workflow-manifests/apex-generation-master-workflow.md`
+- `references/workflows/apex-generation/workflow-manifests/apex-generation-agent-suite.md`
+- `assets/apex-generation/components.registry.json`
+- `references/policies/governance/prompt-normalization.md`
+
+## Execution Agents
+- `references/ops/sqlcl-agents/00-connection-gate.md`
+- `references/workflows/apex-generation/agents/20-agent-draft.md`
+- `references/workflows/apex-generation/agents/30-agent-critique.md`
+- `references/workflows/apex-generation/agents/40-agent-revision.md`
+- `references/ops/runtime-gates/02-direct-sqlcl-validate-gate.md`
+- `references/ops/runtime-gates/01-direct-sqlcl-import.md`
+
+## Loading Guidance
+- Load this package from `SKILL.md` when the request needs broad orchestration, mixed-domain generation, or the full internal generate -> review -> fix loop.
+- In the root-only APEXlang model, this package is not invoked as a direct skill.
+
+## Core workflow
+1. Normalize free-form input directly according to `references/policies/governance/prompt-normalization.md` and ask only one simple-English clarification round for critical blockers.
+2. If the request is complete app generation from functional requirements plus model/schema metadata, load `references/workflows/apexlang/workflow-create-app-from-fr-and-model.md`, complete `references/workflows/apexlang/application-spec.template.md`, and freeze the Application Composition Plan before drafting `.apx` artifacts.
+3. For packaged-build refresh work, classify the change as broad DSL drift or narrow component metadata delta before changing templates, examples, or packaged docs.
+4. Resolve prerequisite metadata and saved-connection discovery first for APEX artifact work: inspect offline schema dictionaries, scan saved SQLcl connections, use discovered aliases as candidates, and require the user to specify the live `db_connection_name` plus corresponding APEX workspace name before live work.
+5. If `db_mode = online`, continue with the resolved `db_connection_name`, APEX workspace name, and metadata/runtime gates as needed.
+6. Select page and component patterns only from `templates/**`, using `page-examples/**` first for page-scoped work.
+7. Use the resolved target app only for integration facts, never as a pattern or DSL source.
+8. Generate APEXlang artifacts from canonical templates and rules inside the transient temp workspace.
+9. Generate or refresh the target build contract pack and keep only the compact validation contexts in scope: user spec, table metadata, target build contract pack, scaffold manifest, and the last live validation problem list.
+10. Run the compiler-truth audit against the generated temp app and record `compiler-truth-report.json`; missing or failing compiler-truth evidence blocks completion.
+11. Review `problems.json` plus diagnostic sources for rule compliance, missing inputs, and required fixes; local lint and VS Code Problems snapshots are syntax hygiene/advisory only after live validation passes.
+12. Apply deterministic fixes only for reported problems, rerun compiler-truth audit as needed, and hand off to `references/ops/runtime-gates/` when a live roundtrip is required and `db_mode = online`.
+
+## Runtime hand-off
+- Live roundtrips use direct SQLcl commands only.
+- Use `node tools/apexctl.mjs runtime validate --app-path <absolute_app_path> --db-connection-name <db_connection_name> --apex-root <resolved_build_root> [--compiler-oracle-home <compiler_metadata_home>]` as the public validate-only handoff. The wrapper owns preflight/roundtrip details and must emit `validation-report.json`, `validation-transcript.log`, `problems.json`, and `component-contracts/<build>.json`.
+- `--apex-root` is runtime-only. Do not pass it through as compiler metadata; use `--compiler-oracle-home` only for explicit compiler-truth metadata overrides.
+- `apex validate -input` remains mandatory inside the live validate-only gate.
+- Runtime validation requires live APEX validation evidence for generated or revised `.apx` artifacts. Record `LIVE_RUNTIME_VALIDATION_REQUIRED_001` and block completion when required runtime inputs or live runtime evidence are missing; compiler-truth and VS Code Problems snapshots are diagnostics after a live pass.
+- Runtime hand-off defaults to check-only; in user-facing responses, call that `Check APEXlang code`. After the live APEXlang check passes, offer GUI/clickable choices for `Check APEXlang code` or `Check and import APEXlang code`.
+- `apex import -input` runs only after an explicit post-check GUI import choice, and then it must use the same authenticated SQLcl user session as the live check.
+- Completion remains blocked until runtime status proves eligibility.