pi-apexlang 0.3.0 → 0.4.0

package/README.md

@@ -11,6 +11,12 @@ APEXlang. It combines two resources:
 
 This is an independent integration and is not an Oracle product.
 
+## Documentation · Документація
+
+- [English documentation](docs/en/README.md): setup, architecture, tool reference, and maintenance.
+- [Українська документація](docs/uk/README.md): початок роботи, архітектура, довідник інструмента та супровід.
+- Infographics / Інфографіка: [English](docs/assets/overview.en.svg) · [Українська](docs/assets/overview.uk.svg).
+
 ## Install
 
 Try the local checkout without installing it:
@@ -92,8 +98,10 @@ code** requires an explicit target mode:
   Only after it proves the alias is absent does Pi ask for a second
   confirmation and rerun validation plus import together.
 
-Without GUI support, the tool always stops after checking and reports import
-as a follow-up.
+Every post-validation choice is abort-aware and bounded to five minutes.
+Without a confirmed GUI response—or when the request is aborted or times
+out—the tool stops after checking and reports import as a follow-up. Silence is
+never treated as import authorization.
 
 When refreshing a full APEXlang export, run one SQLcl export with explicit
 replacement semantics:
@@ -162,7 +170,8 @@ Oracle documents these requirements for live APEXlang work:
 
 - Oracle APEX 26.1 with APEXlang support.
 - ORDS 26.1.1 or newer.
-- SQLcl 26.1 or newer, selected with the compatibility advisory above.
+- SQLcl 26.1.2 or newer, as required by the bundled Oracle skill, selected
+  with the compatibility advisory above.
 - Java 17 or Java 21 for SQLcl.
 - A saved SQLcl connection name and its corresponding APEX workspace name.
 - A local APEX app or authoritative schema, model, API, or table metadata.
@@ -207,9 +216,12 @@ updates `UPSTREAM.json`.
 
 ## Provenance and license
 
+Package **0.4.0** includes Oracle's **2026.09.21** APEXlang skill release.
+See the bundled [Oracle release notes](skills/apexlang/release-notes.json).
+
 The vendored skill comes from
-[`oracle/skills/apex/apexlang`](https://github.com/oracle/skills/tree/30e30dbcbf5f92f3564bc85f8fd59d32736adcd6/apex/apexlang)
-at commit `30e30dbcbf5f92f3564bc85f8fd59d32736adcd6`. See
+[`oracle/skills/apex/apexlang`](https://github.com/oracle/skills/tree/b94ccf4dec34b27859c2378fa71ba2bad884f2fe/apex/apexlang)
+at commit `b94ccf4dec34b27859c2378fa71ba2bad884f2fe`. See
 [`UPSTREAM.json`](UPSTREAM.json) and
 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
 

package/THIRD_PARTY_NOTICES.md

@@ -3,8 +3,8 @@
 ## Oracle APEXlang skill
 
 `skills/apexlang` is an unmodified snapshot of
-[`oracle/skills/apex/apexlang`](https://github.com/oracle/skills/tree/30e30dbcbf5f92f3564bc85f8fd59d32736adcd6/apex/apexlang)
-at commit `30e30dbcbf5f92f3564bc85f8fd59d32736adcd6`.
+[`oracle/skills/apex/apexlang`](https://github.com/oracle/skills/tree/b94ccf4dec34b27859c2378fa71ba2bad884f2fe/apex/apexlang)
+at commit `b94ccf4dec34b27859c2378fa71ba2bad884f2fe`.
 
 Copyright (c) 2025 Oracle and/or its affiliates.
 

package/UPSTREAM.json

@@ -1,8 +1,8 @@
 {
   "repository": "https://github.com/oracle/skills.git",
-  "commit": "30e30dbcbf5f92f3564bc85f8fd59d32736adcd6",
+  "commit": "b94ccf4dec34b27859c2378fa71ba2bad884f2fe",
   "source_path": "apex/apexlang",
   "vendored_path": "skills/apexlang",
-  "content_sha256": "413de83cf898dce3d3752469d9ebc5fbd57ebff6805e6224ad82420b74230494",
+  "content_sha256": "b3622811c1cfaf62d5987802ab449b033c5b22220164be909a2fedd8c5cef8ca",
   "license": "UPL-1.0"
 }

package/docs/assets/overview.en.svg

@@ -0,0 +1,89 @@
+<svg xmlns="http://www.w3.org/2000/svg" xml:lang="en" width="1440" height="1490" viewBox="0 0 1440 1490" role="img" aria-labelledby="title desc">
+<title id="title">pi-apexlang — From app files to verified import</title>
+<desc id="desc">Two complementary components: the unchanged Oracle skill and the Pi extension. Discover context, check files locally and against compiler metadata, then validate live. Import requires an explicit choice and target proof; otherwise finish without import.</desc>
+<defs><marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="#7d989f"/></marker></defs>
+<style>text{font-family:Arial,"DejaVu Sans",sans-serif}.mono{font-family:"DejaVu Sans Mono",monospace}.eyebrow{letter-spacing:2px}</style>
+<rect x="0" y="0" width="1440" height="1490" rx="0" fill="#f4f6f2" stroke="none"/>
+<rect x="0" y="0" width="1440" height="204" rx="0" fill="#123642" stroke="none"/>
+<rect x="64" y="36" width="7" height="28" rx="2" fill="#91dbc0" stroke="none"/>
+<text x="88" y="58" font-size="22" fill="#91dbc0" font-weight="700" class="eyebrow">PI / APEXLANG</text>
+<text x="64" y="118" font-size="46" fill="#ffffff" font-weight="700">From app files to verified import</text>
+<text x="64" y="163" font-size="26" fill="#d0e2e3" font-weight="400">Oracle APEXlang development inside pi</text>
+<text x="64" y="247" font-size="16" fill="#526c73" font-weight="700" class="eyebrow">TWO COMPLEMENTARY PARTS</text>
+<rect x="64" y="269" width="640" height="122" rx="16" fill="#ffffff" stroke="#d6e2db"/>
+<rect x="736" y="269" width="640" height="122" rx="16" fill="#ffffff" stroke="#d6e2db"/>
+<text x="88" y="307" font-size="28" fill="#183b47" font-weight="700">Oracle skill</text>
+<text x="88" y="340" font-size="21" fill="#183b47" font-weight="400">References · templates · bundled runtime</text>
+<text x="88" y="371" font-size="20" fill="#526c73" font-weight="400">Pinned snapshot, preserved unchanged</text>
+<text x="760" y="307" font-size="28" fill="#183b47" font-weight="700">Pi extension</text>
+<text x="760" y="340" font-size="21" fill="#183b47" font-weight="400">Tool actions · process adapter · confirmations</text>
+<text x="760" y="371" font-size="20" fill="#526c73" font-weight="400">Works inside the active project workspace</text>
+<text x="64" y="435" font-size="16" fill="#526c73" font-weight="700" class="eyebrow">RECOMMENDED WORKFLOW</text>
+<text x="1170" y="435" font-size="20" fill="#146d5d" font-weight="700">8 tool actions</text>
+<rect x="64" y="461" width="758" height="110" rx="16" fill="#ffffff" stroke="#d6e2db"/>
+<rect x="84" y="479" width="44" height="44" rx="12" fill="#dcefe9" stroke="none"/>
+<text x="97" y="509" font-size="24" fill="#146d5d" font-weight="700">1</text>
+<text x="147" y="494" font-size="26" fill="#183b47" font-weight="700">Establish project context</text>
+<text x="147" y="522" font-size="20" fill="#146d5d" font-weight="500" class="mono">workspace_probe</text>
+<text x="147" y="551" font-size="20" fill="#526c73" font-weight="400">Existing app or authoritative metadata</text>
+<rect x="850" y="461" width="526" height="110" rx="16" fill="#e8eee8" stroke="#cad7cc"/>
+<text x="873" y="494" font-size="23" fill="#183b47" font-weight="700">Optional: create a local scaffold</text>
+<text x="873" y="522" font-size="20" fill="#146d5d" font-weight="500" class="mono">new_app_materialize</text>
+<text x="873" y="551" font-size="19" fill="#526c73" font-weight="400">Exact suggested path + confirmation</text>
+<path d="M 107 571 L 107 594" stroke="#7d989f" stroke-width="2" fill="none" marker-end="url(#arrow)"/>
+<rect x="64" y="604" width="1312" height="143" rx="16" fill="#ffffff" stroke="#d6e2db"/>
+<rect x="84" y="621" width="44" height="44" rx="12" fill="#dcefe9" stroke="none"/>
+<text x="97" y="651" font-size="24" fill="#146d5d" font-weight="700">2</text>
+<text x="147" y="651" font-size="27" fill="#183b47" font-weight="700">Check locally and against compiler metadata</text>
+<rect x="147" y="670" width="364" height="39" rx="8" fill="#edf4f4" stroke="none"/>
+<text x="163" y="696" font-size="20" fill="#183b47" font-weight="500" class="mono">query_valid_props</text>
+<rect x="531" y="670" width="364" height="39" rx="8" fill="#edf4f4" stroke="none"/>
+<text x="547" y="696" font-size="20" fill="#183b47" font-weight="500" class="mono">local_validate</text>
+<rect x="915" y="670" width="434" height="39" rx="8" fill="#edf4f4" stroke="none"/>
+<text x="931" y="696" font-size="20" fill="#183b47" font-weight="500" class="mono">compiler_truth_audit</text>
+<text x="147" y="732" font-size="20" fill="#526c73" font-weight="400">Local success does not establish a live server pass.</text>
+<path d="M 107 747 L 107 771" stroke="#7d989f" stroke-width="2" fill="none" marker-end="url(#arrow)"/>
+<rect x="64" y="781" width="1312" height="143" rx="16" fill="#ffffff" stroke="#d6e2db"/>
+<rect x="84" y="798" width="44" height="44" rx="12" fill="#dcefe9" stroke="none"/>
+<text x="97" y="828" font-size="24" fill="#146d5d" font-weight="700">3</text>
+<text x="147" y="828" font-size="27" fill="#183b47" font-weight="700">Check the runtime, then validate live</text>
+<rect x="147" y="847" width="364" height="39" rx="8" fill="#edf4f4" stroke="none"/>
+<text x="163" y="873" font-size="20" fill="#183b47" font-weight="500" class="mono">runtime_preflight</text>
+<rect x="531" y="847" width="364" height="39" rx="8" fill="#edf4f4" stroke="none"/>
+<text x="547" y="873" font-size="20" fill="#183b47" font-weight="500" class="mono">runtime_doctor</text>
+<rect x="915" y="847" width="434" height="39" rx="8" fill="#e1eee4" stroke="none"/>
+<text x="931" y="873" font-size="20" fill="#183b47" font-weight="500" class="mono">runtime_validate</text>
+<text x="147" y="909" font-size="20" fill="#526c73" font-weight="400">Saved SQLcl connection + matching APEX workspace</text>
+<path d="M 720 924 L 720 947" stroke="#7d989f" stroke-width="2" fill="none" marker-end="url(#arrow)"/>
+<rect x="64" y="957" width="1312" height="73" rx="16" fill="#fbefcf" stroke="#e4ce95"/>
+<text x="88" y="988" font-size="27" fill="#725017" font-weight="700">Authoritative live pass → interactive choice</text>
+<text x="88" y="1016" font-size="20" fill="#725017" font-weight="400">A failed check returns to diagnosis and repair.</text>
+<path d="M 250 1030 L 250 1054" stroke="#7d989f" stroke-width="2" fill="none" marker-end="url(#arrow)"/>
+<path d="M 905 1030 L 905 1054" stroke="#7d989f" stroke-width="2" fill="none" marker-end="url(#arrow)"/>
+<rect x="64" y="1065" width="384" height="284" rx="16" fill="#e8efeb" stroke="#c8d9cd"/>
+<text x="88" y="1104" font-size="25" fill="#183b47" font-weight="700">Finish after checking</text>
+<text x="88" y="1147" font-size="19" fill="#183b47" font-weight="400">Choose “Check APEXlang code”</text>
+<path d="M 88 1170 L 424 1170" stroke="#c3d4ca" stroke-width="2" fill="none"/>
+<text x="88" y="1202" font-size="18" fill="#526c73" font-weight="400">No UI, cancellation, or timeout</text>
+<text x="88" y="1230" font-size="18" fill="#526c73" font-weight="400">also means no import.</text>
+<text x="88" y="1315" font-size="23" fill="#146d5d" font-weight="700" class="mono">imported = false</text>
+<rect x="476" y="1065" width="900" height="284" rx="16" fill="#ffffff" stroke="#b5d5c8"/>
+<text x="500" y="1104" font-size="26" fill="#183b47" font-weight="700">Choose import and an explicit target</text>
+<rect x="500" y="1125" width="393" height="103" rx="10" fill="#f0f5ef" stroke="none"/>
+<rect x="913" y="1125" width="439" height="103" rx="10" fill="#f0f5ef" stroke="none"/>
+<text x="518" y="1155" font-size="17" fill="#146d5d" font-weight="700">UPDATE EXISTING</text>
+<text x="518" y="1184" font-size="21" fill="#183b47" font-weight="400">Prove one existing</text>
+<text x="518" y="1211" font-size="21" fill="#183b47" font-weight="400">remote application.</text>
+<text x="931" y="1155" font-size="17" fill="#146d5d" font-weight="700">CREATE NEW</text>
+<text x="931" y="1184" font-size="21" fill="#183b47" font-weight="400">Prove alias is absent,</text>
+<text x="931" y="1211" font-size="21" fill="#183b47" font-weight="400">then confirm creation again.</text>
+<rect x="500" y="1244" width="852" height="81" rx="10" fill="#146d5d" stroke="none"/>
+<text x="518" y="1276" font-size="25" fill="#ffffff" font-weight="700">Same app digest → revalidate + import</text>
+<text x="518" y="1306" font-size="20" fill="#e1f3e9" font-weight="400">One SQLcl session · validation, import, runtime gate = pass</text>
+<path d="M 64 1380 L 1376 1380" stroke="#c7d6ce" stroke-width="2" fill="none"/>
+<text x="64" y="1417" font-size="22" fill="#183b47" font-weight="700">5 min per dialog</text>
+<text x="366" y="1417" font-size="22" fill="#183b47" font-weight="700">10 min per process</text>
+<text x="735" y="1417" font-size="22" fill="#183b47" font-weight="700">Save reports before session shutdown</text>
+<text x="64" y="1458" font-size="17" fill="#526c73" font-weight="400">Independent integration · Package 0.4.0 · Oracle b94ccf4 · 2026-09-22</text>
+<text x="1000" y="1458" font-size="16" fill="#526c73" font-weight="400">Documentation: docs/en/README.md</text>
+</svg>

package/docs/assets/overview.uk.svg

@@ -0,0 +1,89 @@
+<svg xmlns="http://www.w3.org/2000/svg" xml:lang="uk" width="1440" height="1490" viewBox="0 0 1440 1490" role="img" aria-labelledby="title desc">
+<title id="title">pi-apexlang — Від файлів до перевіреного імпорту</title>
+<desc id="desc">Дві складові: незмінений Oracle skill і розширення Pi. Визначте контекст, перевірте файли локально та за метаданими компілятора, потім на сервері. Імпорт потребує явного вибору й доказу цілі; інакше робота завершується без імпорту.</desc>
+<defs><marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="#7d989f"/></marker></defs>
+<style>text{font-family:Arial,"DejaVu Sans",sans-serif}.mono{font-family:"DejaVu Sans Mono",monospace}.eyebrow{letter-spacing:2px}</style>
+<rect x="0" y="0" width="1440" height="1490" rx="0" fill="#f4f6f2" stroke="none"/>
+<rect x="0" y="0" width="1440" height="204" rx="0" fill="#123642" stroke="none"/>
+<rect x="64" y="36" width="7" height="28" rx="2" fill="#91dbc0" stroke="none"/>
+<text x="88" y="58" font-size="22" fill="#91dbc0" font-weight="700" class="eyebrow">PI / APEXLANG</text>
+<text x="64" y="118" font-size="46" fill="#ffffff" font-weight="700">Від файлів до перевіреного імпорту</text>
+<text x="64" y="163" font-size="26" fill="#d0e2e3" font-weight="400">Розробка Oracle APEXlang у pi</text>
+<text x="64" y="247" font-size="16" fill="#526c73" font-weight="700" class="eyebrow">ДВІ СКЛАДОВІ</text>
+<rect x="64" y="269" width="640" height="122" rx="16" fill="#ffffff" stroke="#d6e2db"/>
+<rect x="736" y="269" width="640" height="122" rx="16" fill="#ffffff" stroke="#d6e2db"/>
+<text x="88" y="307" font-size="28" fill="#183b47" font-weight="700">Oracle skill</text>
+<text x="88" y="340" font-size="21" fill="#183b47" font-weight="400">Довідники · шаблони · вбудоване середовище</text>
+<text x="88" y="371" font-size="20" fill="#526c73" font-weight="400">Зафіксований знімок без змін</text>
+<text x="760" y="307" font-size="28" fill="#183b47" font-weight="700">Розширення Pi</text>
+<text x="760" y="340" font-size="21" fill="#183b47" font-weight="400">Дії інструмента · адаптер · підтвердження</text>
+<text x="760" y="371" font-size="20" fill="#526c73" font-weight="400">Працює в активному каталозі проєкту</text>
+<text x="64" y="435" font-size="16" fill="#526c73" font-weight="700" class="eyebrow">РЕКОМЕНДОВАНИЙ ПОРЯДОК РОБОТИ</text>
+<text x="1170" y="435" font-size="20" fill="#146d5d" font-weight="700">8 дій інструмента</text>
+<rect x="64" y="461" width="758" height="110" rx="16" fill="#ffffff" stroke="#d6e2db"/>
+<rect x="84" y="479" width="44" height="44" rx="12" fill="#dcefe9" stroke="none"/>
+<text x="97" y="509" font-size="24" fill="#146d5d" font-weight="700">1</text>
+<text x="147" y="494" font-size="26" fill="#183b47" font-weight="700">Визначити контекст проєкту</text>
+<text x="147" y="522" font-size="20" fill="#146d5d" font-weight="500" class="mono">workspace_probe</text>
+<text x="147" y="551" font-size="20" fill="#526c73" font-weight="400">Наявний застосунок або достовірні метадані</text>
+<rect x="850" y="461" width="526" height="110" rx="16" fill="#e8eee8" stroke="#cad7cc"/>
+<text x="873" y="494" font-size="23" fill="#183b47" font-weight="700">За потреби: локальний каркас</text>
+<text x="873" y="522" font-size="20" fill="#146d5d" font-weight="500" class="mono">new_app_materialize</text>
+<text x="873" y="551" font-size="19" fill="#526c73" font-weight="400">Точний запропонований шлях + підтвердження</text>
+<path d="M 107 571 L 107 594" stroke="#7d989f" stroke-width="2" fill="none" marker-end="url(#arrow)"/>
+<rect x="64" y="604" width="1312" height="143" rx="16" fill="#ffffff" stroke="#d6e2db"/>
+<rect x="84" y="621" width="44" height="44" rx="12" fill="#dcefe9" stroke="none"/>
+<text x="97" y="651" font-size="24" fill="#146d5d" font-weight="700">2</text>
+<text x="147" y="651" font-size="27" fill="#183b47" font-weight="700">Перевірити локально й за метаданими компілятора</text>
+<rect x="147" y="670" width="364" height="39" rx="8" fill="#edf4f4" stroke="none"/>
+<text x="163" y="696" font-size="20" fill="#183b47" font-weight="500" class="mono">query_valid_props</text>
+<rect x="531" y="670" width="364" height="39" rx="8" fill="#edf4f4" stroke="none"/>
+<text x="547" y="696" font-size="20" fill="#183b47" font-weight="500" class="mono">local_validate</text>
+<rect x="915" y="670" width="434" height="39" rx="8" fill="#edf4f4" stroke="none"/>
+<text x="931" y="696" font-size="20" fill="#183b47" font-weight="500" class="mono">compiler_truth_audit</text>
+<text x="147" y="732" font-size="20" fill="#526c73" font-weight="400">Локальна перевірка не доводить успіху на сервері.</text>
+<path d="M 107 747 L 107 771" stroke="#7d989f" stroke-width="2" fill="none" marker-end="url(#arrow)"/>
+<rect x="64" y="781" width="1312" height="143" rx="16" fill="#ffffff" stroke="#d6e2db"/>
+<rect x="84" y="798" width="44" height="44" rx="12" fill="#dcefe9" stroke="none"/>
+<text x="97" y="828" font-size="24" fill="#146d5d" font-weight="700">3</text>
+<text x="147" y="828" font-size="27" fill="#183b47" font-weight="700">Перевірити середовище, потім застосунок на сервері</text>
+<rect x="147" y="847" width="364" height="39" rx="8" fill="#edf4f4" stroke="none"/>
+<text x="163" y="873" font-size="20" fill="#183b47" font-weight="500" class="mono">runtime_preflight</text>
+<rect x="531" y="847" width="364" height="39" rx="8" fill="#edf4f4" stroke="none"/>
+<text x="547" y="873" font-size="20" fill="#183b47" font-weight="500" class="mono">runtime_doctor</text>
+<rect x="915" y="847" width="434" height="39" rx="8" fill="#e1eee4" stroke="none"/>
+<text x="931" y="873" font-size="20" fill="#183b47" font-weight="500" class="mono">runtime_validate</text>
+<text x="147" y="909" font-size="20" fill="#526c73" font-weight="400">Збережене підключення SQLcl + відповідний APEX workspace</text>
+<path d="M 720 924 L 720 947" stroke="#7d989f" stroke-width="2" fill="none" marker-end="url(#arrow)"/>
+<rect x="64" y="957" width="1312" height="73" rx="16" fill="#fbefcf" stroke="#e4ce95"/>
+<text x="88" y="988" font-size="27" fill="#725017" font-weight="700">Підтверджений успіх на сервері → вибір користувача</text>
+<text x="88" y="1016" font-size="20" fill="#725017" font-weight="400">Невдала перевірка повертає до діагностики та виправлень.</text>
+<path d="M 250 1030 L 250 1054" stroke="#7d989f" stroke-width="2" fill="none" marker-end="url(#arrow)"/>
+<path d="M 905 1030 L 905 1054" stroke="#7d989f" stroke-width="2" fill="none" marker-end="url(#arrow)"/>
+<rect x="64" y="1065" width="384" height="284" rx="16" fill="#e8efeb" stroke="#c8d9cd"/>
+<text x="88" y="1104" font-size="25" fill="#183b47" font-weight="700">Завершити перевірку</text>
+<text x="88" y="1147" font-size="19" fill="#183b47" font-weight="400">Обрати “Check APEXlang code”</text>
+<path d="M 88 1170 L 424 1170" stroke="#c3d4ca" stroke-width="2" fill="none"/>
+<text x="88" y="1202" font-size="18" fill="#526c73" font-weight="400">Немає UI, скасування чи таймаут</text>
+<text x="88" y="1230" font-size="18" fill="#526c73" font-weight="400">також означають відсутність імпорту.</text>
+<text x="88" y="1315" font-size="23" fill="#146d5d" font-weight="700" class="mono">imported = false</text>
+<rect x="476" y="1065" width="900" height="284" rx="16" fill="#ffffff" stroke="#b5d5c8"/>
+<text x="500" y="1104" font-size="26" fill="#183b47" font-weight="700">Обрати імпорт і конкретний режим цілі</text>
+<rect x="500" y="1125" width="393" height="103" rx="10" fill="#f0f5ef" stroke="none"/>
+<rect x="913" y="1125" width="439" height="103" rx="10" fill="#f0f5ef" stroke="none"/>
+<text x="518" y="1155" font-size="17" fill="#146d5d" font-weight="700">ОНОВИТИ НАЯВНИЙ</text>
+<text x="518" y="1184" font-size="21" fill="#183b47" font-weight="400">Довести наявність одного</text>
+<text x="518" y="1211" font-size="21" fill="#183b47" font-weight="400">застосунку на сервері.</text>
+<text x="931" y="1155" font-size="17" fill="#146d5d" font-weight="700">СТВОРИТИ НОВИЙ</text>
+<text x="931" y="1184" font-size="21" fill="#183b47" font-weight="400">Довести відсутність alias,</text>
+<text x="931" y="1211" font-size="21" fill="#183b47" font-weight="400">потім підтвердити створення ще раз.</text>
+<rect x="500" y="1244" width="852" height="81" rx="10" fill="#146d5d" stroke="none"/>
+<text x="518" y="1276" font-size="25" fill="#ffffff" font-weight="700">Той самий хеш → повторна перевірка + імпорт</text>
+<text x="518" y="1306" font-size="20" fill="#e1f3e9" font-weight="400">Одна сесія SQLcl · validation, import, runtime gate = pass</text>
+<path d="M 64 1380 L 1376 1380" stroke="#c7d6ce" stroke-width="2" fill="none"/>
+<text x="64" y="1417" font-size="22" fill="#183b47" font-weight="700">5 хв на діалог</text>
+<text x="366" y="1417" font-size="22" fill="#183b47" font-weight="700">10 хв на процес</text>
+<text x="735" y="1417" font-size="22" fill="#183b47" font-weight="700">Зберегти звіти до завершення сесії</text>
+<text x="64" y="1458" font-size="17" fill="#526c73" font-weight="400">Незалежна інтеграція · Пакет 0.4.0 · Oracle b94ccf4 · 2026-09-22</text>
+<text x="1000" y="1458" font-size="16" fill="#526c73" font-weight="400">Документація: docs/uk/README.md</text>
+</svg>

package/docs/en/README.md

@@ -0,0 +1,41 @@
+# pi-apexlang documentation
+
+[Українська](../uk/README.md) · [Project README](../../README.md)
+
+`pi-apexlang` connects the pi coding agent to Oracle's APEXlang development resources. The agent uses Oracle's templates and guidance to work on application files; the extension provides a controlled tool for discovery, scaffolding, validation, and runtime diagnostics. An import becomes available through an interactive choice after a successful live check.
+
+This is an independent integration, not an Oracle product. The repository is named `pi-apex`; the package and its version are defined in [package.json](../../package.json).
+
+## Read by task
+
+| Your task | Guide |
+| --- | --- |
+| Install the package and check your first app | [Getting started](getting-started.md) |
+| Understand the components and import flow | [Architecture](architecture.md) |
+| Look up actions, parameters, and result evidence | [Tool reference](tool-reference.md) |
+| Find reports, diagnose failures, or maintain the package | [Maintenance](maintenance.md) |
+
+## At a glance
+
+![APEXlang workflow: establish context, run local and compiler checks, validate live, then choose whether to import.](../assets/overview.en.svg)
+
+[Scalable infographic](../assets/overview.en.svg) · [PNG image](../assets/overview.en.png)
+
+## What a successful check means
+
+| Evidence | What it establishes |
+| --- | --- |
+| Local validation passes | The bundled vocabulary, DSL, and validation-rule checks passed. |
+| Compiler-truth audit passes | Component structure and attributes passed checks against the selected compiler metadata. |
+| Authoritative live validation passes | The runtime returned successful live-validator evidence for the application snapshot. |
+| Import passes | Validation, import, and the runtime gate each returned `pass`. |
+
+Local success alone does not establish that an app is valid on a particular server. A live check alone does not mean that the app was imported.
+
+## Documentation baseline
+
+These guides describe package version **0.4.0**, updated on **2026-09-22** with Oracle's **2026.09.21** APEXlang skill release, pinned in [`UPSTREAM.json`](../../UPSTREAM.json). The update adds Media List and Comments workflows, expands Metric Card, Cards, and Region Display Selector support, and strengthens Smart Filter and Search validation. See the bundled [Oracle release notes](../../skills/apexlang/release-notes.json).
+
+Examples use illustrative paths and connection names. Server access, credentials, and deployment targets are supplied by the operator.
+
+Implementation claims link to local source files. Oracle prerequisite links are provided in the setup guide. The compatibility table is an advisory maintained by this project; its recorded review date is independent of this documentation date. No production validation or import is implied by these guides.

package/docs/en/architecture.md

@@ -0,0 +1,73 @@
+# Architecture
+
+[Documentation](README.md) · [Українська](../uk/architecture.md)
+
+## Components
+
+| Layer | Responsibility | Source |
+| --- | --- | --- |
+| Oracle skill | Task routing, references, templates, and bundled Oracle runtime | [skills/apexlang](../../skills/apexlang) |
+| Pi extension | Registers `apexlang`, exposes its schema, handles confirmation and session cleanup | [index.ts](../../extensions/apexlang/index.ts) |
+| Process adapter | Builds argument arrays, checks paths and runtime context, tracks app digests, runs child processes | [apexlang-cli.mjs](../../extensions/lib/apexlang-cli.mjs) |
+| Local validation wrapper | Runs vocabulary, DSL, and validation-rule checks | [apexlang-local-validate.mjs](../../extensions/lib/apexlang-local-validate.mjs) |
+| Parser acceleration | Caches repeated block parsing and nesting lookups within one Python process | [apexlang-local-validator.py](../../extensions/lib/apexlang-local-validator.py) |
+| Runtime bridge | Invokes the bundled validation and roundtrip runtimes; supports a controlled SQLcl PTY path | [validation bridge](../../extensions/lib/apexlang-runtime-validate.mjs), [roundtrip bridge](../../extensions/lib/apexlang-runtime-roundtrip.mjs), [PTY bridge](../../extensions/lib/apexlang-sqlcl-pty.py) |
+| Compatibility advisory | Detects broad findings and presents version guidance | [compatibility.ts](../../extensions/apexlang/compatibility.ts), [table](../../extensions/apexlang/ords-sqlcl-compatibility.json) |
+
+The skill is vendored unchanged at the commit and digest recorded in [UPSTREAM.json](../../UPSTREAM.json). The extension's acceleration wraps Oracle's validator; it does not edit the vendor snapshot or omit validation stages. Pi discovers the skill through the `pi.skills` package entry and loads task-specific material progressively.
+
+The validation bridge supplies the packaged grammar and Python validator paths for Media List target-build checks. Oracle's 2026.09.21 runtime otherwise looks for these files under source-tree paths that are absent from the public skill package. The bridge retains Oracle's validation and failure handling.
+
+## Working flow
+
+```mermaid
+flowchart TD
+    A[User request + app or authoritative metadata] --> B[workspace_probe]
+    B --> C[Agent creates or edits APEXlang files]
+    B -. Optional confirmed scaffold .-> S[new_app_materialize]
+    S --> C
+    C --> D[query_valid_props + local_validate + compiler_truth_audit]
+    D --> E[runtime_preflight / runtime_doctor]
+    E --> F[runtime_validate: live check]
+    F --> G{Authoritative pass?}
+    G -- No --> H[Review findings and repair]
+    H --> C
+    G -- Yes --> I{Interactive next step}
+    I -- Check only / cancel / no UI --> J[Finish without import]
+    I -- Import --> K[Resolve target + check app digest]
+    K --> L[Revalidate and import in one SQLcl session]
+```
+
+This is the recommended workflow. The registered tool is not a scheduler that automatically runs all eight actions. Editing application code is work performed by the agent; there is no general-purpose `generate` or `edit` action in the tool schema.
+
+## Import flow
+
+1. `runtime_validate` must return a successful process result plus `live_check_status=pass` or `validation_status=pass`, and `validation_sources.live_validator.status=pass`.
+2. With a UI, the extension offers **Check APEXlang code** or **Check and import APEXlang code**. Without a UI, it returns the live-check result with `imported=false`.
+3. Choosing import requires a valid SHA-256 application digest and an explicit target mode:
+
+   | Target mode | Required evidence |
+   | --- | --- |
+   | Update existing | Oracle resolves exactly one existing remote application. |
+   | Create new | Oracle proves the alias is absent in the selected workspace without import authority; the user then confirms creation in an additional dialog. |
+
+4. The adapter checks that the application snapshot still matches the approved digest. A changed tree requires revalidation.
+5. Validation and import run together in one SQLcl session. The extension reports import success only when `validate_status`, `import_status`, and `runtime_gate_status` are all `pass`, with a successful process result.
+
+There is no standalone import action in the model-visible action list. Every confirmation and selection dialog receives the abort signal and a five-minute timeout. Selecting nothing never authorizes import. These are controls implemented by the package; they do not replace the database privileges of the saved connection.
+
+## Runtime staging and evidence
+
+App-scoped runtime operations require a JSON object in `deployments/default.json`. The adapter accepts workspace metadata under `workspace.name` or the exported `app.workspace.name`, rejects conflicts, and compares it with the explicit `workspace_name` without case sensitivity. An unresolved `__REQUIRED_WORKSPACE_NAME__` placeholder is rejected.
+
+The adapter copies the app under the session output root for runtime preflight, diagnostics, validation, import, and create-new proof. It injects the workspace and uses Oracle's line-ending normalizer on the staged `.apx` files before computing the digest. Project files remain unchanged. Validation and import therefore use the same LF-normalized snapshot. The digest also normalizes JSON formatting and the injected `workspace.name`; other deployment properties remain part of the digest, and substantive source changes require revalidation.
+
+The extension creates a temporary `pi-apexlang-*` output directory on first use and reuses it during the session. Reports and runtime context therefore share a stable session root. Known validation/roundtrip evidence is cleared before a new corresponding run. The entire output root is removed on `session_shutdown`: copy needed evidence before ending the session.
+
+## Execution boundaries
+
+Application paths stay inside the active Pi workspace. The adapter checks real paths, rejects symlinks in app trees and relevant discovery inputs, and rejects multiply linked files for vocabulary rewrites. Commands use argument arrays rather than shell interpolation. Cancellation, timeout, or excess output terminates the spawned process tree.
+
+The tool runs sequentially. Its configured command timeout is **10 minutes per invoked process**, not a total deadline for a multi-phase action. The adapter's default combined process-output limit is **8 MiB**; text presented to the model is trimmed at **80,000 characters**, with the full report location retained.
+
+See [runner tests](../../test/runner.test.mjs) and [extension tests](../../test/extension.test.mjs) for executable examples of these boundaries.

package/docs/en/getting-started.md

@@ -0,0 +1,77 @@
+# Getting started
+
+[Documentation](README.md) · [Українська](../uk/getting-started.md)
+
+## Requirements
+
+For local work, have pi installed, Node.js **22.19.0 or newer**, and `python3` available on `PATH`. Node's minimum is declared in [package.json](../../package.json); the [local validator wrapper](../../extensions/lib/apexlang-local-validate.mjs) invokes `python3` directly.
+
+For live commands, the [bundled Oracle skill](../../skills/apexlang/README.md#requirements) requires SQLcl **26.1.2 or newer** and the latest available APEX **26.1** build, with a valid database connection and privileges for the target workspace and schema. The general [Oracle APEXlang prerequisites](https://docs.oracle.com/en/database/oracle/sql-developer-command-line/26.1/sqcug/prerequisites-apexlang.html) list SQLcl 26.1 as the minimum. ORDS **26.1.1** introduced the required APEXlang support; see [ORDS 26.1.1 release notes](https://www.oracle.com/tools/ords/ords-relnotes-26.1.1.html). For the SQLcl 26.1.2 line, Oracle lists Java **17 or 21** in its [release notes](https://www.oracle.com/tools/sqlcl/sqlcl-relnotes-26.1.2.html). Check the relevant release documentation when selecting another version.
+
+Provide a **saved SQLcl connection name** and its corresponding **APEX workspace name**. The extension accepts names, not passwords, credentials, or connection strings. Local work also needs an existing APEXlang app or authoritative schema, model, API, or table metadata.
+
+## Install and open a project
+
+Install for the current user:
+
+```bash
+pi install git:github.com/avhrst/pi-apex
+```
+
+For installation scoped to an application project, run this inside that project:
+
+```bash
+pi install git:github.com/avhrst/pi-apex -l
+```
+
+Then start `pi` in the directory that contains your application and metadata. This directory is the active workspace: `app_path` must stay inside it.
+
+To try this repository locally, run `pi -e .` from its checkout. That makes the checkout the workspace; it does not select an external application project. The root README also documents the npm installation form for use after an npm release. This guide does not assert that a particular version has been published.
+
+Pi loads the skill when relevant. Prefix a request with `/skill:apexlang` to select it explicitly.
+
+## First check of an existing app
+
+The names below are examples; substitute a real app path and saved connection.
+
+1. Establish context:
+
+   ```text
+   /skill:apexlang Probe this workspace. Identify candidate APEX apps and the available authoritative metadata. Explain any missing inputs.
+   ```
+
+2. Check the intended app locally:
+
+   ```text
+   /skill:apexlang Check applications/service-ops locally. Run the compiler-truth audit when compiler metadata is available. Show findings and report paths. Do not import it.
+   ```
+
+3. When the runtime is configured, request a server check:
+
+   ```text
+   /skill:apexlang Check applications/service-ops using saved connection apex_dev and APEX workspace SERVICE_OPS_DEV. Diagnose the runtime first, then validate live. Do not import it.
+   ```
+
+If the successful live check displays a next-step dialog, select **Check APEXlang code** to finish without importing. Each interactive dialog is limited to five minutes; cancellation, timeout, or an unavailable UI does not authorize an import.
+
+See [the tool reference](tool-reference.md) for exact action names and [the import flow](architecture.md#import-flow) for the separate import path.
+
+## Create a local scaffold
+
+Provide authoritative metadata and an app alias, target path, or title hint. `workspace_probe` must resolve the context, set `app_context.status=create_new_allowed`, and return the exact `suggested_app_path`. `new_app_materialize` requires this path, the saved connection/workspace pair, and interactive confirmation.
+
+```text
+/skill:apexlang Use the verified schema metadata in this workspace to prepare a new APEXlang app. Probe first and report the proposed app path. Materialize the scaffold through the confirmation dialog, then check it locally. Do not import it.
+```
+
+Materialization creates local files. Creating a remote application is a later, separately confirmed import operation.
+
+## Refresh a complete export
+
+In an appropriately connected SQLcl session, replace the placeholders before running:
+
+```text
+apex export -applicationid <id> -exptype APEXLANG -split -dir <absolute-parent-directory> -force
+```
+
+`-dir` is the parent directory; SQLcl creates the application-alias folder below it. `-force` removes and recreates that export folder. Preserve local-only changes before refreshing. The extension's export guidance calls for one replacement export to avoid collision-suffixed copies such as `p00005_1.apx`; see the [registered guideline](../../extensions/apexlang/index.ts).

package/docs/en/maintenance.md

@@ -0,0 +1,83 @@
+# Maintenance and troubleshooting
+
+[Documentation](README.md) · [Українська](../uk/maintenance.md)
+
+## Keep the reports you need
+
+Read the `outputRoot` in tool result details or the `APEXlang reports:` path in an execution error. The extension passes this directory to subprocesses as `APEXLANG_OUTPUT_ROOT`; its own temporary root is created internally rather than selected by a tool parameter.
+
+| Relative location | Contents |
+| --- | --- |
+| `logs/apexlang-vocab-report.json` | Vocabulary findings and unsupported-MMD diagnostics |
+| `logs/apexlang-dsl-report.json` | DSL validation findings |
+| `logs/apexlang-validations-report.json` | Validation-rule findings |
+| `logs/validation/` | Live-validation artifacts when produced by the runtime |
+| `logs/runtime-run.json`, `logs/runtime-run.log` | Roundtrip runtime report and transcript when produced |
+| `logs/compat/` | Compatibility evidence when that path is used |
+| `runtime-apps/` | Temporary staged application copies |
+
+Not every action creates every file. New runs clear known stale evidence, and session shutdown deletes the whole root. Save the relevant reports to a project-owned evidence directory before another run or shutdown if you need a durable record. Reports can contain application code, names, and diagnostics; review their contents before sharing them.
+
+## Diagnose by symptom
+
+| Symptom | Next step |
+| --- | --- |
+| `Missing Inputs` during scaffolding | Supply authoritative metadata and an app identity hint; probe again and use exactly `suggested_app_path`. |
+| App path or symlink rejected | Open pi at the intended project root and use a real app directory inside it. |
+| Vocabulary fix rejects a multiply linked file | Make the intended app file independent before requesting a rewrite. |
+| Saved connection or workspace rejected | Use the saved alias, not a connection string; supply the matching workspace. |
+| `deployments/default.json` missing/conflicting | Inspect the exported deployment metadata and reconcile the intended workspace before retrying. |
+| Compiler properties cannot be resolved | Check the app's `mmdVersion` and the available compiler metadata; use `compiler_oracle_home` where supported. |
+| Many findings across the app | Review SQLcl/APEX/ORDS and compiler-metadata compatibility before bulk edits. |
+| Live process exits successfully but import is unavailable | Inspect authoritative live-validator fields; a process exit code alone is insufficient. |
+| App changed after the approved check | Revalidate the current app snapshot. |
+| Post-check dialog cancelled or timed out | The app was not imported; request a fresh check if an import is still intended. |
+| Process timeout or output-limit error | Inspect saved output, diagnose with `runtime_doctor`, and address the cause before rerunning. |
+
+## Version advisory
+
+The [machine-readable table](../../extensions/apexlang/ords-sqlcl-compatibility.json) records `policy=advisory-only` and a review date of **2026-07-19**. Its SQLcl build **26.1.2.132.1334** is a diagnostic baseline for the documented APEX 26.1 scenarios, not a universal version pin. SQLcl 26.2 is not categorically blocked.
+
+The [advisory detector](../../extensions/apexlang/compatibility.ts) triggers for at least **50 structured findings**. Local JSON reports and compiler-truth text additionally need at least **5 distinct `.apx` files**; duplicate findings are deduplicated. A local vocabulary report explicitly declaring `UNSUPPORTED_MMD_VERSION` also triggers guidance.
+
+Check `sql -version`, `.apex/apexlang.json` → `mmdVersion`, and the server's APEX/ORDS releases with its administrator. The table adds guidance without changing validation status or granting import authority. Its recorded Oracle minima and project diagnostic recommendations have distinct `basis` values; consult the linked release documentation for other release lines.
+
+## Develop and verify
+
+From the repository root:
+
+```bash
+npm install --ignore-scripts
+npm run check
+```
+
+`npm run check` runs these stages in order:
+
+| Stage | What it checks |
+| --- | --- |
+| `typecheck` | Strict TypeScript checks without emitting files |
+| `verify:vendor` | The pinned Oracle snapshot digest and provenance |
+| `test` | Extension/adapter contracts and validator-output parity |
+| `smoke` | Probe of an empty temporary workspace and local validation of the bundled scaffold |
+| `verify:package` | npm dry-run package contents and excluded development/cache files |
+
+These checks are local automated verification, not proof of a successful live validation or import against a real server. The publish workflow is manually dispatched and runs `npm run check` before publishing; see [publish-npm.yml](../../.github/workflows/publish-npm.yml).
+
+## Refresh Oracle's snapshot
+
+Use a reviewed commit/ref in place of `<reviewed-ref>`:
+
+```bash
+npm run sync:oracle -- --ref <reviewed-ref>
+npm run check
+```
+
+The [sync script](../../scripts/sync-oracle-apexlang.mjs) fetches Oracle's repository, replaces `skills/apexlang`, refreshes `LICENSE`, updates the commit/digest in `UPSTREAM.json`, and updates pinned references in the root README and third-party notices. It uses a backup while replacing the snapshot. Review the resulting diff before committing.
+
+Keep custom behavior in `extensions/`; local edits inside the Oracle snapshot break the provenance check. After behavior changes, update both language guides and both infographic SVGs/PNGs together. The guides' baseline date/commit is a documentation snapshot, not automatically rewritten by the Oracle sync script.
+
+## Documentation assets
+
+The infographics are editable SVGs in [docs/assets](../assets), with PNG copies for sharing. Both use the same layout and workflow. SVG is the source of each image; regenerate its PNG after changing labels or diagrams. The npm `files` list includes `docs` so the installed README's documentation links remain usable.
+
+Project source/test links in these guides refer to the Git checkout. `scripts/` and `test/` are development resources and are intentionally not included in the npm package; open the [source repository](https://github.com/avhrst/pi-apex) for them. Licensing and vendor attribution are in [LICENSE](../../LICENSE), [THIRD_PARTY_NOTICES.md](../../THIRD_PARTY_NOTICES.md), and [UPSTREAM.json](../../UPSTREAM.json).