apexrest 1.2.0 → 1.3.0

package/dist/codex-compat/plugins/apexrest-apex/runtime/{chunk-2Z3BZF66.mjs → chunk-WPS3CSQJ.mjs}

@@ -40,7 +40,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // packages/core/src/fs.ts
-import { mkdir, open, readFile, readdir, realpath, rename, lstat, rm } from "node:fs/promises";
+import { mkdir, open, readFile, readdir, realpath, rename, lstat, rm, link } from "node:fs/promises";
 import { createReadStream } from "node:fs";
 import path from "node:path";
 import { hostname } from "node:os";
@@ -48,17 +48,54 @@ import { createHash, randomUUID as randomUUID2 } from "node:crypto";
 
 // packages/core/src/result.ts
 import { randomUUID } from "node:crypto";
+var DIAGNOSTIC_LIMIT = 50;
 var Fault = class extends Error {
-  constructor(code, message, exitCode = 1, status = "failed") {
+  constructor(code, message, exitCode = 1, status = "failed", details) {
     super(message);
     this.code = code;
     this.exitCode = exitCode;
     this.status = status;
+    this.details = details;
   }
   code;
   exitCode;
   status;
+  details;
 };
+var faultNextActions = {
+  VALIDATION_FAILED: "Fix the listed diagnostics in the named .apx files, then rerun apexrest_apex_validate until it reports no errors.",
+  VALIDATION_UNCONFIRMED: "The compiler returned no success marker. Read the diagnostics, fix the source and rerun apexrest_apex_validate.",
+  SOURCE_DRIFT: "Sources changed after review. Rerun apexrest_ship with mode:plan, review it, then apply.",
+  TARGET_DRIFT: "The target changed after review. Rerun apexrest_ship with mode:plan and review the new plan.",
+  PLAN_EXPIRED: "Rerun apexrest_ship with mode:plan; plans expire 30 minutes after creation.",
+  DEPLOY_APPROVAL_REQUIRED: "Run apexrest_ship with mode:apply and userRequest set to the user's literal instruction; it records a plan-bound deploy grant for this attempt.",
+  PRODUCTION_CI_REQUIRED: "Production targets need a signed external approval in a protected CI runner; apexrest_ship cannot apply them. Report this to the user.",
+  RECOVERY_REVIEW_REQUIRED: "The plan carries destructive, privileged or security risks. Review them with the user and provide a recovery path before applying.",
+  PROJECT_TRUST_REQUIRED: "Ask the user to add the project's canonical path to trustedProjects in APEXREST_HOME/policy.json (CLI: apexrest status --detail project shows the path), then retry.",
+  PROJECT_NOT_CONFIGURED: "Pass the absolute directory containing apexrest.json, or create one with apexrest_project action:init.",
+  CONNECTION_REQUIRED: "Configure the named connection reference with apexrest_project action:connection_add (never send passwords in chat).",
+  ENVIRONMENT_REQUIRED: "Pass env with a configured environment name; apexrest_project action:inspect lists them.",
+  UNKNOWN_ENVIRONMENT: "Use an environment listed by apexrest_project action:inspect.",
+  OUTCOME_UNKNOWN: "Do not retry. Read apexrest_job status for the same jobId and reconcile the target before any new deployment.",
+  SYNC_BLOCKED: "Reconcile the interrupted import before syncing or deploying again; do not clear ownership.",
+  SYNC_DIRTY: "Local sources differ from the checkpoint. Review or commit them before refreshing the working copy.",
+  UNSUPPORTED_CAPABILITY: "The installed SQLcl lacks this apex command. Run apexrest_status detail:doctor and install the pinned toolchain.",
+  JOB_OUTCOME_UNKNOWN: "Read apexrest_job status with this jobId; do not repeat the operation."
+};
+function normalizeDiagnostic(entry, code) {
+  const d = {
+    severity: entry.severity ?? "error",
+    code: entry.code ?? code,
+    message: redact(String(entry.message))
+  };
+  if (typeof entry.file === "string") d.file = redact(entry.file);
+  if (Number.isInteger(entry.line)) d.line = entry.line;
+  if (Number.isInteger(entry.column)) d.column = entry.column;
+  if (typeof entry.type === "string") d.type = entry.type;
+  if (typeof entry.hint === "string") d.hint = redact(entry.hint);
+  if (Array.isArray(entry.validValues)) d.validValues = entry.validValues.map(String);
+  return d;
+}
 var safeArtifactPages = /* @__PURE__ */ new WeakSet();
 function artifactPage(content, format, id, offset, limit, metadata = {}) {
   const safe = format === "json" ? JSON.stringify(sanitized(JSON.parse(content))) : redact(content);
@@ -125,6 +162,12 @@ function success(operation, data, summary = "Operation completed.") {
 }
 function failure(operation, error) {
   const e = error instanceof Fault ? error : new Fault("INTERNAL_ERROR", error instanceof Error ? error.message : "Unknown failure");
+  const structured = Array.isArray(e.details?.diagnostics) ? e.details.diagnostics : [];
+  const diagnostics = structured.length ? structured.slice(0, DIAGNOSTIC_LIMIT).map((entry) => normalizeDiagnostic(entry, e.code)) : [{ severity: "error", code: e.code, message: redact(e.message) }];
+  const nextActions = [
+    ...Array.isArray(e.details?.nextActions) ? e.details.nextActions.map(redact) : [],
+    ...faultNextActions[e.code] ? [faultNextActions[e.code]] : []
+  ];
   return {
     schemaVersion: 1,
     ok: false,
@@ -132,9 +175,10 @@ function failure(operation, error) {
     status: e.status,
     runId: randomUUID(),
     summary: redact(e.message),
-    diagnostics: [{ severity: "error", code: e.code, message: redact(e.message) }],
+    diagnostics,
     artifacts: [],
-    nextActions: [],
+    nextActions,
+    ...structured.length > DIAGNOSTIC_LIMIT ? { data: { diagnosticsOmitted: structured.length - DIAGNOSTIC_LIMIT } } : {},
     exitCode: e.exitCode
   };
 }
@@ -169,6 +213,21 @@ async function atomicWrite(file, value) {
     await rm(temporary, { force: true });
     throw error;
   }
+  await syncDirectory(path.dirname(file));
+}
+async function syncDirectory(directory) {
+  let handle;
+  try {
+    handle = await open(directory, "r");
+    await handle.sync();
+  } catch (error) {
+    const code = error.code;
+    if (process.platform === "win32" || ["EPERM", "EISDIR", "EINVAL", "ENOTSUP", "EBADF"].includes(code ?? ""))
+      return;
+    throw error;
+  } finally {
+    await handle?.close();
+  }
 }
 var writeJson = (file, value) => atomicWrite(file, JSON.stringify(value, null, 2) + "\n");
 async function readJson(file) {
@@ -184,15 +243,25 @@ async function exists(file) {
   }
 }
 async function contained(root, candidate) {
+  return containedPath(root, candidate, false);
+}
+async function containedChild(root, candidate) {
+  return containedPath(root, candidate, true);
+}
+async function containedPath(root, candidate, child) {
   const base = await realpath(root), target = path.resolve(base, candidate);
   const rel = path.relative(base, target);
   if (rel === ".." || rel.startsWith(".." + path.sep) || path.isAbsolute(rel))
     throw new Fault("PATH_ESCAPE", "Path escapes the permitted root.", 2);
+  if (child && rel === "")
+    throw new Fault("PATH_ESCAPE", "Path must be inside, not equal to, the permitted root.", 2);
   let probe = target;
   while (!await exists(probe)) probe = path.dirname(probe);
   const physical = await realpath(probe), physicalRel = path.relative(base, physical);
   if (physicalRel === ".." || physicalRel.startsWith(".." + path.sep) || path.isAbsolute(physicalRel))
     throw new Fault("SYMLINK_ESCAPE", "Symlink escapes the permitted root.", 2);
+  if (child && probe === target && physicalRel === "")
+    throw new Fault("PATH_ESCAPE", "Path must be inside, not equal to, the permitted root.", 2);
   return target;
 }
 async function inventory(root) {
@@ -211,6 +280,36 @@ async function inventory(root) {
   await walk(root);
   return Object.fromEntries(Object.entries(out).sort());
 }
+var LOCK_CORRUPT_AFTER_MS = 3e4;
+async function createLock(file, owner) {
+  const temporary = file + "." + randomUUID2() + ".owner";
+  const handle = await open(temporary, "wx", 384);
+  try {
+    try {
+      await handle.writeFile(owner);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    try {
+      await link(temporary, file);
+      return;
+    } catch (error) {
+      const code = error.code;
+      if (code === "EEXIST") throw error;
+      if (!["EPERM", "ENOTSUP", "ENOSYS", "EXDEV", "EOPNOTSUPP"].includes(code ?? "")) throw error;
+    }
+    const fallback = await open(file, "wx", 384);
+    try {
+      await fallback.writeFile(owner);
+      await fallback.sync();
+    } finally {
+      await fallback.close();
+    }
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
 async function withLock(file, action) {
   await mkdir(path.dirname(file), { recursive: true, mode: 448 });
   const recovery = file + ".recovery";
@@ -227,6 +326,20 @@ async function withLock(file, action) {
       owner = await readJson(file);
     } catch {
     }
+    if (!owner || typeof owner !== "object" || !Number.isInteger(owner.pid)) {
+      let age = 0;
+      try {
+        age = Date.now() - (await lstat(file)).mtimeMs;
+      } catch {
+      }
+      if (age > LOCK_CORRUPT_AFTER_MS)
+        throw new Fault(
+          "LOCK_CORRUPT",
+          `Lock file ${file} has no readable owner (an interrupted earlier process left it). Confirm no apexrest operation is running on any host, then delete that file and retry.`,
+          5,
+          "conflict"
+        );
+    }
     if (owner && owner.hostname === hostname() && Number.isInteger(owner.pid) && owner.pid > 0) {
       let dead = false;
       try {
@@ -249,9 +362,11 @@ async function withLock(file, action) {
       }
     }
   }
-  let handle;
   try {
-    handle = await open(file, "wx", 384);
+    await createLock(
+      file,
+      JSON.stringify({ pid: process.pid, hostname: hostname(), createdAt: (/* @__PURE__ */ new Date()).toISOString() })
+    );
   } catch (e) {
     if (e.code === "EEXIST")
       throw new Fault(
@@ -263,13 +378,8 @@ async function withLock(file, action) {
     throw e;
   }
   try {
-    await handle.writeFile(
-      JSON.stringify({ pid: process.pid, hostname: hostname(), createdAt: (/* @__PURE__ */ new Date()).toISOString() })
-    );
-    await handle.sync();
     return await action();
   } finally {
-    await handle.close();
     await rm(file, { force: true });
   }
 }
@@ -289,10 +399,13 @@ export {
   hashFile,
   canonical,
   atomicWrite,
+  syncDirectory,
   writeJson,
   readJson,
   exists,
   contained,
+  containedChild,
   inventory,
+  LOCK_CORRUPT_AFTER_MS,
   withLock
 };

package/dist/codex-compat/plugins/apexrest-apex/runtime/mcp.mjs

@@ -1,14 +1,9 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
-import {
-  startMcp
-} from "./chunk-2ZUNLCLK.mjs";
-import "./chunk-TXVQLYTH.mjs";
-import "./chunk-AQZLLQ3D.mjs";
-import "./chunk-BD2AVCFU.mjs";
-import "./chunk-4MYHJ2IU.mjs";
-import "./chunk-S24BD6PY.mjs";
-import "./chunk-3MDDJFXN.mjs";
-import "./chunk-2Z3BZF66.mjs";
 
 // packages/mcp/src/main.ts
+if (Number(process.versions.node.split(".")[0]) < 24) {
+  process.stderr.write("APEXREST requires Node.js 24 or newer.\n");
+  process.exit(3);
+}
+var { startMcp } = await import("./chunk-QKYF6N6U.mjs");
 await startMcp();

package/dist/codex-compat/plugins/apexrest-apex/skills/apexrest-apexlang/SKILL.md

@@ -1,40 +1,37 @@
 ---
 name: apexrest-apexlang
-description: Create or edit Oracle APEXlang (.apx) using pinned Oracle references and compiler validation. Excludes Salesforce Apex.
+description: Write or edit Oracle APEXlang (.apx) sources using pinned Oracle references, bundled component and pattern recipes, and compiler validation. Read when a change needs syntax, a component contract or a page composition. Excludes Salesforce Apex.
 ---
 
-Pass the user's absolute workspace as `project` on project-scoped calls.
+# APEXlang
 
-## Reuse first
+Pass the absolute project directory as `project`. Reuse source already read; retrieve only what changes the edit, with at most 3 `apexrest_reference` lookups per change. Never guess grammar or leave placeholders; `apexrest_apex_validate` is the arbiter.
 
-Inspect relevant source and pinned toolchain once. Reuse existing components, IDs, templates and shared components; export only for missing/stale source. For a new app, use `apexrest_apex_generate` or an installed project template. Preserve `.apex/apexlang.json` and MMD; generate/export into new destinations.
+## Retrieval
 
-For a reusable component, search `apexrest_reference_search` with `corpus: "components"`, the requested English or Ukrainian name, target `version`, `kind: "template"` and `limit: 3`. Read the selected `component:` recipe and its required parameter/Oracle contracts. Compare its APEX, theme and MMD compatibility with the project. `ready` proves the recorded offline compilation only; inspect SQL/import/browser statuses separately. Read an unresolved result's reason instead of inventing support. The catalog is local reference data: ordinary lookup never connects to the source application. Do not read the complete inventory unless maintaining the catalog.
+- Known entry: `apexrest_reference` `mode:read` with the ID. `oracle:` is a complete document, `grammar:production-name` one production, `component:`/`pattern:` a bundled recipe. Follow only the `requires` and `related` links you need; page with `offset`/`nextOffset`.
+- Unknown syntax: `mode:search` with the exact property or short English terms, `kind` (`grammar`, `template`, `contract`, `guide`), the route `family` from the table below and `limit:3`. `version` `26.1` is the bundled snapshot. Empty results do not prove a feature absent.
+- Reusable component: `mode:search`, `corpus:components`, `kind:template`, English or Ukrainian name, `limit:3`; read the `component:` recipe and its parameter contract. `ready` proves offline compilation only.
+- UX flow across components: `corpus:patterns` the same way; read the `pattern:` recipe and its required `component:`/`oracle:` contracts and keep its page, item and action relationships.
 
-Keep component hosts distinct (for example, a Media List list template versus its template component). Adapt recipe page/item names, DOM IDs, source projections, keys, shared references and submitted items together. Merge into the existing application; the recipe compiler scaffold is not permission to replace authentication, authorization or app settings. Synthetic sources show a data contract and do not establish the user's business schema.
+Entry IDs are `oracle:templates/<family>/<name>._index`; `family` is the search filter:
 
-For a reusable UX flow or page composition, search the separate pattern catalog with `corpus: "patterns"`, a short English or Ukrainian query, `kind: "template"`, the target `version` and `limit: 3`. Read the returned `pattern:` recipe and its required component/Oracle contracts. Preserve its dependency closure and adapt the actual interaction, not just its layout. Ordinary pattern lookup is offline and adds no source-application dependency. Use [pattern catalog maintenance](../apexrest-pattern-catalog/SKILL.md) only when asked to add or update catalog entries from an application.
+- Form page `page-examples/form-page`; form region `region-components/form`.
+- Interactive report, interactive grid, classic report: `region-components/<name>`.
+- Dashboard page `page-examples/dashboard-page`; chart `region-components/chart`; cards `region-components/cards`; metric card `template-components/metric-card`.
+- Media List, Comments: `template-components/<name>`.
+- Smart Filters/Search `region-components/smart-filter-search`; Region Display Selector `region-components/region-display-selector`.
+- Dynamic actions, processes, validations: `business-logic/<name>`.
+- Buttons `buttons`; select list, date picker, popup LOV: `items/<name>`; shared SQL LOV `shared-components/lovs` (`lovs.dynamic.query`).
 
-## Retrieve only what changes the edit
+Other families: search the English type with `kind:contract`, then use the returned `family`. Read the owning component production to establish valid nesting; grammar presence does not prove that a combination compiles.
 
-Read the selected contract through [component routes](references/component-routes.md). Reuse prior reads; do not dump the reference index or load unrelated families.
+## Contract notes
 
-- Known ID: `apexrest_reference_read`; `oracle:` selects a complete document, `grammar:production-name` a production.
-- Unknown syntax: `apexrest_reference_search` with exact property/short English terms, relevant `kind` (`grammar`, `template`, `contract`, `guide`), route `family` and `limit: 3`. Check the returned version against the toolchain: `26.1` selects the bundled snapshot; `26.1@...` stays exact. Empty results do not prove a feature absent.
-- Read the full relevant block using its `offset`/`nextOffset`; `nextResultOffset` pages matches. Follow template `requires` and relevant production `related` links. Batch independent reads only.
+Read the family section in [component contracts](references/component-contracts.md) before Media List, Comments, Metric Card, Cards, Smart Filters/Search or Region Display Selector. Key points: Media List and Comments need column metadata for every projection and one source variant (never mix named and unnamed columns); partial regions need a provably single-row source; Smart Filters need the results region mapped and submitted items on every dependent source; Region Display Selector lists only regions on the same page; Cards and Metric Card bind title/value/icon columns explicitly. Theme option inventories and release notes do not prove compiler support.
 
-Oracle documents supply versioned syntax/template contracts; their orchestration, design defaults and deploy commands do not override user choices or plugin workflows. Bind template variables and remove unused alternatives. Never guess grammar or leave placeholders in `.apx` files.
+Filtered dashboards: submit each filter item with every dependent region or chart series (`pageItemsToSubmit`), refresh dependent regions together with one Dynamic Action, keep date-range text inside a refreshed region, and reconcile source queries for default, changed, single-entity and empty cases ([native dashboard notes](references/native-dashboard.md)). A compiler-checked filtered chart/cards composition is in [p00020-filtered-components.apx](assets/p00020-filtered-components.apx): adapt page number, alias, item names and theme references together; it uses synthetic DUAL data.
 
-For Media List, Comments, Metric Card, Cards, Smart Filters/Search or Region Display Selector, read the relevant [component contract notes](references/component-contracts.md) before choosing source mappings, nested blocks or actions. Theme option inventories and release notes do not prove target-build compiler support. When a requested capability lacks a resolved contract, report that specific gap and continue independent work.
+## Editing rules
 
-## Make a coherent change
-
-Establish tables, joins, keys, bindings and metric meanings. Batch independent metadata/read-only source-query checks within authorization and reuse their results. Resolve unknown fields/units instead of inventing data.
-
-Edit related components together. Check column mappings, shared-component references and submitted items for every AJAX-dependent query. For filtered dashboards, read [native dashboard guidance](references/native-dashboard.md). Preserve authentication/authorization unless explicitly requested otherwise.
-
-## Compile and finish
-
-Compile coherent edits with the pinned Oracle compiler; deployment planning already does this for unchanged source. Fix errors using the owning production/template and rerun relevant checks. Resolve warnings about ignored requested behavior; report actual output.
-
-Continue identified development/test application requests through [authorized import](../apexrest-deploy/SKILL.md); existing apps use a reviewed full-application import. Verify UI using the [selected browser](../apexrest-test/SKILL.md#in-app-browser-verification). Separate source, compiler and browser evidence; report unavailable verification and why.
+Establish tables, joins, keys and metric meanings from metadata (`apexrest_metadata_read`, batched `requests` for several objects) before binding sources. Edit related components together: column mappings, shared-component references, submitted items and refresh actions for every AJAX-dependent query. Preserve `.apex/apexlang.json`, Oracle IDs, templates, authentication and authorization; merge recipes into the existing application rather than replacing settings. Resolve warnings that say a requested behavior was ignored. Then continue with validation, shipping and browser checks in [work](../apexrest-work/SKILL.md).

package/dist/codex-compat/plugins/apexrest-apex/skills/apexrest-apexlang/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "APEX applications"
-  short_description: "Build, edit, export and validate APEX applications"
-  default_prompt: "Use $apexrest-apexlang. Help me build or update an Oracle APEX application with APEXlang."
+  display_name: 'APEXlang'
+  short_description: 'Write APEXlang with pinned Oracle references and recipes'
+  default_prompt: 'Use $apexrest-apexlang to write or fix the APEXlang for this Oracle APEX change using the bundled references.'

package/dist/codex-compat/plugins/apexrest-apex/skills/apexrest-apexlang/references/component-routes.md

@@ -1,10 +1,6 @@
 # APEXlang routes for Codex
 
-For ready component recipes, first search the bundled component catalog with `corpus: "components"` and the relevant name, `kind: "template"`, target `version` and `limit: 3`. Read the returned `component:` ID and its dependencies. Known entrypoints include `component:template-components/metric-card`, `component:regions/cards`, `component:reports/interactive-grid` and `component:regions/region-display-selector`. English and Ukrainian names are searchable. Keep recipe readiness separate from SQL, import and browser evidence. The complete inventory is `component:catalog`; do not load it for an ordinary component edit.
-
-For a UX pattern spanning several components, use `corpus: "patterns"` with the requested workflow, `kind: "template"`, target `version` and `limit: 3`. Read the selected `pattern:` recipe, then only its required `component:`/`oracle:` contracts. Preserve the page/item/action relationships and data contract. Adding another application's patterns to the catalog uses [pattern catalog maintenance](../../apexrest-pattern-catalog/SKILL.md); using an existing pattern does not invoke capture or refresh its source.
-
-Read the selected entry with `apexrest_reference_read`, then its `requires` and one scenario template. No search is needed for these entrypoints. The IDs below resolve inside the installed plugin outside the source repository. The bundled Oracle APEXlang skills release is 2026.09.21 for APEX 26.1; compiler metadata remains authoritative for the actual target.
+Read the selected entry with `apexrest_reference` `mode:read`, then its `requires` and one scenario template. No search is needed for these entrypoints. The IDs below resolve inside the installed plugin outside the source repository. The bundled Oracle APEXlang skills release is 2026.09.21 for APEX 26.1; compiler metadata remains authoritative for the actual target.
 
 | Requested work | Entry ID | Search family |
 | --- | --- | --- |

package/dist/codex-compat/plugins/apexrest-apex/skills/apexrest-pattern-catalog/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: apexrest-pattern-catalog
-description: Add or update reusable Oracle APEX UX patterns in the bundled catalog from an identified application. Use for catalog maintenance; ordinary pattern use belongs to apexrest-apexlang.
+description: Maintainer-only - add or update reusable Oracle APEX UX patterns in the bundled catalog from an identified application. Not for ordinary application work; using a pattern belongs to apexrest-apexlang.
 ---
 
-# Maintain the pattern catalog
+# Maintain the pattern catalog (maintainers)
 
 Turn an identified source application's reusable page compositions into reviewed catalog records and APEXlang recipes. Keep this workflow separate from using a pattern to change the user's application: route that work to [APEXlang](../apexrest-apexlang/SKILL.md).
 
@@ -11,7 +11,7 @@ Turn an identified source application's reusable page compositions into reviewed
 
 Resolve the requested saved SQLcl connection, application ID, workspace and parsing schema from the user's request and available configuration. Check the live identity before capture. Read-only inspection/export does not authorize imports, business-table changes or changing authentication. Preserve existing authorization; ask only for a missing target or an action outside it. Never request credentials in chat.
 
-Read [capture and curation](references/capture-and-curation.md) for maintainer commands and the source record. Capture/build helpers run from a source checkout of `https://github.com/apexrest-dev/apexrest-codex`; do not assume those repository scripts exist relative to an installed skill. An installed plugin can retrieve existing patterns offline. Locate an available checkout for maintenance, or explain the missing checkout while completing source inspection and a local candidate inventory. Do not mutate the installed plugin cache.
+Read [capture and curation](references/capture-and-curation.md) for maintainer commands and the source record. Capture/build helpers run from a source checkout of `https://github.com/apexrest-dev/apexrest`; do not assume those repository scripts exist relative to an installed skill. An installed plugin can retrieve existing patterns offline. Locate an available checkout for maintenance, or explain the missing checkout while completing source inspection and a local candidate inventory. Do not mutate the installed plugin cache.
 
 ## Curate a reusable composition
 
@@ -29,4 +29,4 @@ Create an original or redistribution-authorized recipe with synthetic data or an
 
 Resolve the recipe's complete local dependency closure and compile it with its declared scaffold before marking it `ready`. Bind evidence to the recipe, dependencies, scaffold and compiler inputs so edits invalidate stale results. Record source inspection, offline compilation, SQL execution, import and browser behavior separately; an unavailable check remains `not-run`.
 
-Review the source/ID/content diff, then merge only the selected source's curated records. Build and check the pattern catalog, including rejection of missing/stale reviews, orphan patterns and unknown source anchors. Verify focused recipe and coverage retrieval (`pattern:source/<sourceId>/review` and `/review/page-<id>`, family `coverage`), installed-package portability, and paired English/Ukrainian documentation. Preserve raw captures outside the public package. Report added/updated IDs, compatibility, actual checks and unresolved items. Catalog maintenance does not authorize publishing a release or importing into any application.
+Review the source/ID/content diff, then merge only the selected source's curated records. Build and check the pattern catalog, including rejection of missing/stale reviews, orphan patterns and unknown source anchors. Verify focused recipe and coverage retrieval (`pattern:source/<sourceId>/review` and `/review/page-<id>`, family `coverage`), installed-package portability, and the English documentation. Preserve raw captures outside the public package. Report added/updated IDs, compatibility, actual checks and unresolved items. Catalog maintenance does not authorize publishing a release or importing into any application.

package/dist/codex-compat/plugins/apexrest-apex/skills/apexrest-pattern-catalog/agents/openai.yaml

@@ -1,3 +1,3 @@
 interface:
-  display_name: "APEXREST Pattern Catalog"
+  display_name: "Pattern catalog (maintainers)"
   short_description: "Add reusable APEX UX patterns to the catalog"

package/dist/codex-compat/plugins/apexrest-apex/skills/apexrest-pattern-catalog/references/capture-and-curation.md

@@ -78,9 +78,9 @@ Source redistribution rights must be evaluated independently for each applicatio
 
 The verifier must compile every recipe declared `ready` with its complete local dependency set and the exact scaffold/MMD. Review diagnostics about ignored behavior. A positive compiler result does not establish that a query runs, navigation reaches a real target, or a dynamic action behaves correctly in a browser.
 
-Keep SQL/import/browser results separate and retain `not-run` with a reason when unavailable. Do not import into the source application to establish catalog readiness. A runtime verification request needs its own identified authorized target and the existing [deployment workflow](../../apexrest-deploy/SKILL.md).
+Keep SQL/import/browser results separate and retain `not-run` with a reason when unavailable. Do not import into the source application to establish catalog readiness. A runtime verification request needs its own identified authorized target and the existing [deployment workflow](../../apexrest-work/SKILL.md).
 
-After review, rebuild the catalog and validate deterministic output, ID/link integrity, source isolation, evidence hashes and search/read bounds. Use the repository's normal build, packaging and plugin synchronization checks. Ordinary retrieval uses `apexrest_reference_search` with `corpus: "patterns"`, then `apexrest_reference_read` for a returned `pattern:` ID; it must work offline outside the source checkout.
+After review, rebuild the catalog and validate deterministic output, ID/link integrity, source isolation, evidence hashes and search/read bounds. Use the repository's normal build, packaging and plugin synchronization checks. Ordinary retrieval uses `apexrest_reference` `mode:search` with `corpus: "patterns"`, then `mode:read` for a returned `pattern:` ID; it must work offline outside the source checkout.
 
 ```sh
 node scripts/verify-pattern-recipes.mjs

package/dist/codex-compat/plugins/apexrest-apex/skills/apexrest-safety/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: apexrest-safety
+description: Deployment, test, production and unknown-outcome policy for APEXREST. Read when apexrest_ship, apexrest_test_run or apexrest_job returns blocked, failed or outcome_unknown, or before any production or database change.
+---
+
+# Safety policy
+
+Authorization. An explicit user request to create, update or import an identified development/test application authorizes that import; `apexrest_ship` records it as a short-lived grant bound to the exact project, target and plan digest, deploy only, and removes it. Never invent consent, widen it to business-table writes, authentication changes or other targets, or edit `policy.json` grants by hand. Production targets (`kind: production` or listed in the administrator-owned `production-trust.json`) refuse `mode:apply`; they need a signed external approval in a protected CI runner. Never create, edit or relax that file.
+
+Trust. `PROJECT_TRUST_REQUIRED` means the user must add the project path to `trustedProjects` in `APEXREST_HOME/policy.json` after reviewing its code. Ask; do not write it.
+
+Plans. A plan expires after 30 minutes and binds sources, configuration, toolchain and target. `SOURCE_DRIFT`, `TARGET_DRIFT`, `PLAN_EXPIRED` or `SYNC_REPLAN_REQUIRED`: run `apexrest_ship` `mode:plan` again and review the new preview. `RECOVERY_REVIEW_REQUIRED`: the plan carries destructive, privileged or security risks; present them and the recovery path to the user before applying. Working-copy plans cannot run migrations or packages; invalidate the sync explicitly first.
+
+Unknown outcomes. `outcome_unknown`, `OUTCOME_UNKNOWN`, an expired heartbeat or a lost import response mean the database may have changed. Do not retry, cancel or clear ownership. Read `apexrest_job` `action:status` for the same `jobId`, then reconcile with the CLI `deploy status --run RUNID` before any new plan. Cancellation never implies rollback. Backups under `.apexrest/backups` restore application metadata only through a separate restore plan.
+
+Tests. Required suites fail when absent, empty, skipped or blocked; never relabel them as passed. Remote suites (sql, api, e2e) mutate data and need a non-production environment listed in `mutationAllowedEnvironments` plus a user test grant. Application-only page changes are verified by the compiler, their read-only source queries and the browser; do not install utPLSQL or add empty suites just to import a page. Changing an established required-suite scope needs user authorization.
+
+Evidence. Separate implemented code, fixture results, real Oracle results and browser observations. Report blockers with their fault code and `nextActions`; never describe a partial or unverified change as complete. Secrets never travel through chat, tool input or evidence.

package/dist/codex-compat/plugins/apexrest-apex/skills/apexrest-safety/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Safety policy'
+  short_description: 'Deployment, test and recovery rules for APEX changes'
+  default_prompt: 'Use $apexrest-safety to explain what blocked my APEX deployment or test and what is allowed next.'

package/dist/codex-compat/plugins/apexrest-apex/skills/apexrest-setup/SKILL.md

@@ -1,15 +1,25 @@
 ---
 name: apexrest-setup
-description: Set up APEXREST for Codex, diagnose local toolchain capabilities and guide connection onboarding. Use for APEXREST setup or missing runtime tools.
+description: Check and set up the APEXREST toolchain and connections - doctor, Node/Java/SQLcl/Playwright dependencies, SQLcl mode and ORDS transport, connection references and the project status snapshot. Use for setup, missing tools or connection onboarding.
 ---
 
-Pass the user's absolute workspace as `project` on project-scoped calls.
-Call apexrest_doctor first. Distinguish detected tools, validated compiler, installed native plugin and database connectivity.
-The doctor's `sqlcl.mode` selects the Oracle backend: `cli` invokes SQLcl directly; `mcp` invokes the official SQLcl stdio server (`sql -mcp`). This is independent of the APEXREST MCP interface exposed to Codex. Use the TUI's **SQLcl mode: CLI / MCP** action or the bundled CLI `sqlcl configure --mode cli|mcp`; `sqlcl status --json` reads the saved choice. Resolve `../../runtime/apexrest.mjs` from this skill directory and invoke it with Node when no launcher is on PATH. The choice is saved under the active `APEXREST_HOME` and applies to new Oracle operations without reinstalling the plugin. Preserve the selected backend; never silently retry through the other backend after failure. MCP restrict level 4 is the default; use `--mcp-restrict-level 1` only when the user requests script execution. Connected Oracle MCP operations may write Oracle's own `DBTOOLS$MCP_LOG`; do not call them strictly read-only database activity. Keep application imports in the existing plan/apply workflow in both modes.
-Run the bundled installer only under the host's approved filesystem/network scope. Never change host trust or copy login tokens.
-Request connection references through local onboarding; never ask for passwords in chat.
-If a dependency is missing, use [Install dependencies](../apexrest-install-dependencies/SKILL.md) and the bundled `dependencies install` command. This installs the client toolchain without reinstalling the native plugin. Reserve `setup` for bootstrap plus native registration. No download runs during MCP startup.
-An existing clean supported APEX installation is sufficient for ordinary deployment. APEXREST service tables and utPLSQL are not client/deploy setup prerequisites. Local deployment history/coordination is the default; utPLSQL is needed only for SQL suites, and database control tables only for the explicitly selected optional database mode.
-After reinstall, use a new Codex thread. A saved JSON file does not prove host discovery or readiness.
+# Setup
 
-For `sqlcl.databaseTransport: ords`, read [ORDS setup](references/ords.md) before connection or transport changes; never silently switch transport or send passwords through chat/MCP.
+Call `apexrest_status` `detail:doctor` first. It probes SQLcl and Java; Codex availability is informational for Claude Code without downloads or database calls and reports `sqlcl.mode` (`cli` direct SQLcl, `mcp` the official SQLcl stdio server) and `databaseTransport` (`direct` or `ords`). A detected tool is not a validated compiler or a live connection; say which was observed.
+
+Dependencies. Missing SQLcl or Java is a reason to install, not to stop. Use the bundled CLI at `../../runtime/apexrest.mjs` relative to this skill directory, resolved to an absolute path and run with `node` from the user's project directory (native installation adds nothing to PATH):
+
+```sh
+node "<plugin-root>/runtime/apexrest.mjs" dependencies install --dry-run --json
+node "<plugin-root>/runtime/apexrest.mjs" dependencies install --yes --json
+```
+
+Preview first and summarize versions, destinations and license requirements. Add `--accept-oracle-license` only after the user accepted the Oracle terms linked in the preview; `--skip-browser` omits Playwright/Chromium; `--install-os-deps` needs explicit authorization. Use the pinned lockfile versions only. Rerun the doctor afterwards; with a custom `--home`, set `APEXREST_HOME` for the CLI and the MCP process.
+
+SQLcl backend. `apexrest sqlcl configure --mode cli|mcp --database-transport direct|ords --json`; `sqlcl status --json` reads it. ORDS requires `cli` mode and plugin-level connection credentials ([ORDS notes](references/ords.md)). Never silently retry through the other backend or transport.
+
+Connections. `apexrest_project` `action:connection_add` with `name` plus either `sqlclName` (saved SQLcl connection) or `ordsUrl` and `ordsUsername` with `passwordFile` (a private local file). `action:connection_list` and `action:connection_test` check references. Never ask for or relay passwords in chat; each environment in `apexrest.json` needs `readConnectionRef` and `deployConnectionRef`, the workspace, parsing schema, application ID, base URL and database identity. Ask only for missing non-secret values; never infer production.
+
+Project status. `apexrest_status` `detail:project` returns one read-only snapshot: configuration, SQLcl settings, connection references without secrets, browser preference (`.apexrest/panel/preferences.json`, `browserMode: codex|external`), Git changes, sync state, recent jobs and deployments, and active grants. `trusted: false` or `configured: false` are findings; trust is granted by the user in `APEXREST_HOME/policy.json`.
+
+A clean supported APEX installation is enough: APEXREST service tables and utPLSQL are not prerequisites. After reinstalling the plugin, start a new host session. Implementation continues in [work](../apexrest-work/SKILL.md).

package/dist/codex-compat/plugins/apexrest-apex/skills/apexrest-setup/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "Setup and connections"
-  short_description: "Check tools and manage local connection references"
-  default_prompt: "Use $apexrest-setup. Check my APEXREST setup and show the connection and toolchain actions available."
+  display_name: 'Setup and connections'
+  short_description: 'Check tools, install dependencies and manage connection references'
+  default_prompt: 'Use $apexrest-setup. Check my APEXREST setup and show the connection and toolchain actions available.'

package/dist/codex-compat/plugins/apexrest-apex/skills/apexrest-work/SKILL.md

@@ -1,14 +1,19 @@
 ---
 name: apexrest-work
-description: Complete Oracle APEX changes directly in the current Codex chat. Excludes setup, reference questions and Salesforce Apex.
+description: Create or change an Oracle APEX application end to end - project, references, APEXlang edits, compiler validation, shipping to a dev/test environment and browser verification. Use for any APEX build or change request. Excludes Salesforce Apex.
 ---
 
 # APEX work
 
-Work directly in the user's current Codex session. Preserve its task, context, model, permissions and read-only constraints. Resolve the absolute application project containing `apexrest.json`; reuse known project settings or call `apexrest_project_inspect` with `detail: "summary"` when needed. No plugin task registration or startup call is required. Configured target identity is not live verification.
+Work in the current host session (Codex or Claude Code). Every project-scoped tool takes `project`: the absolute directory containing `apexrest.json`, never the plugin directory.
 
-Read relevant source and focused reference matches; follow offsets/contracts when needed. Reuse discovery until its inputs change, batch coherent edits and independent reads, and run relevant checks once per change. Broaden checks only for a failure or unresolved risk. Long MCP tools wait up to 25 seconds automatically. For completed jobs, inspect `data.result.ok` and actual checks; completion alone is not success. For queued/running jobs, use `apexrest_job_status` with the existing ID and `waitSeconds: 25`. Never rerun an operation to retrieve output. Read full artifacts only for omitted details needed to proceed; reconcile uncertain writes before retrying.
+1. Project. New app: `apexrest_project` `action:init` with `directory` and `template` (`blank-app` or `customer-crm`); it generates real Oracle sources, no separate generate call. Existing app: `action:inspect` (summary) for source directories and environments; `apexrest_apex_sync` `action:status` shows a working copy.
+2. References, at most 3 lookups per change: `apexrest_reference` `mode:search` with short English terms, `kind` and `limit:3`, then `mode:read` the chosen ID. Routes and contracts: [apexlang](../apexrest-apexlang/SKILL.md).
+3. Edit `.apx` files under the application source directory. Keep `.apex/apexlang.json`, Oracle IDs, authentication and authorization. Edit related components together; never leave placeholders.
+4. `apexrest_apex_validate` until `diagnostics` is empty: fix the named file and line, rerun. Never ship with errors.
+5. `apexrest_ship` `mode:plan` with `env` and `userRequest` (the user's literal instruction). Review `risks`, `sources` and `target`.
+6. `apexrest_ship` `mode:apply` with the same `userRequest` when the user asked for the change in that dev/test environment. That explicit request to create, update or import an identified dev/test app is the authorization: do not ask again. The runtime records a grant bound to this plan and removes it afterwards. Wait for the result (`waitSeconds` default 25); if still running, `apexrest_job` `action:status` with the returned `jobId`. Never rerun ship to fetch results.
+7. Verify visibly changed pages: `apexrest_browser_open` for `env`, then open the returned URL with the selected browser's controls (`codex` host browser or `external` system browser). Check rendering, navigation and the changed interaction; opening a page is not verification.
+8. Report files changed, validation result, ship status and runId, pages verified in the browser, and anything not verified with its reason.
 
-For visible changes, call `apexrest_browser_open` for the configured environment and honor the returned browser preference; follow [browser verification](../apexrest-test/SKILL.md#in-app-browser-verification). A URL is not verified behavior; report missing controls/login. Open the [development panel](../apexrest-panel/SKILL.md) only when useful or requested.
-
-An identified authorized application import follows [deploy](../apexrest-deploy/SKILL.md): fresh target checks, backup, source/target drift, plan/apply and runtime verification remain required. Preserve required suites and unknown-outcome recovery. Report actual changes, checks and limitations in this conversation. No broader DB changes, downloads, publication or external messages are implied.
+Blocked, failed or unknown outcomes: [safety](../apexrest-safety/SKILL.md). Missing tools or connections: [setup](../apexrest-setup/SKILL.md).

package/dist/codex-compat/plugins/apexrest-apex/skills/apexrest-work/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
-  display_name: 'APEX work from chat'
-  short_description: 'Complete APEX changes directly in this Codex session'
-  default_prompt: 'Use $apexrest-work to complete my Oracle APEX change directly in this Codex session using my project and browser settings; report actual results here.'
+  display_name: 'APEX work'
+  short_description: 'Build or change an Oracle APEX application in this session'
+  default_prompt: 'Use $apexrest-work to build or change my Oracle APEX application in this session using my project settings; report actual results here.'
 
 policy:
   allow_implicit_invocation: true

package/dist/resources/blocks/evidence/block%3Aanalytics%2Fstatus-summary%401.0.0.json

@@ -0,0 +1,19 @@
+[
+  {
+    "schemaVersion": 1,
+    "kind": "compiler",
+    "status": "passed",
+    "sourceDigest": "a38b31d68964a3175d17af8598b81c6d2c0d90f4143cc33c4f6c94febc913d3f",
+    "generatorDigest": "b6664f483ba51882e81ccb44bccbd2f99d8b94f74ce58f5bb10297209fa7c196",
+    "configurationDigest": "4b5d1204a620cea10ca6e8253e7e68dd9677d9be73bacac4271126898ce95400",
+    "fixtureDigest": "e81e5fdbbf8203d148e3c70e958cd40b14ccc95de6541b60b000d2d7a195959c",
+    "profile": "profile:apex261-ut261-mmd3102",
+    "tool": "SQLcl: Release 26.1.2.0 Production Build: 26.1.2.132.1334; MMD 26.1.0+3102",
+    "runner": "local",
+    "timestamp": "2026-09-29T17:58:15.026524+00:00",
+    "artifacts": [
+      "docs/evidence/composer-local.json"
+    ],
+    "reason": "Real offline SQLcl validation of complete crm fixture containing this block. No live SQL, import, DML or browser qualification."
+  }
+]

package/dist/resources/blocks/evidence/block%3Acrud%2Freport-dialog%401.0.0.json

@@ -0,0 +1,19 @@
+[
+  {
+    "schemaVersion": 1,
+    "kind": "compiler",
+    "status": "passed",
+    "sourceDigest": "3f22afdd45513ac6819f0be2562a3525f5971265cd4de22f183c607d3ced2431",
+    "generatorDigest": "b6664f483ba51882e81ccb44bccbd2f99d8b94f74ce58f5bb10297209fa7c196",
+    "configurationDigest": "4b5d1204a620cea10ca6e8253e7e68dd9677d9be73bacac4271126898ce95400",
+    "fixtureDigest": "e81e5fdbbf8203d148e3c70e958cd40b14ccc95de6541b60b000d2d7a195959c",
+    "profile": "profile:apex261-ut261-mmd3102",
+    "tool": "SQLcl: Release 26.1.2.0 Production Build: 26.1.2.132.1334; MMD 26.1.0+3102",
+    "runner": "local",
+    "timestamp": "2026-09-29T17:58:15.028028+00:00",
+    "artifacts": [
+      "docs/evidence/composer-local.json"
+    ],
+    "reason": "Real offline SQLcl validation of complete crm fixture containing this block. No live SQL, import, DML or browser qualification."
+  }
+]

package/dist/resources/blocks/evidence/block%3Aread%2Fdetail%401.0.0.json

@@ -0,0 +1,19 @@
+[
+  {
+    "schemaVersion": 1,
+    "kind": "compiler",
+    "status": "passed",
+    "sourceDigest": "fd38f4d780ae0a9af3b77e9375ebd26f86391092505c55bd5a16090eb662f7e6",
+    "generatorDigest": "b6664f483ba51882e81ccb44bccbd2f99d8b94f74ce58f5bb10297209fa7c196",
+    "configurationDigest": "4b5d1204a620cea10ca6e8253e7e68dd9677d9be73bacac4271126898ce95400",
+    "fixtureDigest": "83171baefa7b1cf5cbab5bd9d63b95dc5ae56223626e30175a27c4136eb19ff9",
+    "profile": "profile:apex261-ut261-mmd3102",
+    "tool": "SQLcl: Release 26.1.2.0 Production Build: 26.1.2.132.1334; MMD 26.1.0+3102",
+    "runner": "local",
+    "timestamp": "2026-09-29T17:58:15.027755+00:00",
+    "artifacts": [
+      "docs/evidence/composer-local.json"
+    ],
+    "reason": "Real offline SQLcl validation of complete library fixture containing this block. No live SQL, import, DML or browser qualification."
+  }
+]

package/dist/resources/blocks/evidence/block%3Aread%2Ffiltered-list%401.0.0.json

@@ -0,0 +1,19 @@
+[
+  {
+    "schemaVersion": 1,
+    "kind": "compiler",
+    "status": "passed",
+    "sourceDigest": "fec688afd7be366569f71dac270d619fb813ccb7d99b218450f4e5da80fa21f9",
+    "generatorDigest": "b6664f483ba51882e81ccb44bccbd2f99d8b94f74ce58f5bb10297209fa7c196",
+    "configurationDigest": "4b5d1204a620cea10ca6e8253e7e68dd9677d9be73bacac4271126898ce95400",
+    "fixtureDigest": "83171baefa7b1cf5cbab5bd9d63b95dc5ae56223626e30175a27c4136eb19ff9",
+    "profile": "profile:apex261-ut261-mmd3102",
+    "tool": "SQLcl: Release 26.1.2.0 Production Build: 26.1.2.132.1334; MMD 26.1.0+3102",
+    "runner": "local",
+    "timestamp": "2026-09-29T17:58:15.027399+00:00",
+    "artifacts": [
+      "docs/evidence/composer-local.json"
+    ],
+    "reason": "Real offline SQLcl validation of complete library fixture containing this block. No live SQL, import, DML or browser qualification."
+  }
+]