plsqlwks 0.2.0__tar.gz → 0.2.1__tar.gz

{plsqlwks-0.2.0 → plsqlwks-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plsqlwks
-Version: 0.2.0
+Version: 0.2.1
 Summary: An ncurses SQL and PL/SQL workspace for Oracle databases.
 Author: unu2000
 License-Expression: LicenseRef-plsqlwks-Donationware
@@ -98,6 +98,55 @@ protect it with `chmod 600`.
 `PLSQLWKS_ARRAYSIZE` sets the Oracle cursor array size. Both values must be
 positive integers.
 
+### Oracle Thin and Thick modes
+
+Thin mode is the default and needs no Oracle Client installation. To use an
+installed Oracle Client, start with `plsqlwks --thick`. Use `plsqlwks --thin` to
+override a workspace's thick preference for one invocation. The flags are
+mutually exclusive and are never saved to configuration.
+
+For a persistent preference, edit the selected workspace's `config.ini` (or the
+platform configuration file when using the default workspace):
+
+```ini
+[database]
+thick_mode = no
+oracle_client_lib_dir =
+oracle_client_config_dir =
+```
+
+Set `thick_mode = yes` to enable Thick mode. Invalid boolean values are errors.
+Both optional directories expand `~`; relative paths are resolved from the
+configuration file's directory. Blank values use Oracle's normal discovery.
+The directory settings are used only in Thick mode. All tabs and reconnects
+share one driver mode; restart after changing mode or client settings.
+
+Install an Oracle Instant Client **Basic** or **Basic Light** package compatible
+with your Python architecture, python-oracledb version, and database. Libraries
+are installed separately and are not bundled with PLSQLWKS. On Linux, normally
+leave `oracle_client_lib_dir` blank and configure `ldconfig` or `LD_LIBRARY_PATH`
+**before** launching Python. Setting that directory alone does not configure
+Linux's dependent-library search path. On macOS, an explicit library directory
+can be useful. When running through SSH or WSL, install the libraries where the
+Python process runs. For a full Oracle Client installation, configure its
+Oracle environment before launch.
+
+`oracle_client_config_dir` selects the directory containing Oracle network
+configuration such as `sqlnet.ora` and `tnsnames.ora`; when blank, Oracle uses
+its normal lookup, including `TNS_ADMIN`. Native network encryption is configured
+through Oracle Client's `sqlnet.ora` and the server's matching requirements.
+The existing `ORACLE_USER`, `ORACLE_DSN`, and password-file authentication remain
+in use. See the [Oracle Client initialization guide](https://python-oracledb.readthedocs.io/en/v3.4.2/user_guide/initialization.html)
+for platform setup and the [compatibility contract](doc/COMPATIBILITY.md) for
+validated combinations.
+
+Client-loading failures such as `DPI-1047` stop startup before the terminal UI,
+with no automatic fallback. Check library architecture, required system
+libraries, and the pre-launch library search path. Mode conflicts or changed
+initialization arguments require a process restart. Successful connection status
+includes `Thin mode` or `Thick mode`. Help, version, and plugin management commands
+do not initialize Oracle Client libraries.
+
 ## Install
 
 Python 3.10 or newer is required, along with a compatible terminal and a Python
@@ -850,12 +899,11 @@ period; DATE and TIMESTAMP input uses ISO
 Character and CLOB input is preserved as entered. Types that cannot be compared
 without losing information, including time-zone timestamps and timestamps with
 precision above six, are read-only in the grid.
-In python-oracledb Thin mode, non-null `TIMESTAMP WITH TIME ZONE` and
-`TIMESTAMP WITH LOCAL TIME ZONE` values are shown and exported as explicit
-lossless-fetch-unavailable markers instead of misleading naive datetimes. Use
-an explicit `TO_CHAR` expression with the required precision and zone fields
-when the exact value is needed; named-zone timestamps are not supported by the
-current Thin driver.
+In both driver modes, ordinary SELECT/WITH queries format zoned timestamps on
+Oracle to preserve their zone and fractional precision. Query forms that cannot
+use this projection show explicit lossless-fetch-unavailable markers for
+non-null zoned values on the native fetch path. Use an explicit `TO_CHAR`
+expression with the required precision and zone fields for those query forms.
 Displayed CLOB and BLOB values are limited to the first 65,536 characters or
 bytes and include a truncation marker with the full size. Truncated LOB cells
 cannot be edited safely. Schema-browser DDL is always read in full.
@@ -1136,6 +1184,18 @@ lifecycle change requires a restart. See the
 [managed-package guide](https://gitlab.com/unununu/plsqlwks/-/blob/main/doc/PLUGINS.md#managed-plugin-packages)
 for the exact manifest, source layout, validation, replacement, and trust rules.
 
+### Table DDL Export
+
+Install `plugins/packages/table-ddl-export-0.1.1.plwgn` with
+`plsqlwks plugin install` and restart. **Alt-O -> Database -> Export table DDL**
+lets you choose a schema, filter table names as you type, select tables, and
+optionally remap them to another schema. It automatically includes related
+sequences and directly referencing packages, functions, procedures, and views, and follows
+required source-schema tables and views recursively. Definitions, constraints, indexes,
+foreign keys and triggers are ordered by creation dependencies in a new
+unsaved SQL tab for review. Generation activates that tab and focuses its editor.
+See the [selection keys and remapping details](doc/PLUGIN_CATALOG.md#table-ddl-export).
+
 ### Dependencies walker
 
 Install the optional dependency browser and restart PLSQLWKS:

{plsqlwks-0.2.0 → plsqlwks-0.2.1}/README.md

@@ -64,6 +64,55 @@ protect it with `chmod 600`.
 `PLSQLWKS_ARRAYSIZE` sets the Oracle cursor array size. Both values must be
 positive integers.
 
+### Oracle Thin and Thick modes
+
+Thin mode is the default and needs no Oracle Client installation. To use an
+installed Oracle Client, start with `plsqlwks --thick`. Use `plsqlwks --thin` to
+override a workspace's thick preference for one invocation. The flags are
+mutually exclusive and are never saved to configuration.
+
+For a persistent preference, edit the selected workspace's `config.ini` (or the
+platform configuration file when using the default workspace):
+
+```ini
+[database]
+thick_mode = no
+oracle_client_lib_dir =
+oracle_client_config_dir =
+```
+
+Set `thick_mode = yes` to enable Thick mode. Invalid boolean values are errors.
+Both optional directories expand `~`; relative paths are resolved from the
+configuration file's directory. Blank values use Oracle's normal discovery.
+The directory settings are used only in Thick mode. All tabs and reconnects
+share one driver mode; restart after changing mode or client settings.
+
+Install an Oracle Instant Client **Basic** or **Basic Light** package compatible
+with your Python architecture, python-oracledb version, and database. Libraries
+are installed separately and are not bundled with PLSQLWKS. On Linux, normally
+leave `oracle_client_lib_dir` blank and configure `ldconfig` or `LD_LIBRARY_PATH`
+**before** launching Python. Setting that directory alone does not configure
+Linux's dependent-library search path. On macOS, an explicit library directory
+can be useful. When running through SSH or WSL, install the libraries where the
+Python process runs. For a full Oracle Client installation, configure its
+Oracle environment before launch.
+
+`oracle_client_config_dir` selects the directory containing Oracle network
+configuration such as `sqlnet.ora` and `tnsnames.ora`; when blank, Oracle uses
+its normal lookup, including `TNS_ADMIN`. Native network encryption is configured
+through Oracle Client's `sqlnet.ora` and the server's matching requirements.
+The existing `ORACLE_USER`, `ORACLE_DSN`, and password-file authentication remain
+in use. See the [Oracle Client initialization guide](https://python-oracledb.readthedocs.io/en/v3.4.2/user_guide/initialization.html)
+for platform setup and the [compatibility contract](doc/COMPATIBILITY.md) for
+validated combinations.
+
+Client-loading failures such as `DPI-1047` stop startup before the terminal UI,
+with no automatic fallback. Check library architecture, required system
+libraries, and the pre-launch library search path. Mode conflicts or changed
+initialization arguments require a process restart. Successful connection status
+includes `Thin mode` or `Thick mode`. Help, version, and plugin management commands
+do not initialize Oracle Client libraries.
+
 ## Install
 
 Python 3.10 or newer is required, along with a compatible terminal and a Python
@@ -816,12 +865,11 @@ period; DATE and TIMESTAMP input uses ISO
 Character and CLOB input is preserved as entered. Types that cannot be compared
 without losing information, including time-zone timestamps and timestamps with
 precision above six, are read-only in the grid.
-In python-oracledb Thin mode, non-null `TIMESTAMP WITH TIME ZONE` and
-`TIMESTAMP WITH LOCAL TIME ZONE` values are shown and exported as explicit
-lossless-fetch-unavailable markers instead of misleading naive datetimes. Use
-an explicit `TO_CHAR` expression with the required precision and zone fields
-when the exact value is needed; named-zone timestamps are not supported by the
-current Thin driver.
+In both driver modes, ordinary SELECT/WITH queries format zoned timestamps on
+Oracle to preserve their zone and fractional precision. Query forms that cannot
+use this projection show explicit lossless-fetch-unavailable markers for
+non-null zoned values on the native fetch path. Use an explicit `TO_CHAR`
+expression with the required precision and zone fields for those query forms.
 Displayed CLOB and BLOB values are limited to the first 65,536 characters or
 bytes and include a truncation marker with the full size. Truncated LOB cells
 cannot be edited safely. Schema-browser DDL is always read in full.
@@ -1102,6 +1150,18 @@ lifecycle change requires a restart. See the
 [managed-package guide](https://gitlab.com/unununu/plsqlwks/-/blob/main/doc/PLUGINS.md#managed-plugin-packages)
 for the exact manifest, source layout, validation, replacement, and trust rules.
 
+### Table DDL Export
+
+Install `plugins/packages/table-ddl-export-0.1.1.plwgn` with
+`plsqlwks plugin install` and restart. **Alt-O -> Database -> Export table DDL**
+lets you choose a schema, filter table names as you type, select tables, and
+optionally remap them to another schema. It automatically includes related
+sequences and directly referencing packages, functions, procedures, and views, and follows
+required source-schema tables and views recursively. Definitions, constraints, indexes,
+foreign keys and triggers are ordered by creation dependencies in a new
+unsaved SQL tab for review. Generation activates that tab and focuses its editor.
+See the [selection keys and remapping details](doc/PLUGIN_CATALOG.md#table-ddl-export).
+
 ### Dependencies walker
 
 Install the optional dependency browser and restart PLSQLWKS:

{plsqlwks-0.2.0 → plsqlwks-0.2.1}/doc/API.md

@@ -190,6 +190,7 @@ class PluginContext(Protocol):
     def start_result_export(self, request: ResultExportRequest) -> None: ...
     def start_code_generation(self, request: CodeGenerationRequest) -> None: ...
     def start_dependency_walk(self) -> None: ...
+    def start_table_ddl_export(self) -> None: ...
     def start_sqlplus(self, executable: str = "sqlplus") -> None: ...
 ```
 
@@ -532,6 +533,31 @@ def generate_select(context: PluginContext) -> None:
 ordinary exceptions are also reported through the plugin error UI. The exact
 wording of either presentation is not part of the API.
 
+## Table DDL export
+
+`PluginContext.start_table_ddl_export()` is an additive API-v1 capability.
+It starts a host-owned workflow to choose a source schema, filter and select
+tables, and choose a target schema. Sequences and source-schema packages,
+functions, procedures, and views that directly reference the tables are included
+automatically, without a separate sequence picker. It returns immediately while the host
+reads metadata through the initiating tab's database worker. No connection,
+credentials, cursor, or arbitrary SQL capability crosses the plugin boundary.
+
+Required source-schema tables and views are followed recursively; tables include
+their constraints, indexes, triggers, and detected sequences. Selection of callers stays
+limited to direct references to the initially checked tables. Definitions are
+ordered by creation dependencies across object types; unresolved prerequisites
+and genuine dependency cycles are reported in the generated script.
+
+On success the host opens and activates a new unsaved tab containing the generated
+SQL, with keyboard focus in the editor. Cancellation,
+metadata failure, session replacement, or a stale editor context prevents that
+tab from opening. Metadata calls neither execute generated SQL nor commit,
+roll back, or drain DBMS_OUTPUT. Transform settings belong to individual
+DBMS_METADATA handles, not to the session. See the
+[catalog workflow](PLUGIN_CATALOG.md#table-ddl-export) for selection keys,
+remapping behavior, prerequisites, and metadata privilege requirements.
+
 ## Dependency walking
 
 `PluginContext.start_dependency_walk()` is an additive API v1 capability. The

{plsqlwks-0.2.0 → plsqlwks-0.2.1}/doc/ARCHITECTURE.md

@@ -112,6 +112,16 @@ metadata reads, optional safe numeric primary-key start derivation,
 cancellation, stale-editor checks, and fresh unsaved-tab creation, while the
 plugin receives only frozen column and primary-key descriptions.
 
+The Table DDL Export command delegates through `start_table_ddl_export()`.
+Its host controller owns the table checklist with incremental substring filtering
+and cancellable worker jobs. Its database service discovers related sequences
+and directly referencing source-schema program units using bound dictionary
+reads, orders included routines by dependency, and extracts definitions using
+per-handle DBMS_METADATA transforms. Generation creates a fresh unsaved tab only for the originating
+editor/session. Identifier-aware remapping preserves literals and comments and
+reports ambiguous references. The plugin itself never receives database or UI
+internals and generated SQL is never automatically executed.
+
 Plugin API version 1 does not expose the database worker, `OracleWorkspace`,
 mutable results or `UIState`, curses objects, global shortcut registration,
 lifecycle events, arbitrary background jobs, declarative settings schemas, hot

{plsqlwks-0.2.0 → plsqlwks-0.2.1}/doc/COMPATIBILITY.md

@@ -52,8 +52,8 @@ database failover configurations are not release-gating combinations.
 
 Oracle `DATE` has no time-zone component. Plain `DATE` and `TIMESTAMP(6)` values
 are materialized as NLS-independent Python datetimes and ISO display strings.
-The current pinned python-oracledb Thin driver does not preserve the offset or
-zone of `TIMESTAMP WITH TIME ZONE` and `TIMESTAMP WITH LOCAL TIME ZONE` values,
+The native timestamp fetch path does not provide the lossless representation
+PLSQLWKS requires for `TIMESTAMP WITH TIME ZONE` and `TIMESTAMP WITH LOCAL TIME ZONE` values,
 and it truncates precision beyond Python microseconds. Returning the resulting
 naive datetime would falsely imply a lossless value.
 
@@ -73,6 +73,13 @@ Original headings, bind values, ordering, row limits, and timestamp metadata
 are preserved. Zoned cells remain read-only; neighboring editable columns are
 unaffected. Plain `DATE` and `TIMESTAMP` behavior is unchanged.
 
+For duplicate headings, simple trailing `OFFSET` and `FETCH FIRST/NEXT ... ONLY`
+limits are applied after positional column aliases and the original native-value
+ordering. Counts can be numeric literals or simple named binds; an omitted
+`FETCH` count is also supported. `WITH TIES`, `PERCENT`, and count expressions
+retain their original placement and use the fallback below if Oracle rejects
+the projection.
+
 The projection is parsed before executing the user query, which executes once.
 Special forms such as `SELECT FOR UPDATE`, inline `WITH FUNCTION/PROCEDURE`, and
 results containing LONG, REF CURSOR, or object columns use the existing native
@@ -81,8 +88,8 @@ or rejects the projection's syntax or types, the original query runs instead.
 Non-null zoned cells on this fallback path retain a warning
 and these fail-safe display/export values:
 
-- `<TIMESTAMP WITH TIME ZONE: lossless Thin-mode fetch unavailable; use TO_CHAR>`
-- `<TIMESTAMP WITH LOCAL TIME ZONE: lossless Thin-mode fetch unavailable; use TO_CHAR>`
+- `<TIMESTAMP WITH TIME ZONE: lossless native fetch unavailable; use TO_CHAR>`
+- `<TIMESTAMP WITH LOCAL TIME ZONE: lossless native fetch unavailable; use TO_CHAR>`
 
 Named-zone values on that native fallback path can still raise Thin-mode
 `DPY-3022`. Select a lossless companion string explicitly for these query forms:
@@ -96,17 +103,41 @@ For a local-time-zone column, first cast it at the required precision to
 
 ### Experimental connection matrices
 
-No executable experimental connection job or runtime switch is part of the
-current release gate. The following names reserve separate future contracts so
-their results cannot be mistaken for coverage of the mandatory Thin matrix:
+PLSQLWKS supports an optional startup Thick-mode switch (`--thick` or
+`[database] thick_mode = yes`); Thin mode remains the default. The experimental
+Thick matrix is a separate opt-in local test profile, outside the mandatory
+release gates. Wallet/TCPS and TNS-alias matrices remain reserved. Experimental
+results do not broaden the mandatory Thin compatibility claim:
 
-| Reserved matrix | Required isolated infrastructure |
+| Experimental matrix | Required isolated infrastructure |
 | --- | --- |
 | `oracle-experimental-thick` | A separate process and protected runner image with reviewed Oracle Instant Client libraries |
 | `oracle-experimental-wallet-tcps` | A dedicated TCPS endpoint and disposable protected wallet/configuration files |
 | `oracle-experimental-tns-alias` | A disposable `tnsnames.ora`/`TNS_ADMIN` configuration and a dedicated alias |
 
-Each future experiment must retain the identity, version, endpoint-fingerprint,
+To run the Thick experiment, provision the complete isolated matrix described
+below for the selected target and install compatible Oracle Client libraries.
+Optional client directories come from the selected workspace configuration;
+Linux library discovery must be configured before launch. Run each target in a
+separate process, with its matching matrix environment:
+
+```bash
+PLSQLWKS_TEST_ORACLE_TARGET=19c python3 tools/dev.py test oracle-experimental-thick
+PLSQLWKS_TEST_ORACLE_TARGET=26ai python3 tools/dev.py test oracle-experimental-thick
+```
+
+This profile explicitly enables `PLSQLWKS_TEST_ORACLE_THICK=1` together with the
+base Oracle and matrix opt-ins. Direct pytest use of the Thick selector without
+both opt-ins is rejected. Other development profiles, including `all`, clear
+this selector and retain Thin-mode validation. Every matrix and live-suite
+connection, including fresh-workspace tests, receives the selected mode. The
+preflight verifies the actual mode before accessing endpoints, and suite
+metadata includes the Oracle Client version for Thick runs. Missing client
+libraries or incomplete infrastructure fail the experiment rather than skip it.
+No protected CI job is added in this release; any future job must use isolated
+reviewed client infrastructure and remain separate from the Thin release gates.
+
+The Thick experiment and each future experiment must retain the identity, version, endpoint-fingerprint,
 privilege, guard-token, and database-lock checks used by the base matrix. It
 starts as a separate non-gating job with separate secrets and no artifacts or
 caches. It can be added to the compatibility claim only after becoming

{plsqlwks-0.2.0 → plsqlwks-0.2.1}/doc/PLUGINS.md

@@ -168,6 +168,15 @@ SQL*Plus exits before restoring PLSQLWKS. SQL*Plus has its own session and
 transaction settings, including when launched from a read-only host. Install
 and configuration instructions are in the [catalog](PLUGIN_CATALOG.md#sqlplus-launcher).
 
+## Table DDL Export package
+
+`table-ddl-export-0.1.1.plwgn` adds **Database -> Export table DDL** through
+`PluginContext.start_table_ddl_export()`. The host supplies schema/table selection
+with filtering as you type, automatic dependent-object and directly referencing
+program-unit/view extraction, schema remapping, progress, and a new unsaved SQL tab.
+No extra dependencies are required. See the
+[catalog guide](PLUGIN_CATALOG.md#table-ddl-export) for installation and details.
+
 ## Dependencies walker package
 
 `dependencies-walker-0.1.0.plwgn` adds **Database -> Dependencies walker** through

{plsqlwks-0.2.0 → plsqlwks-0.2.1}/doc/PLUGIN_CATALOG.md

@@ -14,6 +14,7 @@ the [Plugin API v1 reference](API.md) for the normative contract.
 | csv2oratab importer | `plugins/packages/csv2oratab-0.1.0.plwgn` | `plsqlwks[csv2oratab]` |
 | Dependencies walker | `plugins/packages/dependencies-walker-0.1.0.plwgn` | Host with dependency-walker support |
 | SQL*Plus launcher | `plugins/packages/sqlplus-0.1.0.plwgn` | SQL*Plus client on the POSIX host |
+| Table DDL Export | `plugins/packages/table-ddl-export-0.1.1.plwgn` | Updated host with table DDL export support |
 
 Install the commands you want from a checkout or unpacked source distribution:
 
@@ -52,6 +53,119 @@ archives are deterministic copies of the adjacent source trees; tests require
 byte-for-byte equality. The source distribution includes this catalog, while
 the application wheel does not.
 
+## Table DDL Export
+
+Install the package and restart PLSQLWKS:
+
+```bash
+plsqlwks plugin install plugins/packages/table-ddl-export-0.1.1.plwgn
+```
+
+Choose **Alt-O -> Database -> Export table DDL**. Enter a source schema
+(the current schema is suggested), filter and select tables, and enter a target
+schema. Keeping the source name disables remapping. Use
+double quotes for exact mixed-case or unusual schema names.
+
+Type in the table list to filter names immediately by a case-insensitive literal
+substring. **Backspace** edits the filter, **Ctrl+L** clears it, and **/** opens
+an optional filter prompt for text containing spaces. An empty filter shows all
+tables. Use arrows/Page Up/Page Down/Home/End to navigate, **Space** to toggle
+an entry, **Ctrl+A** to select matching tables, and **Ctrl+U** to deselect them.
+Checked tables stay selected when hidden by a filter; the screen shows both
+total and visible selection counts. **Enter** exports the checked tables,
+including hidden selections. **Esc** or **Ctrl+C** cancels, including during
+metadata reads. At least one table must be checked.
+
+There is no sequence-selection dialog. Source-schema sequences referenced by
+defaults and Oracle-recorded table/trigger/program-unit dependencies are included
+automatically. Trigger bodies are also scanned for explicit NEXTVAL/CURRVAL
+references to accessible sequences, including invalid or disabled triggers whose
+dictionary dependencies may be incomplete. Comments, strings, and remote
+references are ignored; names are not inferred from table names. Identity backing
+sequences are excluded: identity definitions remain in CREATE TABLE. Sequences
+shared by several tables are emitted once.
+
+For ordinary sequences, START WITH uses the exporting session's CURRVAL plus
+INCREMENT BY when CURRVAL is defined, taking priority over the metadata cache
+boundary. A cycling sequence wraps at its configured bounds; an exhausted
+noncycling sequence stops the export with an error. If CURRVAL is undefined in
+that session (ORA-08002), the original DBMS_METADATA START WITH is preserved.
+Scalable/sharded sequences retain their metadata restart position with a review
+comment because raw CURRVAL includes offsets. Other sequence options remain intact.
+
+Each definition states which restart source was used. CURRVAL describes only
+the export session: other sessions may have consumed different values. Metadata
+snapshots may skip unused cached numbers, and later source activity is not
+reflected in the script. Export never calls NEXTVAL, changes sequence settings,
+recompiles source triggers, or scans table data to calculate a start value.
+
+Source-schema packages, standalone functions, procedures, and views that directly
+reference any initially checked table are also included. A package match includes its
+specification and its body when present, even if only the body references the
+table. Shared objects are emitted once; indirect callers, views built only on
+other views, and routines accessing tables only through views are not selected. Detection uses Oracle's
+recorded dependencies, so dynamic SQL references cannot be discovered reliably.
+
+Required source-schema tables and views are included automatically, following dependencies
+recursively through table definitions, foreign keys, triggers, indexes, and the
+included routines and views. For example, exporting `HARDWARE` also exports `HARDWARE_HIST`
+when a hardware trigger references that history table, and exporting `ECONOMIC_CALENDAR`
+includes the prerequisite view `LDR_ECOCAL_FF`. Each added table includes
+its constraints, indexes, triggers, and detected sequences; shared tables are
+emitted once. The script header lists automatically added tables and views. This expansion
+does not select additional callers of those tables or recursively include other
+callers of the added views. Tables excluded from the table picker and objects in other schemas
+remain prerequisites.
+
+After generation, the new unsaved tab is named `YYYYMMDD_<table_name>.sql`
+using the local export date, for example `20261001_HARDWARE.sql`. Multiple
+tables use the alphabetically first checked name plus the checked table count
+padded to three digits, for example `20261001_HARDWARE_010.sql` for ten tables.
+Characters unsuitable for filenames are replaced with underscores. The tab becomes active with keyboard
+focus in its editor, and Save suggests the generated filename.
+Definitions are ordered by creation dependencies across all exported object types.
+Independent objects prefer sequences, tables with non-FK constraints, package
+specifications, functions, procedures, package bodies, views, indexes, foreign keys, then
+triggers, with stable name ordering within each group. A prerequisite overrides
+that grouping: an included function used by a virtual column precedes its table,
+and a trigger named by `FOLLOWS` or `PRECEDES` precedes the trigger naming it.
+Static function calls in virtual-column and index expressions supplement Oracle's
+recorded dependencies. Foreign keys follow both participating tables and keys;
+mutual foreign keys do not create a table-creation cycle. Genuine dependency
+cycles identify only their participating objects in a warning; creation order
+alone cannot resolve them, and no automatic recovery/recompilation is generated.
+Primary/unique key indexes are not duplicated. Constraint and trigger states,
+identity/virtual columns, defaults, and partitioning are preserved. Tablespace
+and segment-storage clauses are omitted. Ordinary user tables are listed;
+recycle-bin entries, materialized-view storage and internal storage tables are excluded.
+
+Remapping changes source-schema ownership and identifiable static references,
+including references to automatically included tables. Required source tables
+that cannot be included must already exist in the **target** schema. References
+to other schemas remain unchanged. Strings and comments are preserved; dynamic
+SQL, ambiguous qualifiers, and source qualifiers in strings receive review
+notes. Dependencies outside the export appear as prerequisites in the script
+header; Oracle metadata cannot discover every dynamic or indirect dependency.
+
+The source account must be able to retrieve each requested object's metadata.
+Normally this means owning the objects; cross-schema extraction requires
+appropriate DBMS_METADATA catalog privileges, such as SELECT_CATALOG_ROLE.
+Having SELECT on another schema's table alone is insufficient. Metadata errors
+abort generation instead of presenting an incomplete export as successful.
+
+Review and save the script normally. Export does not execute SQL, create the
+destination schema, copy rows, grant privileges, commit, roll back, or drain
+DBMS_OUTPUT. The destination schema must already exist when the script is run.
+Grants, synonyms, other routines, types and other dependent
+schemas are not exported recursively. Missing prerequisite objects and sequences
+used only through dynamic SQL may require manual additions. Existing editor content/results remain
+intact. Both Thin and Thick connections are supported.
+
+When upgrading an existing package, add `--replace` to the install command.
+Update the host application and restart as well: the selection and extraction
+workflow is implemented by the host, so replacing only the plugin archive does
+not update an older host's behavior.
+
 ## SQL*Plus launcher
 
 Install the optional package, then restart PLSQLWKS: