add APEX administration skills

.gitignore

@@ -1 +1,2 @@
 .claude/settings.local.json
+apex/PRIVATE_NOTES_APEX_SKILLS.md

README.md

@@ -9,6 +9,7 @@ The goal is to give developers and agents a single place to find source-backed O
 Install a domain by appending the root-level domain directory to the repository name:
 
 ```bash
+npx skills add oracle/skills/apex
 npx skills add oracle/skills/db
 npx skills add oracle/skills/graal
 ...
@@ -26,7 +27,7 @@ npx skills add oracle/skills/graal
 - `db/` is the active Oracle Database domain and includes database, ORDS, SQLcl, framework, container, and agent workflow skills.
 - `oci/` is the root for future Oracle Cloud Infrastructure skills.
 - `fusion/` is the root for future Oracle Fusion skills.
-- `apex/` is the root for future Oracle APEX skills.
+- `apex/` contains Oracle APEX skills, starting with workspace provisioning and administration. The APEX root skill is token-optimized: it keeps `apex/SKILL.md` concise, routes to topic files on demand, and includes token-use rules to avoid loading whole categories unnecessarily.
 - `graal/` contains GraalVM skills, starting with Native Image.
 
 ## Start Here
@@ -61,7 +62,12 @@ npx skills add oracle/skills/graal
 ├── fusion/
 │   └── SKILL.md
 ├── apex/
-│   └── SKILL.md
+│   ├── SKILL.md
+│   └── deployment/
+│   └── monitoring/
+│   └── security/
+│   └── workspace/
+│   └── test-apex-skills.sh
 ├── graal/
 │   ├── SKILL.md
 │   └── native-image/

apex/SKILL.md

@@ -1,5 +1,77 @@
+---
+name: apex
+description: Oracle APEX skills for workspace administration, application development, deployment, monitoring, and source-backed operational workflows.
+---
+
 # Oracle APEX Skills
 
-This file is a sample domain skeleton.
+Only the root `apex/SKILL.md` is a skill entry point. Category folders contain topic `.md` files; read only the specific topic needed for the request.
+
+## Token Use
+
+- Load one routed topic first; add a second topic only when the workflow crosses that boundary.
+- Use `rg`/section search for exact checks instead of reading whole categories.
+- Load `apex/security/safety-messages.md` only when an exact user-facing message is needed.
+- For SQL examples, prefer the smallest relevant snippet from the topic file.
+
+## Routing
+
+- Workspace lifecycle/provisioning/listing/removal: `apex/workspace/lifecycle.md`, `apex/workspace/resource-governance.md`, `apex/workspace/users-and-auth.md`, `apex/workspace/schema-mapping.md`, `apex/workspace/removal.md`, `apex/workspace/version-notes.md`, `apex/workspace/security-review.md`
+- Security/auth/session/export safety: `apex/security/guardrails.md`, `apex/security/safety-messages.md`, `apex/security/audit-columns.md`, `apex/security/security-review.md`
+- Monitoring/runtime diagnosis/MCP availability: `apex/monitoring/activity-log.md`, `apex/monitoring/error-handling.md`, `apex/monitoring/user-journey-replay.md`, `apex/monitoring/background-jobs.md`, `apex/monitoring/rest-data-sources.md`, `apex/monitoring/page-performance.md`, `apex/monitoring/ir-ig-tuning.md`, `apex/monitoring/awr-wait-correlation.md`, `apex/monitoring/mcp-availability.md`, `apex/monitoring/security-review.md`
+- Deployment/export/import/patching: `apex/deployment/pre-check.md`, `apex/deployment/export-review.md`, `apex/deployment/import-promotion.md`, `apex/deployment/post-deploy-validation.md`, `apex/deployment/patching.md`, `apex/deployment/security-review.md`
+
+## Scope
+
+Keep APEX skills APEX-specific. Before adding or expanding an APEX skill, check whether the generic database topic is already covered under `db/`.
+
+Use APEX skills for APEX workspaces, applications, App Builder, runtime behavior, session state, APEX activity/debug logs, APEX users, Team Development, supported `APEX_*` views, and APEX APIs such as `APEX_UTIL`, `APEX_INSTANCE_ADMIN`, and `APEX_APPLICATION_INSTALL`.
+
+Do not duplicate generic database guidance in APEX skills. Privilege management, auditing, encryption, network security, data masking, VPD/RLS, AWR, ASH, wait events, SQL tuning, SQLcl basics, and ORDS fundamentals belong in `db/`.
+
+When using a generic DB skill, announce it with `DB skill in use: db/...`, for example:
+
+```text
+DB skill in use: db/performance/wait-events.md for the generic wait-event analysis. The APEX skill is being used for APEX activity-log correlation.
+```
+
+## Safety
+
+- Use least privilege for parsing schemas, workspace users, database-login users, and automation accounts. Do not recommend broad grants such as `DBA`, `SYSDBA`, `SELECT ANY TABLE`, `EXECUTE ANY PROCEDURE`, `CREATE ANY TABLE`, `GRANT ANY ROLE`, `GRANT ANY PRIVILEGE`, or `WITH ADMIN OPTION` unless the user explicitly asks for privileged administration and the risk is called out.
+- Keep APEX security contexts separate: workspace administrator, developer, end user, parsing schema, database-login user, ORDS/APEX runtime account, and DBA/admin account are different roles.
+- Do not treat APEX parsing schemas as personal interactive logins in production.
+- Prefer supported APEX APIs and views. Do not write directly to internal APEX repository tables.
+- Treat versions and managed environments as variable. Inspect availability with `ALL_TAB_COLUMNS`, `ALL_ARGUMENTS`, `DESC`, `APEX_RELEASE`, or `APEX_DICTIONARY` before relying on version-specific columns or package signatures.
+- Protect destructive actions with object listings, fresh exact English confirmation prompts, protected-account checks, and no remembered-context assumptions. Workspace-related database users may be dropped only when the user explicitly asks to remove the workspace and its listed related database users/components and confirms that this is their own will. Load `apex/workspace/removal.md`.
+- After interrupted APEX provisioning, reconnect, inventory each planned artifact individually, and ask whether to roll back only the listed artifacts before retrying or continuing. Load `apex/monitoring/mcp-availability.md` and `apex/workspace/lifecycle.md`.
+- Before APEX workflows that use MCP database access, run the APEX MCP availability guard. If MCP reports `Transport closed` or an unavailable tool channel, stop and do not continue from stale database state.
+- Never include real secrets in skills, examples, logs, exports, or chat output.
+- Treat APEX activity logs, debug logs, error messages, request values, Team Development files, exports, and session context as potentially sensitive.
+- Do not treat APEX session state, hidden items, read-only items, or client-side checks as a security boundary.
+- For tenant isolation or sensitive row access, APEX authorization can help the UI, but critical data isolation belongs in the database. Hand off implementation details to `db/security/row-level-security.md`.
+- APEX exports may contain application logic, URLs, authorization schemes, build options, static files, credential references, defaults, and other sensitive metadata.
+- For APEX-owned application tables, include safe audit columns when appropriate: `created_at`, `created_by`, `updated_at`, `updated_by`. Audit-column triggers should use APEX user context with a database-user fallback, not only `USER`; for database auditing, announce and use `db/security/auditing.md`.
+- Mark licensed features and production constraints, especially AWR/ASH/Diagnostics Pack and database security options whose licensing depends on deployment.
+- End substantial APEX skill additions with a security review covering privileges, secrets, auditability, data exposure, version/cloud restrictions, and destructive actions.
+
+## Documentation
+
+Use official Oracle APEX documentation and prefer the newest available documentation unless the user names a specific installed APEX version. Start from:
+
+```text
+https://apex.oracle.com/en/learn/documentation/
+```
+
+Do not hard-code older APEX documentation URLs unless the guidance is explicitly about that older version.
+
+## Safety Messages
+
+For exact user-facing safety messages, load `apex/security/safety-messages.md`. Use it for broad grants, direct internal repository writes, destructive changes, interrupted provisioning recovery, sensitive logs/exports, session-state assumptions, audit triggers, version-sensitive APEX views, or unavailable MCP-backed database access.
+
+## Validation
+
+Run after changing APEX skills:
 
-For the repo-wide structure and authoring pattern, read the root `README.md` and `SKILL_AUTHORING_GUIDE.md`.
+```bash
+bash apex/test-apex-skills.sh
+```

apex/deployment/export-review.md

@@ -0,0 +1,21 @@
+# APEX Export Review
+
+APEX exports can contain sensitive metadata: URLs, authorization schemes, build options, substitution strings, static files, credential references, REST endpoints, defaults, install scripts, and business logic. Review before commit, sharing, or import.
+
+Use App Builder export or SQLcl APEX export workflows, but keep generic SQLcl syntax and CI/CD mechanics in the SQLcl DB skills.
+
+## Review Checklist
+
+- Application ID and alias are intentional for the target environment.
+- Workspace and parsing schema mapping are explicit.
+- Build options match the target environment.
+- Substitution strings do not include real secrets or production-only endpoints unless intentionally deployed.
+- Static files and supporting objects do not embed tokens, passwords, private URLs, or customer data.
+- Authentication and authorization schemes are correct for the target environment.
+- Web Credentials are referenced safely; secret values are not printed, committed, or copied into examples.
+- REST Data Sources and remote server URLs are environment-aware.
+- No real passwords, tokens, OAuth secrets, SMTP credentials, wallet passwords, web credential values, or secret-bearing URLs appear in exports, scripts, examples, logs, or chat output.
+
+## DB Skill Usage
+
+DB skill in use: `db/security/encryption.md`, `db/security/network-security.md`, or `db/security/privilege-management.md` for generic secret storage, TLS/network, and privilege implementation. The APEX deployment skill is being used for APEX export and credential-reference review.

apex/deployment/import-promotion.md

@@ -0,0 +1,51 @@
+# APEX Import And Promotion
+
+Use `APEX_APPLICATION_INSTALL` when the import needs deterministic workspace, application ID, offset, alias, proxy, image prefix, or schema settings. Keep these calls in the import wrapper, not scattered through application code.
+
+Version check: inspect `ALL_ARGUMENTS` for `APEX_APPLICATION_INSTALL` in the target APEX release before using version-specific procedures or parameters.
+
+```sql
+BEGIN
+    APEX_APPLICATION_INSTALL.SET_WORKSPACE(:target_workspace);
+    APEX_APPLICATION_INSTALL.SET_APPLICATION_ID(:target_application_id);
+    APEX_APPLICATION_INSTALL.SET_SCHEMA(:target_parsing_schema);
+    APEX_APPLICATION_INSTALL.SET_APPLICATION_ALIAS(:target_application_alias);
+END;
+/
+```
+
+Check package arguments in the target APEX version before using less common procedures or parameters. Do not assume every APEX release supports the same install API shape.
+
+## Replace Safety
+
+For replace imports, list the existing target application and workspace before import and require explicit confirmation for production:
+
+```sql
+SELECT workspace,
+       application_id,
+       application_name,
+       alias,
+       owner,
+       last_updated_on
+FROM apex_applications
+WHERE application_id = :target_application_id
+   OR UPPER(alias) = UPPER(:target_application_alias)
+ORDER BY workspace,
+         application_id;
+```
+
+Treat these as destructive or high-risk:
+
+- Replace an existing application in production.
+- Run supporting objects that drop or truncate tables.
+- Delete or rotate APEX Web Credentials.
+- Change authentication or authorization schemes.
+- Change parsing schema mapping.
+- Remove static files used by deployed pages.
+- Import into a different workspace than expected.
+
+Safety stop: list affected workspace, application, parsing schema, authentication scheme, authorization schemes, credentials, and supporting objects. Require explicit confirmation before generating or running replace, delete, or destructive supporting-object steps.
+
+## DB Skill Usage
+
+DB skill in use: `db/devops/schema-migrations.md` and `db/devops/version-control-sql.md` for generic schema migration and release governance. The APEX deployment skill is being used for APEX application artifact promotion and environment mapping.

apex/deployment/patching.md

@@ -0,0 +1,140 @@
+# APEX Patch Set Bundle Workflow
+
+Use this topic for Oracle APEX Patch Set Bundle status checks and patch planning. Patch availability is time-sensitive, so verify the latest patch number, patch version, README, and known issues from Oracle before giving exact patch instructions.
+
+Use this for self-managed or co-managed environments. For fully managed Autonomous Database or APEX Application Development Service, Oracle normally applies APEX patch bundles; do not advise manual patching unless the service documentation says patching is customer-managed.
+
+## Version And View Availability
+
+Check APEX version first:
+
+```sql
+SELECT version_no
+FROM apex_release;
+```
+
+Check whether `APEX_PATCHES` is available and which columns exist before querying patch rows:
+
+```sql
+SELECT table_name,
+       column_id,
+       column_name,
+       data_type
+FROM all_tab_columns
+WHERE table_name = 'APEX_PATCHES'
+ORDER BY column_id;
+```
+
+Then query installed patch rows:
+
+```sql
+SELECT patch_number,
+       patch_version,
+       installed_on
+FROM apex_patches
+ORDER BY installed_on;
+```
+
+If `APEX_PATCHES` returns no rows, that only means no patch rows are recorded in that view for the current APEX installation. It does not prove that the system is unsupported or broken. Compare `APEX_RELEASE.VERSION_NO` with the latest official APEX release and patch bundle information.
+
+## Find The Latest Patch Bundle
+
+Before recommending a patch number:
+
+- Check the Oracle APEX Downloads and Known Issues page.
+- Check My Oracle Support for the target APEX release.
+- Read the patch README included in the downloaded patch bundle.
+- Confirm whether the patch applies to the exact installed APEX base release.
+
+As of May 11, 2026, Oracle's APEX downloads page lists Patch Set Bundle for Oracle APEX 24.2 as patch `37366599`, last updated April 30, 2026, with `PATCH_VERSION` 16. Oracle states that applying it updates the APEX product version to `24.2.16`. Treat this as a dated reference point, not a permanent rule.
+
+## High-Level Patch Flow
+
+Follow the patch README for exact commands. Use this as the operational checklist:
+
+1. Confirm target PDB and installed APEX version.
+2. Query `APEX_PATCHES`.
+3. Download the matching APEX Patch Set Bundle from My Oracle Support.
+4. Read the patch README completely.
+5. Back up the database/PDB and export critical APEX applications.
+6. Stop ORDS or put APEX behind maintenance if the README or local policy requires it.
+7. Unzip the patch on the database host or approved deployment host.
+8. Connect to the PDB where APEX is installed with the required administrative privileges, typically `SYS AS SYSDBA` when the README requires it.
+9. Run the patch script from the extracted patch directory exactly as documented.
+10. Recompile invalid objects.
+11. Update APEX static files, or set the image prefix to the matching Oracle CDN path when CDN images are used.
+12. Restart or reload ORDS.
+13. Verify APEX version, patch rows, invalid objects, App Builder, application runtime, and static resources.
+
+## Post-Patch Verification
+
+```sql
+SELECT version_no
+FROM apex_release;
+```
+
+```sql
+SELECT patch_number,
+       patch_version,
+       installed_on
+FROM apex_patches
+ORDER BY installed_on;
+```
+
+```sql
+SELECT owner,
+       object_type,
+       COUNT(*) AS invalid_objects
+FROM dba_objects
+WHERE status = 'INVALID'
+  AND owner LIKE 'APEX\_%' ESCAPE ''
+GROUP BY owner, object_type
+ORDER BY owner, object_type;
+```
+
+Also verify:
+
+- APEX Administration Services opens.
+- At least one workspace can sign in.
+- App Builder opens without JavaScript/CSS errors.
+- A representative runtime application works.
+- Browser developer tools show no missing `/i/` static resources.
+- ORDS logs have no new APEX static-resource or pool errors.
+
+## Static Files And CDN
+
+APEX patches can require static file updates. The database APEX version and the served image files must match.
+
+If using local images:
+
+- Copy the patched `images` directory according to the README.
+- Confirm ORDS or the web server serves the updated `/i/` path.
+
+If using Oracle CDN:
+
+- Confirm the known-issues/downloads page lists a CDN URL for the exact patched APEX version.
+- Set the image prefix only to the matching version path.
+- Test App Builder and runtime pages for missing assets.
+
+## Autonomous And Managed Services
+
+For Autonomous Database and APEX Application Development Service:
+
+- Check `APEX_RELEASE` and `APEX_PATCHES`.
+- Report the observed version and patch rows.
+- Do not instruct the user to manually download and apply a patch bundle unless Oracle service documentation explicitly says that patching is customer-managed.
+- If the environment is behind the latest published patch, advise checking the service maintenance schedule or opening an Oracle Support service request.
+
+## DB Skill Usage
+
+DB skill in use: `db/admin/backup-recovery.md` for generic database backup and restore planning. The APEX deployment skill is being used for APEX patch-bundle workflow context.
+
+DB skill in use: `db/ords/ords-monitoring.md` for generic ORDS runtime checks. The APEX deployment skill is being used for APEX static-file and App Builder verification context.
+
+## Guardrails
+
+- Do not treat `APEX_PATCHES` with no rows as proof that the newest patch is missing.
+- Do not apply a patch bundle to the wrong APEX base version.
+- Do not run patch scripts in `CDB$ROOT` unless the patch README explicitly instructs it.
+- Do not forget to update static files or CDN image prefix.
+- Do not give a hard-coded latest patch number without checking Oracle first.

apex/deployment/post-deploy-validation.md

@@ -0,0 +1,22 @@
+# APEX Post-Deploy Validation
+
+Validate APEX-specific behavior after import.
+
+## Validation Checklist
+
+- Application exists in the expected workspace with the expected ID, alias, owner, and parsing schema.
+- Build options and substitution strings match target environment policy.
+- Authentication and authorization schemes work for Workspace Admin, Developer, End User, parsing schema, database-login user, ORDS/APEX runtime account, and DBA/admin account boundaries.
+- REST Data Sources and Web Credentials resolve without exposing secret values.
+- Critical pages compile and run with expected authorization and session-state protection.
+- Supporting objects ran only when intended and did not perform surprise destructive work.
+- APEX activity/debug/error logs are free of deployment-time secret leakage.
+
+## Security Review
+
+- Privileges remain least-privilege.
+- No broad grants such as `DBA`, `SELECT ANY TABLE`, `EXECUTE ANY PROCEDURE`, `CREATE ANY TABLE`, `GRANT ANY ROLE`, or `GRANT ANY PRIVILEGE` were introduced for ordinary APEX deployment.
+- APEX session state, hidden items, read-only items, and client-side checks are not treated as security boundaries.
+- Any database auditing requirement is handled by the DB auditing skill.
+
+DB skill in use: `db/security/auditing.md` for generic database audit policy and evidence handling. The APEX deployment skill is being used for APEX release traceability and post-import validation context.